ThemeManagerInterface.php 4.78 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<?php

namespace Drupal\Core\Theme;

/**
 * Provides a high level access to the active theme and methods to use it.
 *
 * Beside the active theme it provides a wrapper around _theme as well as the
 * alter functionality for themes.
 */
interface ThemeManagerInterface {

  /**
   * Generates themed output.
   *
16 17 18
   * See the @link themeable Default theme implementations topic @endlink for
   * details.
   *
19 20 21 22 23
   * @param string $hook
   *   The name of the theme hook to call.
   * @param array $variables
   *   An associative array of theme variables.
   *
24 25
   * @return string|\Drupal\Component\Render\MarkupInterface
   *   The rendered output, or a Markup object.
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
   */
  public function render($hook, array $variables);

  /**
   * Returns the active theme object.
   *
   * @return \Drupal\Core\Theme\ActiveTheme
   */
  public function getActiveTheme();

  /**
   * Determines whether there is an active theme.
   *
   * @return bool
   */
  public function hasActiveTheme();

  /**
   * Resets the current active theme.
   *
   * Note: This method should not be used in common cases, just in special cases
   * like tests.
   *
   * @return $this
   */
  public function resetActiveTheme();

  /**
   * Sets the current active theme manually.
   *
   * Note: This method should not be used in common cases, just in special cases
   * like tests.
   *
   * @param \Drupal\Core\Theme\ActiveTheme $active_theme
   *   The new active theme.
   * @return $this
   */
  public function setActiveTheme(ActiveTheme $active_theme);

  /**
   * Passes alterable variables to specific $theme_TYPE_alter() implementations.
   *
68 69
   * Executes an alter hook on the current theme. It also invokes alter hooks
   * for all base themes.
70
   *
71
   * $theme specifies the theme name of the active theme and all its base
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
   * themes.
   *
   * This dispatch function hands off the passed-in variables to type-specific
   * $theme_TYPE_alter() implementations in the active theme. It ensures a
   * consistent interface for all altering operations.
   *
   * A maximum of 2 alterable arguments is supported. In case more arguments
   * need to be passed and alterable, modules provide additional variables
   * assigned by reference in the last $context argument:
   * @code
   *   $context = array(
   *     'alterable' => &$alterable,
   *     'unalterable' => $unalterable,
   *     'foo' => 'bar',
   *   );
   *   $this->alter('mymodule_data', $alterable1, $alterable2, $context);
   * @endcode
   *
   * Note that objects are always passed by reference in PHP5. If it is
   * absolutely required that no implementation alters a passed object in
   * $context, then an object needs to be cloned:
   * @code
   *   $context = array(
   *     'unalterable_object' => clone $object,
   *   );
   *   $this->alter('mymodule_data', $data, $context);
   * @endcode
   *
   * @param string|array $type
   *   A string describing the type of the alterable $data. 'form', 'links',
   *   'node_content', and so on are several examples. Alternatively can be an
   *   array, in which case $theme_TYPE_alter() is invoked for each value in the
   *   array. When Form API is using $this->alter() to
   *   execute both $theme_form_alter() and $theme_form_FORM_ID_alter()
   *   implementations, it passes array('form', 'form_' . $form_id) for $type.
   * @param mixed $data
   *   The variable that will be passed to $theme_TYPE_alter() implementations
   *   to be altered. The type of this variable depends on the value of the
   *   $type argument. For example, when altering a 'form', $data will be a
   *   structured array. When altering a 'profile', $data will be an object.
   * @param mixed $context1
   *   (optional) An additional variable that is passed by reference.
   * @param mixed $context2
   *   (optional) An additional variable that is passed by reference. If more
   *   context needs to be provided to implementations, then this should be an
   *   associative array as described above.
   *
   * @see \Drupal\Core\Extension\ModuleHandlerInterface
   */
  public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL);

123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
  /**
   * Provides an alter hook for a specific theme.
   *
   * Similar to ::alter, it also invokes the alter hooks for the base themes.
   *
   * @param \Drupal\Core\Theme\ActiveTheme $theme
   *   A manually specified theme.
   * @param string|array $type
   *   A string describing the type of the alterable $data.
   * @param mixed $data
   *   The variable that will be passed to $theme_TYPE_alter() implementations
   * @param mixed $context1
   *   (optional) An additional variable that is passed by reference.
   * @param mixed $context2
   *   (optional) An additional variable that is passed by reference.
   *
   * @see ::alter
   */
  public function alterForTheme(ActiveTheme $theme, $type, &$data, &$context1 = NULL, &$context2 = NULL);

143
}