PluginBase.php 20.6 KB
Newer Older
1 2
<?php

3
namespace Drupal\views\Plugin\views;
4

5
use Drupal\Component\Plugin\DependentPluginInterface;
6
use Drupal\Component\Utility\Xss;
7
use Drupal\Core\Form\FormStateInterface;
8
use Drupal\Core\Language\LanguageInterface;
9
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
10
use Drupal\Core\Plugin\PluginBase as ComponentPluginBase;
11
use Drupal\Core\Render\Element;
12
use Drupal\Core\StringTranslation\TranslatableMarkup;
13 14
use Drupal\views\Plugin\views\display\DisplayPluginBase;
use Drupal\views\ViewExecutable;
15
use Symfony\Component\DependencyInjection\ContainerInterface;
16

17 18 19 20 21 22 23 24 25 26 27
/**
 * Base class for any views plugin types.
 *
 * Via the @Plugin definition the plugin may specify a theme function or
 * template to be used for the plugin. It also can auto-register the theme
 * implementation for that file or function.
 * - theme: the theme implementation to use in the plugin. This may be the name
 *   of the function (without theme_ prefix) or the template file (without
 *   template engine extension).
 *   If a template file should be used, the file has to be placed in the
 *   module's templates folder.
28 29
 *   Example: theme = "mymodule_row" of module "mymodule" will implement
 *   mymodule-row.html.twig in the [..]/modules/mymodule/templates folder.
30 31 32 33 34 35 36 37
 * - register_theme: (optional) When set to TRUE (default) the theme is
 *   registered automatically. When set to FALSE the plugin reuses an existing
 *   theme implementation, defined by another module or views plugin.
 * - theme_file: (optional) the location of an include file that may hold the
 *   theme or preprocess function. The location has to be relative to module's
 *   root directory.
 * - module: machine name of the module. It must be present for any plugin that
 *   wants to register a theme.
38 39
 *
 * @ingroup views_plugins
40
 */
41
abstract class PluginBase extends ComponentPluginBase implements ContainerFactoryPluginInterface, ViewsPluginInterface, DependentPluginInterface {
42

43 44 45 46 47 48 49
  /**
   * Include negotiated languages when listing languages.
   *
   * @see \Drupal\views\Plugin\views\PluginBase::listLanguages()
   */
  const INCLUDE_NEGOTIATED = 16;

50 51 52 53 54 55 56
  /**
   * Include entity row languages when listing languages.
   *
   * @see \Drupal\views\Plugin\views\PluginBase::listLanguages()
   */
  const INCLUDE_ENTITY = 32;

57 58 59 60 61 62 63
  /**
   * Query string to indicate the site default language.
   *
   * @see \Drupal\Core\Language\LanguageInterface::LANGCODE_DEFAULT
   */
  const VIEWS_QUERY_LANGUAGE_SITE_DEFAULT = '***LANGUAGE_site_default***';

64
  /**
65
   * Options for this plugin will be held here.
66 67
   *
   * @var array
68
   */
69
  public $options = [];
70 71 72 73

  /**
   * The top object of a view.
   *
74
   * @var \Drupal\views\ViewExecutable
75
   */
76
  public $view = NULL;
77

78 79 80 81 82 83 84
  /**
   * The display object this plugin is for.
   *
   * For display plugins this is empty.
   *
   * @todo find a better description
   *
85
   * @var \Drupal\views\Plugin\views\display\DisplayPluginBase
86 87 88
   */
  public $displayHandler;

89
  /**
90
   * Plugins's definition
91 92 93
   *
   * @var array
   */
94
  public $definition;
95

96
  /**
97 98 99 100
   * Denotes whether the plugin has an additional options form.
   *
   * @var bool
   */
101
  protected $usesOptions = FALSE;
102

103 104 105 106 107 108
  /**
   * Stores the render API renderer.
   *
   * @var \Drupal\Core\Render\RendererInterface
   */
  protected $renderer;
109

aspilicious's avatar
aspilicious committed
110
  /**
111 112 113 114 115 116 117 118
   * Constructs a PluginBase object.
   *
   * @param array $configuration
   *   A configuration array containing information about the plugin instance.
   * @param string $plugin_id
   *   The plugin_id for the plugin instance.
   * @param mixed $plugin_definition
   *   The plugin implementation definition.
aspilicious's avatar
aspilicious committed
119
   */
120
  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
121
    parent::__construct($configuration, $plugin_id, $plugin_definition);
122

123
    $this->definition = $plugin_definition + $configuration;
aspilicious's avatar
aspilicious committed
124 125
  }

126 127 128
  /**
   * {@inheritdoc}
   */
129
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
130 131 132
    return new static($configuration, $plugin_id, $plugin_definition);
  }

133
  /**
134
   * {@inheritdoc}
135 136 137
   */
  public function init(ViewExecutable $view, DisplayPluginBase $display, array &$options = NULL) {
    $this->view = $view;
138
    $this->setOptionDefaults($this->options, $this->defineOptions());
139 140 141 142 143
    $this->displayHandler = $display;

    $this->unpackOptions($this->options, $options);
  }

144 145 146 147 148 149 150 151 152
  /**
   * Information about options for all kinds of purposes will be held here.
   * @code
   * 'option_name' => array(
   *  - 'default' => default value,
   *  - 'contains' => (optional) array of items this contains, with its own
   *      defaults, etc. If contains is set, the default will be ignored and
   *      assumed to be array().
   *  ),
153
   * @endcode
154 155 156 157
   *
   * @return array
   *   Returns the options of this handler/plugin.
   */
158 159 160
  protected function defineOptions() {
    return [];
  }
161

162 163 164 165 166 167 168 169
  /**
   * Fills up the options of the plugin with defaults.
   *
   * @param array $storage
   *   An array which stores the actual option values of the plugin.
   * @param array $options
   *   An array which describes the options of a plugin. Each element is an
   *   associative array containing:
170
   *   - default: The default value of one option. Should be translated to the
171
   *     interface text language selected for page if translatable.
172 173 174 175 176 177
   *   - (optional) contains: An array which describes the available options
   *     under the key. If contains is set, the default will be ignored and
   *     assumed to be an empty array.
   *   - (optional) 'bool': TRUE if the value is boolean, else FALSE.
   */
  protected function setOptionDefaults(array &$storage, array $options) {
178
    foreach ($options as $option => $definition) {
179
      if (isset($definition['contains'])) {
180
        $storage[$option] = [];
181
        $this->setOptionDefaults($storage[$option], $definition['contains']);
182 183
      }
      else {
184
        $storage[$option] = $definition['default'];
185 186
      }
    }
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
  }

  /**
   * {@inheritdoc}
   */
  public function filterByDefinedOptions(array &$storage) {
    $this->doFilterByDefinedOptions($storage, $this->defineOptions());
  }

  /**
   * Do the work to filter out stored options depending on the defined options.
   *
   * @param array $storage
   *   The stored options.
   * @param array $options
   *   The defined options.
   */
  protected function doFilterByDefinedOptions(array &$storage, array $options) {
    foreach ($storage as $key => $sub_storage) {
      if (!isset($options[$key])) {
        unset($storage[$key]);
      }

      if (isset($options[$key]['contains'])) {
        $this->doFilterByDefinedOptions($storage[$key], $options[$key]['contains']);
      }
    }
214 215 216
  }

  /**
217
   * {@inheritdoc}
218
   */
219
  public function unpackOptions(&$storage, $options, $definition = NULL, $all = TRUE, $check = TRUE) {
220 221 222 223 224
    if ($check && !is_array($options)) {
      return;
    }

    if (!isset($definition)) {
225
      $definition = $this->defineOptions();
226 227 228 229 230 231 232 233 234 235
    }

    foreach ($options as $key => $value) {
      if (is_array($value)) {
        // Ignore arrays with no definition.
        if (!$all && empty($definition[$key])) {
          continue;
        }

        if (!isset($storage[$key]) || !is_array($storage[$key])) {
236
          $storage[$key] = [];
237 238 239 240 241 242 243 244 245 246
        }

        // If we're just unpacking our known options, and we're dropping an
        // unknown array (as might happen for a dependent plugin fields) go
        // ahead and drop that in.
        if (!$all && isset($definition[$key]) && !isset($definition[$key]['contains'])) {
          $storage[$key] = $value;
          continue;
        }

247
        $this->unpackOptions($storage[$key], $value, isset($definition[$key]['contains']) ? $definition[$key]['contains'] : [], $all, FALSE);
248
      }
249
      elseif ($all || !empty($definition[$key])) {
250 251 252 253 254
        $storage[$key] = $value;
      }
    }
  }

255
  /**
256
   * {@inheritdoc}
257
   */
258
  public function destroy() {
259
    unset($this->view, $this->display, $this->query);
260 261 262
  }

  /**
263
   * {@inheritdoc}
264
   */
265
  public function buildOptionsForm(&$form, FormStateInterface $form_state) {
266
    // Some form elements belong in a fieldset for presentation, but can't
267
    // be moved into one because of the $form_state->getValues() hierarchy. Those
268
    // elements can add a #fieldset => 'fieldset_name' property, and they'll
269
    // be moved to their fieldset during pre_render.
270
    $form['#pre_render'][] = [get_class($this), 'preRenderAddFieldsetMarkup'];
271 272 273
  }

  /**
274
   * {@inheritdoc}
275
   */
276
  public function validateOptionsForm(&$form, FormStateInterface $form_state) {}
277 278

  /**
279
   * {@inheritdoc}
280
   */
281
  public function submitOptionsForm(&$form, FormStateInterface $form_state) {}
282 283

  /**
284
   * {@inheritdoc}
285
   */
286
  public function query() {}
287 288

  /**
289
   * {@inheritdoc}
290
   */
291
  public function themeFunctions() {
292
    return $this->view->buildThemeFunctions($this->definition['theme']);
293 294 295
  }

  /**
296
   * {@inheritdoc}
297
   */
298 299 300
  public function validate() {
    return [];
  }
301 302

  /**
303
   * {@inheritdoc}
304
   */
305
  public function summaryTitle() {
306
    return $this->t('Settings');
307
  }
308

309
  /**
310
   * {@inheritdoc}
311
   */
312
  public function pluginTitle() {
313 314
    // Short_title is optional so its defaults to an empty string.
    if (!empty($this->definition['short_title'])) {
315
      return $this->definition['short_title'];
316
    }
317
    return $this->definition['title'];
318
  }
319

320
  /**
321
   * {@inheritdoc}
322
   */
323
  public function usesOptions() {
324 325 326
    return $this->usesOptions;
  }

327
  /**
328
   * {@inheritdoc}
329
   */
330 331
  public function globalTokenReplace($string = '', array $options = []) {
    return \Drupal::token()->replace($string, ['view' => $this->view], $options);
332 333
  }

334
  /**
335 336
   * Replaces Views' tokens in a given string. The resulting string will be
   * sanitized with Xss::filterAdmin.
337 338
   *
   * @param $text
339
   *   Unsanitized string with possible tokens.
340 341 342
   * @param $tokens
   *   Array of token => replacement_value items.
   *
alexpott's avatar
alexpott committed
343
   * @return string
344 345
   */
  protected function viewsTokenReplace($text, $tokens) {
346 347 348 349
    if (!strlen($text)) {
      // No need to run filterAdmin on an empty string.
      return '';
    }
350
    if (empty($tokens)) {
351
      return Xss::filterAdmin($text);
352 353
    }

354
    $twig_tokens = [];
355
    foreach ($tokens as $token => $replacement) {
356 357
      // Twig wants a token replacement array stripped of curly-brackets.
      // Some Views tokens come with curly-braces, others do not.
358
      // @todo: https://www.drupal.org/node/2544392
359 360
      if (strpos($token, '{{') !== FALSE) {
        // Twig wants a token replacement array stripped of curly-brackets.
361 362
        $token = trim(str_replace(['{{', '}}'], '', $token));
      }
363

364 365 366 367
      // Check for arrays in Twig tokens. Internally these are passed as
      // dot-delimited strings, but need to be turned into associative arrays
      // for parsing.
      if (strpos($token, '.') === FALSE) {
368 369
        // We need to validate tokens are valid Twig variables. Twig uses the
        // same variable naming rules as PHP.
370
        // @see http://php.net/manual/language.variables.basics.php
371
        assert('preg_match(\'/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/\', $token) === 1', 'Tokens need to be valid Twig variables.');
372 373 374
        $twig_tokens[$token] = $replacement;
      }
      else {
375 376 377
        $parts = explode('.', $token);
        $top = array_shift($parts);
        assert('preg_match(\'/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/\', $top) === 1', 'Tokens need to be valid Twig variables.');
378
        $token_array = [array_pop($parts) => $replacement];
379
        foreach (array_reverse($parts) as $key) {
380 381
          // The key could also be numeric (array index) so allow that.
          assert('is_numeric($key) || (preg_match(\'/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/\', $key) === 1)', 'Tokens need to be valid Twig variables.');
382
          $token_array = [$key => $token_array];
383
        }
384 385 386 387
        if (!isset($twig_tokens[$top])) {
          $twig_tokens[$top] = [];
        }
        $twig_tokens[$top] += $token_array;
388 389 390
      }
    }

391 392 393 394
    if ($twig_tokens) {
      // Use the unfiltered text for the Twig template, then filter the output.
      // Otherwise, Xss::filterAdmin could remove valid Twig syntax before the
      // template is parsed.
395

396
      $build = [
397 398 399
        '#type' => 'inline_template',
        '#template' => $text,
        '#context' => $twig_tokens,
400 401 402 403 404
        '#post_render' => [
          function ($children, $elements) {
            return Xss::filterAdmin($children);
          }
        ],
405
      ];
406

407 408 409 410 411
      // Currently you cannot attach assets to tokens with
      // Renderer::renderPlain(). This may be unnecessarily limiting. Consider
      // using Renderer::executeInRenderContext() instead.
      // @todo: https://www.drupal.org/node/2566621
      return (string) $this->getRenderer()->renderPlain($build);
412 413
    }
    else {
414
      return Xss::filterAdmin($text);
415 416 417
    }
  }

418
  /**
419
   * {@inheritdoc}
420
   */
421
  public function getAvailableGlobalTokens($prepared = FALSE, array $types = []) {
422
    $info = \Drupal::token()->getInfo();
423
    // Site and view tokens should always be available.
424
    $types += ['site', 'view'];
425 426 427 428
    $available = array_intersect_key($info['tokens'], array_flip($types));

    // Construct the token string for each token.
    if ($prepared) {
429
      $prepared = [];
430 431 432 433 434 435 436 437 438 439 440 441 442
      foreach ($available as $type => $tokens) {
        foreach (array_keys($tokens) as $token) {
          $prepared[$type][] = "[$type:$token]";
        }
      }

      return $prepared;
    }

    return $available;
  }

  /**
443
   * {@inheritdoc}
444
   */
445
  public function globalTokenForm(&$form, FormStateInterface $form_state) {
446
    $token_items = [];
447 448

    foreach ($this->getAvailableGlobalTokens() as $type => $tokens) {
449
      $item = [
450
        '#markup' => $type,
451 452
        'children' => [],
      ];
453 454 455 456 457 458 459
      foreach ($tokens as $name => $info) {
        $item['children'][$name] = "[$type:$name]" . ' - ' . $info['name'] . ': ' . $info['description'];
      }

      $token_items[$type] = $item;
    }

460
    $form['global_tokens'] = [
461
      '#type' => 'details',
462
      '#title' => $this->t('Available global token replacements'),
463 464
    ];
    $form['global_tokens']['list'] = [
465 466
      '#theme' => 'item_list',
      '#items' => $token_items,
467 468 469 470
      '#attributes' => [
        'class' => ['global-tokens'],
      ],
    ];
471 472
  }

473
  /**
474
   * {@inheritdoc}
475 476
   */
  public static function preRenderAddFieldsetMarkup(array $form) {
477
    foreach (Element::children($form) as $key) {
478 479 480 481 482 483 484 485 486 487 488 489 490 491
      $element = $form[$key];
      // In our form builder functions, we added an arbitrary #fieldset property
      // to any element that belongs in a fieldset. If this form element has
      // that property, move it into its fieldset.
      if (isset($element['#fieldset']) && isset($form[$element['#fieldset']])) {
        $form[$element['#fieldset']][$key] = $element;
        // Remove the original element this duplicates.
        unset($form[$key]);
      }
    }
    return $form;
  }

  /**
492
   * {@inheritdoc}
493 494
   */
  public static function preRenderFlattenData($form) {
495
    foreach (Element::children($form) as $key) {
496 497
      $element = $form[$key];
      if (!empty($element['#flatten'])) {
498
        foreach (Element::children($element) as $child_key) {
499 500 501 502 503 504 505 506 507 508
          $form[$child_key] = $form[$key][$child_key];
        }
        // All done, remove the now-empty parent.
        unset($form[$key]);
      }
    }

    return $form;
  }

509
  /**
510
   * {@inheritdoc}
511
   */
512 513 514 515 516 517 518 519 520 521
  public function calculateDependencies() {
    return [];
  }

  /**
   * {@inheritdoc}
   */
  public function getProvider() {
    $definition = $this->getPluginDefinition();
    return $definition['provider'];
522 523
  }

524 525 526 527 528 529 530 531 532 533 534 535 536
  /**
   * Makes an array of languages, optionally including special languages.
   *
   * @param int $flags
   *   (optional) Flags for which languages to return (additive). Options:
   *   - \Drupal\Core\Language::STATE_ALL (default): All languages
   *     (configurable and default).
   *   - \Drupal\Core\Language::STATE_CONFIGURABLE: Configurable languages.
   *   - \Drupal\Core\Language::STATE_LOCKED: Locked languages.
   *   - \Drupal\Core\Language::STATE_SITE_DEFAULT: Add site default language;
   *     note that this is not included in STATE_ALL.
   *   - \Drupal\views\Plugin\views\PluginBase::INCLUDE_NEGOTIATED: Add
   *     negotiated language types.
537 538 539
   *   - \Drupal\views\Plugin\views\PluginBase::INCLUDE_ENTITY: Add
   *     entity row language types. Note that these are only supported for
   *     display options, not substituted in queries.
540 541
   * @param array|null $current_values
   *   The currently-selected options in the list, if available.
542 543 544 545
   *
   * @return array
   *   An array of language names, keyed by the language code. Negotiated and
   *   special languages have special codes that are substituted in queries by
546
   *   PluginBase::queryLanguageSubstitutions().
547 548
   *   Only configurable languages and languages that are in $current_values are
   *   included in the list.
549
   */
550
  protected function listLanguages($flags = LanguageInterface::STATE_ALL, array $current_values = NULL) {
551
    $manager = \Drupal::languageManager();
552
    $languages = $manager->getLanguages($flags);
553
    $list = [];
554

555 556 557 558 559 560
    // The entity languages should come first, if requested.
    if ($flags & PluginBase::INCLUDE_ENTITY) {
      $list['***LANGUAGE_entity_translation***'] = $this->t('Content language of view row');
      $list['***LANGUAGE_entity_default***'] = $this->t('Original language of content in view row');
    }

561 562
    // STATE_SITE_DEFAULT comes in with ID set
    // to LanguageInterface::LANGCODE_SITE_DEFAULT.
563 564
    // Since this is not a real language, surround it by '***LANGUAGE_...***',
    // like the negotiated languages below.
565
    if ($flags & LanguageInterface::STATE_SITE_DEFAULT) {
566 567 568 569
      $name = $languages[LanguageInterface::LANGCODE_SITE_DEFAULT]->getName();
      // The language name may have already been translated, no need to
      // translate it again.
      // @see Drupal\Core\Language::filterLanguages().
570
      if (!$name instanceof TranslatableMarkup) {
571 572 573
        $name = $this->t($name);
      }
      $list[PluginBase::VIEWS_QUERY_LANGUAGE_SITE_DEFAULT] = $name;
574 575 576
      // Remove site default language from $languages so it's not added
      // twice with the real languages below.
      unset($languages[LanguageInterface::LANGCODE_SITE_DEFAULT]);
577 578 579 580
    }

    // Add in negotiated languages, if requested.
    if ($flags & PluginBase::INCLUDE_NEGOTIATED) {
581 582 583 584 585 586 587 588
      $types_info = $manager->getDefinedLanguageTypesInfo();
      $types = $manager->getLanguageTypes();
      // We only go through the configured types.
      foreach ($types as $id) {
        if (isset($types_info[$id]['name'])) {
          $name = $types_info[$id]['name'];
          // Surround IDs by '***LANGUAGE_...***', to avoid query collisions.
          $id = '***LANGUAGE_' . $id . '***';
589
          $list[$id] = $this->t('@type language selected for page', ['@type' => $name]);
590 591 592 593
        }
      }
      if (!empty($current_values)) {
        foreach ($types_info as $id => $type) {
594
          $id = '***LANGUAGE_' . $id . '***';
595 596 597 598
          // If this (non-configurable) type is among the current values,
          // add that option too, so it is not lost. If not among the current
          // values, skip displaying it to avoid user confusion.
          if (isset($type['name']) && !isset($list[$id]) && in_array($id, $current_values)) {
599
            $list[$id] = $this->t('@type language selected for page', ['@type' => $type['name']]);
600
          }
601 602 603 604
        }
      }
    }

605 606
    // Add real languages.
    foreach ($languages as $id => $language) {
607
      $list[$id] = $language->getName();
608 609
    }

610 611 612 613 614 615 616
    return $list;
  }

  /**
   * Returns substitutions for Views queries for languages.
   *
   * This is needed so that the language options returned by
617
   * PluginBase::listLanguages() are able to be used in queries. It is called
618 619 620 621 622 623 624 625
   * by the Views module implementation of hook_views_query_substitutions()
   * to get the language-related substitutions.
   *
   * @return array
   *   An array in the format of hook_views_query_substitutions() that gives
   *   the query substitutions needed for the special language types.
   */
  public static function queryLanguageSubstitutions() {
626
    $changes = [];
627 628 629
    $manager = \Drupal::languageManager();

    // Handle default language.
630
    $default = $manager->getDefaultLanguage()->getId();
631
    $changes[PluginBase::VIEWS_QUERY_LANGUAGE_SITE_DEFAULT] = $default;
632 633 634 635 636

    // Handle negotiated languages.
    $types = $manager->getDefinedLanguageTypesInfo();
    foreach ($types as $id => $type) {
      if (isset($type['name'])) {
637
        $changes['***LANGUAGE_' . $id . '***'] = $manager->getCurrentLanguage($id)->getId();
638 639 640 641 642
      }
    }

    return $changes;
  }
643 644 645 646 647 648 649 650 651 652 653 654 655 656

  /**
   * Returns the render API renderer.
   *
   * @return \Drupal\Core\Render\RendererInterface
   */
  protected function getRenderer() {
    if (!isset($this->renderer)) {
      $this->renderer = \Drupal::service('renderer');
    }

    return $this->renderer;
  }

657
}