function _tour_update_joyride in Drupal 9

Updates a tour to make it compatible with the Shepherd library.

@internal

@todo https://www.drupal.org/i/3195823 Remove once deprecated properties are no longer supported.

Parameters

\Drupal\tour\Entity\Tour $tour: The tour to update.

bool $trigger_deprecation: (optional) Whether to trigger deprecations. Defaults to TRUE.

Return value

bool Whether or not the entity needs saving.

See also

tour_post_update_joyride_selectors_to_selector_property()

2 calls to _tour_update_joyride()

tour_post_update_joyride_selectors_to_selector_property in core/modules/tour/tour.post_update.php

Convert Joyride selectors to `selector` property.

tour_tour_presave in core/modules/tour/tour.module

Implements hook_ENTITY_TYPE_presave() for tour entities.

File

core/modules/tour/tour.module, line 146

Main functions of the module.

Code

function _tour_update_joyride(Tour $tour, bool $trigger_deprecation = TRUE) : bool {
  $needs_save = FALSE;

  // Update jQuery Joyride based plugins into a new, more structured format that
  // is compatible with Shepherd.
  $tips = $tour
    ->get('tips');
  foreach ($tips as &$tip) {
    if (isset($tip['attributes']['data-class']) || isset($tip['attributes']['data-id'])) {
      if ($trigger_deprecation) {
        @trigger_error("The tour.tip 'attributes' config schema property is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Instead of 'data-class' and 'data-id' attributes, use 'selector' to specify the element a tip attaches to. See https://www.drupal.org/node/3204093", E_USER_DEPRECATED);
      }
      $needs_save = TRUE;
      $selector = isset($tip['attributes']['data-class']) ? ".{$tip['attributes']['data-class']}" : NULL;
      $selector = isset($tip['attributes']['data-id']) ? "#{$tip['attributes']['data-id']}" : $selector;
      $tip['selector'] = $selector;

      // Although the attributes property is deprecated, only the properties
      // with 1:1 equivalents are unset.
      unset($tip['attributes']['data-class'], $tip['attributes']['data-id']);

      // Remove attributes if it is now empty.
      if (empty($tip['attributes'])) {
        unset($tip['attributes']);
      }
    }
    if (isset($tip['location'])) {
      if ($trigger_deprecation) {
        @trigger_error("The tour.tip 'location' config schema property is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Instead use 'position'. The value must be a valid placement accepted by PopperJS. See https://www.drupal.org/node/3204093", E_USER_DEPRECATED);
      }
      $needs_save = TRUE;

      // Joyride only supports four location options: 'top', 'bottom',
      // 'left', and 'right'. Shepherd also accepts these as options, but they
      // result in different behavior. A given Joyride location option will
      // provide the same results in Shepherd if '-start' is appended to it (
      // e.g. the 'left-start' option in Shepherd positions the element the
      // same way that 'left' does in Joyride.
      //
      // @see https://shepherdjs.dev/docs/Step.html
      $tip['position'] = $tip['location'] . '-start';
      unset($tip['location']);
    }
  }
  if ($needs_save) {
    $tour
      ->set('tips', $tips);
  }
  return $needs_save;
}