Unverified Commit 84fc7490 authored by alexpott's avatar alexpott
Browse files

Issue #2938969 by msankhala, dhirendra.mishra, paulocs, TR, MerryHamster,...

Issue #2938969 by msankhala, dhirendra.mishra, paulocs, TR, MerryHamster, alexpott, jofitz, longwave, Manuel Garcia, tameeshb, boaloysius, Yasiru Nilan, xjm, wturrell, ritzz, ZeiP, darrenwh: Replace drupal_render() in docblock and comments outside of @param, @return, @Link, @see and outside of @code - @endcode
parent 8ff4d48c
......@@ -2419,8 +2419,8 @@ function hook_validation_constraint_alter(array &$definitions) {
* @code
* array('#type' => 'status_messages')
* @endcode
* to a render array, use drupal_render() to render it, and add a command to
* place the messages in an appropriate location.
* to a render array, use \Drupal::service('renderer')->render() to render it,
* and add a command to place the messages in an appropriate location.
*
* @section sec_other Other methods for triggering Ajax
* Here are some additional methods you can use to trigger Ajax responses in
......
......@@ -413,13 +413,13 @@ function render(&$element) {
/**
* Hides an element from later rendering.
*
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to hide an
* element, be sure to call hide() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* The first time render() or RenderInterface::render() is called on an element
* tree, as each element in the tree is rendered, it is marked with a #printed
* flag and the rendered children of the element are cached. Subsequent calls to
* render() or RenderInterface::render() will not traverse the child tree of
* this element again: they will just use the cached children. So if you want to
* hide an element, be sure to call hide() on the element before its parent tree
* is rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
*
* @param $element
......@@ -428,6 +428,7 @@ function render(&$element) {
* @return
* The element.
*
* @see \Drupal\Core\Render\RendererInterface
* @see render()
* @see show()
*/
......@@ -442,13 +443,13 @@ function hide(&$element) {
* You can also use render($element), which shows the element while rendering
* it.
*
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to show an
* element, be sure to call show() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* The first time render() or RenderInterface::render() is called on an element
* tree, as each element in the tree is rendered, it is marked with a #printed
* flag and the rendered children of the element are cached. Subsequent calls to
* render() or RenderInterface::render() will not traverse the child tree of
* this element again: they will just use the cached children. So if you want to
* show an element, be sure to call show() on the element before its parent tree
* is rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
*
* @param $element
......@@ -457,6 +458,7 @@ function hide(&$element) {
* @return
* The element.
*
* @see \Drupal\Core\Render\RendererInterface
* @see render()
* @see hide()
*/
......
......@@ -246,8 +246,8 @@ public function build(array $build) {
* This function is assigned as a #pre_render callback in ::viewMultiple().
*
* By delaying the building of an entity until the #pre_render processing in
* drupal_render(), the processing cost of assembling an entity's renderable
* array is saved on cache-hit requests.
* \Drupal::service('renderer')->render(), the processing cost of assembling
* an entity's renderable array is saved on cache-hit requests.
*
* @param array $build_list
* A renderable array containing build information and context for an
......
......@@ -1537,7 +1537,7 @@ function hook_ENTITY_TYPE_view(array &$build, \Drupal\Core\Entity\EntityInterfac
* the particular entity type template, if there is one (e.g., node.html.twig).
*
* See the @link themeable Default theme implementations topic @endlink and
* drupal_render() for details.
* \Drupal\Core\Render\RendererInterface::render() for details.
*
* @param array &$build
* A renderable array representing the entity content.
......@@ -1576,7 +1576,7 @@ function hook_entity_view_alter(array &$build, \Drupal\Core\Entity\EntityInterfa
* the particular entity type template, if there is one (e.g., node.html.twig).
*
* See the @link themeable Default theme implementations topic @endlink and
* drupal_render() for details.
* \Drupal\Core\Render\RendererInterface::render() for details.
*
* @param array &$build
* A renderable array representing the entity content.
......@@ -1659,7 +1659,7 @@ function hook_entity_view_mode_alter(&$view_mode, \Drupal\Core\Entity\EntityInte
}
/**
* Alter entity renderable values before cache checking in drupal_render().
* Alter entity renderable values before cache checking during rendering.
*
* Invoked for a specific entity type.
*
......@@ -1685,7 +1685,7 @@ function hook_ENTITY_TYPE_build_defaults_alter(array &$build, \Drupal\Core\Entit
}
/**
* Alter entity renderable values before cache checking in drupal_render().
* Alter entity renderable values before cache checking during rendering.
*
* The values in the #cache key of the renderable array are used to determine if
* a cache entry exists for the entity's rendered output. Ideally only values
......
......@@ -17,11 +17,11 @@
/**
* Subscriber that wraps controllers, to handle early rendering.
*
* When controllers call drupal_render() (RendererInterface::render()) outside
* of a render context, we call that "early rendering". Controllers should
* return only render arrays, but we cannot prevent controllers from doing early
* rendering. The problem with early rendering is that the bubbleable metadata
* (cacheability & attachments) are lost.
* When controllers call RendererInterface::render() outside of a render
* context, we call that "early rendering". Controllers should return
* only render arrays, but we cannot prevent controllers from doing
* early rendering. The problem with early rendering is that the
* bubbleable metadata (cacheability & attachments) are lost.
*
* This can lead to broken pages (missing assets), stale pages (missing cache
* tags causing a page not to be invalidated) or even security problems (missing
......@@ -36,8 +36,8 @@
* ::renderPlain() methods. In that case, no bubbleable metadata is lost.
*
* If the render context is not empty, then the controller did use
* drupal_render(), and bubbleable metadata was collected. This bubbleable
* metadata is then merged onto the render array.
* RendererInterface::render(), and bubbleable metadata was collected.
* This bubbleable metadata is then merged onto the render array.
*
* In other words: this just exists to ease the transition to Drupal 8: it
* allows controllers that return render arrays (the majority) and
......@@ -124,8 +124,8 @@ protected function wrapControllerExecutionInRenderContext($controller, array $ar
});
// If early rendering happened, i.e. if code in the controller called
// drupal_render() outside of a render context, then the bubbleable metadata
// for that is stored in the current render context.
// RendererInterface::render() outside of a render context, then the
// bubbleable metadata for that is stored in the current render context.
if (!$context->isEmpty()) {
/** @var \Drupal\Core\Render\BubbleableMetadata $early_rendering_bubbleable_metadata */
$early_rendering_bubbleable_metadata = $context->pop();
......
......@@ -245,10 +245,11 @@ public function prepareForm($form_id, &$form, FormStateInterface &$form_state);
* This is one of the three primary functions that recursively iterates a form
* array. This one does it for completing the form building process. The other
* two are self::doValidateForm() (invoked via self::validateForm() and used
* to invoke validation logic for each element) and drupal_render() (for
* rendering each element). Each of these three pipelines provides ample
* opportunity for modules to customize what happens. For example, during this
* function's life cycle, the following functions get called for each element:
* to invoke validation logic for each element) and
* RendererInterface::render() (for rendering each element).
* Each of these three pipelines provides ample opportunity for modules to
* customize what happens. For example, during this function's life cycle,
* the following functions get called for each element:
* - $element['#value_callback']: A callable that implements how user input is
* mapped to an element's #value property. This defaults to a function named
* 'form_type_TYPE_value' where TYPE is $element['#type'].
......@@ -269,8 +270,8 @@ public function prepareForm($form_id, &$form, FormStateInterface &$form_state);
* called in postorder traversal, meaning they are called for the child
* elements first, then for the parent element.
* There are similar properties containing callback functions invoked by
* self::doValidateForm() and drupal_render(), appropriate for those
* operations.
* self::doValidateForm() and RendererInterface::render(),
* appropriate for those operations.
*
* Developers are strongly encouraged to integrate the functionality needed by
* their form or module within one of these three pipelines, using the
......
......@@ -171,7 +171,8 @@ public function build(array $tree) {
$tree_cacheability->applyTo($build);
if ($items) {
// Make sure drupal_render() does not re-order the links.
// Make sure Drupal\Core\Render\Element::children() does not re-order the
// links.
$build['#sorted'] = TRUE;
// Get the menu name from the last link.
$item = end($items);
......
......@@ -57,7 +57,8 @@ public static function child($key) {
* Identifies the children of an element array, optionally sorted by weight.
*
* The children of an element array are those key/value pairs whose key does
* not start with a '#'. See drupal_render() for details.
* not start with a '#'. See \Drupal\Core\Render\RendererInterface::render()
* for details.
*
* @param array $elements
* The element array whose children are to be identified. Passed by
......
......@@ -172,8 +172,8 @@ public static function preRenderConditionalComments($element) {
// technique. See http://wikipedia.org/wiki/Conditional_comment
// for details.
// Ensure what we are dealing with is safe.
// This would be done later anyway in drupal_render().
// Ensure what we are dealing with is safe. This would be done later anyway
// in \Drupal::service('renderer')->render().
$prefix = isset($element['#prefix']) ? $element['#prefix'] : '';
if ($prefix && !($prefix instanceof MarkupInterface)) {
$prefix = Xss::filterAdmin($prefix);
......
......@@ -111,9 +111,10 @@ public static function preRenderLink($element) {
*
* The purpose of this is to allow links to be logically grouped into related
* categories, so that each child group can be rendered as its own list of
* links if drupal_render() is called on it, but calling drupal_render() on
* the parent element will still produce a single list containing all the
* remaining links, regardless of what group they were in.
* links if RendererInterface::render() is called on it, but
* calling RendererInterface::render() on the parent element will
* still produce a single list containing all the remaining links, regardless
* of what group they were in.
*
* A typical example comes from node links, which are stored in a renderable
* array similar to this:
......
......@@ -548,7 +548,7 @@ protected function doRender(&$elements, $is_root_call = FALSE) {
$this->replacePlaceholders($elements);
// @todo remove as part of https://www.drupal.org/node/2511330.
if ($context->count() !== 1) {
throw new \LogicException('A stray drupal_render() invocation with $is_root_call = TRUE is causing bubbling of attached assets to break.');
throw new \LogicException('A stray RendererInterface::render() invocation with $is_root_call = TRUE is causing bubbling of attached assets to break.');
}
}
......
......@@ -17,11 +17,12 @@
* hierarchical arrays that include the data to be rendered into HTML (or XML or
* another output format), and options that affect the markup. Render arrays
* are ultimately rendered into HTML or other output formats by recursive calls
* to drupal_render(), traversing the depth of the render array hierarchy. At
* each level, the theme system is invoked to do the actual rendering. See the
* documentation of drupal_render() and the
* @link theme_render Theme system and Render API topic @endlink for more
* information about render arrays and rendering.
* to \Drupal\Core\Render\RendererInterface::render(), traversing the depth of
* the render array hierarchy. At each level, the theme system is invoked to do
* the actual rendering. See the documentation of
* \Drupal\Core\Render\RendererInterface::render() and the @link theme_render
* Theme system and Render API topic @endlink for more information about render
* arrays and rendering.
*
* @section sec_twig_theme Twig Templating Engine
* Drupal 8 uses the templating engine Twig. Twig offers developers a fast,
......@@ -241,13 +242,16 @@
* hierarchical associative array containing data to be rendered and properties
* describing how the data should be rendered. A render array that is returned
* by a function to specify markup to be sent to the web browser or other
* services will eventually be rendered by a call to drupal_render(), which will
* recurse through the render array hierarchy if appropriate, making calls into
* the theme system to do the actual rendering. If a function or method actually
* needs to return rendered output rather than a render array, the best practice
* would be to create a render array, render it by calling drupal_render(), and
* return that result, rather than writing the markup directly. See the
* documentation of drupal_render() for more details of the rendering process.
* services will eventually be rendered by a call to
* \Drupal\Core\Render\RendererInterface::render(), which will recurse through
* the render array hierarchy if appropriate, making calls into the theme system
* to do the actual rendering. If a function or method actually needs to return
* rendered output rather than a render array, the best practice would be to
* create a render array, render it by calling
* \Drupal\Core\Render\RendererInterface::render(), and return that result,
* rather than writing the markup directly. See the documentation of
* \Drupal\Core\Render\RendererInterface::render() for more details of the
* rendering process.
*
* Each level in the hierarchy of a render array (including the outermost array)
* has one or more array elements. Array elements whose names start with '#' are
......
......@@ -72,8 +72,9 @@
* If the module wishes to act on the rendered HTML of the block rather than
* the structured content array, it may use this hook to add a #post_render
* callback. Alternatively, it could also implement hook_preprocess_HOOK() for
* block.html.twig. See drupal_render() documentation or the
* @link themeable Default theme implementations topic @endlink for details.
* block.html.twig. See \Drupal\Core\Render\RendererInterface::render()
* documentation or the @link themeable Default theme implementations topic
* @endlink for details.
*
* In addition to hook_block_view_alter(), which is called for all blocks, there
* is hook_block_view_BASE_BLOCK_ID_alter(), which can be used to target a
......
......@@ -596,7 +596,8 @@ public function bookTreeOutput(array $tree) {
$build = [];
if ($items) {
// Make sure drupal_render() does not re-order the links.
// Make sure Drupal\Core\Render\Element::children() does not re-order the
// links.
$build['#sorted'] = TRUE;
// Get the book id from the last link.
$item = end($items);
......
......@@ -86,7 +86,8 @@ public static function preRenderLinks(array $element) {
// Allow modules to alter the renderable contextual links element.
static::moduleHandler()->alter('contextual_links_view', $element, $items);
// If there are no links, tell drupal_render() to abort rendering.
// If there are no links, tell \Drupal::service('renderer')->render() to
// abort rendering.
if (empty($element['#links'])) {
$element['#printed'] = TRUE;
}
......
......@@ -296,11 +296,12 @@ public function testImageDimensions() {
/**
* Render an image style element.
*
* Function drupal_render() alters the passed $variables array by adding a new
* key '#printed' => TRUE. This prevents next call to re-render the element.
* We wrap drupal_render() in a helper protected method and pass each time a
* fresh array so that $variables won't get altered and the element is
* re-rendered each time.
* Function \Drupal\Core\Render\RendererInterface::render() alters the passed
* $variables array by adding a new key '#printed' => TRUE. This prevents next
* call to re-render the element. We wrap
* \Drupal\Core\Render\RendererInterface::render() in a helper protected
* method and pass each time a fresh array so that $variables won't get
* altered and the element is re-rendered each time.
*/
protected function getImageTag($variables) {
return str_replace("\n", NULL, \Drupal::service('renderer')->renderRoot($variables));
......
......@@ -63,12 +63,12 @@ function theme_theme_test_function_template_override($variables) {
}
/**
* Theme function for testing rendering of child elements via drupal_render().
* Theme function for testing rendering of child elements.
*
* Theme hooks defining a 'render element' add an internal '#render_children'
* property. When this property is found, drupal_render() avoids calling
* the 'theme.manager' service 'render' method on the top-level element to
* prevent infinite recursion.
* property. When this property is found, \Drupal::service('renderer')->render()
* avoids calling the 'theme.manager' service's ThemeManagerInterface::render()
* method on the top-level element to prevent infinite recursion.
*
* @param array $variables
* An associative array containing:
......
......@@ -8,7 +8,7 @@
use Drupal\Tests\system\Functional\Cache\AssertPageCacheContextsAndTagsTrait;
/**
* Performs integration tests on drupal_render().
* Performs integration tests on \Drupal::service('renderer')->render().
*
* @group Common
*/
......
......@@ -7,7 +7,7 @@
use Drupal\KernelTests\KernelTestBase;
/**
* Performs integration tests on drupal_render().
* Performs integration tests on \Drupal::service('renderer')->render().
*
* @group system
*/
......
......@@ -135,7 +135,7 @@ public function testDrupalRenderChildren() {
'#markup' => 'Foo',
],
];
$this->assertThemeOutput('theme_test_render_element_children', $element, 'Foo', 'drupal_render() avoids #theme recursion loop when rendering a render element.');
$this->assertThemeOutput('theme_test_render_element_children', $element, 'Foo', "\Drupal::service('renderer')->render() avoids #theme recursion loop when rendering a render element.");
$element = [
'#theme_wrappers' => ['theme_test_render_element_children'],
......@@ -143,7 +143,7 @@ public function testDrupalRenderChildren() {
'#markup' => 'Foo',
],
];
$this->assertThemeOutput('theme_test_render_element_children', $element, 'Foo', 'drupal_render() avoids #theme_wrappers recursion loop when rendering a render element.');
$this->assertThemeOutput('theme_test_render_element_children', $element, 'Foo', "\Drupal::service('renderer')->render() avoids #theme_wrappers recursion loop when rendering a render element.");
}
/**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment