2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
3 For licensing, see LICENSE.html or http://ckeditor.com/license
7 * @fileOverview The "filebrowser" plugin, it adds support for file uploads and
10 * When file is selected inside of the file browser or uploaded, its url is
11 * inserted automatically to a field, which is described in the 'filebrowser'
12 * attribute. To specify field that should be updated, pass the tab id and
13 * element id, separated with a colon.
21 * filebrowser : 'tabId:elementId',
22 * label : editor.lang.common.browseServer
26 * If you set the 'filebrowser' attribute on any element other than
27 * 'fileButton', the 'Browse' action will be triggered.
29 * Example 2: (Quick Upload)
33 * type : 'fileButton',
34 * id : 'uploadButton',
35 * filebrowser : 'tabId:elementId',
36 * label : editor.lang.common.uploadSubmit,
37 * 'for' : [ 'upload', 'upload' ]
41 * If you set the 'filebrowser' attribute on a fileButton element, the
42 * 'QuickUpload' action will be executed.
44 * Filebrowser plugin also supports more advanced configuration (through
47 * The following settings are supported:
50 * [action] - Browse or QuickUpload
51 * [target] - field to update, tabId:elementId
52 * [params] - additional arguments to be passed to the server connector (optional)
53 * [onSelect] - function to execute when file is selected/uploaded (optional)
54 * [url] - the URL to be called (optional)
57 * Example 3: (Quick Upload)
61 * type : 'fileButton',
62 * label : editor.lang.common.uploadSubmit,
66 * action : 'QuickUpload', //required
67 * target : 'tab1:elementId', //required
71 * currentFolder : '/folder/'
73 * onSelect : function( fileUrl, errorMessage ) //optional
75 * // Do not call the built-in selectFuntion
79 * 'for' : [ 'tab1', 'myFile' ]
83 * Suppose we have a file element with id 'myFile', text field with id
84 * 'elementId' and a fileButton. If filebowser.url is not specified explicitly,
85 * form action will be set to 'filebrowser[DialogName]UploadUrl' or, if not
86 * specified, to 'filebrowserUploadUrl'. Additional parameters from 'params'
87 * object will be added to the query string. It is possible to create your own
88 * uploadHandler and cancel the built-in updateTargetElement command.
96 * label : editor.lang.common.browseServer,
100 * url : '/ckfinder/ckfinder.html&type=Images',
101 * target : 'tab1:elementId'
106 * In this example, after pressing a button, file browser will be opened in a
107 * popup. If we don't specify filebrowser.url attribute,
108 * 'filebrowser[DialogName]BrowseUrl' or 'filebrowserBrowseUrl' will be used.
109 * After selecting a file in a file browser, an element with id 'elementId' will
110 * be updated. Just like in the third example, a custom 'onSelect' function may be
116 * Adds (additional) arguments to given url.
121 * params Additional parameters.
123 function addQueryString( url, params )
125 var queryString = [];
131 for ( var i in params )
132 queryString.push( i + "=" + encodeURIComponent( params[ i ] ) );
135 return url + ( ( url.indexOf( "?" ) != -1 ) ? "&" : "?" ) + queryString.join( "&" );
139 * Make a string's first character uppercase.
144 function ucFirst( str )
147 var f = str.charAt( 0 ).toUpperCase();
148 return f + str.substr( 1 );
152 * The onlick function assigned to the 'Browse Server' button. Opens the
153 * file browser and updates target field when file is selected.
155 * @param {CKEDITOR.event}
156 * evt The event object.
158 function browseServer( evt )
160 var dialog = this.getDialog();
161 var editor = dialog.getParentEditor();
163 editor._.filebrowserSe = this;
165 var width = editor.config[ 'filebrowser' + ucFirst( dialog.getName() ) + 'WindowWidth' ]
166 || editor.config.filebrowserWindowWidth || '80%';
167 var height = editor.config[ 'filebrowser' + ucFirst( dialog.getName() ) + 'WindowHeight' ]
168 || editor.config.filebrowserWindowHeight || '70%';
170 var params = this.filebrowser.params || {};
171 params.CKEditor = editor.name;
172 params.CKEditorFuncNum = editor._.filebrowserFn;
173 if ( !params.langCode )
174 params.langCode = editor.langCode;
176 var url = addQueryString( this.filebrowser.url, params );
177 editor.popup( url, width, height, editor.config.fileBrowserWindowFeatures );
181 * The onlick function assigned to the 'Upload' button. Makes the final
182 * decision whether form is really submitted and updates target field when
185 * @param {CKEDITOR.event}
186 * evt The event object.
188 function uploadFile( evt )
190 var dialog = this.getDialog();
191 var editor = dialog.getParentEditor();
193 editor._.filebrowserSe = this;
195 // If user didn't select the file, stop the upload.
196 if ( !dialog.getContentElement( this[ 'for' ][ 0 ], this[ 'for' ][ 1 ] ).getInputElement().$.value )
199 if ( !dialog.getContentElement( this[ 'for' ][ 0 ], this[ 'for' ][ 1 ] ).getAction() )
206 * Setups the file element.
208 * @param {CKEDITOR.ui.dialog.file}
209 * fileInput The file element used during file upload.
211 * filebrowser Object containing filebrowser settings assigned to
212 * the fileButton associated with this file element.
214 function setupFileElement( editor, fileInput, filebrowser )
216 var params = filebrowser.params || {};
217 params.CKEditor = editor.name;
218 params.CKEditorFuncNum = editor._.filebrowserFn;
219 if ( !params.langCode )
220 params.langCode = editor.langCode;
222 fileInput.action = addQueryString( filebrowser.url, params );
223 fileInput.filebrowser = filebrowser;
227 * Traverse through the content definition and attach filebrowser to
228 * elements with 'filebrowser' attribute.
231 * dialogName Dialog name.
232 * @param {CKEDITOR.dialog.dialogDefinitionObject}
233 * definition Dialog definition.
235 * elements Array of {@link CKEDITOR.dialog.contentDefinition}
238 function attachFileBrowser( editor, dialogName, definition, elements )
240 var element, fileInput;
242 for ( var i in elements )
244 element = elements[ i ];
246 if ( element.type == 'hbox' || element.type == 'vbox' )
247 attachFileBrowser( editor, dialogName, definition, element.children );
249 if ( !element.filebrowser )
252 if ( typeof element.filebrowser == 'string' )
256 action : ( element.type == 'fileButton' ) ? 'QuickUpload' : 'Browse',
257 target : element.filebrowser
259 element.filebrowser = fb;
262 if ( element.filebrowser.action == 'Browse' )
264 var url = element.filebrowser.url;
265 if ( url === undefined )
267 url = editor.config[ 'filebrowser' + ucFirst( dialogName ) + 'BrowseUrl' ];
268 if ( url === undefined )
269 url = editor.config.filebrowserBrowseUrl;
274 element.onClick = browseServer;
275 element.filebrowser.url = url;
276 element.hidden = false;
279 else if ( element.filebrowser.action == 'QuickUpload' && element[ 'for' ] )
281 url = element.filebrowser.url;
282 if ( url === undefined )
284 url = editor.config[ 'filebrowser' + ucFirst( dialogName ) + 'UploadUrl' ];
285 if ( url === undefined )
286 url = editor.config.filebrowserUploadUrl;
291 var onClick = element.onClick;
292 element.onClick = function( evt )
294 // "element" here means the definition object, so we need to find the correct
295 // button to scope the event call
296 var sender = evt.sender;
297 if ( onClick && onClick.call( sender, evt ) === false )
300 return uploadFile.call( sender, evt );
303 element.filebrowser.url = url;
304 element.hidden = false;
305 setupFileElement( editor, definition.getContents( element[ 'for' ][ 0 ] ).get( element[ 'for' ][ 1 ] ), element.filebrowser );
312 * Updates the target element with the url of uploaded/selected file.
315 * url The url of a file.
317 function updateTargetElement( url, sourceElement )
319 var dialog = sourceElement.getDialog();
320 var targetElement = sourceElement.filebrowser.target || null;
321 url = url.replace( /#/g, '%23' );
323 // If there is a reference to targetElement, update it.
326 var target = targetElement.split( ':' );
327 var element = dialog.getContentElement( target[ 0 ], target[ 1 ] );
330 element.setValue( url );
331 dialog.selectPage( target[ 0 ] );
337 * Returns true if filebrowser is configured in one of the elements.
339 * @param {CKEDITOR.dialog.dialogDefinitionObject}
340 * definition Dialog definition.
342 * tabId The tab id where element(s) can be found.
344 * elementId The element id (or ids, separated with a semicolon) to check.
346 function isConfigured( definition, tabId, elementId )
348 if ( elementId.indexOf( ";" ) !== -1 )
350 var ids = elementId.split( ";" );
351 for ( var i = 0 ; i < ids.length ; i++ )
353 if ( isConfigured( definition, tabId, ids[i] ) )
359 var elementFileBrowser = definition.getContents( tabId ).get( elementId ).filebrowser;
360 return ( elementFileBrowser && elementFileBrowser.url );
363 function setUrl( fileUrl, data )
365 var dialog = this._.filebrowserSe.getDialog(),
366 targetInput = this._.filebrowserSe[ 'for' ],
367 onSelect = this._.filebrowserSe.filebrowser.onSelect;
370 dialog.getContentElement( targetInput[ 0 ], targetInput[ 1 ] ).reset();
372 if ( typeof data == 'function' && data.call( this._.filebrowserSe ) === false )
375 if ( onSelect && onSelect.call( this._.filebrowserSe, fileUrl, data ) === false )
378 // The "data" argument may be used to pass the error message to the editor.
379 if ( typeof data == 'string' && data )
383 updateTargetElement( fileUrl, this._.filebrowserSe );
386 CKEDITOR.plugins.add( 'filebrowser',
388 init : function( editor, pluginPath )
390 editor._.filebrowserFn = CKEDITOR.tools.addFunction( setUrl, editor );
391 editor.on( 'destroy', function () { CKEDITOR.tools.removeFunction( this._.filebrowserFn ); } );
395 CKEDITOR.on( 'dialogDefinition', function( evt )
397 var definition = evt.data.definition,
399 // Associate filebrowser to elements with 'filebrowser' attribute.
400 for ( var i in definition.contents )
402 if ( ( element = definition.contents[ i ] ) )
404 attachFileBrowser( evt.editor, evt.data.name, definition, element.elements );
405 if ( element.hidden && element.filebrowser )
407 element.hidden = !isConfigured( definition, element[ 'id' ], element.filebrowser );
416 * The location of an external file browser, that should be launched when "Browse Server" button is pressed.
417 * If configured, the "Browse Server" button will appear in Link, Image and Flash dialogs.
418 * @see The <a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/File_Browser_(Uploader)">File Browser/Uploader</a> documentation.
419 * @name CKEDITOR.config.filebrowserBrowseUrl
422 * @default '' (empty string = disabled)
424 * config.filebrowserBrowseUrl = '/browser/browse.php';
428 * The location of a script that handles file uploads.
429 * If set, the "Upload" tab will appear in "Link", "Image" and "Flash" dialogs.
430 * @name CKEDITOR.config.filebrowserUploadUrl
431 * @see The <a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/File_Browser_(Uploader)">File Browser/Uploader</a> documentation.
434 * @default '' (empty string = disabled)
436 * config.filebrowserUploadUrl = '/uploader/upload.php';
440 * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Image dialog.
441 * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
442 * @name CKEDITOR.config.filebrowserImageBrowseUrl
445 * @default '' (empty string = disabled)
447 * config.filebrowserImageBrowseUrl = '/browser/browse.php?type=Images';
451 * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Flash dialog.
452 * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
453 * @name CKEDITOR.config.filebrowserFlashBrowseUrl
456 * @default '' (empty string = disabled)
458 * config.filebrowserFlashBrowseUrl = '/browser/browse.php?type=Flash';
462 * The location of a script that handles file uploads in the Image dialog.
463 * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserUploadUrl}.
464 * @name CKEDITOR.config.filebrowserImageUploadUrl
467 * @default '' (empty string = disabled)
469 * config.filebrowserImageUploadUrl = '/uploader/upload.php?type=Images';
473 * The location of a script that handles file uploads in the Flash dialog.
474 * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserUploadUrl}.
475 * @name CKEDITOR.config.filebrowserFlashUploadUrl
478 * @default '' (empty string = disabled)
480 * config.filebrowserFlashUploadUrl = '/uploader/upload.php?type=Flash';
484 * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Link tab of Image dialog.
485 * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
486 * @name CKEDITOR.config.filebrowserImageBrowseLinkUrl
489 * @default '' (empty string = disabled)
491 * config.filebrowserImageBrowseLinkUrl = '/browser/browse.php';
495 * The "features" to use in the file browser popup window.
496 * @name CKEDITOR.config.filebrowserWindowFeatures
499 * @default 'location=no,menubar=no,toolbar=no,dependent=yes,minimizable=no,modal=yes,alwaysRaised=yes,resizable=yes,scrollbars=yes'
501 * config.filebrowserWindowFeatures = 'resizable=yes,scrollbars=no';