danielebarchiesi@0: <?php
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * @defgroup themeable Default theme implementations
danielebarchiesi@0:  * @{
danielebarchiesi@0:  * Functions and templates for the user interface to be implemented by themes.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Drupal's presentation layer is a pluggable system known as the theme
danielebarchiesi@0:  * layer. Each theme can take control over most of Drupal's output, and
danielebarchiesi@0:  * has complete control over the CSS.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Inside Drupal, the theme layer is utilized by the use of the theme()
danielebarchiesi@0:  * function, which is passed the name of a component (the theme hook)
danielebarchiesi@0:  * and an array of variables. For example,
danielebarchiesi@0:  * theme('table', array('header' => $header, 'rows' => $rows));
danielebarchiesi@0:  * Additionally, the theme() function can take an array of theme
danielebarchiesi@0:  * hooks, which can be used to provide 'fallback' implementations to
danielebarchiesi@0:  * allow for more specific control of output. For example, the function:
danielebarchiesi@0:  * theme(array('table__foo', 'table'), $variables) would look to see if
danielebarchiesi@0:  * 'table__foo' is registered anywhere; if it is not, it would 'fall back'
danielebarchiesi@0:  * to the generic 'table' implementation. This can be used to attach specific
danielebarchiesi@0:  * theme functions to named objects, allowing the themer more control over
danielebarchiesi@0:  * specific types of output.
danielebarchiesi@0:  *
danielebarchiesi@0:  * As of Drupal 6, every theme hook is required to be registered by the
danielebarchiesi@0:  * module that owns it, so that Drupal can tell what to do with it and
danielebarchiesi@0:  * to make it simple for themes to identify and override the behavior
danielebarchiesi@0:  * for these calls.
danielebarchiesi@0:  *
danielebarchiesi@0:  * The theme hooks are registered via hook_theme(), which returns an
danielebarchiesi@0:  * array of arrays with information about the hook. It describes the
danielebarchiesi@0:  * arguments the function or template will need, and provides
danielebarchiesi@0:  * defaults for the template in case they are not filled in. If the default
danielebarchiesi@0:  * implementation is a function, by convention it is named theme_HOOK().
danielebarchiesi@0:  *
danielebarchiesi@0:  * Each module should provide a default implementation for theme_hooks that
danielebarchiesi@0:  * it registers. This implementation may be either a function or a template;
danielebarchiesi@0:  * if it is a function it must be specified via hook_theme(). By convention,
danielebarchiesi@0:  * default implementations of theme hooks are named theme_HOOK. Default
danielebarchiesi@0:  * template implementations are stored in the module directory.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Drupal's default template renderer is a simple PHP parsing engine that
danielebarchiesi@0:  * includes the template and stores the output. Drupal's theme engines
danielebarchiesi@0:  * can provide alternate template engines, such as XTemplate, Smarty and
danielebarchiesi@0:  * PHPTal. The most common template engine is PHPTemplate (included with
danielebarchiesi@0:  * Drupal and implemented in phptemplate.engine, which uses Drupal's default
danielebarchiesi@0:  * template renderer.
danielebarchiesi@0:  *
danielebarchiesi@0:  * In order to create theme-specific implementations of these hooks, themes can
danielebarchiesi@0:  * implement their own version of theme hooks, either as functions or templates.
danielebarchiesi@0:  * These implementations will be used instead of the default implementation. If
danielebarchiesi@0:  * using a pure .theme without an engine, the .theme is required to implement
danielebarchiesi@0:  * its own version of hook_theme() to tell Drupal what it is implementing;
danielebarchiesi@0:  * themes utilizing an engine will have their well-named theming functions
danielebarchiesi@0:  * automatically registered for them. While this can vary based upon the theme
danielebarchiesi@0:  * engine, the standard set by phptemplate is that theme functions should be
danielebarchiesi@0:  * named THEMENAME_HOOK. For example, for Drupal's default theme (Bartik) to
danielebarchiesi@0:  * implement the 'table' hook, the phptemplate.engine would find
danielebarchiesi@0:  * bartik_table().
danielebarchiesi@0:  *
danielebarchiesi@0:  * The theme system is described and defined in theme.inc.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see theme()
danielebarchiesi@0:  * @see hook_theme()
danielebarchiesi@0:  * @see hooks
danielebarchiesi@0:  * @see callbacks
danielebarchiesi@0:  *
danielebarchiesi@0:  * @} End of "defgroup themeable".
danielebarchiesi@0:  */
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Allow themes to alter the theme-specific settings form.
danielebarchiesi@0:  *
danielebarchiesi@0:  * With this hook, themes can alter the theme-specific settings form in any way
danielebarchiesi@0:  * allowable by Drupal's Form API, such as adding form elements, changing
danielebarchiesi@0:  * default values and removing form elements. See the Form API documentation on
danielebarchiesi@0:  * api.drupal.org for detailed information.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Note that the base theme's form alterations will be run before any sub-theme
danielebarchiesi@0:  * alterations.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $form
danielebarchiesi@0:  *   Nested array of form elements that comprise the form.
danielebarchiesi@0:  * @param $form_state
danielebarchiesi@0:  *   A keyed array containing the current state of the form.
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_form_system_theme_settings_alter(&$form, &$form_state) {
danielebarchiesi@0:   // Add a checkbox to toggle the breadcrumb trail.
danielebarchiesi@0:   $form['toggle_breadcrumb'] = array(
danielebarchiesi@0:     '#type' => 'checkbox',
danielebarchiesi@0:     '#title' => t('Display the breadcrumb'),
danielebarchiesi@0:     '#default_value' => theme_get_setting('toggle_breadcrumb'),
danielebarchiesi@0:     '#description'   => t('Show a trail of links from the homepage to the current page.'),
danielebarchiesi@0:   );
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Preprocess theme variables for templates.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook allows modules to preprocess theme variables for theme templates.
danielebarchiesi@0:  * It is called for all theme hooks implemented as templates, but not for theme
danielebarchiesi@0:  * hooks implemented as functions. hook_preprocess_HOOK() can be used to
danielebarchiesi@0:  * preprocess variables for a specific theme hook, whether implemented as a
danielebarchiesi@0:  * template or function.
danielebarchiesi@0:  *
danielebarchiesi@0:  * For more detailed information, see theme().
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $variables
danielebarchiesi@0:  *   The variables array (modify in place).
danielebarchiesi@0:  * @param $hook
danielebarchiesi@0:  *   The name of the theme hook.
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_preprocess(&$variables, $hook) {
danielebarchiesi@0:  static $hooks;
danielebarchiesi@0: 
danielebarchiesi@0:   // Add contextual links to the variables, if the user has permission.
danielebarchiesi@0: 
danielebarchiesi@0:   if (!user_access('access contextual links')) {
danielebarchiesi@0:     return;
danielebarchiesi@0:   }
danielebarchiesi@0: 
danielebarchiesi@0:   if (!isset($hooks)) {
danielebarchiesi@0:     $hooks = theme_get_registry();
danielebarchiesi@0:   }
danielebarchiesi@0: 
danielebarchiesi@0:   // Determine the primary theme function argument.
danielebarchiesi@0:   if (isset($hooks[$hook]['variables'])) {
danielebarchiesi@0:     $keys = array_keys($hooks[$hook]['variables']);
danielebarchiesi@0:     $key = $keys[0];
danielebarchiesi@0:   }
danielebarchiesi@0:   else {
danielebarchiesi@0:     $key = $hooks[$hook]['render element'];
danielebarchiesi@0:   }
danielebarchiesi@0: 
danielebarchiesi@0:   if (isset($variables[$key])) {
danielebarchiesi@0:     $element = $variables[$key];
danielebarchiesi@0:   }
danielebarchiesi@0: 
danielebarchiesi@0:   if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
danielebarchiesi@0:     $variables['title_suffix']['contextual_links'] = contextual_links_view($element);
danielebarchiesi@0:     if (!empty($variables['title_suffix']['contextual_links'])) {
danielebarchiesi@0:       $variables['classes_array'][] = 'contextual-links-region';
danielebarchiesi@0:     }
danielebarchiesi@0:   }
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Preprocess theme variables for a specific theme hook.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook allows modules to preprocess theme variables for a specific theme
danielebarchiesi@0:  * hook. It should only be used if a module needs to override or add to the
danielebarchiesi@0:  * theme preprocessing for a theme hook it didn't define.
danielebarchiesi@0:  *
danielebarchiesi@0:  * For more detailed information, see theme().
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $variables
danielebarchiesi@0:  *   The variables array (modify in place).
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_preprocess_HOOK(&$variables) {
danielebarchiesi@0:   // This example is from rdf_preprocess_image(). It adds an RDF attribute
danielebarchiesi@0:   // to the image hook's variables.
danielebarchiesi@0:   $variables['attributes']['typeof'] = array('foaf:Image');
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Process theme variables for templates.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook allows modules to process theme variables for theme templates. It
danielebarchiesi@0:  * is called for all theme hooks implemented as templates, but not for theme
danielebarchiesi@0:  * hooks implemented as functions. hook_process_HOOK() can be used to process
danielebarchiesi@0:  * variables for a specific theme hook, whether implemented as a template or
danielebarchiesi@0:  * function.
danielebarchiesi@0:  *
danielebarchiesi@0:  * For more detailed information, see theme().
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $variables
danielebarchiesi@0:  *   The variables array (modify in place).
danielebarchiesi@0:  * @param $hook
danielebarchiesi@0:  *   The name of the theme hook.
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_process(&$variables, $hook) {
danielebarchiesi@0:   // Wraps variables in RDF wrappers.
danielebarchiesi@0:   if (!empty($variables['rdf_template_variable_attributes_array'])) {
danielebarchiesi@0:     foreach ($variables['rdf_template_variable_attributes_array'] as $variable_name => $attributes) {
danielebarchiesi@0:       $context = array(
danielebarchiesi@0:         'hook' => $hook,
danielebarchiesi@0:         'variable_name' => $variable_name,
danielebarchiesi@0:         'variables' => $variables,
danielebarchiesi@0:       );
danielebarchiesi@0:       $variables[$variable_name] = theme('rdf_template_variable_wrapper', array('content' => $variables[$variable_name], 'attributes' => $attributes, 'context' => $context));
danielebarchiesi@0:     }
danielebarchiesi@0:   }
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Process theme variables for a specific theme hook.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook allows modules to process theme variables for a specific theme
danielebarchiesi@0:  * hook. It should only be used if a module needs to override or add to the
danielebarchiesi@0:  * theme processing for a theme hook it didn't define.
danielebarchiesi@0:  *
danielebarchiesi@0:  * For more detailed information, see theme().
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $variables
danielebarchiesi@0:  *   The variables array (modify in place).
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_process_HOOK(&$variables) {
danielebarchiesi@0:   // @todo There are no use-cases in Drupal core for this hook. Find one from a
danielebarchiesi@0:   //   contributed module, or come up with a good example. Coming up with a good
danielebarchiesi@0:   //   example might be tough, since the intent is for nearly everything to be
danielebarchiesi@0:   //   achievable via preprocess functions, and for process functions to only be
danielebarchiesi@0:   //   used when requiring the later execution time.
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Respond to themes being enabled.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param array $theme_list
danielebarchiesi@0:  *   Array containing the names of the themes being enabled.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see theme_enable()
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_themes_enabled($theme_list) {
danielebarchiesi@0:   foreach ($theme_list as $theme) {
danielebarchiesi@0:     block_theme_initialize($theme);
danielebarchiesi@0:   }
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Respond to themes being disabled.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param array $theme_list
danielebarchiesi@0:  *   Array containing the names of the themes being disabled.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see theme_disable()
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_themes_disabled($theme_list) {
danielebarchiesi@0:  // Clear all update module caches.
danielebarchiesi@0:   _update_cache_clear();
danielebarchiesi@0: }