You are here

Home » API reference » Drupal 9 » TourViewBuilder.php

class TourViewBuilder in Drupal 9

Same name and namespace in other branches
  1. 8 core/modules/tour/src/TourViewBuilder.php \Drupal\tour\TourViewBuilder

Provides a Tour view builder.

Hierarchy

Expanded class hierarchy of TourViewBuilder

File

core/modules/tour/src/TourViewBuilder.php, line 12

Namespace

Drupal\tour
View source 
class TourViewBuilder extends EntityViewBuilder {

  /**
   * {@inheritdoc}
   */
  public function viewMultiple(array $entities = [], $view_mode = 'full', $langcode = NULL) {

    /** @var \Drupal\tour\TourInterface[] $entities */
    $tour = [];
    $cache_tags = [];
    $total_tips = 0;
    foreach ($entities as $entity_id => $entity) {
      $tour[$entity_id] = $entity
        ->getTips();
      $total_tips += count($tour[$entity_id]);
      $cache_tags = Cache::mergeTags($cache_tags, $entity
        ->getCacheTags());
    }
    $items = [];
    foreach ($tour as $tour_id => $tips) {
      $tourEntity = $entities[$tour_id];
      foreach ($tips as $index => $tip) {
        $classes = [
          'tip-module-' . Html::getClass($tourEntity
            ->getModule()),
          'tip-type-' . Html::getClass($tip
            ->getPluginId()),
          'tip-' . Html::getClass($tip
            ->id()),
        ];
        $selector = $tip
          ->getSelector();
        $location = $tip
          ->getLocation();

        // If $location is null, it's possible that a value is available
        // by directly accessing the `location` property. This can occur if
        // a tour with the deprecated `location` property was installed and
        // tour_post_update_joyride_selectors_to_selector_property() has not run
        // with it installed.
        // @see tour_post_update_joyride_selectors_to_selector_property()
        if (!$location && ($location = $tip
          ->get('location'))) {

          // If the `location` property still has a value, this means the tip
          // is configured for Joyride. The position value must be appended with
          // '-start' to provide the same experience as Joyride.
          $location = $location . '-start';
        }

        // @todo remove conditional in https://drupal.org/node/3195193, as all
        //   instances will already be instances of TourTipPluginInterface.
        if ($tip instanceof TourTipPluginInterface) {
          $body_render_array = $tip
            ->getBody();
          $body = (string) \Drupal::service('renderer')
            ->renderPlain($body_render_array);
          $output = [
            'body' => $body,
            'title' => Html::escape($tip
              ->getLabel()),
          ];
          $selector = $tip
            ->getSelector();
        }
        else {

          // This condition is met if the tip does not implement
          // TourTipPluginInterface. This means the tour tip must be constructed
          // with the deprecated getOutput() method. The resulting tour tip
          // should be largely identical, with the following exceptions:
          // - If the tour tip `attributes` property included anything other
          //   than `data-class` or `data-id`, these additional attributes
          //   will not be available in the resulting tour tip. Note that such
          //   uses are uncommon.
          // - Although the tour tip content is identical, the markup structure
          //   will be different due to being rendered by Shepherd instead of
          //   Joyride. Themes extending Stable or Stable 9 will not experience
          //   these changes as a script is provided that reconstructs each tip
          //   to match Joyride's markup structure.
          $attributes = (array) $tip
            ->get('attributes');
          if (array_diff([
            'data-class',
            'data-id',
          ], array_keys($attributes + [
            'data-class',
            'data-id',
          ]))) {
            trigger_error('The tour tips only support data-class and data-id attributes and they will have to be upgraded manually. See https://www.drupal.org/node/3204093', E_USER_WARNING);
          }
          $tour_render_array = $tip
            ->getOutput();
          if (!empty($tour_render_array)) {

            // The output render array intentionally omits title. The deprecated
            // getOutput() returns a render array with the title and main
            // content.
            $output = [
              'body' => (string) \Drupal::service('renderer')
                ->renderPlain($tour_render_array),
            ];

            // Add a class so JavaScript in Stable themes can identify deprecated
            // tip plugins. The logic used to make markup backwards compatible
            // with Joyride is different depending on the type of
            // plugin used.
            $classes[] = 'tip-uses-get-output';
          }
        }
        if ($output) {
          $items[] = [
            'id' => $tip
              ->id(),
            'selector' => $selector,
            'module' => $tourEntity
              ->getModule(),
            'type' => $tip
              ->getPluginId(),
            'counter' => $this
              ->t('@tour_item of @total', [
              '@tour_item' => $index + 1,
              '@total' => $total_tips,
            ]),
            'attachTo' => [
              'element' => $selector,
              'on' => $location ?? 'bottom-start',
            ],
            // Shepherd expects classes to be provided as a string.
            'classes' => implode(' ', $classes),
          ] + $output;
        }
      }
    }

    // If there is at least one tour item, build the tour.
    if ($items) {
      end($items);
      $key = key($items);
      $items[$key]['cancelText'] = t('End tour');
    }
    $build = [
      '#cache' => [
        'tags' => $cache_tags,
      ],
    ];

    // If at least one tour was built, attach tips and the tour library.
    if ($items) {
      $build['#attached']['drupalSettings']['tourShepherdConfig'] = [
        'defaultStepOptions' => [
          'classes' => 'drupal-tour',
          'cancelIcon' => [
            'enabled' => TRUE,
            'label' => $this
              ->t('Close'),
          ],
          'modalOverlayOpeningPadding' => 3,
          'scrollTo' => [
            'behavior' => 'smooth',
            'block' => 'center',
          ],
          'popperOptions' => [
            'modifiers' => [
              // Prevent overlap with the element being highlighted.
              [
                'name' => 'offset',
                'options' => [
                  'offset' => [
                    -10,
                    20,
                  ],
                ],
              ],
              // Pad the arrows so they don't hit the edge of rounded corners.
              [
                'name' => 'arrow',
                'options' => [
                  'padding' => 12,
                ],
              ],
              // Disable Shepherd's focusAfterRender modifier, which results in
              // the tour item container being focused on any scroll or resize
              // event.
              [
                'name' => 'focusAfterRender',
                'enabled' => FALSE,
              ],
            ],
          ],
        ],
        'useModalOverlay' => TRUE,
      ];

      // This property is used for storing the tour items. It may change without
      // notice and should not be extended or modified in contrib.
      // see: https://www.drupal.org/project/drupal/issues/3214593
      $build['#attached']['drupalSettings']['_tour_internal'] = $items;
      $build['#attached']['library'][] = 'tour/tour';
    }
    return $build;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
DependencySerializationTrait::$_entityStorages protected property
DependencySerializationTrait::$_serviceIds protected property
DependencySerializationTrait::__sleep public function 2
DependencySerializationTrait::__wakeup public function 2
EntityHandlerBase::$moduleHandler protected property The module handler to invoke hooks on. 5
EntityHandlerBase::moduleHandler protected function Gets the module handler. 5
EntityHandlerBase::setModuleHandler public function Sets the module handler for this handler.
EntityViewBuilder::$cacheBin protected property The cache bin used to store the render cache.
EntityViewBuilder::$entityDisplayRepository protected property The entity display repository.
EntityViewBuilder::$entityRepository protected property The entity repository service.
EntityViewBuilder::$entityType protected property Information about the entity type.
EntityViewBuilder::$entityTypeId protected property The type of entities for which this view builder is instantiated.
EntityViewBuilder::$languageManager protected property The language manager.
EntityViewBuilder::$singleFieldDisplays protected property The EntityViewDisplay objects created for individual field rendering.
EntityViewBuilder::$themeRegistry protected property The theme registry.
EntityViewBuilder::addContextualLinks protected function Add contextual links.
EntityViewBuilder::alterBuild protected function Specific per-entity building. 1
EntityViewBuilder::build public function Builds an entity's view; augments entity defaults.
EntityViewBuilder::buildComponents public function Builds the component fields and properties of a set of entities. Overrides EntityViewBuilderInterface::buildComponents 7
EntityViewBuilder::buildMultiple public function Builds multiple entities' views; augments entity defaults.
EntityViewBuilder::createInstance public static function Instantiates a new instance of this entity handler. Overrides EntityHandlerInterface::createInstance 3
EntityViewBuilder::getBuildDefaults protected function Provides entity-specific defaults to the build process. 4
EntityViewBuilder::getCacheTags public function The cache tag associated with this entity view builder. Overrides EntityViewBuilderInterface::getCacheTags
EntityViewBuilder::getSingleFieldDisplay protected function Gets an EntityViewDisplay for rendering an individual field.
EntityViewBuilder::isViewModeCacheable protected function Determines whether the view mode is cacheable.
EntityViewBuilder::resetCache public function Resets the entity render cache. Overrides EntityViewBuilderInterface::resetCache
EntityViewBuilder::trustedCallbacks public static function Lists the trusted callbacks provided by the implementing class. Overrides TrustedCallbackInterface::trustedCallbacks 2
EntityViewBuilder::view public function Builds the render array for the provided entity. Overrides EntityViewBuilderInterface::view 4
EntityViewBuilder::viewField public function Builds a renderable array for the value of a single field in an entity. Overrides EntityViewBuilderInterface::viewField
EntityViewBuilder::viewFieldItem public function Builds a renderable array for a single field item. Overrides EntityViewBuilderInterface::viewFieldItem
EntityViewBuilder::__construct public function Constructs a new EntityViewBuilder. 2
StringTranslationTrait::$stringTranslation protected property The string translation service. 4
StringTranslationTrait::formatPlural protected function Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals protected function Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation protected function Gets the string translation service.
StringTranslationTrait::setStringTranslation public function Sets the string translation service to use. 2
StringTranslationTrait::t protected function Translates a string to the current language or to a given language.
TourViewBuilder::viewMultiple public function Builds the render array for the provided entities. Overrides EntityViewBuilder::viewMultiple
TrustedCallbackInterface::THROW_EXCEPTION constant Untrusted callbacks throw exceptions.
TrustedCallbackInterface::TRIGGER_SILENCED_DEPRECATION constant Untrusted callbacks trigger silenced E_USER_DEPRECATION errors.
TrustedCallbackInterface::TRIGGER_WARNING constant Untrusted callbacks trigger E_USER_WARNING errors.