1. 8.3.x core/lib/Drupal/Core/Render/theme.api.php
  2. 8.0.x core/lib/Drupal/Core/Render/theme.api.php
  3. 8.1.x core/lib/Drupal/Core/Render/theme.api.php
  4. 8.2.x core/lib/Drupal/Core/Render/theme.api.php
  5. 8.4.x core/lib/Drupal/Core/Render/theme.api.php
  6. 7.x modules/system/theme.api.php

Hooks and documentation related to the theme and render system.

File

core/lib/Drupal/Core/Render/theme.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks and documentation related to the theme and render system.
  5. */
  6. /**
  7. * @defgroup themeable Theme system overview
  8. * @{
  9. * Functions and templates for the user interface that themes can override.
  10. *
  11. * Drupal's theme system allows a theme to have nearly complete control over
  12. * the appearance of the site, which includes both the markup and the CSS used
  13. * to style the markup. For this system to work, modules, instead of writing
  14. * HTML markup directly, need to return "render arrays", which are structured
  15. * hierarchical arrays that include the data to be rendered into HTML (or XML or
  16. * another output format), and options that affect the markup. Render arrays
  17. * are ultimately rendered into HTML or other output formats by recursive calls
  18. * to drupal_render(), traversing the depth of the render array hierarchy. At
  19. * each level, the theme system is invoked to do the actual rendering. See the
  20. * documentation of drupal_render() and the
  21. * @link theme_render Theme system and Render API topic @endlink for more
  22. * information about render arrays and rendering.
  23. *
  24. * @section sec_twig_theme Twig Templating Engine
  25. * Drupal 8 uses the templating engine Twig. Twig offers developers a fast,
  26. * secure, and flexible method for building templates for Drupal 8 sites. Twig
  27. * also offers substantial usability improvements over PHPTemplate, and does
  28. * not require front-end developers to know PHP to build and manipulate Drupal
  29. * 8 themes.
  30. *
  31. * For further information on theming in Drupal 8 see
  32. * https://www.drupal.org/theme-guide/8
  33. *
  34. * For further Twig documentation see
  35. * http://twig.sensiolabs.org/doc/templates.html
  36. *
  37. * @section sec_theme_hooks Theme Hooks
  38. * The theme system is invoked in \Drupal\Core\Render\Renderer::doRender() by
  39. * calling the \Drupal\Core\Theme\ThemeManagerInterface::render() function,
  40. * which operates on the concept of "theme hooks". Theme hooks define how a
  41. * particular type of data should be rendered. They are registered by modules by
  42. * implementing hook_theme(), which specifies the name of the hook, the input
  43. * "variables" used to provide data and options, and other information. Modules
  44. * implementing hook_theme() also need to provide a default implementation for
  45. * each of their theme hooks, normally in a Twig file, and they may also provide
  46. * preprocessing functions. For example, the core Search module defines a theme
  47. * hook for a search result item in search_theme():
  48. * @code
  49. * return array(
  50. * 'search_result' => array(
  51. * 'variables' => array(
  52. * 'result' => NULL,
  53. * 'plugin_id' => NULL,
  54. * ),
  55. * 'file' => 'search.pages.inc',
  56. * ),
  57. * );
  58. * @endcode
  59. * Given this definition, the template file with the default implementation is
  60. * search-result.html.twig, which can be found in the
  61. * core/modules/search/templates directory, and the variables for rendering are
  62. * the search result and the plugin ID. In addition, there is a function
  63. * template_preprocess_search_result(), located in file search.pages.inc, which
  64. * preprocesses the information from the input variables so that it can be
  65. * rendered by the Twig template; the processed variables that the Twig template
  66. * receives are documented in the header of the default Twig template file.
  67. *
  68. * hook_theme() implementations can also specify that a theme hook
  69. * implementation is a theme function, but that is uncommon and not recommended.
  70. * Note that while Twig templates will auto-escape variables, theme functions
  71. * must explicitly escape any variables by using theme_render_and_autoescape().
  72. * Failure to do so is likely to result in security vulnerabilities. Theme
  73. * functions are deprecated in Drupal 8.0.x and will be removed before
  74. * Drupal 9.0.x. Use Twig templates instead.
  75. *
  76. * @section sec_overriding_theme_hooks Overriding Theme Hooks
  77. * Themes may register new theme hooks within a hook_theme() implementation, but
  78. * it is more common for themes to override default implementations provided by
  79. * modules than to register entirely new theme hooks. Themes can override a
  80. * default implementation by creating a template file with the same name as the
  81. * default implementation; for example, to override the display of search
  82. * results, a theme would add a file called search-result.html.twig to its
  83. * templates directory. A good starting point for doing this is normally to
  84. * copy the default implementation template, and then modifying it as desired.
  85. *
  86. * In the uncommon case that a theme hook uses a theme function instead of a
  87. * template file, a module would provide a default implementation function
  88. * called theme_HOOK, where HOOK is the name of the theme hook (for example,
  89. * theme_search_result() would be the name of the function for search result
  90. * theming). In this case, a theme can override the default implementation by
  91. * defining a function called THEME_HOOK() in its THEME.theme file, where THEME
  92. * is the machine name of the theme (for example, 'bartik' is the machine name
  93. * of the core Bartik theme, and it would define a function called
  94. * bartik_search_result() in the bartik.theme file, if the search_result hook
  95. * implementation was a function instead of a template). Normally, copying the
  96. * default function is again a good starting point for overriding its behavior.
  97. * Again, note that theme functions (unlike templates) must explicitly escape
  98. * variables using theme_render_and_autoescape() or risk security
  99. * vulnerabilities. Theme functions are deprecated in Drupal 8.0.x and will be
  100. * removed before Drupal 9.0.x. Use Twig templates instead.
  101. *
  102. * @section sec_preprocess_templates Preprocessing for Template Files
  103. * If the theme implementation is a template file, several functions are called
  104. * before the template file is invoked to modify the variables that are passed
  105. * to the template. These make up the "preprocessing" phase, and are executed
  106. * (if they exist), in the following order (note that in the following list,
  107. * HOOK indicates the hook being called or a less specific hook. For example, if
  108. * '#theme' => 'node__article' is called, hook is node__article and node. MODULE
  109. * indicates a module name, THEME indicates a theme name, and ENGINE indicates a
  110. * theme engine name). Modules, themes, and theme engines can provide these
  111. * functions to modify how the data is preprocessed, before it is passed to the
  112. * theme template:
  113. * - template_preprocess(&$variables, $hook): Creates a default set of variables
  114. * for all theme hooks with template implementations. Provided by Drupal Core.
  115. * - template_preprocess_HOOK(&$variables): Should be implemented by the module
  116. * that registers the theme hook, to set up default variables.
  117. * - MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all
  118. * implementing modules.
  119. * - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on
  120. * all implementing modules, so that modules that didn't define the theme hook
  121. * can alter the variables.
  122. * - ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to
  123. * set necessary variables for all theme hooks with template implementations.
  124. * - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set
  125. * necessary variables for the particular theme hook.
  126. * - THEME_preprocess(&$variables, $hook): Allows the theme to set necessary
  127. * variables for all theme hooks with template implementations.
  128. * - THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary
  129. * variables specific to the particular theme hook.
  130. *
  131. * @section sec_preprocess_functions Preprocessing for Theme Functions
  132. * If the theming implementation is a function, only the theme-hook-specific
  133. * preprocess functions (the ones ending in _HOOK) are called from the list
  134. * above. This is because theme hooks with function implementations need to be
  135. * fast, and calling the non-theme-hook-specific preprocess functions for them
  136. * would incur a noticeable performance penalty.
  137. *
  138. * @section sec_suggestions Theme hook suggestions
  139. * In some cases, instead of calling the base theme hook implementation (either
  140. * the default provided by the module that defined the hook, or the override
  141. * provided by the theme), the theme system will instead look for "suggestions"
  142. * of other hook names to look for. Suggestions can be specified in several
  143. * ways:
  144. * - In a render array, the '#theme' property (which gives the name of the hook
  145. * to use) can be an array of theme hook names instead of a single hook name.
  146. * In this case, the render system will look first for the highest-priority
  147. * hook name, and if no implementation is found, look for the second, and so
  148. * on. Note that the highest-priority suggestion is at the end of the array.
  149. * - In a render array, the '#theme' property can be set to the name of a hook
  150. * with a '__SUGGESTION' suffix. For example, in search results theming, the
  151. * hook 'item_list__search_results' is given. In this case, the render system
  152. * will look for theme templates called item-list--search-results.html.twig,
  153. * which would only be used for rendering item lists containing search
  154. * results, and if this template is not found, it will fall back to using the
  155. * base item-list.html.twig template. This type of suggestion can also be
  156. * combined with providing an array of theme hook names as described above.
  157. * - A module can implement hook_theme_suggestions_HOOK(). This allows the
  158. * module that defines the theme template to dynamically return an array
  159. * containing specific theme hook names (presumably with '__' suffixes as
  160. * defined above) to use as suggestions. For example, the Search module
  161. * does this in search_theme_suggestions_search_result() to suggest
  162. * search_result__PLUGIN as the theme hook for search result items, where
  163. * PLUGIN is the machine name of the particular search plugin type that was
  164. * used for the search (such as node_search or user_search).
  165. *
  166. * For further information on overriding theme hooks see
  167. * https://www.drupal.org/node/2186401
  168. *
  169. * @section sec_alternate_suggestions Altering theme hook suggestions
  170. * Modules can also alter the theme suggestions provided using the mechanisms
  171. * of the previous section. There are two hooks for this: the
  172. * theme-hook-specific hook_theme_suggestions_HOOK_alter() and the generic
  173. * hook_theme_suggestions_alter(). These hooks get the current list of
  174. * suggestions as input, and can change this array (adding suggestions and
  175. * removing them).
  176. *
  177. * @section assets Assets
  178. * We can distinguish between three types of assets:
  179. * - Unconditional page-level assets (loaded on all pages where the theme is in
  180. * use): these are defined in the theme's *.info.yml file.
  181. * - Conditional page-level assets (loaded on all pages where the theme is in
  182. * use and a certain condition is met): these are attached in
  183. * hook_page_attachments_alter(), e.g.:
  184. * @code
  185. * function THEME_page_attachments_alter(array &$page) {
  186. * if ($some_condition) {
  187. * $page['#attached']['library'][] = 'mytheme/something';
  188. * }
  189. * }
  190. * @endcode
  191. * - Template-specific assets (loaded on all pages where a specific template is
  192. * in use): these can be added by in preprocessing functions, using @code
  193. * $variables['#attached'] @endcode, e.g.:
  194. * @code
  195. * function THEME_preprocess_menu_local_action(array &$variables) {
  196. * // We require Modernizr's touch test for button styling.
  197. * $variables['#attached']['library'][] = 'core/modernizr';
  198. * }
  199. * @endcode
  200. *
  201. * @see hooks
  202. * @see callbacks
  203. * @see theme_render
  204. *
  205. * @}
  206. */
  207. /**
  208. * @defgroup theme_render Render API overview
  209. * @{
  210. * Overview of the Theme system and Render API.
  211. *
  212. * The main purpose of Drupal's Theme system is to give themes complete control
  213. * over the appearance of the site, which includes the markup returned from HTTP
  214. * requests and the CSS files used to style that markup. In order to ensure that
  215. * a theme can completely customize the markup, module developers should avoid
  216. * directly writing HTML markup for pages, blocks, and other user-visible output
  217. * in their modules, and instead return structured "render arrays" (see
  218. * @ref arrays below). Doing this also increases usability, by ensuring that the
  219. * markup used for similar functionality on different areas of the site is the
  220. * same, which gives users fewer user interface patterns to learn.
  221. *
  222. * For further information on the Theme and Render APIs, see:
  223. * - https://www.drupal.org/documentation/theme
  224. * - https://www.drupal.org/developing/api/8/render
  225. * - https://www.drupal.org/node/722174
  226. * - https://www.drupal.org/node/933976
  227. * - https://www.drupal.org/node/930760
  228. *
  229. * @todo Check these links. Some are for Drupal 7, and might need updates for
  230. * Drupal 8.
  231. *
  232. * @section arrays Render arrays
  233. * The core structure of the Render API is the render array, which is a
  234. * hierarchical associative array containing data to be rendered and properties
  235. * describing how the data should be rendered. A render array that is returned
  236. * by a function to specify markup to be sent to the web browser or other
  237. * services will eventually be rendered by a call to drupal_render(), which will
  238. * recurse through the render array hierarchy if appropriate, making calls into
  239. * the theme system to do the actual rendering. If a function or method actually
  240. * needs to return rendered output rather than a render array, the best practice
  241. * would be to create a render array, render it by calling drupal_render(), and
  242. * return that result, rather than writing the markup directly. See the
  243. * documentation of drupal_render() for more details of the rendering process.
  244. *
  245. * Each level in the hierarchy of a render array (including the outermost array)
  246. * has one or more array elements. Array elements whose names start with '#' are
  247. * known as "properties", and the array elements with other names are "children"
  248. * (constituting the next level of the hierarchy); the names of children are
  249. * flexible, while property names are specific to the Render API and the
  250. * particular type of data being rendered. A special case of render arrays is a
  251. * form array, which specifies the form elements for an HTML form; see the
  252. * @link form_api Form generation topic @endlink for more information on forms.
  253. *
  254. * Render arrays (at any level of the hierarchy) will usually have one of the
  255. * following properties defined:
  256. * - #type: Specifies that the array contains data and options for a particular
  257. * type of "render element" (for example, 'form', for an HTML form;
  258. * 'textfield', 'submit', for HTML form element types; 'table', for a table
  259. * with rows, columns, and headers). See @ref elements below for more on
  260. * render element types.
  261. * - #theme: Specifies that the array contains data to be themed by a particular
  262. * theme hook. Modules define theme hooks by implementing hook_theme(), which
  263. * specifies the input "variables" used to provide data and options; if a
  264. * hook_theme() implementation specifies variable 'foo', then in a render
  265. * array, you would provide this data using property '#foo'. Modules
  266. * implementing hook_theme() also need to provide a default implementation for
  267. * each of their theme hooks, normally in a Twig file. For more information
  268. * and to discover available theme hooks, see the documentation of
  269. * hook_theme() and the
  270. * @link themeable Default theme implementations topic. @endlink
  271. * - #markup: Specifies that the array provides HTML markup directly. Unless
  272. * the markup is very simple, such as an explanation in a paragraph tag, it
  273. * is normally preferable to use #theme or #type instead, so that the theme
  274. * can customize the markup. Note that the value is passed through
  275. * \Drupal\Component\Utility\Xss::filterAdmin(), which strips known XSS
  276. * vectors while allowing a permissive list of HTML tags that are not XSS
  277. * vectors. (For example, <script> and <style> are not allowed.) See
  278. * \Drupal\Component\Utility\Xss::$adminTags for the list of allowed tags. If
  279. * your markup needs any of the tags not in this whitelist, then you can
  280. * implement a theme hook and/or an asset library. Alternatively, you can use
  281. * the key #allowed_tags to alter which tags are filtered.
  282. * - #plain_text: Specifies that the array provides text that needs to be
  283. * escaped. This value takes precedence over #markup.
  284. * - #allowed_tags: If #markup is supplied, this can be used to change which
  285. * tags are allowed in the markup. The value is an array of tags that
  286. * Xss::filter() would accept. If #plain_text is set, this value is ignored.
  287. *
  288. * Usage example:
  289. * @code
  290. * $output['admin_filtered_string'] = [
  291. * '#markup' => '<em>This is filtered using the admin tag list</em>',
  292. * ];
  293. * $output['filtered_string'] = [
  294. * '#markup' => '<video><source src="v.webm" type="video/webm"></video>',
  295. * '#allowed_tags' => ['video', 'source'],
  296. * ];
  297. * $output['escaped_string'] = [
  298. * '#plain_text' => '<em>This is escaped</em>',
  299. * ];
  300. * @endcode
  301. *
  302. * @see core.libraries.yml
  303. * @see hook_theme()
  304. *
  305. * JavaScript and CSS assets are specified in the render array using the
  306. * #attached property (see @ref sec_attached).
  307. *
  308. * @section elements Render elements
  309. * Render elements are defined by Drupal core and modules. The primary way to
  310. * define a render element is to create a render element plugin. There are
  311. * two types of render element plugins:
  312. * - Generic elements: Generic render element plugins implement
  313. * \Drupal\Core\Render\Element\ElementInterface, are annotated with
  314. * \Drupal\Core\Render\Annotation\RenderElement annotation, go in plugin
  315. * namespace Element, and generally extend the
  316. * \Drupal\Core\Render\Element\RenderElement base class.
  317. * - Form input elements: Render elements representing form input elements
  318. * implement \Drupal\Core\Render\Element\FormElementInterface, are annotated
  319. * with \Drupal\Core\Render\Annotation\FormElement annotation, go in plugin
  320. * namespace Element, and generally extend the
  321. * \Drupal\Core\Render\Element\FormElement base class.
  322. * See the @link plugin_api Plugin API topic @endlink for general information
  323. * on plugins. You can search for classes with the RenderElement or FormElement
  324. * annotation to discover what render elements are available. API reference
  325. * sites (such as https://api.drupal.org) generate lists of all existing
  326. * elements from these classes. Look for the Elements link in the API Navigation
  327. * block.
  328. *
  329. * Modules can define render elements by defining an element plugin.
  330. *
  331. * @section sec_caching Caching
  332. * The Drupal rendering process has the ability to cache rendered output at any
  333. * level in a render array hierarchy. This allows expensive calculations to be
  334. * done infrequently, and speeds up page loading. See the
  335. * @link cache Cache API topic @endlink for general information about the cache
  336. * system.
  337. *
  338. * In order to make caching possible, the following information needs to be
  339. * present:
  340. * - Cache keys: Identifiers for cacheable portions of render arrays. These
  341. * should be created and added for portions of a render array that
  342. * involve expensive calculations in the rendering process.
  343. * - Cache contexts: Contexts that may affect rendering, such as user role and
  344. * language. When no context is specified, it means that the render array
  345. * does not vary by any context.
  346. * - Cache tags: Tags for data that rendering depends on, such as for
  347. * individual nodes or user accounts, so that when these change the cache
  348. * can be automatically invalidated. If the data consists of entities, you
  349. * can use \Drupal\Core\Entity\EntityInterface::getCacheTags() to generate
  350. * appropriate tags; configuration objects have a similar method.
  351. * - Cache max-age: The maximum duration for which a render array may be cached.
  352. * Defaults to \Drupal\Core\Cache\Cache::PERMANENT (permanently cacheable).
  353. *
  354. * Cache information is provided in the #cache property in a render array. In
  355. * this property, always supply the cache contexts, tags, and max-age if a
  356. * render array varies by context, depends on some modifiable data, or depends
  357. * on information that's only valid for a limited time, respectively. Cache keys
  358. * should only be set on the portions of a render array that should be cached.
  359. * Contexts are automatically replaced with the value for the current request
  360. * (e.g. the current language) and combined with the keys to form a cache ID.
  361. * The cache contexts, tags, and max-age will be propagated up the render array
  362. * hierarchy to determine cacheability for containing render array sections.
  363. *
  364. * Here's an example of what a #cache property might contain:
  365. * @code
  366. * '#cache' => [
  367. * 'keys' => ['entity_view', 'node', $node->id()],
  368. * 'contexts' => ['languages'],
  369. * 'tags' => ['node:' . $node->id()],
  370. * 'max-age' => Cache::PERMANENT,
  371. * ],
  372. * @endcode
  373. *
  374. * At the response level, you'll see X-Drupal-Cache-Contexts and
  375. * X-Drupal-Cache-Tags headers.
  376. *
  377. * See https://www.drupal.org/developing/api/8/render/arrays/cacheability for
  378. * details.
  379. *
  380. * @section sec_attached Attaching libraries in render arrays
  381. * Libraries, JavaScript settings, feeds, HTML <head> tags and HTML <head> links
  382. * are attached to elements using the #attached property. The #attached property
  383. * is an associative array, where the keys are the attachment types and the
  384. * values are the attached data.
  385. *
  386. * The #attached property can also be used to specify HTTP headers and the
  387. * response status code.
  388. *
  389. * The #attached property allows loading of asset libraries (which may contain
  390. * CSS assets, JavaScript assets, and JavaScript setting assets), JavaScript
  391. * settings, feeds, HTML <head> tags and HTML <head> links. Specify an array of
  392. * type => value pairs, where the type (most often 'library' — for libraries, or
  393. * 'drupalSettings' — for JavaScript settings) to attach these response-level
  394. * values. Example:
  395. * @code
  396. * $build['#attached']['library'][] = 'core/jquery';
  397. * $build['#attached']['drupalSettings']['foo'] = 'bar';
  398. * $build['#attached']['feed'][] = [$url, $this->t('Feed title')];
  399. * @endcode
  400. *
  401. * See \Drupal\Core\Render\AttachmentsResponseProcessorInterface for additional
  402. * information.
  403. *
  404. * See \Drupal\Core\Asset\LibraryDiscoveryParser::parseLibraryInfo() for more
  405. * information on how to define libraries.
  406. *
  407. * @section sec_placeholders Placeholders in render arrays
  408. * Render arrays have a placeholder mechanism, which can be used to add data
  409. * into the render array late in the rendering process. This works in a similar
  410. * manner to \Drupal\Component\Render\FormattableMarkup::placeholderFormat(),
  411. * with the text that ends up in the #markup property of the element at the
  412. * end of the rendering process getting substitutions from placeholders that
  413. * are stored in the 'placeholders' element of the #attached property.
  414. *
  415. * For example, after the rest of the rendering process was done, if your
  416. * render array contained:
  417. * @code
  418. * $build['my_element'] = [
  419. * '#attached' => ['placeholders' => ['@foo' => 'replacement']],
  420. * '#markup' => ['Something about @foo'],
  421. * ];
  422. * @endcode
  423. * then #markup would end up containing 'Something about replacement'.
  424. *
  425. * Note that each placeholder value can itself be a render array, which will be
  426. * rendered, and any cache tags generated during rendering will be added to the
  427. * cache tags for the markup.
  428. *
  429. * @section render_pipeline The render pipeline
  430. * The term "render pipeline" refers to the process Drupal uses to take
  431. * information provided by modules and render it into a response. See
  432. * https://www.drupal.org/developing/api/8/render for more details on this
  433. * process. For background on routing concepts, see
  434. * @link routing Routing API. @endlink
  435. *
  436. * There are in fact multiple render pipelines:
  437. * - Drupal always uses the Symfony render pipeline. See
  438. * http://symfony.com/doc/2.7/components/http_kernel/introduction.html
  439. * - Within the Symfony render pipeline, there is a Drupal render pipeline,
  440. * which handles controllers that return render arrays. (Symfony's render
  441. * pipeline only knows how to deal with Response objects; this pipeline
  442. * converts render arrays into Response objects.) These render arrays are
  443. * considered the main content, and can be rendered into multiple formats:
  444. * HTML, Ajax, dialog, and modal. Modules can add support for more formats, by
  445. * implementing a main content renderer, which is a service tagged with
  446. * 'render.main_content_renderer'.
  447. * - Finally, within the HTML main content renderer, there is another pipeline,
  448. * to allow for rendering the page containing the main content in multiple
  449. * ways: no decoration at all (just a page showing the main content) or blocks
  450. * (a page with regions, with blocks positioned in regions around the main
  451. * content). Modules can provide additional options, by implementing a page
  452. * variant, which is a plugin annotated with
  453. * \Drupal\Core\Display\Annotation\PageDisplayVariant.
  454. *
  455. * Routes whose controllers return a \Symfony\Component\HttpFoundation\Response
  456. * object are fully handled by the Symfony render pipeline.
  457. *
  458. * Routes whose controllers return the "main content" as a render array can be
  459. * requested in multiple formats (HTML, JSON, etc.) and/or in a "decorated"
  460. * manner, as described above.
  461. *
  462. * @see themeable
  463. * @see \Symfony\Component\HttpKernel\KernelEvents::VIEW
  464. * @see \Drupal\Core\EventSubscriber\MainContentViewSubscriber
  465. * @see \Drupal\Core\Render\MainContent\MainContentRendererInterface
  466. * @see \Drupal\Core\Render\MainContent\HtmlRenderer
  467. * @see \Drupal\Core\Render\RenderEvents::SELECT_PAGE_DISPLAY_VARIANT
  468. * @see \Drupal\Core\Render\Plugin\DisplayVariant\SimplePageVariant
  469. * @see \Drupal\block\Plugin\DisplayVariant\BlockPageVariant
  470. * @see \Drupal\Core\Render\BareHtmlPageRenderer
  471. *
  472. * @}
  473. */
  474. /**
  475. * @defgroup listing_page_element Page header for Elements page
  476. * @{
  477. * Introduction to form and render elements
  478. *
  479. * Render elements are referenced in render arrays. Render arrays contain data
  480. * to be rendered, along with meta-data and attributes that specify how to
  481. * render the data into markup; see the
  482. * @link theme_render Render API topic @endlink for an overview of render
  483. * arrays and render elements. Form arrays are a subset of render arrays,
  484. * representing HTML forms; form elements are a subset of render elements,
  485. * representing HTML elements for forms. See the
  486. * @link form_api Form API topic @endlink for an overview of forms, form
  487. * processing, and form arrays.
  488. *
  489. * Each form and render element type corresponds to an element plugin class;
  490. * each of them either extends \Drupal\Core\Render\Element\RenderElement
  491. * (render elements) or \Drupal\Core\Render\Element\FormElement (form
  492. * elements). Usage and properties are documented on the individual classes,
  493. * and the two base classes list common properties shared by all render
  494. * elements and the form element subset, respectively.
  495. *
  496. * @see theme_render
  497. * @see form_api
  498. * @see \Drupal\Core\Render\Element\RenderElement
  499. * @see \Drupal\Core\Render\Element\FormElement
  500. *
  501. * @}
  502. */
  503. /**
  504. * @addtogroup hooks
  505. * @{
  506. */
  507. /**
  508. * Allow themes to alter the theme-specific settings form.
  509. *
  510. * With this hook, themes can alter the theme-specific settings form in any way
  511. * allowable by Drupal's Form API, such as adding form elements, changing
  512. * default values and removing form elements. See the Form API documentation on
  513. * api.drupal.org for detailed information.
  514. *
  515. * Note that the base theme's form alterations will be run before any sub-theme
  516. * alterations.
  517. *
  518. * @param $form
  519. * Nested array of form elements that comprise the form.
  520. * @param $form_state
  521. * The current state of the form.
  522. */
  523. function hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state) {
  524. // Add a checkbox to toggle the breadcrumb trail.
  525. $form['toggle_breadcrumb'] = array(
  526. '#type' => 'checkbox',
  527. '#title' => t('Display the breadcrumb'),
  528. '#default_value' => theme_get_setting('features.breadcrumb'),
  529. '#description' => t('Show a trail of links from the homepage to the current page.'),
  530. );
  531. }
  532. /**
  533. * Preprocess theme variables for templates.
  534. *
  535. * This hook allows modules to preprocess theme variables for theme templates.
  536. * It is called for all theme hooks implemented as templates, but not for theme
  537. * hooks implemented as functions. hook_preprocess_HOOK() can be used to
  538. * preprocess variables for a specific theme hook, whether implemented as a
  539. * template or function.
  540. *
  541. * For more detailed information, see the
  542. * @link themeable Theme system overview topic @endlink.
  543. *
  544. * @param $variables
  545. * The variables array (modify in place).
  546. * @param $hook
  547. * The name of the theme hook.
  548. */
  549. function hook_preprocess(&$variables, $hook) {
  550. static $hooks;
  551. // Add contextual links to the variables, if the user has permission.
  552. if (!\Drupal::currentUser()->hasPermission('access contextual links')) {
  553. return;
  554. }
  555. if (!isset($hooks)) {
  556. $hooks = theme_get_registry();
  557. }
  558. // Determine the primary theme function argument.
  559. if (isset($hooks[$hook]['variables'])) {
  560. $keys = array_keys($hooks[$hook]['variables']);
  561. $key = $keys[0];
  562. }
  563. else {
  564. $key = $hooks[$hook]['render element'];
  565. }
  566. if (isset($variables[$key])) {
  567. $element = $variables[$key];
  568. }
  569. if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
  570. $variables['title_suffix']['contextual_links'] = contextual_links_view($element);
  571. if (!empty($variables['title_suffix']['contextual_links'])) {
  572. $variables['attributes']['class'][] = 'contextual-links-region';
  573. }
  574. }
  575. }
  576. /**
  577. * Preprocess theme variables for a specific theme hook.
  578. *
  579. * This hook allows modules to preprocess theme variables for a specific theme
  580. * hook. It should only be used if a module needs to override or add to the
  581. * theme preprocessing for a theme hook it didn't define.
  582. *
  583. * For more detailed information, see the
  584. * @link themeable Theme system overview topic @endlink.
  585. *
  586. * @param $variables
  587. * The variables array (modify in place).
  588. */
  589. function hook_preprocess_HOOK(&$variables) {
  590. // This example is from rdf_preprocess_image(). It adds an RDF attribute
  591. // to the image hook's variables.
  592. $variables['attributes']['typeof'] = array('foaf:Image');
  593. }
  594. /**
  595. * Provides alternate named suggestions for a specific theme hook.
  596. *
  597. * This hook allows modules to provide alternative theme function or template
  598. * name suggestions.
  599. *
  600. * HOOK is the least-specific version of the hook being called. For example, if
  601. * '#theme' => 'node__article' is called, then hook_theme_suggestions_node()
  602. * will be invoked, not hook_theme_suggestions_node__article(). The specific
  603. * hook called (in this case 'node__article') is available in
  604. * $variables['theme_hook_original'].
  605. *
  606. * @todo Add @code sample.
  607. *
  608. * @param array $variables
  609. * An array of variables passed to the theme hook. Note that this hook is
  610. * invoked before any preprocessing.
  611. *
  612. * @return array
  613. * An array of theme suggestions.
  614. *
  615. * @see hook_theme_suggestions_HOOK_alter()
  616. */
  617. function hook_theme_suggestions_HOOK(array $variables) {
  618. $suggestions = array();
  619. $suggestions[] = 'node__' . $variables['elements']['#langcode'];
  620. return $suggestions;
  621. }
  622. /**
  623. * Alters named suggestions for all theme hooks.
  624. *
  625. * This hook is invoked for all theme hooks, if you are targeting a specific
  626. * theme hook it's best to use hook_theme_suggestions_HOOK_alter().
  627. *
  628. * The call order is as follows: all existing suggestion alter functions are
  629. * called for module A, then all for module B, etc., followed by all for any
  630. * base theme(s), and finally for the active theme. The order is
  631. * determined by system weight, then by extension (module or theme) name.
  632. *
  633. * Within each module or theme, suggestion alter hooks are called in the
  634. * following order: first, hook_theme_suggestions_alter(); second,
  635. * hook_theme_suggestions_HOOK_alter(). So, for each module or theme, the more
  636. * general hooks are called first followed by the more specific.
  637. *
  638. * In the following example, we provide an alternative template suggestion to
  639. * node and taxonomy term templates based on the user being logged in.
  640. * @code
  641. * function MYMODULE_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {
  642. * if (\Drupal::currentUser()->isAuthenticated() && in_array($hook, array('node', 'taxonomy_term'))) {
  643. * $suggestions[] = $hook . '__' . 'logged_in';
  644. * }
  645. * }
  646. *
  647. * @endcode
  648. *
  649. * @param array $suggestions
  650. * An array of alternate, more specific names for template files or theme
  651. * functions.
  652. * @param array $variables
  653. * An array of variables passed to the theme hook. Note that this hook is
  654. * invoked before any variable preprocessing.
  655. * @param string $hook
  656. * The base hook name. For example, if '#theme' => 'node__article' is called,
  657. * then $hook will be 'node', not 'node__article'. The specific hook called
  658. * (in this case 'node__article') is available in
  659. * $variables['theme_hook_original'].
  660. *
  661. * @return array
  662. * An array of theme suggestions.
  663. *
  664. * @see hook_theme_suggestions_HOOK_alter()
  665. */
  666. function hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {
  667. // Add an interface-language specific suggestion to all theme hooks.
  668. $suggestions[] = $hook . '__' . \Drupal::languageManager()->getCurrentLanguage()->getId();
  669. }
  670. /**
  671. * Alters named suggestions for a specific theme hook.
  672. *
  673. * This hook allows any module or theme to provide alternative theme function or
  674. * template name suggestions and reorder or remove suggestions provided by
  675. * hook_theme_suggestions_HOOK() or by earlier invocations of this hook.
  676. *
  677. * HOOK is the least-specific version of the hook being called. For example, if
  678. * '#theme' => 'node__article' is called, then node_theme_suggestions_node()
  679. * will be invoked, not node_theme_suggestions_node__article(). The specific
  680. * hook called (in this case 'node__article') is available in
  681. * $variables['theme_hook_original'].
  682. *
  683. * @todo Add @code sample.
  684. *
  685. * @param array $suggestions
  686. * An array of theme suggestions.
  687. * @param array $variables
  688. * An array of variables passed to the theme hook. Note that this hook is
  689. * invoked before any preprocessing.
  690. *
  691. * @see hook_theme_suggestions_alter()
  692. * @see hook_theme_suggestions_HOOK()
  693. */
  694. function hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  695. if (empty($variables['header'])) {
  696. $suggestions[] = 'hookname__' . 'no_header';
  697. }
  698. }
  699. /**
  700. * Respond to themes being installed.
  701. *
  702. * @param array $theme_list
  703. * Array containing the names of the themes being installed.
  704. *
  705. * @see \Drupal\Core\Extension\ThemeHandler::install()
  706. */
  707. function hook_themes_installed($theme_list) {
  708. foreach ($theme_list as $theme) {
  709. block_theme_initialize($theme);
  710. }
  711. }
  712. /**
  713. * Respond to themes being uninstalled.
  714. *
  715. * @param array $theme_list
  716. * Array containing the names of the themes being uninstalled.
  717. *
  718. * @see \Drupal\Core\Extension\ThemeHandler::uninstall()
  719. */
  720. function hook_themes_uninstalled(array $themes) {
  721. // Remove some state entries depending on the theme.
  722. foreach ($themes as $theme) {
  723. \Drupal::state()->delete('example.' . $theme);
  724. }
  725. }
  726. /**
  727. * Declare a template file extension to be used with a theme engine.
  728. *
  729. * This hook is used in a theme engine implementation in the format of
  730. * ENGINE_extension().
  731. *
  732. * @return string
  733. * The file extension the theme engine will recognize.
  734. */
  735. function hook_extension() {
  736. // Extension for template base names in Twig.
  737. return '.html.twig';
  738. }
  739. /**
  740. * Render a template using the theme engine.
  741. *
  742. * @param string $template_file
  743. * The path (relative to the Drupal root directory) to the template to be
  744. * rendered including its extension in the format 'path/to/TEMPLATE_NAME.EXT'.
  745. * @param array $variables
  746. * A keyed array of variables that are available for composing the output. The
  747. * theme engine is responsible for passing all the variables to the template.
  748. * Depending on the code in the template, all or just a subset of the
  749. * variables might be used in the template.
  750. *
  751. * @return string
  752. * The output generated from the template. In most cases this will be a string
  753. * containing HTML markup.
  754. */
  755. function hook_render_template($template_file, $variables) {
  756. $twig_service = \Drupal::service('twig');
  757. return $twig_service->loadTemplate($template_file)->render($variables);
  758. }
  759. /**
  760. * Alter the element type information returned from modules.
  761. *
  762. * A module may implement this hook in order to alter the element type defaults
  763. * defined by a module.
  764. *
  765. * @param array $info
  766. * An associative array with structure identical to that of the return value
  767. * of \Drupal\Core\Render\ElementInfoManagerInterface::getInfo().
  768. *
  769. * @see \Drupal\Core\Render\ElementInfoManager
  770. * @see \Drupal\Core\Render\Element\ElementInterface
  771. */
  772. function hook_element_info_alter(array &$info) {
  773. // Decrease the default size of textfields.
  774. if (isset($info['textfield']['#size'])) {
  775. $info['textfield']['#size'] = 40;
  776. }
  777. }
  778. /**
  779. * Perform necessary alterations to the JavaScript before it is presented on
  780. * the page.
  781. *
  782. * @param $javascript
  783. * An array of all JavaScript being presented on the page.
  784. * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  785. * The assets attached to the current response.
  786. *
  787. * @see drupal_js_defaults()
  788. * @see \Drupal\Core\Asset\AssetResolver
  789. */
  790. function hook_js_alter(&$javascript, \Drupal\Core\Asset\AttachedAssetsInterface $assets) {
  791. // Swap out jQuery to use an updated version of the library.
  792. $javascript['core/assets/vendor/jquery/jquery.min.js']['data'] = drupal_get_path('module', 'jquery_update') . '/jquery.js';
  793. }
  794. /**
  795. * Add dynamic library definitions.
  796. *
  797. * Modules may implement this hook to add dynamic library definitions. Static
  798. * libraries, which do not depend on any runtime information, should be declared
  799. * in a modulename.libraries.yml file instead.
  800. *
  801. * @return array[]
  802. * An array of library definitions to register, keyed by library ID. The
  803. * library ID will be prefixed with the module name automatically.
  804. *
  805. * @see core.libraries.yml
  806. * @see hook_library_info_alter()
  807. */
  808. function hook_library_info_build() {
  809. $libraries = [];
  810. // Add a library whose information changes depending on certain conditions.
  811. $libraries['mymodule.zombie'] = [
  812. 'dependencies' => [
  813. 'core/backbone',
  814. ],
  815. ];
  816. if (Drupal::moduleHandler()->moduleExists('minifyzombies')) {
  817. $libraries['mymodule.zombie'] += [
  818. 'js' => [
  819. 'mymodule.zombie.min.js' => [],
  820. ],
  821. 'css' => [
  822. 'base' => [
  823. 'mymodule.zombie.min.css' => [],
  824. ],
  825. ],
  826. ];
  827. }
  828. else {
  829. $libraries['mymodule.zombie'] += [
  830. 'js' => [
  831. 'mymodule.zombie.js' => [],
  832. ],
  833. 'css' => [
  834. 'base' => [
  835. 'mymodule.zombie.css' => [],
  836. ],
  837. ],
  838. ];
  839. }
  840. // Add a library only if a certain condition is met. If code wants to
  841. // integrate with this library it is safe to (try to) load it unconditionally
  842. // without reproducing this check. If the library definition does not exist
  843. // the library (of course) not be loaded but no notices or errors will be
  844. // triggered.
  845. if (Drupal::moduleHandler()->moduleExists('vampirize')) {
  846. $libraries['mymodule.vampire'] = [
  847. 'js' => [
  848. 'js/vampire.js' => [],
  849. ],
  850. 'css' => [
  851. 'base' => [
  852. 'css/vampire.css',
  853. ],
  854. ],
  855. 'dependencies' => [
  856. 'core/jquery',
  857. ],
  858. ];
  859. }
  860. return $libraries;
  861. }
  862. /**
  863. * Modify the JavaScript settings (drupalSettings).
  864. *
  865. * @param array &$settings
  866. * An array of all JavaScript settings (drupalSettings) being presented on the
  867. * page.
  868. * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  869. * The assets attached to the current response.
  870. *
  871. * @see \Drupal\Core\Asset\AssetResolver
  872. *
  873. * The results of this hook are cached, however modules may use
  874. * hook_js_settings_alter() to dynamically alter settings.
  875. */
  876. function hook_js_settings_build(array &$settings, \Drupal\Core\Asset\AttachedAssetsInterface $assets) {
  877. // Manipulate settings.
  878. if (isset($settings['dialog'])) {
  879. $settings['dialog']['autoResize'] = FALSE;
  880. }
  881. }
  882. /**
  883. * Perform necessary alterations to the JavaScript settings (drupalSettings).
  884. *
  885. * @param array &$settings
  886. * An array of all JavaScript settings (drupalSettings) being presented on the
  887. * page.
  888. * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  889. * The assets attached to the current response.
  890. *
  891. * @see \Drupal\Core\Asset\AssetResolver
  892. */
  893. function hook_js_settings_alter(array &$settings, \Drupal\Core\Asset\AttachedAssetsInterface $assets) {
  894. // Add settings.
  895. $settings['user']['uid'] = \Drupal::currentUser();
  896. // Manipulate settings.
  897. if (isset($settings['dialog'])) {
  898. $settings['dialog']['autoResize'] = FALSE;
  899. }
  900. }
  901. /**
  902. * Alter libraries provided by an extension.
  903. *
  904. * Allows modules and themes to change libraries' definitions; mostly used to
  905. * update a library to a newer version, while ensuring backward compatibility.
  906. * In general, such manipulations should only be done to extend the library's
  907. * functionality in a backward-compatible way, to avoid breaking other modules
  908. * and themes that may be using the library.
  909. *
  910. * @param array $libraries
  911. * An associative array of libraries registered by $extension. Keyed by
  912. * internal library name and passed by reference.
  913. * @param string $extension
  914. * Can either be 'core' or the machine name of the extension that registered
  915. * the libraries.
  916. *
  917. * @see \Drupal\Core\Asset\LibraryDiscoveryParser::parseLibraryInfo()
  918. */
  919. function hook_library_info_alter(&$libraries, $extension) {
  920. // Update Farbtastic to version 2.0.
  921. if ($extension == 'core' && isset($libraries['jquery.farbtastic'])) {
  922. // Verify existing version is older than the one we are updating to.
  923. if (version_compare($libraries['jquery.farbtastic']['version'], '2.0', '<')) {
  924. // Update the existing Farbtastic to version 2.0.
  925. $libraries['jquery.farbtastic']['version'] = '2.0';
  926. // To accurately replace library files, the order of files and the options
  927. // of each file have to be retained; e.g., like this:
  928. $old_path = 'assets/vendor/farbtastic';
  929. // Since the replaced library files are no longer located in a directory
  930. // relative to the original extension, specify an absolute path (relative
  931. // to DRUPAL_ROOT / base_path()) to the new location.
  932. $new_path = '/' . drupal_get_path('module', 'farbtastic_update') . '/js';
  933. $new_js = array();
  934. $replacements = array(
  935. $old_path . '/farbtastic.js' => $new_path . '/farbtastic-2.0.js',
  936. );
  937. foreach ($libraries['jquery.farbtastic']['js'] as $source => $options) {
  938. if (isset($replacements[$source])) {
  939. $new_js[$replacements[$source]] = $options;
  940. }
  941. else {
  942. $new_js[$source] = $options;
  943. }
  944. }
  945. $libraries['jquery.farbtastic']['js'] = $new_js;
  946. }
  947. }
  948. }
  949. /**
  950. * Alter CSS files before they are output on the page.
  951. *
  952. * @param $css
  953. * An array of all CSS items (files and inline CSS) being requested on the page.
  954. * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  955. * The assets attached to the current response.
  956. *
  957. * @see Drupal\Core\Asset\LibraryResolverInterface::getCssAssets()
  958. */
  959. function hook_css_alter(&$css, \Drupal\Core\Asset\AttachedAssetsInterface $assets) {
  960. // Remove defaults.css file.
  961. unset($css[drupal_get_path('module', 'system') . '/defaults.css']);
  962. }
  963. /**
  964. * Add attachments (typically assets) to a page before it is rendered.
  965. *
  966. * Use this hook when you want to conditionally add attachments to a page.
  967. *
  968. * If you want to alter the attachments added by other modules or if your module
  969. * depends on the elements of other modules, use hook_page_attachments_alter()
  970. * instead, which runs after this hook.
  971. *
  972. * If you try to add anything but #attached and #cache to the array, an
  973. * exception is thrown.
  974. *
  975. * @param array &$attachments
  976. * An array that you can add attachments to.
  977. *
  978. * @see hook_page_attachments_alter()
  979. */
  980. function hook_page_attachments(array &$attachments) {
  981. // Unconditionally attach an asset to the page.
  982. $attachments['#attached']['library'][] = 'core/domready';
  983. // Conditionally attach an asset to the page.
  984. if (!\Drupal::currentUser()->hasPermission('may pet kittens')) {
  985. $attachments['#attached']['library'][] = 'core/jquery';
  986. }
  987. }
  988. /**
  989. * Alter attachments (typically assets) to a page before it is rendered.
  990. *
  991. * Use this hook when you want to remove or alter attachments on the page, or
  992. * add attachments to the page that depend on another module's attachments (this
  993. * hook runs after hook_page_attachments().
  994. *
  995. * If you try to add anything but #attached and #cache to the array, an
  996. * exception is thrown.
  997. *
  998. * @param array &$attachments
  999. * Array of all attachments provided by hook_page_attachments() implementations.
  1000. *
  1001. * @see hook_page_attachments()
  1002. */
  1003. function hook_page_attachments_alter(array &$attachments) {
  1004. // Conditionally remove an asset.
  1005. if (in_array('core/jquery', $attachments['#attached']['library'])) {
  1006. $index = array_search('core/jquery', $attachments['#attached']['library']);
  1007. unset($attachments['#attached']['library'][$index]);
  1008. }
  1009. }
  1010. /**
  1011. * Add a renderable array to the top of the page.
  1012. *
  1013. * @param array $page_top
  1014. * A renderable array representing the top of the page.
  1015. */
  1016. function hook_page_top(array &$page_top) {
  1017. $page_top['mymodule'] = ['#markup' => 'This is the top.'];
  1018. }
  1019. /**
  1020. * Add a renderable array to the bottom of the page.
  1021. *
  1022. * @param array $page_bottom
  1023. * A renderable array representing the bottom of the page.
  1024. */
  1025. function hook_page_bottom(array &$page_bottom) {
  1026. $page_bottom['mymodule'] = ['#markup' => 'This is the bottom.'];
  1027. }
  1028. /**
  1029. * Register a module or theme's theme implementations.
  1030. *
  1031. * The implementations declared by this hook specify how a particular render
  1032. * array is to be rendered as HTML.
  1033. *
  1034. * @param array $existing
  1035. * An array of existing implementations that may be used for override
  1036. * purposes. This is primarily useful for themes that may wish to examine
  1037. * existing implementations to extract data (such as arguments) so that
  1038. * it may properly register its own, higher priority implementations.
  1039. * @param $type
  1040. * Whether a theme, module, etc. is being processed. This is primarily useful
  1041. * so that themes tell if they are the actual theme being called or a parent
  1042. * theme. May be one of:
  1043. * - 'module': A module is being checked for theme implementations.
  1044. * - 'base_theme_engine': A theme engine is being checked for a theme that is
  1045. * a parent of the actual theme being used.
  1046. * - 'theme_engine': A theme engine is being checked for the actual theme
  1047. * being used.
  1048. * - 'base_theme': A base theme is being checked for theme implementations.
  1049. * - 'theme': The actual theme in use is being checked.
  1050. * @param $theme
  1051. * The actual name of theme, module, etc. that is being being processed.
  1052. * @param $path
  1053. * The directory path of the theme or module, so that it doesn't need to be
  1054. * looked up.
  1055. *
  1056. * @return array
  1057. * An associative array of information about theme implementations. The keys
  1058. * on the outer array are known as "theme hooks". For theme suggestions,
  1059. * instead of the array key being the base theme hook, the key is a theme
  1060. * suggestion name with the format 'base_hook_name__sub_hook_name'.
  1061. * For render elements, the key is the machine name of the render element.
  1062. * The array values are themselves arrays containing information about the
  1063. * theme hook and its implementation. Each information array must contain
  1064. * either a 'variables' element (for using a #theme element) or a
  1065. * 'render element' element (for render elements), but not both.
  1066. * The following elements may be part of each information array:
  1067. * - variables: Only used for #theme in render array: an array of variables,
  1068. * where the array keys are the names of the variables, and the array
  1069. * values are the default values if they are not given in the render array.
  1070. * Template implementations receive each array key as a variable in the
  1071. * template file (so they must be legal PHP/Twig variable names). Function
  1072. * implementations are passed the variables in a single $variables function
  1073. * argument. If you are using these variables in a render array, prefix the
  1074. * variable names defined here with a #.
  1075. * - render element: Used for render element items only: the name of the
  1076. * renderable element or element tree to pass to the theme function. This
  1077. * name is used as the name of the variable that holds the renderable
  1078. * element or tree in preprocess and process functions.
  1079. * - file: The file the implementation resides in. This file will be included
  1080. * prior to the theme being rendered, to make sure that the function or
  1081. * preprocess function (as needed) is actually loaded.
  1082. * - path: Override the path of the file to be used. Ordinarily the module or
  1083. * theme path will be used, but if the file will not be in the default
  1084. * path, include it here. This path should be relative to the Drupal root
  1085. * directory.
  1086. * - template: If specified, the theme implementation is a template file, and
  1087. * this is the template name. Do not add 'html.twig' on the end of the
  1088. * template name. The extension will be added automatically by the default
  1089. * rendering engine (which is Twig.) If 'path' is specified, 'template'
  1090. * should also be specified. If neither 'template' nor 'function' are
  1091. * specified, a default template name will be assumed. For example, if a
  1092. * module registers the 'search_result' theme hook, 'search-result' will be
  1093. * assigned as its template name.
  1094. * - function: (deprecated in Drupal 8.0.x, will be removed in Drupal 9.0.x)
  1095. * If specified, this will be the function name to invoke for this
  1096. * implementation. If neither 'template' nor 'function' are specified, a
  1097. * default template name will be assumed. See above for more details.
  1098. * - base hook: Used for theme suggestions only: the base theme hook name.
  1099. * Instead of this suggestion's implementation being used directly, the base
  1100. * hook will be invoked with this implementation as its first suggestion.
  1101. * The base hook's files will be included and the base hook's preprocess
  1102. * functions will be called in place of any suggestion's preprocess
  1103. * functions. If an implementation of hook_theme_suggestions_HOOK() (where
  1104. * HOOK is the base hook) changes the suggestion order, a different
  1105. * suggestion may be used in place of this suggestion. If after
  1106. * hook_theme_suggestions_HOOK() this suggestion remains the first
  1107. * suggestion, then this suggestion's function or template will be used to
  1108. * generate the rendered output.
  1109. * - pattern: A regular expression pattern to be used to allow this theme
  1110. * implementation to have a dynamic name. The convention is to use __ to
  1111. * differentiate the dynamic portion of the theme. For example, to allow
  1112. * forums to be themed individually, the pattern might be: 'forum__'. Then,
  1113. * when the forum is rendered, following render array can be used:
  1114. * @code
  1115. * $render_array = array(
  1116. * '#theme' => array('forum__' . $tid, 'forum'),
  1117. * '#forum' => $forum,
  1118. * );
  1119. * @endcode
  1120. * - preprocess functions: A list of functions used to preprocess this data.
  1121. * Ordinarily this won't be used; it's automatically filled in. By default,
  1122. * for a module this will be filled in as template_preprocess_HOOK. For
  1123. * a theme this will be filled in as twig_preprocess and
  1124. * twig_preprocess_HOOK as well as themename_preprocess and
  1125. * themename_preprocess_HOOK.
  1126. * - override preprocess functions: Set to TRUE when a theme does NOT want
  1127. * the standard preprocess functions to run. This can be used to give a
  1128. * theme FULL control over how variables are set. For example, if a theme
  1129. * wants total control over how certain variables in the page.html.twig are
  1130. * set, this can be set to true. Please keep in mind that when this is used
  1131. * by a theme, that theme becomes responsible for making sure necessary
  1132. * variables are set.
  1133. * - type: (automatically derived) Where the theme hook is defined:
  1134. * 'module', 'theme_engine', or 'theme'.
  1135. * - theme path: (automatically derived) The directory path of the theme or
  1136. * module, so that it doesn't need to be looked up.
  1137. *
  1138. * @see themeable
  1139. * @see hook_theme_registry_alter()
  1140. */
  1141. function hook_theme($existing, $type, $theme, $path) {
  1142. return array(
  1143. 'forum_display' => array(
  1144. 'variables' => array('forums' => NULL, 'topics' => NULL, 'parents' => NULL, 'tid' => NULL, 'sortby' => NULL, 'forum_per_page' => NULL),
  1145. ),
  1146. 'forum_list' => array(
  1147. 'variables' => array('forums' => NULL, 'parents' => NULL, 'tid' => NULL),
  1148. ),
  1149. 'forum_icon' => array(
  1150. 'variables' => array('new_posts' => NULL, 'num_posts' => 0, 'comment_mode' => 0, 'sticky' => 0),
  1151. ),
  1152. 'status_report' => array(
  1153. 'render element' => 'requirements',
  1154. 'file' => 'system.admin.inc',
  1155. ),
  1156. );
  1157. }
  1158. /**
  1159. * Alter the theme registry information returned from hook_theme().
  1160. *
  1161. * The theme registry stores information about all available theme hooks,
  1162. * including which callback functions those hooks will call when triggered,
  1163. * what template files are exposed by these hooks, and so on.
  1164. *
  1165. * Note that this hook is only executed as the theme cache is re-built.
  1166. * Changes here will not be visible until the next cache clear.
  1167. *
  1168. * The $theme_registry array is keyed by theme hook name, and contains the
  1169. * information returned from hook_theme(), as well as additional properties
  1170. * added by \Drupal\Core\Theme\Registry::processExtension().
  1171. *
  1172. * For example:
  1173. * @code
  1174. * $theme_registry['block_content_add_list'] = array (
  1175. * 'template' => 'block-content-add-list',
  1176. * 'path' => 'core/themes/seven/templates',
  1177. * 'type' => 'theme_engine',
  1178. * 'theme path' => 'core/themes/seven',
  1179. * 'includes' => array (
  1180. * 0 => 'core/modules/block_content/block_content.pages.inc',
  1181. * ),
  1182. * 'variables' => array (
  1183. * 'content' => NULL,
  1184. * ),
  1185. * 'preprocess functions' => array (
  1186. * 0 => 'template_preprocess',
  1187. * 1 => 'template_preprocess_block_content_add_list',
  1188. * 2 => 'contextual_preprocess',
  1189. * 3 => 'seven_preprocess_block_content_add_list',
  1190. * ),
  1191. * );
  1192. * @endcode
  1193. *
  1194. * @param $theme_registry
  1195. * The entire cache of theme registry information, post-processing.
  1196. *
  1197. * @see hook_theme()
  1198. * @see \Drupal\Core\Theme\Registry::processExtension()
  1199. */
  1200. function hook_theme_registry_alter(&$theme_registry) {
  1201. // Kill the next/previous forum topic navigation links.
  1202. foreach ($theme_registry['forum_topic_navigation']['preprocess functions'] as $key => $value) {
  1203. if ($value == 'template_preprocess_forum_topic_navigation') {
  1204. unset($theme_registry['forum_topic_navigation']['preprocess functions'][$key]);
  1205. }
  1206. }
  1207. }
  1208. /**
  1209. * Alter the default, hook-independent variables for all templates.
  1210. *
  1211. * Allows modules to provide additional default template variables or manipulate
  1212. * existing. This hook is invoked from template_preprocess() after basic default
  1213. * template variables have been set up and before the next template preprocess
  1214. * function is invoked.
  1215. *
  1216. * Note that the default template variables are statically cached within a
  1217. * request. When adding a template variable that depends on other context, it is
  1218. * your responsibility to appropriately reset the static cache in
  1219. * template_preprocess() when needed:
  1220. * @code
  1221. * drupal_static_reset('template_preprocess');
  1222. * @endcode
  1223. *
  1224. * See user_template_preprocess_default_variables_alter() for an example.
  1225. *
  1226. * @param array $variables
  1227. * An associative array of default template variables, as set up by
  1228. * _template_preprocess_default_variables(). Passed by reference.
  1229. *
  1230. * @see template_preprocess()
  1231. * @see _template_preprocess_default_variables()
  1232. */
  1233. function hook_template_preprocess_default_variables_alter(&$variables) {
  1234. $variables['is_admin'] = \Drupal::currentUser()->hasPermission('access administration pages');
  1235. }
  1236. /**
  1237. * @} End of "addtogroup hooks".
  1238. */

Functions

Namesort descending Description
hook_css_alter Alter CSS files before they are output on the page.
hook_element_info_alter Alter the element type information returned from modules.
hook_extension Declare a template file extension to be used with a theme engine.
hook_form_system_theme_settings_alter Allow themes to alter the theme-specific settings form.
hook_js_alter Perform necessary alterations to the JavaScript before it is presented on the page.
hook_js_settings_alter Perform necessary alterations to the JavaScript settings (drupalSettings).
hook_js_settings_build Modify the JavaScript settings (drupalSettings).
hook_library_info_alter Alter libraries provided by an extension.
hook_library_info_build Add dynamic library definitions.
hook_page_attachments Add attachments (typically assets) to a page before it is rendered.
hook_page_attachments_alter Alter attachments (typically assets) to a page before it is rendered.
hook_page_bottom Add a renderable array to the bottom of the page.
hook_page_top Add a renderable array to the top of the page.
hook_preprocess Preprocess theme variables for templates.
hook_preprocess_HOOK Preprocess theme variables for a specific theme hook.
hook_render_template Render a template using the theme engine.
hook_template_preprocess_default_variables_alter Alter the default, hook-independent variables for all templates.
hook_theme Register a module or theme's theme implementations.
hook_themes_installed Respond to themes being installed.
hook_themes_uninstalled Respond to themes being uninstalled.
hook_theme_registry_alter Alter the theme registry information returned from hook_theme().
hook_theme_suggestions_alter Alters named suggestions for all theme hooks.
hook_theme_suggestions_HOOK Provides alternate named suggestions for a specific theme hook.
hook_theme_suggestions_HOOK_alter Alters named suggestions for a specific theme hook.