aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Theme/ThemeManagerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Theme;
   4
   5 /**
   6  * Provides a high level access to the active theme and methods to use it.
   7  *
   8  * Beside the active theme it provides a wrapper around _theme as well as the
   9  * alter functionality for themes.
  10  */
  11 interface ThemeManagerInterface {
  12
  13   /**
  14    * Generates themed output.
  15    *
  16    * See the @link themeable Default theme implementations topic @endlink for
  17    * details.
  18    *
  19    * @param string $hook
  20    *   The name of the theme hook to call.
  21    * @param array $variables
  22    *   An associative array of theme variables.
  23    *
  24    * @return string|\Drupal\Component\Render\MarkupInterface
  25    *   The rendered output, or a Markup object.
  26    */
  27   public function render($hook, array $variables);
  28
  29   /**
  30    * Returns the active theme object.
  31    *
  32    * @return \Drupal\Core\Theme\ActiveTheme
  33    */
  34   public function getActiveTheme();
  35
  36   /**
  37    * Determines whether there is an active theme.
  38    *
  39    * @return bool
  40    */
  41   public function hasActiveTheme();
  42
  43   /**
  44    * Resets the current active theme.
  45    *
  46    * Note: This method should not be used in common cases, just in special cases
  47    * like tests.
  48    *
  49    * @return $this
  50    */
  51   public function resetActiveTheme();
  52
  53   /**
  54    * Sets the current active theme manually.
  55    *
  56    * Note: This method should not be used in common cases, just in special cases
  57    * like tests.
  58    *
  59    * @param \Drupal\Core\Theme\ActiveTheme $active_theme
  60    *   The new active theme.
  61    * @return $this
  62    */
  63   public function setActiveTheme(ActiveTheme $active_theme);
  64
  65   /**
  66    * Passes alterable variables to specific $theme_TYPE_alter() implementations.
  67    *
  68    * Executes an alter hook on the current theme. It also invokes alter hooks
  69    * for all base themes.
  70    *
  71    * $theme specifies the theme name of the active theme and all its base
  72    * themes.
  73    *
  74    * This dispatch function hands off the passed-in variables to type-specific
  75    * $theme_TYPE_alter() implementations in the active theme. It ensures a
  76    * consistent interface for all altering operations.
  77    *
  78    * A maximum of 2 alterable arguments is supported. In case more arguments
  79    * need to be passed and alterable, modules provide additional variables
  80    * assigned by reference in the last $context argument:
  81    * @code
  82    *   $context = array(
  83    *     'alterable' => &$alterable,
  84    *     'unalterable' => $unalterable,
  85    *     'foo' => 'bar',
  86    *   );
  87    *   $this->alter('mymodule_data', $alterable1, $alterable2, $context);
  88    * @endcode
  89    *
  90    * Note that objects are always passed by reference in PHP5. If it is
  91    * absolutely required that no implementation alters a passed object in
  92    * $context, then an object needs to be cloned:
  93    * @code
  94    *   $context = array(
  95    *     'unalterable_object' => clone $object,
  96    *   );
  97    *   $this->alter('mymodule_data', $data, $context);
  98    * @endcode
  99    *
 100    * @param string|array $type
 101    *   A string describing the type of the alterable $data. 'form', 'links',
 102    *   'node_content', and so on are several examples. Alternatively can be an
 103    *   array, in which case $theme_TYPE_alter() is invoked for each value in the
 104    *   array. When Form API is using $this->alter() to
 105    *   execute both $theme_form_alter() and $theme_form_FORM_ID_alter()
 106    *   implementations, it passes array('form', 'form_' . $form_id) for $type.
 107    * @param mixed $data
 108    *   The variable that will be passed to $theme_TYPE_alter() implementations
 109    *   to be altered. The type of this variable depends on the value of the
 110    *   $type argument. For example, when altering a 'form', $data will be a
 111    *   structured array. When altering a 'profile', $data will be an object.
 112    * @param mixed $context1
 113    *   (optional) An additional variable that is passed by reference.
 114    * @param mixed $context2
 115    *   (optional) An additional variable that is passed by reference. If more
 116    *   context needs to be provided to implementations, then this should be an
 117    *   associative array as described above.
 118    *
 119    * @see \Drupal\Core\Extension\ModuleHandlerInterface
 120    */
 121   public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL);
 122
 123   /**
 124    * Provides an alter hook for a specific theme.
 125    *
 126    * Similar to ::alter, it also invokes the alter hooks for the base themes.
 127    *
 128    * @param \Drupal\Core\Theme\ActiveTheme $theme
 129    *   A manually specified theme.
 130    * @param string|array $type
 131    *   A string describing the type of the alterable $data.
 132    * @param mixed $data
 133    *   The variable that will be passed to $theme_TYPE_alter() implementations
 134    * @param mixed $context1
 135    *   (optional) An additional variable that is passed by reference.
 136    * @param mixed $context2
 137    *   (optional) An additional variable that is passed by reference.
 138    *
 139    * @see ::alter
 140    */
 141   public function alterForTheme(ActiveTheme $theme, $type, &$data, &$context1 = NULL, &$context2 = NULL);
 142
 143 }