theme.api.php

File

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