3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
19 * @author Trevor Parscal
20 * @author Roan Kattouw
24 * Interface for resource loader modules, with name registration and maxage functionality.
26 abstract class ResourceLoaderModule
{
27 /* Protected Members */
29 protected $name = null;
34 * Get this module's name. This is set when the module is registered
35 * with ResourceLoader::register()
37 * @return Mixed: name (string) or null if no name was set
39 public function getName() {
44 * Set this module's name. This is called by ResourceLodaer::register()
45 * when registering the module. Other code should not call this.
47 * @param $name String: name
49 public function setName( $name ) {
54 * The maximum number of seconds to cache this module for in the
55 * client-side (browser) cache. Override this only if you have a good
56 * reason not to use $wgResourceLoaderClientMaxage.
58 * @return Integer: cache maxage in seconds
60 public function getClientMaxage() {
61 global $wgResourceLoaderClientMaxage;
62 return $wgResourceLoaderClientMaxage;
66 * The maximum number of seconds to cache this module for in the
67 * server-side (Squid / proxy) cache. Override this only if you have a
68 * good reason not to use $wgResourceLoaderServerMaxage.
70 * @return Integer: cache maxage in seconds
72 public function getServerMaxage() {
73 global $wgResourceLoaderServerMaxage;
74 return $wgResourceLoaderServerMaxage;
78 * Get whether CSS for this module should be flipped
80 public function getFlip( $context ) {
81 return $context->getDirection() === 'rtl';
84 /* Abstract Methods */
87 * Get all JS for this module for a given language and skin.
88 * Includes all relevant JS except loader scripts.
90 * @param $context ResourceLoaderContext object
93 public abstract function getScript( ResourceLoaderContext
$context );
96 * Get all CSS for this module for a given skin.
98 * @param $context ResourceLoaderContext object
101 public abstract function getStyle( ResourceLoaderContext
$context );
104 * Get the messages needed for this module.
106 * To get a JSON blob with messages, use MessageBlobStore::get()
108 * @return array of message keys. Keys may occur more than once
110 public abstract function getMessages();
113 * Get the loader JS for this module, if set.
115 * @return Mixed: loader JS (string) or false if no custom loader set
117 public abstract function getLoaderScript();
120 * Get a list of modules this module depends on.
122 * Dependency information is taken into account when loading a module
123 * on the client side. When adding a module on the server side,
124 * dependency information is NOT taken into account and YOU are
125 * responsible for adding dependent modules as well. If you don't do
126 * this, the client side loader will send a second request back to the
127 * server to fetch the missing modules, which kind of defeats the
128 * purpose of the resource loader.
130 * To add dependencies dynamically on the client side, use a custom
131 * loader script, see getLoaderScript()
132 * @return Array of module names (strings)
134 public abstract function getDependencies();
137 * Get this module's last modification timestamp for a given
138 * combination of language, skin and debug mode flag. This is typically
139 * the highest of each of the relevant components' modification
140 * timestamps. Whenever anything happens that changes the module's
141 * contents for these parameters, the mtime should increase.
143 * @param $context ResourceLoaderContext object
144 * @return int UNIX timestamp
146 public abstract function getModifiedTime( ResourceLoaderContext
$context );
150 * Module based on local JS/CSS files. This is the most common type of module.
152 class ResourceLoaderFileModule
extends ResourceLoaderModule
{
153 /* Protected Members */
155 protected $scripts = array();
156 protected $styles = array();
157 protected $messages = array();
158 protected $dependencies = array();
159 protected $debugScripts = array();
160 protected $languageScripts = array();
161 protected $skinScripts = array();
162 protected $skinStyles = array();
163 protected $loaders = array();
164 protected $parameters = array();
166 // In-object cache for file dependencies
167 protected $fileDeps = array();
168 // In-object cache for mtime
169 protected $modifiedTime = array();
174 * Construct a new module from an options array.
176 * @param $options array Options array. If empty, an empty module will be constructed
180 * // Required module options (mutually exclusive)
181 * 'scripts' => 'dir/script.js' | array( 'dir/script1.js', 'dir/script2.js' ... ),
183 * // Optional module options
184 * 'languageScripts' => array(
185 * '[lang name]' => 'dir/lang.js' | '[lang name]' => array( 'dir/lang1.js', 'dir/lang2.js' ... )
188 * 'skinScripts' => 'dir/skin.js' | array( 'dir/skin1.js', 'dir/skin2.js' ... ),
189 * 'debugScripts' => 'dir/debug.js' | array( 'dir/debug1.js', 'dir/debug2.js' ... ),
191 * // Non-raw module options
192 * 'dependencies' => 'module' | array( 'module1', 'module2' ... )
193 * 'loaderScripts' => 'dir/loader.js' | array( 'dir/loader1.js', 'dir/loader2.js' ... ),
194 * 'styles' => 'dir/file.css' | array( 'dir/file1.css', 'dir/file2.css' ... ),
195 * 'skinStyles' => array(
196 * '[skin name]' => 'dir/skin.css' | '[skin name]' => array( 'dir/skin1.css', 'dir/skin2.css' ... )
199 * 'messages' => array( 'message1', 'message2' ... ),
202 public function __construct( $options = array() ) {
203 foreach ( $options as $option => $value ) {
206 $this->scripts
= (array)$value;
209 $this->styles
= (array)$value;
212 $this->messages
= (array)$value;
215 $this->dependencies
= (array)$value;
218 $this->debugScripts
= (array)$value;
220 case 'languageScripts':
221 $this->languageScripts
= (array)$value;
224 $this->skinScripts
= (array)$value;
227 $this->skinStyles
= (array)$value;
230 $this->loaders
= (array)$value;
237 * Add script files to this module. In order to be valid, a module
238 * must contain at least one script file.
240 * @param $scripts Mixed: path to script file (string) or array of paths
242 public function addScripts( $scripts ) {
243 $this->scripts
= array_merge( $this->scripts
, (array)$scripts );
247 * Add style (CSS) files to this module.
249 * @param $styles Mixed: path to CSS file (string) or array of paths
251 public function addStyles( $styles ) {
252 $this->styles
= array_merge( $this->styles
, (array)$styles );
256 * Add messages to this module.
258 * @param $messages Mixed: message key (string) or array of message keys
260 public function addMessages( $messages ) {
261 $this->messages
= array_merge( $this->messages
, (array)$messages );
265 * Add dependencies. Dependency information is taken into account when
266 * loading a module on the client side. When adding a module on the
267 * server side, dependency information is NOT taken into account and
268 * YOU are responsible for adding dependent modules as well. If you
269 * don't do this, the client side loader will send a second request
270 * back to the server to fetch the missing modules, which kind of
271 * defeats the point of using the resource loader in the first place.
273 * To add dependencies dynamically on the client side, use a custom
274 * loader (see addLoaders())
276 * @param $dependencies Mixed: module name (string) or array of module names
278 public function addDependencies( $dependencies ) {
279 $this->dependencies
= array_merge( $this->dependencies
, (array)$dependencies );
283 * Add debug scripts to the module. These scripts are only included
286 * @param $scripts Mixed: path to script file (string) or array of paths
288 public function addDebugScripts( $scripts ) {
289 $this->debugScripts
= array_merge( $this->debugScripts
, (array)$scripts );
293 * Add language-specific scripts. These scripts are only included for
296 * @param $lang String: language code
297 * @param $scripts Mixed: path to script file (string) or array of paths
299 public function addLanguageScripts( $lang, $scripts ) {
300 $this->languageScripts
= array_merge_recursive(
301 $this->languageScripts
,
302 array( $lang => $scripts )
307 * Add skin-specific scripts. These scripts are only included for
310 * @param $skin String: skin name, or 'default'
311 * @param $scripts Mixed: path to script file (string) or array of paths
313 public function addSkinScripts( $skin, $scripts ) {
314 $this->skinScripts
= array_merge_recursive(
316 array( $skin => $scripts )
321 * Add skin-specific CSS. These CSS files are only included for a
322 * given skin. If there are no skin-specific CSS files for a skin,
323 * the files defined for 'default' will be used, if any.
325 * @param $skin String: skin name, or 'default'
326 * @param $scripts Mixed: path to CSS file (string) or array of paths
328 public function addSkinStyles( $skin, $scripts ) {
329 $this->skinStyles
= array_merge_recursive(
331 array( $skin => $scripts )
336 * Add loader scripts. These scripts are loaded on every page and are
337 * responsible for registering this module using
338 * mediaWiki.loader.register(). If there are no loader scripts defined,
339 * the resource loader will register the module itself.
341 * Loader scripts are used to determine a module's dependencies
342 * dynamically on the client side (e.g. based on browser type/version).
343 * Note that loader scripts are included on every page, so they should
344 * be lightweight and use mediaWiki.loader.register()'s callback
345 * feature to defer dependency calculation.
347 * @param $scripts Mixed: path to script file (string) or array of paths
349 public function addLoaders( $scripts ) {
350 $this->loaders
= array_merge( $this->loaders
, (array)$scripts );
353 public function getScript( ResourceLoaderContext
$context ) {
354 $retval = $this->getPrimaryScript() . "\n" .
355 $this->getLanguageScript( $context->getLanguage() ) . "\n" .
356 $this->getSkinScript( $context->getSkin() );
358 if ( $context->getDebug() ) {
359 $retval .= $this->getDebugScript();
365 public function getStyle( ResourceLoaderContext
$context ) {
366 $style = $this->getPrimaryStyle() . "\n" . $this->getSkinStyle( $context->getSkin() );
368 // Extract and store the list of referenced files
369 $files = CSSMin
::getLocalFileReferences( $style );
371 // Only store if modified
372 if ( $files !== $this->getFileDependencies( $context->getSkin() ) ) {
373 $encFiles = FormatJson
::encode( $files );
374 $dbw = wfGetDb( DB_MASTER
);
375 $dbw->replace( 'module_deps',
376 array( array( 'md_module', 'md_skin' ) ), array(
377 'md_module' => $this->getName(),
378 'md_skin' => $context->getSkin(),
379 'md_deps' => $encFiles,
383 // Save into memcached
386 $key = wfMemcKey( 'resourceloader', 'module_deps', $this->getName(), $context->getSkin() );
387 $wgMemc->set( $key, $encFiles );
393 public function getMessages() {
394 return $this->messages
;
397 public function getDependencies() {
398 return $this->dependencies
;
401 public function getLoaderScript() {
402 if ( count( $this->loaders
) == 0 ) {
406 return self
::concatScripts( $this->loaders
);
410 * Get the last modified timestamp of this module, which is calculated
411 * as the highest last modified timestamp of its constituent files and
412 * the files it depends on (see getFileDependencies()). Only files
413 * relevant to the given language and skin are taken into account, and
414 * files only relevant in debug mode are not taken into account when
417 * @param $context ResourceLoaderContext object
418 * @return Integer: UNIX timestamp
420 public function getModifiedTime( ResourceLoaderContext
$context ) {
421 if ( isset( $this->modifiedTime
[$context->getHash()] ) ) {
422 return $this->modifiedTime
[$context->getHash()];
425 $files = array_merge(
428 $context->getDebug() ?
$this->debugScripts
: array(),
429 isset( $this->languageScripts
[$context->getLanguage()] ) ?
430 (array) $this->languageScripts
[$context->getLanguage()] : array(),
431 (array) self
::getSkinFiles( $context->getSkin(), $this->skinScripts
),
432 (array) self
::getSkinFiles( $context->getSkin(), $this->skinStyles
),
434 $this->getFileDependencies( $context->getSkin() )
437 $filesMtime = max( array_map( 'filemtime', array_map( array( __CLASS__
, 'remapFilename' ), $files ) ) );
439 // Get the mtime of the message blob
440 // TODO: This timestamp is queried a lot and queried separately for each module. Maybe it should be put in memcached?
441 $dbr = wfGetDb( DB_SLAVE
);
442 $msgBlobMtime = $dbr->selectField( 'msg_resource', 'mr_timestamp', array(
443 'mr_resource' => $this->getName(),
444 'mr_lang' => $context->getLanguage()
447 $msgBlobMtime = $msgBlobMtime ?
wfTimestamp( TS_UNIX
, $msgBlobMtime ) : 0;
449 $this->modifiedTime
[$context->getHash()] = max( $filesMtime, $msgBlobMtime );
450 return $this->modifiedTime
[$context->getHash()];
453 /* Protected Members */
456 * Get the primary JS for this module. This is pulled from the
457 * script files added through addScripts()
461 protected function getPrimaryScript() {
462 return self
::concatScripts( $this->scripts
);
466 * Get the primary CSS for this module. This is pulled from the CSS
467 * files added through addStyles()
471 protected function getPrimaryStyle() {
472 return self
::concatStyles( $this->styles
);
476 * Get the debug JS for this module. This is pulled from the script
477 * files added through addDebugScripts()
481 protected function getDebugScript() {
482 return self
::concatScripts( $this->debugScripts
);
486 * Get the language-specific JS for a given language. This is pulled
487 * from the language-specific script files added through addLanguageScripts()
491 protected function getLanguageScript( $lang ) {
492 if ( !isset( $this->languageScripts
[$lang] ) ) {
495 return self
::concatScripts( $this->languageScripts
[$lang] );
499 * Get the skin-specific JS for a given skin. This is pulled from the
500 * skin-specific JS files added through addSkinScripts()
504 protected function getSkinScript( $skin ) {
505 return self
::concatScripts( self
::getSkinFiles( $skin, $this->skinScripts
) );
509 * Get the skin-specific CSS for a given skin. This is pulled from the
510 * skin-specific CSS files added through addSkinStyles()
512 * @return String: CSS
514 protected function getSkinStyle( $skin ) {
515 return self
::concatStyles( self
::getSkinFiles( $skin, $this->skinStyles
) );
519 * Helper function to get skin-specific data from an array.
521 * @param $skin String: skin name
522 * @param $map Array: map of skin names to arrays
523 * @return $map[$skin] if set and non-empty, or $map['default'] if set, or an empty array
525 protected static function getSkinFiles( $skin, $map ) {
528 if ( isset( $map[$skin] ) && $map[$skin] ) {
529 $retval = $map[$skin];
530 } else if ( isset( $map['default'] ) ) {
531 $retval = $map['default'];
538 * Get the files this module depends on indirectly for a given skin.
539 * Currently these are only image files referenced by the module's CSS.
541 * @param $skin String: skin name
542 * @return array of files
544 protected function getFileDependencies( $skin ) {
545 // Try in-object cache first
546 if ( isset( $this->fileDeps
[$skin] ) ) {
547 return $this->fileDeps
[$skin];
553 $key = wfMemcKey( 'resourceloader', 'module_deps', $this->getName(), $skin );
554 $deps = $wgMemc->get( $key );
557 $dbr = wfGetDb( DB_SLAVE
);
558 $deps = $dbr->selectField( 'module_deps', 'md_deps', array(
559 'md_module' => $this->getName(),
564 $deps = '[]'; // Empty array so we can do negative caching
566 $wgMemc->set( $key, $deps );
569 $this->fileDeps
= FormatJson
::decode( $deps, true );
571 return $this->fileDeps
;
575 * Get the contents of a set of files and concatenate them, with
576 * newlines in between. Each file is used only once.
578 * @param $files Array of file names
579 * @return String: concatenated contents of $files
581 protected static function concatScripts( $files ) {
582 return implode( "\n", array_map( 'file_get_contents', array_map( array( __CLASS__
, 'remapFilename' ), array_unique( (array) $files ) ) ) );
586 * Get the contents of a set of CSS files, remap then and concatenate
587 * them, with newlines in between. Each file is used only once.
589 * @param $files Array of file names
590 * @return String: concatenated and remapped contents of $files
592 protected static function concatStyles( $files ) {
593 return implode( "\n", array_map( array( __CLASS__
, 'remapStyle' ), array_unique( (array) $files ) ) );
597 * Remap a relative to $IP. Used as a callback for array_map()
599 * @param $file String: file name
600 * @return string $IP/$file
602 protected static function remapFilename( $file ) {
609 * Get the contents of a CSS file and run it through CSSMin::remap().
610 * This wrapper is needed so we can use array_map() in concatStyles()
612 * @param $file String: file name
613 * @return string Remapped CSS
615 protected static function remapStyle( $file ) {
616 return CSSMin
::remap( file_get_contents( self
::remapFilename( $file ) ), dirname( $file ) );
621 * Custom module for MediaWiki:Common.js and MediaWiki:Skinname.js
622 * TODO: Add Site CSS functionality too
624 class ResourceLoaderSiteModule
extends ResourceLoaderModule
{
625 /* Protected Members */
627 // In-object cache for modified time
628 protected $modifiedTime = null;
632 public function getScript( ResourceLoaderContext
$context ) {
633 return Skin
::newFromKey( $context->getSkin() )->generateUserJs();
636 public function getModifiedTime( ResourceLoaderContext
$context ) {
637 if ( isset( $this->modifiedTime
[$context->getHash()] ) ) {
638 return $this->modifiedTime
[$context->getHash()];
641 // HACK: We duplicate the message names from generateUserJs()
642 // here and weird things (i.e. mtime moving backwards) can happen
643 // when a MediaWiki:Something.js page is deleted
644 $jsPages = array( Title
::makeTitle( NS_MEDIAWIKI
, 'Common.js' ),
645 Title
::makeTitle( NS_MEDIAWIKI
, ucfirst( $context->getSkin() ) . '.js' )
648 // Do batch existence check
649 // TODO: This would work better if page_touched were loaded by this as well
650 $lb = new LinkBatch( $jsPages );
653 $this->modifiedTime
= 1; // wfTimestamp() interprets 0 as "now"
655 foreach ( $jsPages as $jsPage ) {
656 if ( $jsPage->exists() ) {
657 $this->modifiedTime
= max( $this->modifiedTime
, wfTimestamp( TS_UNIX
, $jsPage->getTouched() ) );
661 return $this->modifiedTime
;
664 public function getStyle( ResourceLoaderContext
$context ) { return ''; }
665 public function getMessages() { return array(); }
666 public function getLoaderScript() { return ''; }
667 public function getDependencies() { return array(); }
671 class ResourceLoaderStartUpModule
extends ResourceLoaderModule
{
672 /* Protected Members */
674 protected $modifiedTime = null;
678 public function getScript( ResourceLoaderContext
$context ) {
681 $scripts = file_get_contents( "$IP/resources/startup.js" );
683 if ( $context->getOnly() === 'scripts' ) {
684 // Get all module registrations
685 $registration = ResourceLoader
::getModuleRegistrations( $context );
686 // Build configuration
687 $config = FormatJson
::encode(
688 array( 'server' => $context->getServer(), 'debug' => $context->getDebug() )
690 // Add a well-known start-up function
691 $scripts .= "window.startUp = function() { $registration mediaWiki.config.set( $config ); };";
692 // Build load query for jquery and mediawiki modules
693 $query = wfArrayToCGI(
695 'modules' => implode( '|', array( 'jquery', 'mediawiki' ) ),
697 'lang' => $context->getLanguage(),
698 'dir' => $context->getDirection(),
699 'skin' => $context->getSkin(),
700 'debug' => $context->getDebug(),
701 'version' => wfTimestamp( TS_ISO_8601
, round( max(
702 ResourceLoader
::getModule( 'jquery' )->getModifiedTime( $context ),
703 ResourceLoader
::getModule( 'mediawiki' )->getModifiedTime( $context )
708 // Build HTML code for loading jquery and mediawiki modules
709 $loadScript = Html
::linkedScript( $context->getServer() . "?$query" );
710 // Add code to add jquery and mediawiki loading code; only if the current client is compatible
711 $scripts .= "if ( isCompatible() ) { document.write( '$loadScript' ); }";
712 // Delete the compatible function - it's not needed anymore
713 $scripts .= "delete window['isCompatible'];";
719 public function getModifiedTime( ResourceLoaderContext
$context ) {
722 if ( !is_null( $this->modifiedTime
) ) {
723 return $this->modifiedTime
;
726 // HACK getHighestModifiedTime() calls this function, so protect against infinite recursion
727 $this->modifiedTime
= filemtime( "$IP/resources/startup.js" );
728 $this->modifiedTime
= ResourceLoader
::getHighestModifiedTime( $context );
729 return $this->modifiedTime
;
732 public function getClientMaxage() {
733 return 300; // 5 minutes
736 public function getServerMaxage() {
737 return 300; // 5 minutes
740 public function getStyle( ResourceLoaderContext
$context ) { return ''; }
742 public function getFlip( $context ) {
745 return $wgContLang->getDir() !== $context->getDirection();
747 public function getMessages() { return array(); }
748 public function getLoaderScript() { return ''; }
749 public function getDependencies() { return array(); }