public function JuiceboxFormatter::buildEmbed in Juicebox HTML5 Responsive Image Galleries 8.2

Same name and namespace in other branches

8.3 src/JuiceboxFormatter.php \Drupal\juicebox\JuiceboxFormatter::buildEmbed()

Build a render array for the embed code of a Juicebox gallery.

Build once images and options have been added.

Note that this is different from Drupal\juicebox\JuiceboxGalleryInterface:renderEmbed() in that it handles ALL considerations for embedding. This includes the addition of the appropriate js and css which would otherwise need to be done independent of renderEmbed(). It also uses the Drupal theme system as opposed to just returning direct markup. Within Drupal this method should always be used.

Parameters

Drupal\juicebox\JuiceboxGalleryInterface $gallery: An fully populated Juicebox gallery object.

array $settings: An associative array of gallery-specific settings.

array $xml_route_info: Associative array of routing info that can be used to generate the URL to the XML. Includes:

route_name: The route name for the gallery XML.
route_parameters: Route parameters for the gallery XML.
options: An optional associative array of options that can be used by Drupal URL methods like Drupal\Core\Routing::generateFromRoute().

bool $add_js: Whether-or-not to add the Juicebox library and gallery-specific javascript.

bool $add_xml: It may be difficult or impossible to rebuild some types of formatters during a separate XML request, so this option offers a way around that by embedding the XML for the gallery directly into the HTML output. This XML can then be fetched from a request to this same page later via a sub-request. If TRUE xml-source-path and xml-source-id query strings are also added to the XML URL to help the XML building logic locate this XML data later. Setting this option may work around certain limitations but will likely lead to slower XML generation.

array $contextual: Optional contextual link information that may be used in the display. This array will be added as-is to the #contextual-links part of the render array that's used for the gallery's embed code.

Return value

array Drupal render array for the embed code that describes a gallery.

Overrides JuiceboxFormatterInterface::buildEmbed

File

src/JuiceboxFormatter.php, line 190

Class

JuiceboxFormatter: Class to define a Drupal service with common formatter methods.

Namespace

Drupal\juicebox

Code

public function buildEmbed(JuiceboxGalleryInterface $gallery, array $settings, array $xml_route_info, $add_js = TRUE, $add_xml = FALSE, array $contextual = []) {

  // Merge all settings.
  $settings = $settings + $this
    ->getGlobalSettings();

  // Set some defaults for the route info.
  $xml_route_info += [
    'route_name' => '',
    'route_parameters' => [],
    'options' => [],
  ];

  // Prep the ids that may be used.
  $embed_id = $gallery
    ->getId();
  $embed_xml_id = 'xml--' . $embed_id;

  // Construct the base render array for the gallery.
  $output = [
    '#gallery' => $gallery,
    '#theme' => 'juicebox_embed_markup',
    '#settings' => $settings,
    '#attached' => [],
    '#contextual_links' => $contextual + [
      'juicebox_conf_global' => [
        'route_parameters' => [],
      ],
    ],
    '#cache' => [
      'tags' => [
        'juicebox_gallery',
      ],
    ],
    '#suffix' => '',
  ];

  // Process JS additions.
  if ($add_js) {

    // If we are also embedding the XML we want to set some query string
    // values on the XML URL that will allow the XML build methods to fetch
    // it later.
    $embed_query_additions = [];
    if ($add_xml) {
      $embed_query_additions['xml-source-path'] = trim($this->currentPathStack
        ->getPath(), '/');
      $embed_query_additions['xml-source-id'] = $embed_xml_id;
    }

    // Add some query params that apply to all types of Juicebox galleries and
    // generate the final XML URL.
    $xml_query_additions = array_merge([
      'checksum' => $gallery
        ->getChecksum(),
    ], $embed_query_additions);
    $xml_options = array_merge_recursive([
      'query' => $xml_query_additions,
    ], $xml_route_info['options']);
    $xml_url = $this->urlGenerator
      ->generateFromRoute($xml_route_info['route_name'], $xml_route_info['route_parameters'], $xml_options);

    // Add the main library.
    $output['#attached']['library'][] = 'juicebox/juicebox';

    // Add the JS gallery details as Drupal.settings.
    $output['#attached']['drupalSettings']['juicebox'] = [
      $embed_id => $gallery
        ->getJavascriptVars($xml_url),
    ];

    // Add some local JS (implementing Drupal.behaviors) that will process
    // the Drupal.settings above into a new client-side juicebox object.
    $output['#attached']['library'][] = 'juicebox/juicebox.local';
  }
  if ($add_xml) {
    $output['#suffix'] .= $gallery
      ->renderXml($embed_xml_id);
  }

  // Ensure that our suffix is not further sanitized.
  $output['#suffix'] = new FormattableMarkup($output['#suffix'], []);
  return $output;
}

You are here