MediaWiki  REL1_22
ResourceLoader Class Reference

Dynamic JavaScript and CSS resource loading system. More...

List of all members.

Public Member Functions

 __construct ()
 Registers core modules and runs registration hooks.
 addSource ($id, $properties=null)
 Add a foreign source of modules.
 getModule ($name)
 Get the ResourceLoaderModule object for a given module name.
 getModuleNames ()
 Get a list of module names.
 getSources ()
 Get the list of sources.
 getTestModuleNames ($framework= 'all')
 Get a list of test module names for one (or all) frameworks.
 makeModuleResponse (ResourceLoaderContext $context, array $modules, $missing=array())
 Generates code for a response.
 preloadModuleInfo (array $modules, ResourceLoaderContext $context)
 Loads information stored in the database about modules.
 register ($name, $info=null)
 Registers a module with the ResourceLoader system.
 registerTestModules ()
 respond (ResourceLoaderContext $context)
 Outputs a response to a resource load-request, including a content-type header.

Static Public Member Functions

static formatException ($e)
 Handle exception display.
static getLessCompiler ()
 Returns LESS compiler set up for use with MediaWiki.
static getLESSVars ()
 Get global LESS variables.
static inDebugMode ()
 Determine whether debug mode was requested Order of priority is 1) request param, 2) cookie, 3) $wg setting.
static isValidModuleName ($moduleName)
 Check a module name for validity.
static makeComment ($text)
 Generate a CSS or JS comment block.
static makeConfigSetScript (array $configuration)
 Returns JS code which will set the MediaWiki configuration array to the given value.
static makeCustomLoaderScript ($name, $version, $dependencies, $group, $source, $script)
 Returns JS code which calls the script given by $script.
static makeLoaderConditionalScript ($script)
 Returns JS code which runs given JS code if the client-side framework is present.
static makeLoaderImplementScript ($name, $scripts, $styles, $messages)
 Returns JS code to call to mw.loader.implement for a module with given properties.
static makeLoaderQuery ($modules, $lang, $skin, $user=null, $version=null, $debug=false, $only=null, $printable=false, $handheld=false, $extraQuery=array())
 Build a query array (array representation of query string) for load.php.
static makeLoaderRegisterScript ($name, $version=null, $dependencies=null, $group=null, $source=null)
 Returns JS code which calls mw.loader.register with the given parameters.
static makeLoaderSourcesScript ($id, $properties=null)
 Returns JS code which calls mw.loader.addSource() with the given parameters.
static makeLoaderStateScript ($name, $state=null)
 Returns a JS call to mw.loader.state, which sets the state of a module or modules to a given value.
static makeLoaderURL ($modules, $lang, $skin, $user=null, $version=null, $debug=false, $only=null, $printable=false, $handheld=false, $extraQuery=array())
 Build a load.php URL.
static makeMessageSetScript ($messages)
 Returns JS code which, when called, will register a given list of messages.
static makePackedModulesString ($modules)
 Convert an array of module names to a packed query string.

Protected Member Functions

 filter ($filter, $data)
 Runs JavaScript or CSS data through a filter, caching the filtered result for future calls.
 sendResponseHeaders (ResourceLoaderContext $context, $mtime, $errors)
 Send content type and last modified headers to the client.
 tryRespondFromFileCache (ResourceFileCache $fileCache, ResourceLoaderContext $context)
 Send out code for a response from file cache if possible.
 tryRespondLastModified (ResourceLoaderContext $context, $mtime)
 If there's an If-Modified-Since header, respond with a 304 appropriately and clear out the output buffer.

Protected Attributes

bool $hasErrors = false
 *
 $moduleInfos = array()
 Associative array mapping module name to info associative array.
 $modules = array()
 Array: List of module name/ResourceLoaderModule object pairs.
 $sources = array()
 array( 'source-id' => array( 'loadScript' => 'http://.../load.php' ) )
 $testModuleNames = array()
 Associative array mapping framework ids to a list of names of test suite modules.

Static Protected Attributes

static $filterCacheVersion = 7
static $requiredSourceProperties = array( 'loadScript' )

Static Private Member Functions

static makeCombinedStyles (array $stylePairs)
 Combines an associative array mapping media type to CSS into a single stylesheet with "@media" blocks.

Detailed Description

Dynamic JavaScript and CSS resource loading system.

Most of the documention is on the MediaWiki documentation wiki starting at: http://www.mediawiki.org/wiki/ResourceLoader

Definition at line 31 of file ResourceLoader.php.


Constructor & Destructor Documentation

Registers core modules and runs registration hooks.

Definition at line 198 of file ResourceLoader.php.


Member Function Documentation

ResourceLoader::addSource ( id,
properties = null 
)

Add a foreign source of modules.

Source properties: 'loadScript': URL (either fully-qualified or protocol-relative) of load.php for this source

Parameters:
$idMixed: source ID (string), or array( id1 => props1, id2 => props2, ... )
array$propertiessource properties
Exceptions:
MWException

Definition at line 327 of file ResourceLoader.php.

ResourceLoader::filter ( filter,
data 
) [protected]

Runs JavaScript or CSS data through a filter, caching the filtered result for future calls.

Available filters are:

Parameters:
string$filterName of filter to run
string$dataText to filter, such as JavaScript or CSS text
Returns:
String: Filtered data, or a comment containing an error message

Definition at line 136 of file ResourceLoader.php.

static ResourceLoader::formatException ( e) [static]

Handle exception display.

Parameters:
Exception$eto be shown to the user
Returns:
string sanitized text that can be returned to the user

Definition at line 693 of file ResourceLoader.php.

static ResourceLoader::getLessCompiler ( ) [static]

Returns LESS compiler set up for use with MediaWiki.

Since:
1.22
Returns:
lessc

Definition at line 1222 of file ResourceLoader.php.

Referenced by ResourceLoaderFileModule\compileLESSFile(), and CheckLess\execute().

static ResourceLoader::getLESSVars ( ) [static]

Get global LESS variables.

$since 1.22

Returns:
array: Map of variable names to string CSS values.

Definition at line 1248 of file ResourceLoader.php.

Referenced by ResourceLoaderFileModule\getLESSCacheKey().

Get the ResourceLoaderModule object for a given module name.

Parameters:
string$nameModule name
Returns:
ResourceLoaderModule if module has been registered, null otherwise

Definition at line 389 of file ResourceLoader.php.

Referenced by MessageBlobStore\getFromDB(), and ResourceLoaderTest\testRegisteredValidModulesAreAccessible().

Get a list of module names.

Returns:
Array: List of module names

Definition at line 359 of file ResourceLoader.php.

Get the list of sources.

Returns:
Array: array( id => array of properties, .. )

Definition at line 421 of file ResourceLoader.php.

ResourceLoader::getTestModuleNames ( framework = 'all')

Get a list of test module names for one (or all) frameworks.

If the given framework id is unknkown, or if the in-object variable is not an array, then it will return an empty array.

Parameters:
string$frameworkOptional. Get only the test module names for one particular framework.
Returns:
Array

Definition at line 372 of file ResourceLoader.php.

static ResourceLoader::inDebugMode ( ) [static]

Determine whether debug mode was requested Order of priority is 1) request param, 2) cookie, 3) $wg setting.

Returns:
bool

Definition at line 1120 of file ResourceLoader.php.

Referenced by ResourceLoaderUserTokensModule\getScript(), and ResourceLoaderUserOptionsModule\getScript().

static ResourceLoader::isValidModuleName ( moduleName) [static]

Check a module name for validity.

Module names may not contain pipes (|), commas (,) or exclamation marks (!) and can be at most 255 bytes.

Parameters:
string$moduleNameModule name to check
Returns:
bool Whether $moduleName is a valid module name

Definition at line 1212 of file ResourceLoader.php.

static ResourceLoader::makeCombinedStyles ( array stylePairs) [static, private]

Combines an associative array mapping media type to CSS into a single stylesheet with "@media" blocks.

Parameters:
array$stylePairsArray keyed by media type containing (arrays of) CSS strings.
Returns:
Array

Definition at line 933 of file ResourceLoader.php.

static ResourceLoader::makeComment ( text) [static]

Generate a CSS or JS comment block.

Only use this for public data, not error message details.

Parameters:
$textstring
Returns:
string

Definition at line 682 of file ResourceLoader.php.

static ResourceLoader::makeConfigSetScript ( array configuration) [static]

Returns JS code which will set the MediaWiki configuration array to the given value.

Parameters:
array$configurationList of configuration values keyed by variable name
Returns:
string

Definition at line 1085 of file ResourceLoader.php.

Referenced by MWDebug\getDebugHTML(), and Skin\makeVariablesScript().

static ResourceLoader::makeCustomLoaderScript ( name,
version,
dependencies,
group,
source,
script 
) [static]

Returns JS code which calls the script given by $script.

The script will be called with local variables name, version, dependencies and group, which will have values corresponding to $name, $version, $dependencies and $group as supplied.

Parameters:
string$nameModule name
$versionInteger: Module version number as a timestamp
array$dependenciesList of module names on which this module depends
string$groupGroup which the module is in.
string$sourceSource of the module, or 'local' if not foreign.
string$scriptJavaScript code
Returns:
string

Definition at line 998 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

static ResourceLoader::makeLoaderConditionalScript ( script) [static]

Returns JS code which runs given JS code if the client-side framework is present.

Parameters:
string$scriptJavaScript code
Returns:
string

Definition at line 1073 of file ResourceLoader.php.

Referenced by ProtectionForm\buildCleanupScript(), MWDebug\getDebugHTML(), and Skin\makeVariablesScript().

static ResourceLoader::makeLoaderImplementScript ( name,
scripts,
styles,
messages 
) [static]

Returns JS code to call to mw.loader.implement for a module with given properties.

Parameters:
string$nameModule name
$scriptsMixed: List of URLs to JavaScript files or String of JavaScript code
$stylesMixed: Array of CSS strings keyed by media type, or an array of lists of URLs to CSS files keyed by media type
$messagesMixed: List of messages associated with this module. May either be an associative array mapping message key to value, or a JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object.
Exceptions:
MWException
Returns:
string

Definition at line 890 of file ResourceLoader.php.

static ResourceLoader::makeLoaderQuery ( modules,
lang,
skin,
user = null,
version = null,
debug = false,
only = null,
printable = false,
handheld = false,
extraQuery = array() 
) [static]

Build a query array (array representation of query string) for load.php.

Helper function for makeLoaderURL().

Parameters:
array$modules
string$lang
string$skin
string$user
string$version
bool$debug
string$only
bool$printable
bool$handheld
array$extraQuery
Returns:
array

Definition at line 1173 of file ResourceLoader.php.

static ResourceLoader::makeLoaderRegisterScript ( name,
version = null,
dependencies = null,
group = null,
source = null 
) [static]

Returns JS code which calls mw.loader.register with the given parameters.

Has three calling conventions:

  • ResourceLoader::makeLoaderRegisterScript( array( array( $name1, $version1, $dependencies1, $group1, $source1 ), array( $name2, $version2, $dependencies1, $group2, $source2 ), ... ) ): Registers modules with the given names and parameters.
Parameters:
string$nameModule name
$versionInteger: Module version number as a timestamp
array$dependenciesList of module names on which this module depends
string$groupgroup which the module is in.
string$sourcesource of the module, or 'local' if not foreign
Returns:
string

Definition at line 1030 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

static ResourceLoader::makeLoaderSourcesScript ( id,
properties = null 
) [static]

Returns JS code which calls mw.loader.addSource() with the given parameters.

Has two calling conventions:

Parameters:
string$idsource ID
array$propertiessource properties (see addSource())
Returns:
string

Definition at line 1057 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

static ResourceLoader::makeLoaderStateScript ( name,
state = null 
) [static]

Returns a JS call to mw.loader.state, which sets the state of a module or modules to a given value.

Has two calling conventions:

Parameters:
$namestring
$state
Returns:
string

Definition at line 975 of file ResourceLoader.php.

static ResourceLoader::makeLoaderURL ( modules,
lang,
skin,
user = null,
version = null,
debug = false,
only = null,
printable = false,
handheld = false,
extraQuery = array() 
) [static]

Build a load.php URL.

Parameters:
array$modulesof module names (strings)
string$langLanguage code
string$skinSkin name
string | null$userUser name. If null, the &user= parameter is omitted
string | null$versionVersioning timestamp
bool$debugWhether the request should be in debug mode
string | null$only&only= parameter
bool$printablePrintable mode
bool$handheldHandheld mode
array$extraQueryExtra query parameters to add
Returns:
string URL to load.php. May be protocol-relative (if $wgLoadScript is procol-relative)

Definition at line 1144 of file ResourceLoader.php.

Referenced by ResourceLoaderModule\getScriptURLsForDebug(), and ResourceLoaderModule\getStyleURLsForDebug().

static ResourceLoader::makeMessageSetScript ( messages) [static]

Returns JS code which, when called, will register a given list of messages.

Parameters:
$messagesMixed: Either an associative array mapping message key to value, or a JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object.
Returns:
string

Definition at line 921 of file ResourceLoader.php.

ResourceLoader::makeModuleResponse ( ResourceLoaderContext context,
array modules,
missing = array() 
)

Generates code for a response.

Parameters:
$contextResourceLoaderContext: Context in which to generate a response
array$modulesList of module objects keyed by module name
array$missingList of unavailable modules (optional)
Returns:
String: Response data

Definition at line 711 of file ResourceLoader.php.

static ResourceLoader::makePackedModulesString ( modules) [static]

Convert an array of module names to a packed query string.

For example, array( 'foo.bar', 'foo.baz', 'bar.baz', 'bar.quux' ) becomes 'foo.bar,baz|bar.baz,quux'

Parameters:
array$modulesof module names (strings)
Returns:
string Packed query string

Definition at line 1097 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getScript(), and ResourceLoaderTest\testMakePackedModulesString().

Loads information stored in the database about modules.

This method grabs modules dependencies from the database and updates modules objects.

This is not inside the module code because it is much faster to request all of the information at once than it is to have each module requests its own information. This sacrifice of modularity yields a substantial performance improvement.

Parameters:
array$modulesList of module names to preload information for
$contextResourceLoaderContext: Context to load the information within

Definition at line 68 of file ResourceLoader.php.

ResourceLoader::register ( name,
info = null 
)

Registers a module with the ResourceLoader system.

Parameters:
$nameMixed: Name of module as a string or List of name/object pairs as an array
array$infoModule info array. For backwards compatibility with 1.17alpha, this may also be a ResourceLoaderModule object. Optional when using multiple-registration calling style.
Exceptions:
MWException,:If a duplicate module registration is attempted
MWException,:If a module name contains illegal characters (pipes or commas)
MWException,:If something other than a ResourceLoaderModule is being registered
Returns:
Boolean: False if there were any errors, in which case one or more modules were not registered

Definition at line 235 of file ResourceLoader.php.

Referenced by ResourceLoaderTest\testRegisteredValidModulesAreAccessible().

Outputs a response to a resource load-request, including a content-type header.

Parameters:
$contextResourceLoaderContext: Context in which a response should be formed

Definition at line 430 of file ResourceLoader.php.

ResourceLoader::sendResponseHeaders ( ResourceLoaderContext context,
mtime,
errors 
) [protected]

Send content type and last modified headers to the client.

Parameters:
$contextResourceLoaderContext
string$mtimeTS_MW timestamp to use for last-modified
bool$errorsWhether there are commented-out errors in the response
Returns:
void

Definition at line 557 of file ResourceLoader.php.

Send out code for a response from file cache if possible.

Parameters:
$fileCacheResourceFileCache: Cache object for this request URL
$contextResourceLoaderContext: Context in which to generate a response
Returns:
bool If this found a cache file and handled the response

Definition at line 631 of file ResourceLoader.php.

ResourceLoader::tryRespondLastModified ( ResourceLoaderContext context,
mtime 
) [protected]

If there's an If-Modified-Since header, respond with a 304 appropriately and clear out the output buffer.

If the client cache is too old then do nothing.

Parameters:
$contextResourceLoaderContext
string$mtimeThe TS_MW timestamp to check the header against
Returns:
bool True if 304 header sent and output handled

Definition at line 596 of file ResourceLoader.php.


Member Data Documentation

ResourceLoader::$filterCacheVersion = 7 [static, protected]

Definition at line 34 of file ResourceLoader.php.

bool ResourceLoader::$hasErrors = false [protected]

*

Definition at line 50 of file ResourceLoader.php.

ResourceLoader::$moduleInfos = array() [protected]

Associative array mapping module name to info associative array.

Definition at line 41 of file ResourceLoader.php.

ResourceLoader::$modules = array() [protected]

Array: List of module name/ResourceLoaderModule object pairs.

Definition at line 38 of file ResourceLoader.php.

ResourceLoader::$requiredSourceProperties = array( 'loadScript' ) [static, protected]

Definition at line 35 of file ResourceLoader.php.

ResourceLoader::$sources = array() [protected]

array( 'source-id' => array( 'loadScript' => 'http://.../load.php' ) )

Definition at line 48 of file ResourceLoader.php.

ResourceLoader::$testModuleNames = array() [protected]

Associative array mapping framework ids to a list of names of test suite modules.

like array( 'qunit' => array( 'mediawiki.tests.qunit.suites', 'ext.foo.tests', .. ), .. )

Definition at line 45 of file ResourceLoader.php.


The documentation for this class was generated from the following file: