sources/core/dataprocessor.js

   1 /**
   2  * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md or http://ckeditor.com/license
   4  */
   5
   6 /**
   7  * @fileOverview Defines the "virtual" {@link CKEDITOR.dataProcessor} class, which
   8  *              defines the basic structure of data processor objects to be
   9  *              set to {@link CKEDITOR.editor.dataProcessor}.
  10  */
  11
  12 /**
  13  * If defined, points to the data processor which is responsible for translating
  14  * and transforming the editor data on input and output.
  15  * Generally it will point to an instance of {@link CKEDITOR.htmlDataProcessor},
  16  * which handles HTML data. The editor may also handle other data formats by
  17  * using different data processors provided by specific plugins.
  18  *
  19  * @property {CKEDITOR.dataProcessor} dataProcessor
  20  * @member CKEDITOR.editor
  21  */
  22
  23 /**
  24  * Represents a data processor which is responsible for translating and
  25  * transforming the editor data on input and output.
  26  *
  27  * This class is here for documentation purposes only and is not really part of
  28  * the API. It serves as the base ("interface") for data processor implementations.
  29  *
  30  * @class CKEDITOR.dataProcessor
  31  * @abstract
  32  */
  33
  34 /**
  35  * Transforms input data into HTML to be loaded into the editor.
  36  * While the editor is able to handle non-HTML data (like BBCode), it can only
  37  * handle HTML data at runtime. The role of the data processor is to transform
  38  * the input data into HTML through this function.
  39  *
  40  *              // Tranforming BBCode data, with a custom BBCode data processor available.
  41  *              var data = 'This is [b]an example[/b].';
  42  *              var html = editor.dataProcessor.toHtml( data ); // '<p>This is <b>an example</b>.</p>'
  43  *
  44  * @method toHtml
  45  * @param {String} data The input data to be transformed.
  46  * @param {String} [fixForBody] The tag name to be used if the data must be
  47  * fixed because it is supposed to be loaded direcly into the `<body>`
  48  * tag. This is generally not used by non-HTML data processors.
  49  * @todo fixForBody type - compare to htmlDataProcessor.
  50  */
  51
  52 /**
  53  * Transforms HTML into data to be output by the editor, in the format
  54  * expected by the data processor.
  55  *
  56  * While the editor is able to handle non-HTML data (like BBCode), it can only
  57  * handle HTML data at runtime. The role of the data processor is to transform
  58  * the HTML data containined by the editor into a specific data format through
  59  * this function.
  60  *
  61  *              // Tranforming into BBCode data, with a custom BBCode data processor available.
  62  *              var html = '<p>This is <b>an example</b>.</p>';
  63  *              var data = editor.dataProcessor.toDataFormat( html ); // 'This is [b]an example[/b].'
  64  *
  65  * @method toDataFormat
  66  * @param {String} html The HTML to be transformed.
  67  * @param {String} fixForBody The tag name to be used if the output data is
  68  * coming from the `<body>` element and may be eventually fixed for it. This is
  69  * generally not used by non-HTML data processors.
  70  */