aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Extension/ThemeHandlerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Extension;
   4
   5 /**
   6  * Manages the list of available themes.
   7  */
   8 interface ThemeHandlerInterface {
   9
  10   /**
  11    * Installs a given list of themes.
  12    *
  13    * @param array $theme_list
  14    *   An array of theme names.
  15    * @param bool $install_dependencies
  16    *   (optional) If TRUE, dependencies will automatically be installed in the
  17    *   correct order. This incurs a significant performance cost, so use FALSE
  18    *   if you know $theme_list is already complete and in the correct order.
  19    *
  20    * @return bool
  21    *   Whether any of the given themes have been installed.
  22    *
  23    * @throws \Drupal\Core\Extension\ExtensionNameLengthException
  24    *   Thrown when the theme name is to long.
  25    *
  26    * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 9.0.0.
  27    *   Use the theme_installer service instead.
  28    *
  29    * @see \Drupal\Core\Extension\ThemeInstallerInterface::install
  30    */
  31   public function install(array $theme_list, $install_dependencies = TRUE);
  32
  33   /**
  34    * Uninstalls a given list of themes.
  35    *
  36    * Uninstalling a theme removes all related configuration (like blocks) and
  37    * invokes the 'themes_uninstalled' hook.
  38    *
  39    * @param array $theme_list
  40    *   The themes to uninstall.
  41    *
  42    * @throws \Drupal\Core\Extension\Exception\UninstalledExtensionException
  43    *   Thrown when you try to uninstall a theme that wasn't installed.
  44    *
  45    * @see hook_themes_uninstalled()
  46    *
  47    * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 9.0.0.
  48    *   Use the theme_installer service instead.
  49    *
  50    * @see \Drupal\Core\Extension\ThemeInstallerInterface::uninstall
  51    */
  52   public function uninstall(array $theme_list);
  53
  54   /**
  55    * Returns a list of currently installed themes.
  56    *
  57    * @return \Drupal\Core\Extension\Extension[]
  58    *   An associative array of the currently installed themes. The keys are the
  59    *   themes' machine names and the values are objects having the following
  60    *   properties:
  61    *   - filename: The filepath and name of the .info.yml file.
  62    *   - name: The machine name of the theme.
  63    *   - status: 1 for installed, 0 for uninstalled themes.
  64    *   - info: The contents of the .info.yml file.
  65    *   - stylesheets: A two dimensional array, using the first key for the
  66    *     media attribute (e.g. 'all'), the second for the name of the file
  67    *     (e.g. style.css). The value is a complete filepath (e.g.
  68    *     themes/bartik/style.css). Not set if no stylesheets are defined in the
  69    *     .info.yml file.
  70    *   - scripts: An associative array of JavaScripts, using the filename as key
  71    *     and the complete filepath as value. Not set if no scripts are defined
  72    *     in the .info.yml file.
  73    *   - prefix: The base theme engine prefix.
  74    *   - engine: The machine name of the theme engine.
  75    *   - base_theme: If this is a sub-theme, the machine name of the base theme
  76    *     defined in the .info.yml file. Otherwise, the element is not set.
  77    *   - base_themes: If this is a sub-theme, an associative array of the
  78    *     base-theme ancestors of this theme, starting with this theme's base
  79    *     theme, then the base theme's own base theme, etc. Each entry has an
  80    *     array key equal to the theme's machine name, and a value equal to the
  81    *     human-readable theme name; if a theme with matching machine name does
  82    *     not exist in the system, the value will instead be NULL (and since the
  83    *     system would not know whether that theme itself has a base theme, that
  84    *     will end the array of base themes). This is not set if the theme is not
  85    *     a sub-theme.
  86    *   - sub_themes: An associative array of themes on the system that are
  87    *     either direct sub-themes (that is, they declare this theme to be
  88    *     their base theme), direct sub-themes of sub-themes, etc. The keys are
  89    *     the themes' machine names, and the values are the themes'
  90    *     human-readable names. This element is not set if there are no themes on
  91    *     the system that declare this theme as their base theme.
  92    */
  93   public function listInfo();
  94
  95   /**
  96    * Adds a theme extension to the internal listing.
  97    *
  98    * @param \Drupal\Core\Extension\Extension $theme
  99    *   The theme extension.
 100    */
 101   public function addTheme(Extension $theme);
 102
 103   /**
 104    * Refreshes the theme info data of currently installed themes.
 105    *
 106    * Modules can alter theme info, so this is typically called after a module
 107    * has been installed or uninstalled.
 108    */
 109   public function refreshInfo();
 110
 111   /**
 112    * Resets the internal state of the theme handler.
 113    */
 114   public function reset();
 115
 116   /**
 117    * Scans and collects theme extension data and their engines.
 118    *
 119    * @return \Drupal\Core\Extension\Extension[]
 120    *   An associative array of theme extensions.
 121    */
 122   public function rebuildThemeData();
 123
 124   /**
 125    * Finds all the base themes for the specified theme.
 126    *
 127    * Themes can inherit templates and function implementations from earlier
 128    * themes.
 129    *
 130    * @param \Drupal\Core\Extension\Extension[] $themes
 131    *   An array of available themes.
 132    * @param string $theme
 133    *   The name of the theme whose base we are looking for.
 134    *
 135    * @return array
 136    *   Returns an array of all of the theme's ancestors; the first element's
 137    *   value will be NULL if an error occurred.
 138    */
 139   public function getBaseThemes(array $themes, $theme);
 140
 141   /**
 142    * Gets the human readable name of a given theme.
 143    *
 144    * @param string $theme
 145    *   The machine name of the theme which title should be shown.
 146    *
 147    * @return string
 148    *   Returns the human readable name of the theme.
 149    *
 150    * @throws \Drupal\Core\Extension\Exception\UnknownExtensionException
 151    *   When the specified theme does not exist.
 152    */
 153   public function getName($theme);
 154
 155   /**
 156    * Returns the default theme.
 157    *
 158    * @return string
 159    *   The default theme.
 160    */
 161   public function getDefault();
 162
 163   /**
 164    * Sets a new default theme.
 165    *
 166    * @param string $theme
 167    *   The new default theme.
 168    *
 169    * @return $this
 170    *
 171    * @deprecated in Drupal 8.2.x-dev and will be removed before Drupal 9.0.0.
 172    *   Use
 173    *   @code
 174    *     \Drupal::configFactory()
 175    *       ->getEditable('system.theme')
 176    *       ->set('default', $theme)
 177    *       ->save();
 178    *   @endcode
 179    */
 180   public function setDefault($theme);
 181
 182   /**
 183    * Returns an array of directories for all installed themes.
 184    *
 185    * Useful for tasks such as finding a file that exists in all theme
 186    * directories.
 187    *
 188    * @return array
 189    */
 190   public function getThemeDirectories();
 191
 192   /**
 193    * Determines whether a given theme is installed.
 194    *
 195    * @param string $theme
 196    *   The name of the theme (without the .theme extension).
 197    *
 198    * @return bool
 199    *   TRUE if the theme is installed.
 200    */
 201   public function themeExists($theme);
 202
 203   /**
 204    * Returns a theme extension object from the currently active theme list.
 205    *
 206    * @param string $name
 207    *   The name of the theme to return.
 208    *
 209    * @return \Drupal\Core\Extension\Extension
 210    *   An extension object.
 211    *
 212    * @throws \Drupal\Core\Extension\Extension\UnknownExtensionException
 213    *   Thrown when the requested theme does not exist.
 214    */
 215   public function getTheme($name);
 216
 217   /**
 218    * Determines if a theme should be shown in the user interface.
 219    *
 220    * To be shown in the UI the theme has to be installed. If the theme is hidden
 221    * it will not be shown unless it is the default or admin theme.
 222    *
 223    * @param string $name
 224    *   The name of the theme to check.
 225    *
 226    * @return bool
 227    *   TRUE if the theme should be shown in the UI, FALSE if not.
 228    */
 229   public function hasUi($name);
 230
 231 }