]>
git.immae.eu Git - perso/Immae/Projets/packagist/ludivine-ckeditor-component.git/blob - adapters/jquery.js
2 * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
3 * For licensing, see LICENSE.md or http://ckeditor.com/license
7 * @fileOverview Defines the {@link CKEDITOR_Adapters.jQuery jQuery Adapter}.
11 * @class CKEDITOR_Adapters.jQuery
14 * The jQuery Adapter allows for easy use of basic CKEditor functions and access to the internal API.
15 * To find more information about the jQuery Adapter, go to the [jQuery Adapter section](#!/guide/dev_jquery)
16 * of the Developer's Guide or see the "Create Editors with jQuery" sample.
18 * @aside guide dev_jquery
22 if ( typeof $ == 'undefined' ) {
23 throw new Error( 'jQuery should be loaded before CKEditor jQuery adapter.' );
26 if ( typeof CKEDITOR
== 'undefined' ) {
27 throw new Error( 'CKEditor should be loaded before CKEditor jQuery adapter.' );
31 * Allows CKEditor to override `jQuery.fn.val()`. When set to `true`, the `val()` function
32 * used on textarea elements replaced with CKEditor uses the CKEditor API.
34 * This configuration option is global and is executed during the loading of the jQuery Adapter.
35 * It cannot be customized across editor instances.
37 * Read more in the [documentation](#!/guide/dev_jquery).
40 * CKEDITOR.config.jqueryOverrideVal = true;
43 * <!-- Important: The jQuery Adapter is loaded *after* setting jqueryOverrideVal. -->
44 * <script src="/ckeditor/adapters/jquery.js"></script>
47 * $( 'textarea' ).ckeditor();
49 * $( 'textarea' ).val( 'New content' );
52 * @cfg {Boolean} [jqueryOverrideVal=true]
53 * @member CKEDITOR.config
55 CKEDITOR
.config
.jqueryOverrideVal
=
56 typeof CKEDITOR
.config
.jqueryOverrideVal
== 'undefined' ? true : CKEDITOR
.config
.jqueryOverrideVal
;
58 // jQuery object methods.
61 * Returns an existing CKEditor instance for the first matched element.
62 * Allows to easily use the internal API. Does not return a jQuery object.
64 * Raises an exception if the editor does not exist or is not ready yet.
66 * @returns CKEDITOR.editor
67 * @deprecated Use {@link #editor editor property} instead.
69 ckeditorGet: function() {
70 var instance
= this.eq( 0 ).data( 'ckeditorInstance' );
73 throw 'CKEditor is not initialized yet, use ckeditor() with a callback.';
79 * A jQuery function which triggers the creation of CKEditor with `<textarea>` and
80 * {@link CKEDITOR.dtd#$editable editable} elements.
81 * Every `<textarea>` element will be converted to a classic (`iframe`-based) editor,
82 * while any other supported element will be converted to an inline editor.
83 * This method binds the callback to the `instanceReady` event of all instances.
84 * If the editor has already been created, the callback is fired straightaway.
85 * You can also create multiple editors at once by using `$( '.className' ).ckeditor();`.
87 * **Note**: jQuery chaining and mixed parameter order is allowed.
89 * @param {Function} callback
90 * Function to be run on the editor instance. Callback takes the source element as a parameter.
92 * $( 'textarea' ).ckeditor( function( textarea ) {
93 * // Callback function code.
96 * @param {Object} config
97 * Configuration options for new instance(s) if not already created.
99 * $( 'textarea' ).ckeditor( {
105 ckeditor: function( callback
, config
) {
106 if ( !CKEDITOR
.env
.isCompatible
)
107 throw new Error( 'The environment is incompatible.' );
109 // Reverse the order of arguments if the first one isn't a function.
110 if ( !$.isFunction( callback
) ) {
116 // An array of instanceReady callback promises.
119 config
= config
|| {};
121 // Iterate over the collection.
122 this.each( function() {
123 var $element
= $( this ),
124 editor
= $element
.data( 'ckeditorInstance' ),
125 instanceLock
= $element
.data( '_ckeditorInstanceLock' ),
127 dfd
= new $.Deferred();
129 promises
.push( dfd
.promise() );
131 if ( editor
&& !instanceLock
) {
133 callback
.apply( editor
, [ this ] );
136 } else if ( !instanceLock
) {
137 // CREATE NEW INSTANCE
139 // Handle config.autoUpdateElement inside this plugin if desired.
140 if ( config
.autoUpdateElement
|| ( typeof config
.autoUpdateElement
== 'undefined' && CKEDITOR
.config
.autoUpdateElement
) ) {
141 config
.autoUpdateElementJquery
= true;
144 // Always disable config.autoUpdateElement.
145 config
.autoUpdateElement
= false;
146 $element
.data( '_ckeditorInstanceLock', true );
148 // Set instance reference in element's data.
149 if ( $( this ).is( 'textarea' ) )
150 editor
= CKEDITOR
.replace( element
, config
);
152 editor
= CKEDITOR
.inline( element
, config
);
154 $element
.data( 'ckeditorInstance', editor
);
156 // Register callback.
157 editor
.on( 'instanceReady', function( evt
) {
158 var editor
= evt
.editor
;
160 setTimeout( function() {
161 // Delay bit more if editor is still not ready.
162 if ( !editor
.element
) {
163 setTimeout( arguments
.callee
, 100 );
167 // Remove this listener. Triggered when new instance is ready.
168 evt
.removeListener();
171 * Forwards the CKEditor {@link CKEDITOR.editor#event-dataReady dataReady event} as a jQuery event.
174 * @param {CKEDITOR.editor} editor Editor instance.
176 editor
.on( 'dataReady', function() {
177 $element
.trigger( 'dataReady.ckeditor', [ editor
] );
181 * Forwards the CKEditor {@link CKEDITOR.editor#event-setData setData event} as a jQuery event.
184 * @param {CKEDITOR.editor} editor Editor instance.
186 * @param {String} data.dataValue The data that will be used.
188 editor
.on( 'setData', function( evt
) {
189 $element
.trigger( 'setData.ckeditor', [ editor
, evt
.data
] );
193 * Forwards the CKEditor {@link CKEDITOR.editor#event-getData getData event} as a jQuery event.
196 * @param {CKEDITOR.editor} editor Editor instance.
198 * @param {String} data.dataValue The data that will be returned.
200 editor
.on( 'getData', function( evt
) {
201 $element
.trigger( 'getData.ckeditor', [ editor
, evt
.data
] );
205 * Forwards the CKEditor {@link CKEDITOR.editor#event-destroy destroy event} as a jQuery event.
208 * @param {CKEDITOR.editor} editor Editor instance.
210 editor
.on( 'destroy', function() {
211 $element
.trigger( 'destroy.ckeditor', [ editor
] );
214 // Overwrite save button to call jQuery submit instead of javascript submit.
215 // Otherwise jQuery.forms does not work properly
216 editor
.on( 'save', function() {
217 $( element
.form
).submit();
221 // Integrate with form submit.
222 if ( editor
.config
.autoUpdateElementJquery
&& $element
.is( 'textarea' ) && $( element
.form
).length
) {
223 var onSubmit = function() {
224 $element
.ckeditor( function() {
225 editor
.updateElement();
229 // Bind to submit event.
230 $( element
.form
).submit( onSubmit
);
232 // Bind to form-pre-serialize from jQuery Forms plugin.
233 $( element
.form
).bind( 'form-pre-serialize', onSubmit
);
235 // Unbind when editor destroyed.
236 $element
.bind( 'destroy.ckeditor', function() {
237 $( element
.form
).unbind( 'submit', onSubmit
);
238 $( element
.form
).unbind( 'form-pre-serialize', onSubmit
);
242 // Garbage collect on destroy.
243 editor
.on( 'destroy', function() {
244 $element
.removeData( 'ckeditorInstance' );
248 $element
.removeData( '_ckeditorInstanceLock' );
251 * Forwards the CKEditor {@link CKEDITOR.editor#event-instanceReady instanceReady event} as a jQuery event.
253 * @event instanceReady
254 * @param {CKEDITOR.editor} editor Editor instance.
256 $element
.trigger( 'instanceReady.ckeditor', [ editor
] );
258 // Run given (first) code.
260 callback
.apply( editor
, [ element
] );
264 }, null, null, 9999 );
266 // Editor is already during creation process, bind our code to the event.
267 editor
.once( 'instanceReady', function() {
268 setTimeout( function() {
269 // Delay bit more if editor is still not ready.
270 if ( !editor
.element
) {
271 setTimeout( arguments
.callee
, 100 );
276 if ( editor
.element
.$ == element
&& callback
)
277 callback
.apply( editor
, [ element
] );
281 }, null, null, 9999 );
286 * The [jQuery Promise object]((http://api.jquery.com/promise/)) that handles the asynchronous constructor.
287 * This promise will be resolved after **all** of the constructors.
289 * @property {Function} promise
291 var dfd
= new $.Deferred();
293 this.promise
= dfd
.promise();
295 $.when
.apply( this, promises
).then( function() {
300 * Existing CKEditor instance. Allows to easily use the internal API.
302 * **Note**: This is not a jQuery object.
304 * var editor = $( 'textarea' ).ckeditor().editor;
306 * @property {CKEDITOR.editor} editor
308 this.editor
= this.eq( 0 ).data( 'ckeditorInstance' );
315 * Overwritten jQuery `val()` method for `<textarea>` elements that have bound CKEditor instances.
316 * This method gets or sets editor content by using the {@link CKEDITOR.editor#method-getData editor.getData()}
317 * or {@link CKEDITOR.editor#method-setData editor.setData()} methods. To handle
318 * the {@link CKEDITOR.editor#method-setData editor.setData()} callback (as `setData` is asynchronous),
319 * `val( 'some data' )` will return a [jQuery Promise object](http://api.jquery.com/promise/).
322 * @returns String|Number|Array|jQuery.fn|function(jQuery Promise)
324 if ( CKEDITOR
.config
.jqueryOverrideVal
) {
325 $.fn
.val
= CKEDITOR
.tools
.override( $.fn
.val
, function( oldValMethod
) {
326 return function( value
) {
327 // Setter, i.e. .val( "some data" );
328 if ( arguments
.length
) {
330 promises
= [], //use promise to handle setData callback
332 result
= this.each( function() {
333 var $elem
= $( this ),
334 editor
= $elem
.data( 'ckeditorInstance' );
336 // Handle .val for CKEditor.
337 if ( $elem
.is( 'textarea' ) && editor
) {
338 var dfd
= new $.Deferred();
340 editor
.setData( value
, function() {
344 promises
.push( dfd
.promise() );
346 // Call default .val function for rest of elements
348 return oldValMethod
.call( $elem
, value
);
352 // If there is no promise return default result (jQuery object of chaining).
353 if ( !promises
.length
)
355 // Create one promise which will be resolved when all of promises will be done.
357 var dfd
= new $.Deferred();
359 $.when
.apply( this, promises
).done( function() {
360 dfd
.resolveWith( _this
);
363 return dfd
.promise();
368 var $elem
= $( this ).eq( 0 ),
369 editor
= $elem
.data( 'ckeditorInstance' );
371 if ( $elem
.is( 'textarea' ) && editor
)
372 return editor
.getData();
374 return oldValMethod
.call( $elem
);
379 } )( window
.jQuery
);