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