How to cache correctly a render array for item list value Drupal example

Here I will share with you the code of our I did for implementing my custom requirement on the Item List for rendering the Related Service fields displayed inside the Taxonomy View Page that shows all my Services, for example look at the first Service (Deploy File on Amazon S3..) in my Service page and have a look at this Block:

The Requirement is to hide Links to the Current Service page, for example if the current page is Our Services & Solutions then I do not want to show the Our Services & Solutions link because you are already inside that page so the link is redundant so we want to hide. But when you look at the same Block inside another Service Page such as Custom Modules then you will see that the Custom Module Link is there because it is not Displayed and it is not rendered inside the Twig Template because I added a new Twig with a new custom logic to skip it when it item.hide is TRUE.

Let's have a look how this Rendered Array Looks like (for simplicity I show only what is relevant and it was printed using:

dpm($variables['items']);

Array
[
    [0] => Array
        (
            ['value'] => stdClass Object
                (
                    [__CLASS__] => Drupal\views\Render\ViewsRenderPipelineMarkup
                    [string:protected] => 'Our Services & Solutions'
                )
        )
    [1] => Array
        (
            ['value'] => stdClass Object
                (
                    [__CLASS__] => Drupal\views\Render\ViewsRenderPipelineMarkup
                    [string:protected] => 'Custom Modules'
                )
        )
    [2] => Array
        (
            ['value'] => stdClass Object
                (
                    [__CLASS__] => Drupal\views\Render\ViewsRenderPipelineMarkup
                    [string:protected] => 'Database Integration'
                )

                )

        )
    [3] => Array
        (
            ['value'] => stdClass Object
                (
                    [__CLASS__] => Drupal\views\Render\ViewsRenderPipelineMarkup
                    [string:protected] => 'Information Architecture'
                )
        )
    [4] => Array
        [
            ['value'] => stdClass Object
                (
                    [__CLASS__] => Drupal\views\Render\ViewsRenderPipelineMarkup
                    [string:protected] => 'Integrated Content'
                )
        ]
]

In order to Preprocess these Items we need to set up a new Class for  "item_list" Preprocess:

/**
 * Pre-processes variables for the "item_list" theme hook.
 *
 * @ingroup plugins_preprocess
 *
 * @see item-list.html.twig
 *
 * @BootstrapPreprocess("item_list")
 */
class ItemList extends PreprocessBase implements PreprocessInterface, ContainerFactoryPluginInterface {

This Class also use Dependency Injection to re-use the MariaCustomService, but in here I will focus on the Preprocess.

As I said I want to modify the Rendered Array for "item_list" to exclude all links to the current page, but only on Taxonomy Service Page (Vocabulary is "tags") this is the function:

public function preprocessVariables(Variables $variables) {
    /** @var ContentEntityInterface $term */
    if ($term = $this->route_match->getParameter('taxonomy_term')) {
      if ($term->bundle() == 'tags') {

        static $all_links = [];
        $current_url = $term->toUrl()->toString();
        $variables->addCacheContexts(['url.path']);

        $tot = count($variables['items']);
        for ($delta = 0; ($delta < $tot); $delta++) {
          /** @var ViewsRenderPipelineMarkup $myItem */
          $myItem = $variables['items'][$delta]['value'];

          $alias = $this->customService->findURLfromHTML($myItem->jsonSerialize());
          if (!empty($alias)) {

            // We do not show link to the current page.
            if ($alias == $current_url) {
              $variables['items'][$delta]['hide'] = true;
            }
            // Show the link only on the first occurrence.
            elseif(($my_term = $this->customService->getEntityByAlias($alias)) && $my_term instanceof ContentEntityInterface) {
              $my_tid = $my_term->id();
              if (!empty($all_links[$my_tid])) {
                $variables['items'][$delta]['hide'] = true;
              }
              else {
                $all_links[$my_tid] = 1;
              }
            }

          }

        }
      }
    }
  }

We know the Values of each Link is an HTML link which looks like:

<a href="/services" hreflang="en">Our Services &amp; Solutions</a>

We extract the URL Alias (/service) using findURLfromHTML() function from the Service which returns us the alias which is passed to getEntityByAlias() which returns us the Term, then we compare if the Term ID versus the Current Term ID, if they are identical then we hide this item:

$variables['items'][$delta]['hide'] = true;

Now we must also create a custom Twig that overwrite the Default  item-list.html.twig in order to hide the items which we set to hide, because the default Theme for Item List always display them all. 

This is the easiest part, it require simple Overwriting the item-list.html.twig file, first thing we need to do it is to tell the Theme Preprocessor that we want to Suggest a new Twig file for this Theme HOOK:

namespace Drupal\maria_consulting\Plugin\Alter;

// .... all code is in my Github Repository

/**
 * Implements hook_theme_suggestions_alter().
 *
 * @ingroup plugins_alter
 *
 * @BootstrapAlter("theme_suggestions")
 */
class ThemeSuggestions extends \Drupal\bootstrap\Plugin\Alter\ThemeSuggestions
{

  /**
   * {@inheritdoc}
   */
  public function alter(&$suggestions, &$variables = [], &$hook = NULL)
  {
    if ($hook == 'item_list' && ($taxonomy = \Drupal::routeMatch()->getParameter('taxonomy_term'))) {
      $vocabularyId = $taxonomy->getVocabularyId();
      $suggestions[] = $variables['theme_hook_original'] . '__taxonomy__term__' . $vocabularyId;
    }

Basically it is telling Drupal Theme Processor to suggest other Twig Templates more specific to use for Item_list when they are Displayed inside a Taxonomy Service Term page. In my case this is the file name which Overwrite the Default:

item-list--taxonomy--term--tags.html.twig

And this is the content of this file:

{% if context.list_style %}
  {%- set attributes = attributes.addClass('item-list__' ~ context.list_style) %}
{% endif %}
{% if items or empty %}
  {%- if title is not empty -%}
    <h3>{{ title }}</h3>
  {%- endif -%}

  {%- if items -%}
    <{{ list_type }}{{ attributes }}>
      {%- for item in items -%}
        {%- if not item.hide -%}
        <li{{ item.attributes }}>{{ item.value }}</li>
        {%- endif -%}
      {%- endfor -%}
    </{{ list_type }}>
  {%- else -%}
    {{- empty -}}
  {%- endif -%}
{%- endif %}

It is almost identical to the Original, I only added the extra IF condition to Display the Link when item.hide is FALSE!

It is not finished yet, I must explain you now how Drupal Know how to cache correctly all these modified "Rendered Arrays"

This is the most important part of this Article: Drupal Cache system by Default does not know that we are altering the "Rendered Arrays" for these Item List, so what it does it cache the rendered results when the Item List Links are rendered for the first time and then in the successive Requests re-use the Cached HTML rendered result.

But this is not what we really want because our requirement is to have different values on different Service Page. Basically I want to modify again this "Rendered Arrays" for Item List on specific Page URLs, then I must tell Drupal the Context when to cache my Values. That's why I added this line inside:

  public function preprocessVariables(Variables $variables) {

// All code is inside the Paragraph above
                        $variables->addCacheContexts(['url.path']);

addCacheContexts tells Drupal to cache this Rendered array on our specific Context which is different for each Page Path. For example our specific paths are: /services, /services/custom-modules and so on. Drupal will know to cache this values on path specific because we added this context.

There is a lot to talk about Caching and the way Drupal 8 handle contexts. For now what you need to know is that you can modify Default Context on "Rendered Arrays" to make your Content more specific on specific custom context such as: when URL is front page, when is parent URL, when URL contains certain Query Parameters, when the user is super user or has got specific roles.

url
  .path
    .is_front // Available in 8.3.x or higher.
    .parent
  .query_args
    :key
    .pagers
      :pager_id
  .site
user
  .is_super_user
  .node_grants
    :operation
  .permissions
  .roles
    :role

There is lot to learn about Custom Context. If you want to learn more about how to create your own custom Cache Contexts, I really recommend you to read Cache contexts from Drupal.org.