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