sources/core/resourcemanager.js

   1 /**
   2  * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md or http://ckeditor.com/license
   4  */
   5
   6 /**
   7  * @fileOverview Defines the {@link CKEDITOR.resourceManager} class, which is
   8  *              the base for resource managers, like plugins.
   9  */
  10
  11 /**
  12  * Base class for resource managers, like plugins. This class is not
  13  * intended to be used out of the CKEditor core code.
  14  *
  15  * @class
  16  * @constructor Creates a resourceManager class instance.
  17  * @param {String} basePath The path for the resources folder.
  18  * @param {String} fileName The name used for resource files.
  19  */
  20 CKEDITOR.resourceManager = function( basePath, fileName ) {
  21         /**
  22          * The base directory containing all resources.
  23          *
  24          * @property {String}
  25          */
  26         this.basePath = basePath;
  27
  28         /**
  29          * The name used for resource files.
  30          *
  31          * @property {String}
  32          */
  33         this.fileName = fileName;
  34
  35         /**
  36          * Contains references to all resources that have already been registered
  37          * with {@link #add}.
  38          */
  39         this.registered = {};
  40
  41         /**
  42          * Contains references to all resources that have already been loaded
  43          * with {@link #load}.
  44          */
  45         this.loaded = {};
  46
  47         /**
  48          * Contains references to all resources that have already been registered
  49          * with {@link #addExternal}.
  50          */
  51         this.externals = {};
  52
  53         /**
  54          * @private
  55          */
  56         this._ = {
  57                 // List of callbacks waiting for plugins to be loaded.
  58                 waitingList: {}
  59         };
  60 };
  61
  62 CKEDITOR.resourceManager.prototype = {
  63         /**
  64          * Registers a resource.
  65          *
  66          *              CKEDITOR.plugins.add( 'sample', { ... plugin definition ... } );
  67          *
  68          * @param {String} name The resource name.
  69          * @param {Object} [definition] The resource definition.
  70          * @see CKEDITOR.pluginDefinition
  71          */
  72         add: function( name, definition ) {
  73                 if ( this.registered[ name ] )
  74                         throw new Error( '[CKEDITOR.resourceManager.add] The resource name "' + name + '" is already registered.' );
  75
  76                 var resource = this.registered[ name ] = definition || {};
  77                 resource.name = name;
  78                 resource.path = this.getPath( name );
  79
  80                 CKEDITOR.fire( name + CKEDITOR.tools.capitalize( this.fileName ) + 'Ready', resource );
  81
  82                 return this.get( name );
  83         },
  84
  85         /**
  86          * Gets the definition of a specific resource.
  87          *
  88          *              var definition = CKEDITOR.plugins.get( 'sample' );
  89          *
  90          * @param {String} name The resource name.
  91          * @returns {Object} The registered object.
  92          */
  93         get: function( name ) {
  94                 return this.registered[ name ] || null;
  95         },
  96
  97         /**
  98          * Get the folder path for a specific loaded resource.
  99          *
 100          *              alert( CKEDITOR.plugins.getPath( 'sample' ) ); // '<editor path>/plugins/sample/'
 101          *
 102          * @param {String} name The resource name.
 103          * @returns {String}
 104          */
 105         getPath: function( name ) {
 106                 var external = this.externals[ name ];
 107                 return CKEDITOR.getUrl( ( external && external.dir ) || this.basePath + name + '/' );
 108         },
 109
 110         /**
 111          * Get the file path for a specific loaded resource.
 112          *
 113          *              alert( CKEDITOR.plugins.getFilePath( 'sample' ) ); // '<editor path>/plugins/sample/plugin.js'
 114          *
 115          * @param {String} name The resource name.
 116          * @returns {String}
 117          */
 118         getFilePath: function( name ) {
 119                 var external = this.externals[ name ];
 120                 return CKEDITOR.getUrl( this.getPath( name ) + ( external ? external.file : this.fileName + '.js' ) );
 121         },
 122
 123         /**
 124          * Registers one or more resources to be loaded from an external path
 125          * instead of the core base path.
 126          *
 127          *              // Loads a plugin from '/myplugin/samples/plugin.js'.
 128          *              CKEDITOR.plugins.addExternal( 'sample', '/myplugins/sample/' );
 129          *
 130          *              // Loads a plugin from '/myplugin/samples/my_plugin.js'.
 131          *              CKEDITOR.plugins.addExternal( 'sample', '/myplugins/sample/', 'my_plugin.js' );
 132          *
 133          *              // Loads a plugin from '/myplugin/samples/my_plugin.js'.
 134          *              CKEDITOR.plugins.addExternal( 'sample', '/myplugins/sample/my_plugin.js', '' );
 135          *
 136          * @param {String} names The resource names, separated by commas.
 137          * @param {String} path The path of the folder containing the resource.
 138          * @param {String} [fileName] The resource file name. If not provided, the
 139          * default name is used. If provided with a empty string, will implicitly indicates that `path` argument
 140          * is already the full path.
 141          */
 142         addExternal: function( names, path, fileName ) {
 143                 names = names.split( ',' );
 144                 for ( var i = 0; i < names.length; i++ ) {
 145                         var name = names[ i ];
 146
 147                         // If "fileName" is not provided, we assume that it may be available
 148                         // in "path". Try to extract it in this case.
 149                         if ( !fileName ) {
 150                                 path = path.replace( /[^\/]+$/, function( match ) {
 151                                         fileName = match;
 152                                         return '';
 153                                 } );
 154                         }
 155
 156                         this.externals[ name ] = {
 157                                 dir: path,
 158
 159                                 // Use the default file name if there is no "fileName" and it
 160                                 // was not found in "path".
 161                                 file: fileName || ( this.fileName + '.js' )
 162                         };
 163                 }
 164         },
 165
 166         /**
 167          * Loads one or more resources.
 168          *
 169          *              CKEDITOR.plugins.load( 'myplugin', function( plugins ) {
 170          *                      alert( plugins[ 'myplugin' ] ); // object
 171          *              } );
 172          *
 173          * @param {String/Array} name The name of the resource to load. It may be a
 174          * string with a single resource name, or an array with several names.
 175          * @param {Function} callback A function to be called when all resources
 176          * are loaded. The callback will receive an array containing all loaded names.
 177          * @param {Object} [scope] The scope object to be used for the callback call.
 178          */
 179         load: function( names, callback, scope ) {
 180                 // Ensure that we have an array of names.
 181                 if ( !CKEDITOR.tools.isArray( names ) )
 182                         names = names ? [ names ] : [];
 183
 184                 var loaded = this.loaded,
 185                         registered = this.registered,
 186                         urls = [],
 187                         urlsNames = {},
 188                         resources = {};
 189
 190                 // Loop through all names.
 191                 for ( var i = 0; i < names.length; i++ ) {
 192                         var name = names[ i ];
 193
 194                         if ( !name )
 195                                 continue;
 196
 197                         // If not available yet.
 198                         if ( !loaded[ name ] && !registered[ name ] ) {
 199                                 var url = this.getFilePath( name );
 200                                 urls.push( url );
 201                                 if ( !( url in urlsNames ) )
 202                                         urlsNames[ url ] = [];
 203                                 urlsNames[ url ].push( name );
 204                         } else {
 205                                 resources[ name ] = this.get( name );
 206                         }
 207                 }
 208
 209                 CKEDITOR.scriptLoader.load( urls, function( completed, failed ) {
 210                         if ( failed.length ) {
 211                                 throw new Error( '[CKEDITOR.resourceManager.load] Resource name "' + urlsNames[ failed[ 0 ] ].join( ',' ) +
 212                                         '" was not found at "' + failed[ 0 ] + '".' );
 213                         }
 214
 215                         for ( var i = 0; i < completed.length; i++ ) {
 216                                 var nameList = urlsNames[ completed[ i ] ];
 217                                 for ( var j = 0; j < nameList.length; j++ ) {
 218                                         var name = nameList[ j ];
 219                                         resources[ name ] = this.get( name );
 220
 221                                         loaded[ name ] = 1;
 222                                 }
 223                         }
 224
 225                         callback.call( scope, resources );
 226                 }, this );
 227         }
 228 };