]>
Commit | Line | Data |
---|---|---|
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 | */ |