ckeditor/_source/plugins/filebrowser/plugin.js

   1 /*
   2 Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.
   3 For licensing, see LICENSE.html or http://ckeditor.com/license
   4 */
   5
   6 /**
   7  * @fileOverview The "filebrowser" plugin, it adds support for file uploads and
   8  *               browsing.
   9  *
  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.
  14  *
  15  * Example 1: (Browse)
  16  *
  17  * <pre>
  18  * {
  19  *      type : 'button',
  20  *      id : 'browse',
  21  *      filebrowser : 'tabId:elementId',
  22  *      label : editor.lang.common.browseServer
  23  * }
  24  * </pre>
  25  *
  26  * If you set the 'filebrowser' attribute on any element other than
  27  * 'fileButton', the 'Browse' action will be triggered.
  28  *
  29  * Example 2: (Quick Upload)
  30  *
  31  * <pre>
  32  * {
  33  *      type : 'fileButton',
  34  *      id : 'uploadButton',
  35  *      filebrowser : 'tabId:elementId',
  36  *      label : editor.lang.common.uploadSubmit,
  37  *      'for' : [ 'upload', 'upload' ]
  38  * }
  39  * </pre>
  40  *
  41  * If you set the 'filebrowser' attribute on a fileButton element, the
  42  * 'QuickUpload' action will be executed.
  43  *
  44  * Filebrowser plugin also supports more advanced configuration (through
  45  * javascript object).
  46  *
  47  * The following settings are supported:
  48  *
  49  * <pre>
  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)
  55  * </pre>
  56  *
  57  * Example 3: (Quick Upload)
  58  *
  59  * <pre>
  60  * {
  61  *      type : 'fileButton',
  62  *      label : editor.lang.common.uploadSubmit,
  63  *      id : 'buttonId',
  64  *      filebrowser :
  65  *      {
  66  *              action : 'QuickUpload', //required
  67  *              target : 'tab1:elementId', //required
  68  *              params : //optional
  69  *              {
  70  *                      type : 'Files',
  71  *                      currentFolder : '/folder/'
  72  *              },
  73  *              onSelect : function( fileUrl, errorMessage ) //optional
  74  *              {
  75  *                      // Do not call the built-in selectFuntion
  76  *                      // return false;
  77  *              }
  78  *      },
  79  *      'for' : [ 'tab1', 'myFile' ]
  80  * }
  81  * </pre>
  82  *
  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.
  89  *
  90  * Example 4: (Browse)
  91  *
  92  * <pre>
  93  * {
  94  *      type : 'button',
  95  *      id : 'buttonId',
  96  *      label : editor.lang.common.browseServer,
  97  *      filebrowser :
  98  *      {
  99  *              action : 'Browse',
 100  *              url : '/ckfinder/ckfinder.html&amp;type=Images',
 101  *              target : 'tab1:elementId'
 102  *      }
 103  * }
 104  * </pre>
 105  *
 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
 111  * defined.
 112  */
 113 ( function()
 114 {
 115         /**
 116          * Adds (additional) arguments to given url.
 117          *
 118          * @param {String}
 119          *            url The url.
 120          * @param {Object}
 121          *            params Additional parameters.
 122          */
 123         function addQueryString( url, params )
 124         {
 125                 var queryString = [];
 126
 127                 if ( !params )
 128                         return url;
 129                 else
 130                 {
 131                         for ( var i in params )
 132                                 queryString.push( i + "=" + encodeURIComponent( params[ i ] ) );
 133                 }
 134
 135                 return url + ( ( url.indexOf( "?" ) != -1 ) ? "&" : "?" ) + queryString.join( "&" );
 136         }
 137
 138         /**
 139          * Make a string's first character uppercase.
 140          *
 141          * @param {String}
 142          *            str String.
 143          */
 144         function ucFirst( str )
 145         {
 146                 str += '';
 147                 var f = str.charAt( 0 ).toUpperCase();
 148                 return f + str.substr( 1 );
 149         }
 150
 151         /**
 152          * The onlick function assigned to the 'Browse Server' button. Opens the
 153          * file browser and updates target field when file is selected.
 154          *
 155          * @param {CKEDITOR.event}
 156          *            evt The event object.
 157          */
 158         function browseServer( evt )
 159         {
 160                 var dialog = this.getDialog();
 161                 var editor = dialog.getParentEditor();
 162
 163                 editor._.filebrowserSe = this;
 164
 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%';
 169
 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;
 175
 176                 var url = addQueryString( this.filebrowser.url, params );
 177                 editor.popup( url, width, height );
 178         }
 179
 180         /**
 181          * The onlick function assigned to the 'Upload' button. Makes the final
 182          * decision whether form is really submitted and updates target field when
 183          * file is uploaded.
 184          *
 185          * @param {CKEDITOR.event}
 186          *            evt The event object.
 187          */
 188         function uploadFile( evt )
 189         {
 190                 var dialog = this.getDialog();
 191                 var editor = dialog.getParentEditor();
 192
 193                 editor._.filebrowserSe = this;
 194
 195                 // If user didn't select the file, stop the upload.
 196                 if ( !dialog.getContentElement( this[ 'for' ][ 0 ], this[ 'for' ][ 1 ] ).getInputElement().$.value )
 197                         return false;
 198
 199                 if ( !dialog.getContentElement( this[ 'for' ][ 0 ], this[ 'for' ][ 1 ] ).getAction() )
 200                         return false;
 201
 202                 return true;
 203         }
 204
 205         /**
 206          * Setups the file element.
 207          *
 208          * @param {CKEDITOR.ui.dialog.file}
 209          *            fileInput The file element used during file upload.
 210          * @param {Object}
 211          *            filebrowser Object containing filebrowser settings assigned to
 212          *            the fileButton associated with this file element.
 213          */
 214         function setupFileElement( editor, fileInput, filebrowser )
 215         {
 216                 var params = filebrowser.params || {};
 217                 params.CKEditor = editor.name;
 218                 params.CKEditorFuncNum = editor._.filebrowserFn;
 219                 if ( !params.langCode )
 220                         params.langCode = editor.langCode;
 221
 222                 fileInput.action = addQueryString( filebrowser.url, params );
 223                 fileInput.filebrowser = filebrowser;
 224         }
 225
 226         /**
 227          * Traverse through the content definition and attach filebrowser to
 228          * elements with 'filebrowser' attribute.
 229          *
 230          * @param String
 231          *            dialogName Dialog name.
 232          * @param {CKEDITOR.dialog.dialogDefinitionObject}
 233          *            definition Dialog definition.
 234          * @param {Array}
 235          *            elements Array of {@link CKEDITOR.dialog.contentDefinition}
 236          *            objects.
 237          */
 238         function attachFileBrowser( editor, dialogName, definition, elements )
 239         {
 240                 var element, fileInput;
 241
 242                 for ( var i in elements )
 243                 {
 244                         element = elements[ i ];
 245
 246                         if ( element.type == 'hbox' || element.type == 'vbox' )
 247                                 attachFileBrowser( editor, dialogName, definition, element.children );
 248
 249                         if ( !element.filebrowser )
 250                                 continue;
 251
 252                         if ( typeof element.filebrowser == 'string' )
 253                         {
 254                                 var fb =
 255                                 {
 256                                         action : ( element.type == 'fileButton' ) ? 'QuickUpload' : 'Browse',
 257                                         target : element.filebrowser
 258                                 };
 259                                 element.filebrowser = fb;
 260                         }
 261
 262                         if ( element.filebrowser.action == 'Browse' )
 263                         {
 264                                 var url = element.filebrowser.url || editor.config[ 'filebrowser' + ucFirst( dialogName ) + 'BrowseUrl' ]
 265                                                         || editor.config.filebrowserBrowseUrl;
 266
 267                                 if ( url )
 268                                 {
 269                                         element.onClick = browseServer;
 270                                         element.filebrowser.url = url;
 271                                         element.hidden = false;
 272                                 }
 273                         }
 274                         else if ( element.filebrowser.action == 'QuickUpload' && element[ 'for' ] )
 275                         {
 276                                 url =  element.filebrowser.url || editor.config[ 'filebrowser' + ucFirst( dialogName ) + 'UploadUrl' ]
 277                                                         || editor.config.filebrowserUploadUrl;
 278
 279                                 if ( url )
 280                                 {
 281                                         var onClick = element.onClick;
 282                                         element.onClick = function( evt )
 283                                         {
 284                                                 // "element" here means the definition object, so we need to find the correct
 285                                                 // button to scope the event call
 286                                                 var sender = evt.sender;
 287                                                 if ( onClick && onClick.call( sender, evt ) === false )
 288                                                         return false;
 289
 290                                                 return uploadFile.call( sender, evt );
 291                                         };
 292
 293                                         element.filebrowser.url = url;
 294                                         element.hidden = false;
 295                                         setupFileElement( editor, definition.getContents( element[ 'for' ][ 0 ] ).get( element[ 'for' ][ 1 ] ), element.filebrowser );
 296                                 }
 297                         }
 298                 }
 299         }
 300
 301         /**
 302          * Updates the target element with the url of uploaded/selected file.
 303          *
 304          * @param {String}
 305          *            url The url of a file.
 306          */
 307         function updateTargetElement( url, sourceElement )
 308         {
 309                 var dialog = sourceElement.getDialog();
 310                 var targetElement = sourceElement.filebrowser.target || null;
 311                 url = url.replace( /#/g, '%23' );
 312
 313                 // If there is a reference to targetElement, update it.
 314                 if ( targetElement )
 315                 {
 316                         var target = targetElement.split( ':' );
 317                         var element = dialog.getContentElement( target[ 0 ], target[ 1 ] );
 318                         if ( element )
 319                         {
 320                                 element.setValue( url );
 321                                 dialog.selectPage( target[ 0 ] );
 322                         }
 323                 }
 324         }
 325
 326         /**
 327          * Returns true if filebrowser is configured in one of the elements.
 328          *
 329          * @param {CKEDITOR.dialog.dialogDefinitionObject}
 330          *            definition Dialog definition.
 331          * @param String
 332          *            tabId The tab id where element(s) can be found.
 333          * @param String
 334          *            elementId The element id (or ids, separated with a semicolon) to check.
 335          */
 336         function isConfigured( definition, tabId, elementId )
 337         {
 338                 if ( elementId.indexOf( ";" ) !== -1 )
 339                 {
 340                         var ids = elementId.split( ";" );
 341                         for ( var i = 0 ; i < ids.length ; i++ )
 342                         {
 343                                 if ( isConfigured( definition, tabId, ids[i]) )
 344                                         return true;
 345                         }
 346                         return false;
 347                 }
 348
 349                 var elementFileBrowser = definition.getContents( tabId ).get( elementId ).filebrowser;
 350                 return ( elementFileBrowser && elementFileBrowser.url );
 351         }
 352
 353         function setUrl( fileUrl, data )
 354         {
 355                 var dialog = this._.filebrowserSe.getDialog(),
 356                         targetInput = this._.filebrowserSe[ 'for' ],
 357                         onSelect = this._.filebrowserSe.filebrowser.onSelect;
 358
 359                 if ( targetInput )
 360                         dialog.getContentElement( targetInput[ 0 ], targetInput[ 1 ] ).reset();
 361
 362                 if ( typeof data == 'function' && data.call( this._.filebrowserSe ) === false )
 363                         return;
 364
 365                 if ( onSelect && onSelect.call( this._.filebrowserSe, fileUrl, data ) === false )
 366                         return;
 367
 368                 // The "data" argument may be used to pass the error message to the editor.
 369                 if ( typeof data == 'string' && data )
 370                         alert( data );
 371
 372                 if ( fileUrl )
 373                         updateTargetElement( fileUrl, this._.filebrowserSe );
 374         }
 375
 376         CKEDITOR.plugins.add( 'filebrowser',
 377         {
 378                 init : function( editor, pluginPath )
 379                 {
 380                         editor._.filebrowserFn = CKEDITOR.tools.addFunction( setUrl, editor );
 381                 }
 382         } );
 383
 384         CKEDITOR.on( 'dialogDefinition', function( evt )
 385         {
 386                 var definition = evt.data.definition,
 387                         element;
 388                 // Associate filebrowser to elements with 'filebrowser' attribute.
 389                 for ( var i in definition.contents )
 390                 {
 391                         element = definition.contents[ i ] ;
 392                         attachFileBrowser( evt.editor, evt.data.name, definition, element.elements );
 393                         if ( element.hidden && element.filebrowser )
 394                         {
 395                                 element.hidden = !isConfigured( definition, element[ 'id' ], element.filebrowser );
 396                         }
 397                 }
 398         } );
 399
 400 } )();
 401
 402 /**
 403  * The location of an external file browser, that should be launched when "Browse Server" button is pressed.
 404  * If configured, the "Browse Server" button will appear in Link, Image and Flash dialogs.
 405  * @see The <a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/File_Browser_(Uploader)">File Browser/Uploader</a> documentation.
 406  * @name CKEDITOR.config.filebrowserBrowseUrl
 407  * @since 3.0
 408  * @type String
 409  * @default '' (empty string = disabled)
 410  * @example
 411  * config.filebrowserBrowseUrl = '/browser/browse.php';
 412  */
 413
 414 /**
 415  * The location of a script that handles file uploads.
 416  * If set, the "Upload" tab will appear in "Link", "Image" and "Flash" dialogs.
 417  * @name CKEDITOR.config.filebrowserUploadUrl
 418  * @see The <a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/File_Browser_(Uploader)">File Browser/Uploader</a> documentation.
 419  * @since 3.0
 420  * @type String
 421  * @default '' (empty string = disabled)
 422  * @example
 423  * config.filebrowserUploadUrl = '/uploader/upload.php';
 424  */
 425
 426 /**
 427  * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Image dialog.
 428  * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
 429  * @name CKEDITOR.config.filebrowserImageBrowseUrl
 430  * @since 3.0
 431  * @type String
 432  * @default '' (empty string = disabled)
 433  * @example
 434  * config.filebrowserImageBrowseUrl = '/browser/browse.php?type=Images';
 435  */
 436
 437 /**
 438  * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Flash dialog.
 439  * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
 440  * @name CKEDITOR.config.filebrowserFlashBrowseUrl
 441  * @since 3.0
 442  * @type String
 443  * @default '' (empty string = disabled)
 444  * @example
 445  * config.filebrowserFlashBrowseUrl = '/browser/browse.php?type=Flash';
 446  */
 447
 448 /**
 449  * The location of a script that handles file uploads in the Image dialog.
 450  * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserUploadUrl}.
 451  * @name CKEDITOR.config.filebrowserImageUploadUrl
 452  * @since 3.0
 453  * @type String
 454  * @default '' (empty string = disabled)
 455  * @example
 456  * config.filebrowserImageUploadUrl = '/uploader/upload.php?type=Images';
 457  */
 458
 459 /**
 460  * The location of a script that handles file uploads in the Flash dialog.
 461  * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserUploadUrl}.
 462  * @name CKEDITOR.config.filebrowserFlashUploadUrl
 463  * @since 3.0
 464  * @type String
 465  * @default '' (empty string = disabled)
 466  * @example
 467  * config.filebrowserFlashUploadUrl = '/uploader/upload.php?type=Flash';
 468  */
 469
 470 /**
 471  * The location of an external file browser, that should be launched when "Browse Server" button is pressed in the Link tab of Image dialog.
 472  * If not set, CKEditor will use {@link CKEDITOR.config.filebrowserBrowseUrl}.
 473  * @name CKEDITOR.config.filebrowserImageBrowseLinkUrl
 474  * @since 3.2
 475  * @type String
 476  * @default '' (empty string = disabled)
 477  * @example
 478  * config.filebrowserImageBrowseLinkUrl = '/browser/browse.php';
 479  */