root / drupal7 / modules / system / theme.api.php @ 6d8023f2
| 1 | 85ad3d82 | Assos Assos | <?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 | */
|
||
| 87 | function 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 | */
|
||
| 113 | function 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 | */
|
||
| 159 | function 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 | */
|
||
| 181 | function 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 | */
|
||
| 207 | function 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 | */
|
||
| 223 | function 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 | */
|
||
| 237 | function hook_themes_disabled($theme_list) { |
||
| 238 | // Clear all update module caches.
|
||
| 239 | _update_cache_clear(); |
||
| 240 | } |