1<?php
2
3/**
4 * @defgroup themeable Default theme implementations
5 * @{
6 * Functions and templates for the user interface to be implemented by themes.
7 *
8 * Drupal's presentation layer is a pluggable system known as the theme
9 * layer. Each theme can take control over most of Drupal's output, and
10 * has complete control over the CSS.
11 *
12 * Inside Drupal, the theme layer is utilized by the use of the theme()
13 * function, which is passed the name of a component (the theme hook)
14 * and an array of variables. For example,
15 * theme('table', array('header' => $header, 'rows' => $rows));
16 * Additionally, the theme() function can take an array of theme
17 * hooks, which can be used to provide 'fallback' implementations to
18 * allow for more specific control of output. For example, the function:
19 * theme(array('table__foo', 'table'), $variables) would look to see if
20 * 'table__foo' is registered anywhere; if it is not, it would 'fall back'
21 * to the generic 'table' implementation. This can be used to attach specific
22 * theme functions to named objects, allowing the themer more control over
23 * specific types of output.
24 *
25 * As of Drupal 6, every theme hook is required to be registered by the
26 * module that owns it, so that Drupal can tell what to do with it and
27 * to make it simple for themes to identify and override the behavior
28 * for these calls.
29 *
30 * The theme hooks are registered via hook_theme(), which returns an
31 * array of arrays with information about the hook. It describes the
32 * arguments the function or template will need, and provides
33 * defaults for the template in case they are not filled in. If the default
34 * implementation is a function, by convention it is named theme_HOOK().
35 *
36 * Each module should provide a default implementation for theme_hooks that
37 * it registers. This implementation may be either a function or a template;
38 * if it is a function it must be specified via hook_theme(). By convention,
39 * default implementations of theme hooks are named theme_HOOK. Default
40 * template implementations are stored in the module directory.
41 *
42 * Drupal's default template renderer is a simple PHP parsing engine that
43 * includes the template and stores the output. Drupal's theme engines
44 * can provide alternate template engines, such as XTemplate, Smarty and
45 * PHPTal. The most common template engine is PHPTemplate (included with
46 * Drupal and implemented in phptemplate.engine, which uses Drupal's default
47 * template renderer.
48 *
49 * In order to create theme-specific implementations of these hooks, themes can
50 * implement their own version of theme hooks, either as functions or templates.
51 * These implementations will be used instead of the default implementation. If
52 * using a pure .theme without an engine, the .theme is required to implement
53 * its own version of hook_theme() to tell Drupal what it is implementing;
54 * themes utilizing an engine will have their well-named theming functions
55 * automatically registered for them. While this can vary based upon the theme
56 * engine, the standard set by phptemplate is that theme functions should be
57 * named THEMENAME_HOOK. For example, for Drupal's default theme (Bartik) to
58 * implement the 'table' hook, the phptemplate.engine would find
59 * bartik_table().
60 *
61 * The theme system is described and defined in theme.inc.
62 *
63 * @see theme()
64 * @see hook_theme()
65 * @see hooks
66 * @see callbacks
67 *
68 * @} End of "defgroup themeable".
69 */
70
71/**
72 * Allow themes to alter the theme-specific settings form.
73 *
74 * With this hook, themes can alter the theme-specific settings form in any way
75 * allowable by Drupal's Form API, such as adding form elements, changing
76 * default values and removing form elements. See the Form API documentation on
77 * api.drupal.org for detailed information.
78 *
79 * Note that the base theme's form alterations will be run before any sub-theme
80 * alterations.
81 *
82 * @param $form
83 *   Nested array of form elements that comprise the form.
84 * @param $form_state
85 *   A keyed array containing the current state of the form.
86 */
87function hook_form_system_theme_settings_alter(&$form, &$form_state) {
88  // Add a checkbox to toggle the breadcrumb trail.
89  $form['toggle_breadcrumb'] = array(
90    '#type' => 'checkbox',
91    '#title' => t('Display the breadcrumb'),
92    '#default_value' => theme_get_setting('toggle_breadcrumb'),
93    '#description'   => t('Show a trail of links from the homepage to the current page.'),
94  );
95}
96
97/**
98 * Preprocess theme variables for templates.
99 *
100 * This hook allows modules to preprocess theme variables for theme templates.
101 * It is called for all theme hooks implemented as templates, but not for theme
102 * hooks implemented as functions. hook_preprocess_HOOK() can be used to
103 * preprocess variables for a specific theme hook, whether implemented as a
104 * template or function.
105 *
106 * For more detailed information, see theme().
107 *
108 * @param $variables
109 *   The variables array (modify in place).
110 * @param $hook
111 *   The name of the theme hook.
112 */
113function hook_preprocess(&$variables, $hook) {
114 static $hooks;
115
116  // Add contextual links to the variables, if the user has permission.
117
118  if (!user_access('access contextual links')) {
119    return;
120  }
121
122  if (!isset($hooks)) {
123    $hooks = theme_get_registry();
124  }
125
126  // Determine the primary theme function argument.
127  if (isset($hooks[$hook]['variables'])) {
128    $keys = array_keys($hooks[$hook]['variables']);
129    $key = $keys[0];
130  }
131  else {
132    $key = $hooks[$hook]['render element'];
133  }
134
135  if (isset($variables[$key])) {
136    $element = $variables[$key];
137  }
138
139  if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
140    $variables['title_suffix']['contextual_links'] = contextual_links_view($element);
141    if (!empty($variables['title_suffix']['contextual_links'])) {
142      $variables['classes_array'][] = 'contextual-links-region';
143    }
144  }
145}
146
147/**
148 * Preprocess theme variables for a specific theme hook.
149 *
150 * This hook allows modules to preprocess theme variables for a specific theme
151 * hook. It should only be used if a module needs to override or add to the
152 * theme preprocessing for a theme hook it didn't define.
153 *
154 * For more detailed information, see theme().
155 *
156 * @param $variables
157 *   The variables array (modify in place).
158 */
159function hook_preprocess_HOOK(&$variables) {
160  // This example is from rdf_preprocess_image(). It adds an RDF attribute
161  // to the image hook's variables.
162  $variables['attributes']['typeof'] = array('foaf:Image');
163}
164
165/**
166 * Process theme variables for templates.
167 *
168 * This hook allows modules to process theme variables for theme templates. It
169 * is called for all theme hooks implemented as templates, but not for theme
170 * hooks implemented as functions. hook_process_HOOK() can be used to process
171 * variables for a specific theme hook, whether implemented as a template or
172 * function.
173 *
174 * For more detailed information, see theme().
175 *
176 * @param $variables
177 *   The variables array (modify in place).
178 * @param $hook
179 *   The name of the theme hook.
180 */
181function hook_process(&$variables, $hook) {
182  // Wraps variables in RDF wrappers.
183  if (!empty($variables['rdf_template_variable_attributes_array'])) {
184    foreach ($variables['rdf_template_variable_attributes_array'] as $variable_name => $attributes) {
185      $context = array(
186        'hook' => $hook,
187        'variable_name' => $variable_name,
188        'variables' => $variables,
189      );
190      $variables[$variable_name] = theme('rdf_template_variable_wrapper', array('content' => $variables[$variable_name], 'attributes' => $attributes, 'context' => $context));
191    }
192  }
193}
194
195/**
196 * Process theme variables for a specific theme hook.
197 *
198 * This hook allows modules to process theme variables for a specific theme
199 * hook. It should only be used if a module needs to override or add to the
200 * theme processing for a theme hook it didn't define.
201 *
202 * For more detailed information, see theme().
203 *
204 * @param $variables
205 *   The variables array (modify in place).
206 */
207function hook_process_HOOK(&$variables) {
208  // @todo There are no use-cases in Drupal core for this hook. Find one from a
209  //   contributed module, or come up with a good example. Coming up with a good
210  //   example might be tough, since the intent is for nearly everything to be
211  //   achievable via preprocess functions, and for process functions to only be
212  //   used when requiring the later execution time.
213}
214
215/**
216 * Respond to themes being enabled.
217 *
218 * @param array $theme_list
219 *   Array containing the names of the themes being enabled.
220 *
221 * @see theme_enable()
222 */
223function hook_themes_enabled($theme_list) {
224  foreach ($theme_list as $theme) {
225    block_theme_initialize($theme);
226  }
227}
228
229/**
230 * Respond to themes being disabled.
231 *
232 * @param array $theme_list
233 *   Array containing the names of the themes being disabled.
234 *
235 * @see theme_disable()
236 */
237function hook_themes_disabled($theme_list) {
238 // Clear all update module caches.
239  _update_cache_clear();
240}
241