sources/core/plugindefinition.js

   1 /**
   2  * @license Copyright (c) 2003-2017, 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.pluginDefinition} class which
   8  *              contains the defintion of a plugin. This file serves documentation
   9  *              purposes only.
  10  */
  11
  12 /**
  13  * A virtual class that just illustrates the features of plugin objects which are
  14  * passed to the {@link CKEDITOR.plugins#add} method.
  15  *
  16  * This class is not really a part of the API, so its constructor should not be called.
  17  *
  18  * See also:
  19  *
  20  * * [The Plugin SDK](#!/guide/plugin_sdk_intro)
  21  * * [Creating a CKEditor plugin in 20 Lines of Code](#!/guide/plugin_sdk_sample)
  22  * * [Creating a Simple Plugin Tutorial](#!/guide/plugin_sdk_sample_1)
  23  *
  24  * @class CKEDITOR.pluginDefinition
  25  * @abstract
  26  */
  27
  28 /**
  29  * A list of plugins that are required by this plugin. Note that this property
  30  * does not determine the loading order of the plugins.
  31  *
  32  *              CKEDITOR.plugins.add( 'sample', {
  33  *                      requires: 'button,selection'
  34  *              } );
  35  *
  36  * Or:
  37  *
  38  *              CKEDITOR.plugins.add( 'sample', {
  39  *                      requires: [ 'button', 'selection' ]
  40  *              } );
  41  *
  42  * @property {String/String[]} requires
  43  */
  44
  45 /**
  46  * The list of language files available for this plugin. These files are stored inside
  47  * the `lang` directory in the plugin directory, follow the name
  48  * pattern of `langCode.js`, and contain the language definition created with
  49  * {@link CKEDITOR.plugins#setLang}.
  50  *
  51  * When the plugin is being loaded, the editor checks this list to see if
  52  * a language file in the current editor language ({@link CKEDITOR.editor#langCode})
  53  * is available, and if so, loads it. Otherwise, the file represented by the first item
  54  * in the list is loaded.
  55  *
  56  *              CKEDITOR.plugins.add( 'sample', {
  57  *                      lang: 'en,fr'
  58  *              } );
  59  *
  60  * Or:
  61  *
  62  *              CKEDITOR.plugins.add( 'sample', {
  63  *                      lang: [ 'en', 'fr' ]
  64  *              } );
  65  *
  66  * @property {String/String[]} lang
  67  */
  68
  69 /**
  70  * A function called when the plugin definition is loaded for the first time.
  71  * It is usually used to execute some code once for the entire page,
  72  * for instance code that uses the {@link CKEDITOR}'s methods such as the {@link CKEDITOR#addCss} method.
  73  *
  74  *              CKEDITOR.plugins.add( 'sample', {
  75  *                      onLoad: function() {
  76  *                              CKEDITOR.addCss( '.cke_some_class { ... }' );
  77  *                      }
  78  *              } );
  79  *
  80  * Read more about the initialization order in the {@link #init} method documentation.
  81  *
  82  * @method onLoad
  83  */
  84
  85 /**
  86  * A function called on initialization of every editor instance created on the
  87  * page before the {@link #init} call task. This feature makes it possible to
  88  * initialize things that could be used in the `init` function of other plugins.
  89  *
  90  *              CKEDITOR.plugins.add( 'sample1', {
  91  *                      beforeInit: function( editor ) {
  92  *                              editor.foo = 'bar';
  93  *                      }
  94  *              } );
  95  *
  96  *              CKEDITOR.plugins.add( 'sample2', {
  97  *                      init: function( editor ) {
  98  *                              // This will work regardless of order in which
  99  *                              // plugins sample1 and sample2 where initialized.
 100  *                              console.log( editor.foo ); // 'bar'
 101  *                      }
 102  *              } );
 103  *
 104  * Read more about the initialization order in the {@link #init} method documentation.
 105  *
 106  * @method beforeInit
 107  * @param {CKEDITOR.editor} editor The editor instance being initialized.
 108  */
 109
 110 /**
 111  * A function called on initialization of every editor instance created on the page.
 112  *
 113  *              CKEDITOR.plugins.add( 'sample', {
 114  *                      init: function( editor ) {
 115  *                              console.log( 'Editor "' + editor.name + '" is being initialized!' );
 116  *                      }
 117  *              } );
 118  *
 119  * Initialization order:
 120  *
 121  * 1. The {@link #beforeInit} methods of all enabled plugins are executed.
 122  * 2. The {@link #init} methods of all enabled plugins are executed.
 123  * 3. The {@link #afterInit} methods of all enabled plugins are executed.
 124  * 4. The {@link CKEDITOR.editor#pluginsLoaded} event is fired.
 125  *
 126  * **Note:** The order in which the `init` methods are called does not depend on the plugins' {@link #requires requirements}
 127  * or the order set in the {@link CKEDITOR.config#plugins} option. It may be random and therefore it is
 128  * recommended to use the {@link #beforeInit} and {@link #afterInit} methods in order to ensure
 129  * the right execution sequence.
 130  *
 131  * See also the {@link #onLoad} method.
 132  *
 133  * @method init
 134  * @param {CKEDITOR.editor} editor The editor instance being initialized.
 135  */
 136
 137 /**
 138  * A function called on initialization of every editor instance created on the
 139  * page after the {@link #init} call task. This feature makes it possible to use things
 140  * that were initialized in the `init` function of other plugins.
 141  *
 142  *              CKEDITOR.plugins.add( 'sample1', {
 143  *                      afterInit: function( editor ) {
 144  *                              // This will work regardless of order in which
 145  *                              // plugins sample1 and sample2 where initialized.
 146  *                              console.log( editor.foo ); // 'bar'
 147  *                      }
 148  *              } );
 149  *
 150  *              CKEDITOR.plugins.add( 'sample2', {
 151  *                      init: function( editor ) {
 152  *                              editor.foo = 'bar';
 153  *                      }
 154  *              } );
 155  *
 156  * Read more about the initialization order in the {@link #init} method documentation.
 157  *
 158  * @method afterInit
 159  * @param {CKEDITOR.editor} editor The editor instance being initialized.
 160  */
 161
 162 /**
 163  * Announces the plugin as HiDPI-ready (optimized for high pixel density screens, e.g. *Retina*)
 164  * by providing high-resolution icons and images. HiDPI icons must be twice as big
 165  * (defaults are `16px x 16px`) and stored under `plugin_name/icons/hidpi/` directory.
 166  *
 167  * The common place for additional HiDPI images used by the plugin (**but not icons**)
 168  * is the `plugin_name/images/hidpi/` directory.
 169  *
 170  * This property is optional and only makes sense if `32px x 32px` icons
 171  * and high-resolution images actually exist. If this flag is set to `true`, the editor
 172  * will automatically detect the HiDPI environment and attempt to load the
 173  * high-resolution resources.
 174  *
 175  * @since 4.2
 176  * @property {Boolean} hidpi
 177  */