annotate core/lib/Drupal/Core/Extension/ThemeHandlerInterface.php @ 19:fa3358dc1485 tip

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