annotate core/lib/Drupal/Core/Theme/ThemeManagerInterface.php @ 19:fa3358dc1485 tip

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