includes/resourceloader/ResourceLoaderOOUIModule.php

   1 <?php
   2 /**
   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.
   7  *
   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.
  12  *
  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
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * Convenience methods for dealing with OOUI themes and their relations to MW skins.
  23  *
  24  * @ingroup ResourceLoader
  25  * @internal
  26  */
  27 trait ResourceLoaderOOUIModule {
  28         protected static $knownScriptsModules = [ 'core' ];
  29         protected static $knownStylesModules = [ 'core', 'widgets', 'toolbars', 'windows' ];
  30         protected static $knownImagesModules = [
  31                 'indicators',
  32                 // Extra icons
  33                 'icons-accessibility',
  34                 'icons-alerts',
  35                 'icons-content',
  36                 'icons-editing-advanced',
  37                 'icons-editing-citation',
  38                 'icons-editing-core',
  39                 'icons-editing-list',
  40                 'icons-editing-styling',
  41                 'icons-interactions',
  42                 'icons-layout',
  43                 'icons-location',
  44                 'icons-media',
  45                 'icons-moderation',
  46                 'icons-movement',
  47                 'icons-user',
  48                 'icons-wikimedia',
  49         ];
  50
  51         // Note that keys must be lowercase, values TitleCase.
  52         protected static $builtinSkinThemeMap = [
  53                 'default' => 'WikimediaUI',
  54         ];
  55
  56         // Note that keys must be TitleCase.
  57         protected static $builtinThemePaths = [
  58                 'WikimediaUI' => [
  59                         'scripts' => 'resources/lib/ooui/oojs-ui-wikimediaui.js',
  60                         'styles' => 'resources/lib/ooui/oojs-ui-{module}-wikimediaui.css',
  61                         'images' => 'resources/lib/ooui/themes/wikimediaui/{module}.json',
  62                 ],
  63                 'Apex' => [
  64                         'scripts' => 'resources/lib/ooui/oojs-ui-apex.js',
  65                         'styles' => 'resources/lib/ooui/oojs-ui-{module}-apex.css',
  66                         'images' => 'resources/lib/ooui/themes/apex/{module}.json',
  67                 ],
  68         ];
  69
  70         /**
  71          * Return a map of skin names (in lowercase) to OOUI theme names, defining which theme a given
  72          * skin should use.
  73          *
  74          * @return array
  75          */
  76         public static function getSkinThemeMap() {
  77                 $themeMap = self::$builtinSkinThemeMap;
  78                 $themeMap += ExtensionRegistry::getInstance()->getAttribute( 'SkinOOUIThemes' );
  79                 return $themeMap;
  80         }
  81
  82         /**
  83          * Return a map of theme names to lists of paths from which a given theme should be loaded.
  84          *
  85          * Keys are theme names, values are associative arrays. Keys of the inner array are 'scripts',
  86          * 'styles', or 'images', and values are paths. Paths may be strings or ResourceLoaderFilePaths.
  87          *
  88          * Additionally, the string '{module}' in paths represents the name of the module to load.
  89          *
  90          * @return array
  91          */
  92         protected static function getThemePaths() {
  93                 $themePaths = self::$builtinThemePaths;
  94                 $themePaths += ExtensionRegistry::getInstance()->getAttribute( 'OOUIThemePaths' );
  95
  96                 list( $defaultLocalBasePath, $defaultRemoteBasePath ) =
  97                         ResourceLoaderFileModule::extractBasePaths();
  98
  99                 // Allow custom themes' paths to be relative to the skin/extension that defines them,
 100                 // like with ResourceModuleSkinStyles
 101                 foreach ( $themePaths as $theme => &$paths ) {
 102                         list( $localBasePath, $remoteBasePath ) =
 103                                 ResourceLoaderFileModule::extractBasePaths( $paths );
 104                         if ( $localBasePath !== $defaultLocalBasePath || $remoteBasePath !== $defaultRemoteBasePath ) {
 105                                 foreach ( $paths as &$path ) {
 106                                         $path = new ResourceLoaderFilePath( $path, $localBasePath, $remoteBasePath );
 107                                 }
 108                         }
 109                 }
 110
 111                 return $themePaths;
 112         }
 113
 114         /**
 115          * Return a path to load given module of given theme from.
 116          *
 117          * The file at this path may not exist. This should be handled by the caller (throwing an error or
 118          * falling back to default theme).
 119          *
 120          * @param string $theme OOUI theme name, for example 'WikimediaUI' or 'Apex'
 121          * @param string $kind Kind of the module: 'scripts', 'styles', or 'images'
 122          * @param string $module Module name, for valid values see $knownScriptsModules,
 123          *     $knownStylesModules, $knownImagesModules
 124          * @return string|ResourceLoaderFilePath
 125          */
 126         protected function getThemePath( $theme, $kind, $module ) {
 127                 $paths = self::getThemePaths();
 128                 $path = $paths[$theme][$kind];
 129                 if ( $path instanceof ResourceLoaderFilePath ) {
 130                         $path = new ResourceLoaderFilePath(
 131                                 str_replace( '{module}', $module, $path->getPath() ),
 132                                 $path->getLocalBasePath(),
 133                                 $path->getRemoteBasePath()
 134                         );
 135                 } else {
 136                         $path = str_replace( '{module}', $module, $path );
 137                 }
 138                 return $path;
 139         }
 140
 141         /**
 142          * @param string $theme See getThemePath()
 143          * @param string $module See getThemePath()
 144          * @return string|ResourceLoaderFilePath
 145          */
 146         protected function getThemeScriptsPath( $theme, $module ) {
 147                 if ( !in_array( $module, self::$knownScriptsModules ) ) {
 148                         throw new InvalidArgumentException( "Invalid OOUI scripts module '$module'" );
 149                 }
 150                 return $this->getThemePath( $theme, 'scripts', $module );
 151         }
 152
 153         /**
 154          * @param string $theme See getThemePath()
 155          * @param string $module See getThemePath()
 156          * @return string|ResourceLoaderFilePath
 157          */
 158         protected function getThemeStylesPath( $theme, $module ) {
 159                 if ( !in_array( $module, self::$knownStylesModules ) ) {
 160                         throw new InvalidArgumentException( "Invalid OOUI styles module '$module'" );
 161                 }
 162                 return $this->getThemePath( $theme, 'styles', $module );
 163         }
 164
 165         /**
 166          * @param string $theme See getThemePath()
 167          * @param string $module See getThemePath()
 168          * @return string|ResourceLoaderFilePath
 169          */
 170         protected function getThemeImagesPath( $theme, $module ) {
 171                 if ( !in_array( $module, self::$knownImagesModules ) ) {
 172                         throw new InvalidArgumentException( "Invalid OOUI images module '$module'" );
 173                 }
 174                 return $this->getThemePath( $theme, 'images', $module );
 175         }
 176 }