www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/views/src/Plugin/views/display/DisplayPluginInterface.php

   1 <?php
   2
   3 namespace Drupal\views\Plugin\views\display;
   4
   5 use Drupal\views\ViewExecutable;
   6 use Drupal\Core\Form\FormStateInterface;
   7 use Drupal\Core\Session\AccountInterface;
   8
   9 /**
  10  * @defgroup views_display_plugins Views display plugins
  11  * @{
  12  * Plugins to handle the overall display of views.
  13  *
  14  * Display plugins are responsible for controlling where a view is rendered;
  15  * that is, how it is exposed to other parts of Drupal. 'Page' and 'block' are
  16  * the most commonly used display plugins. Each view also has a 'master' (or
  17  * 'default') display that includes information shared between all its
  18  * displays (see \Drupal\views\Plugin\views\display\DefaultDisplay).
  19  *
  20  * Display plugins extend \Drupal\views\Plugin\views\display\DisplayPluginBase.
  21  * They must be annotated with \Drupal\views\Annotation\ViewsDisplay
  22  * annotation, and they must be in namespace directory Plugin\views\display.
  23  *
  24  * @ingroup views_plugins
  25  *
  26  * @see plugin_api
  27  * @see views_display_extender_plugins
  28  */
  29
  30 /**
  31  * Provides an interface for Views display plugins.
  32  */
  33 interface DisplayPluginInterface {
  34
  35   /**
  36    * Initializes the display plugin.
  37    *
  38    * @param \Drupal\views\ViewExecutable $view
  39    *   The views executable.
  40    * @param array $display
  41    *   The display that will be populated and attached to the view.
  42    * @param array $options
  43    *   (optional) The options for the display plugin. Defaults to NULL.
  44    */
  45   public function initDisplay(ViewExecutable $view, array &$display, array &$options = NULL);
  46
  47   /**
  48    * Destroys the display's components and the display itself.
  49    */
  50   public function destroy();
  51
  52   /**
  53    * Determines if this display is the 'default' display.
  54    *
  55    * 'Default' display contains fallback settings.
  56    */
  57   public function isDefaultDisplay();
  58
  59   /**
  60    * Determines if this display uses exposed filters.
  61    */
  62   public function usesExposed();
  63
  64   /**
  65    * Determines if this display should display the exposed filters widgets.
  66    *
  67    * Regardless of what this function
  68    * returns, exposed filters will not be used nor
  69    * displayed unless usesExposed() returns TRUE.
  70    */
  71   public function displaysExposed();
  72
  73   /**
  74    * Whether the display allows the use of AJAX or not.
  75    *
  76    * @return bool
  77    */
  78   public function usesAJAX();
  79
  80   /**
  81    * Whether the display is actually using AJAX or not.
  82    *
  83    * @return bool
  84    */
  85   public function ajaxEnabled();
  86
  87   /**
  88    * Whether the display is enabled.
  89    *
  90    * @return bool
  91    *   Returns TRUE if the display is marked as enabled, else FALSE.
  92    */
  93   public function isEnabled();
  94
  95   /**
  96    * Whether the display allows the use of a pager or not.
  97    *
  98    * @return bool
  99    */
 100   public function usesPager();
 101
 102   /**
 103    * Whether the display is using a pager or not.
 104    *
 105    * @return bool
 106    */
 107   public function isPagerEnabled();
 108
 109   /**
 110    * Whether the display allows the use of a 'more' link or not.
 111    *
 112    * @return bool
 113    */
 114   public function usesMore();
 115
 116   /**
 117    * Whether the display is using the 'more' link or not.
 118    *
 119    * @return bool
 120    */
 121   public function isMoreEnabled();
 122
 123   /**
 124    * Does the display have groupby enabled?
 125    */
 126   public function useGroupBy();
 127
 128   /**
 129    * Should the enabled display more link be shown when no more items?
 130    */
 131   public function useMoreAlways();
 132
 133   /**
 134    * Does the display have custom link text?
 135    */
 136   public function useMoreText();
 137
 138   /**
 139    * Determines whether this display can use attachments.
 140    *
 141    * @return bool
 142    */
 143   public function acceptAttachments();
 144
 145   /**
 146    * Returns whether the display can use attachments.
 147    *
 148    * @return bool
 149    */
 150   public function usesAttachments();
 151
 152   /**
 153    * Returns whether the display can use areas.
 154    *
 155    * @return bool
 156    *   TRUE if the display can use areas, or FALSE otherwise.
 157    */
 158   public function usesAreas();
 159
 160   /**
 161    * Allows displays to attach to other views.
 162    *
 163    * @param \Drupal\views\ViewExecutable $view
 164    *   The views executable.
 165    * @param string $display_id
 166    *   The display to attach to.
 167    * @param array $build
 168    *   The parent view render array.
 169    */
 170   public function attachTo(ViewExecutable $view, $display_id, array &$build);
 171
 172   /**
 173    * Lists the 'defaultable' sections and what items each section contains.
 174    */
 175   public function defaultableSections($section = NULL);
 176
 177   /**
 178    * Checks to see if the display has a 'path' field.
 179    *
 180    * This is a pure function and not just a setting on the definition
 181    * because some displays (such as a panel pane) may have a path based
 182    * upon configuration.
 183    *
 184    * By default, displays do not have a path.
 185    */
 186   public function hasPath();
 187
 188   /**
 189    * Checks to see if the display has some need to link to another display.
 190    *
 191    * For the most part, displays without a path will use a link display.
 192    * However, sometimes displays that have a path might also need to link to
 193    * another display. This is true for feeds.
 194    */
 195   public function usesLinkDisplay();
 196
 197   /**
 198    * Checks to see if the display can put the exposed form in a block.
 199    *
 200    * By default, displays that do not have a path cannot disconnect
 201    * the exposed form and put it in a block, because the form has no
 202    * place to go and Views really wants the forms to go to a specific
 203    * page.
 204    */
 205   public function usesExposedFormInBlock();
 206
 207   /**
 208    * Find out all displays which are attached to this display.
 209    *
 210    * The method is just using the pure storage object to avoid loading of the
 211    * sub displays which would kill lazy loading.
 212    */
 213   public function getAttachedDisplays();
 214
 215   /**
 216    * Returns the ID of the display to use when making links.
 217    */
 218   public function getLinkDisplay();
 219
 220   /**
 221    * Returns the base path to use for this display.
 222    *
 223    * This can be overridden for displays that do strange things
 224    * with the path.
 225    */
 226   public function getPath();
 227
 228   /**
 229    * Points to the display which can be linked by this display.
 230    *
 231    * If the display has route information, the display itself is returned.
 232    * Otherwise, the configured linked display is returned. For example, if a
 233    * block display links to a page display, the page display will be returned
 234    * in both cases.
 235    *
 236    * @return \Drupal\views\Plugin\views\display\DisplayRouterInterface|null
 237    */
 238   public function getRoutedDisplay();
 239
 240   /**
 241    * Returns a URL to $this display or its configured linked display.
 242    *
 243    * @return \Drupal\Core\Url|null
 244    */
 245   public function getUrl();
 246
 247   /**
 248    * Determines if an option is set to use the default or current display.
 249    *
 250    * @return
 251    *   TRUE for the default display.
 252    */
 253   public function isDefaulted($option);
 254
 255   /**
 256    * Gets an option, from this display or the default display.
 257    */
 258   public function getOption($option);
 259
 260   /**
 261    * Determines if the display's style uses fields.
 262    *
 263    * @return bool
 264    */
 265   public function usesFields();
 266
 267   /**
 268    * Get the instance of a plugin, for example style or row.
 269    *
 270    * @param string $type
 271    *   The type of the plugin.
 272    *
 273    * @return \Drupal\views\Plugin\views\ViewsPluginInterface
 274    */
 275   public function getPlugin($type);
 276
 277   /**
 278    * Get the handler object for a single handler.
 279    */
 280   public function getHandler($type, $id);
 281
 282   /**
 283    * Get a full array of handlers for $type. This caches them.
 284    *
 285    * @return \Drupal\views\Plugin\views\ViewsHandlerInterface[]
 286    */
 287   public function getHandlers($type);
 288
 289   /**
 290    * Retrieves a list of fields for the current display.
 291    *
 292    * This also takes into account any associated relationships, if they exist.
 293    *
 294    * @param bool $groupable_only
 295    *   (optional) TRUE to only return an array of field labels from handlers
 296    *   that support the useStringGroupBy method, defaults to FALSE.
 297    *
 298    * @return array
 299    *   An array of applicable field options, keyed by ID.
 300    */
 301   public function getFieldLabels($groupable_only = FALSE);
 302
 303   /**
 304    * Sets an option, on this display or the default display.
 305    */
 306   public function setOption($option, $value);
 307
 308   /**
 309    * Set an option and force it to be an override.
 310    */
 311   public function overrideOption($option, $value);
 312
 313   /**
 314    * Returns a link to a section of a form.
 315    *
 316    * Because forms may be split up into sections, this provides an easy URL
 317    * to exactly the right section. Don't override this.
 318    */
 319   public function optionLink($text, $section, $class = '', $title = '');
 320
 321   /**
 322    * Returns to tokens for arguments.
 323    *
 324    * This function is similar to views_handler_field::getRenderTokens()
 325    * but without fields tokens.
 326    */
 327   public function getArgumentsTokens();
 328
 329   /**
 330    * Provides the default summary for options in the views UI.
 331    *
 332    * This output is returned as an array.
 333    */
 334   public function optionsSummary(&$categories, &$options);
 335
 336   /**
 337    * Provides the default form for setting options.
 338    */
 339   public function buildOptionsForm(&$form, FormStateInterface $form_state);
 340
 341   /**
 342    * Validates the options form.
 343    */
 344   public function validateOptionsForm(&$form, FormStateInterface $form_state);
 345
 346   /**
 347    * Performs any necessary changes to the form values prior to storage.
 348    *
 349    * There is no need for this function to actually store the data.
 350    */
 351   public function submitOptionsForm(&$form, FormStateInterface $form_state);
 352
 353   /**
 354    * If override/revert was clicked, perform the proper toggle.
 355    */
 356   public function optionsOverride($form, FormStateInterface $form_state);
 357
 358   /**
 359    * Flip the override setting for the given section.
 360    *
 361    * @param string $section
 362    *   Which option should be marked as overridden, for example "filters".
 363    * @param bool $new_state
 364    *   Select the new state of the option:
 365    *   - TRUE: Revert new state option to default.
 366    *   - FALSE: Mark it as overridden.
 367    */
 368   public function setOverride($section, $new_state = NULL);
 369
 370   /**
 371    * Injects anything into the query that the display handler needs.
 372    */
 373   public function query();
 374
 375   /**
 376    * Does nothing (obsolete function).
 377    *
 378    * @todo This function no longer seems to be used.
 379    */
 380   public function renderFilters();
 381
 382   /**
 383    * Checks to see if the display plugins support pager rendering.
 384    */
 385   public function renderPager();
 386
 387   /**
 388    * Renders the 'more' link.
 389    */
 390   public function renderMoreLink();
 391
 392   /**
 393    * Renders this display.
 394    */
 395   public function render();
 396
 397   /**
 398    * #pre_render callback for view display rendering.
 399    *
 400    * @see self::render()
 401    *
 402    * @param array $element
 403    *   The element to #pre_render
 404    *
 405    * @return array
 406    *   The processed element.
 407    */
 408   public function elementPreRender(array $element);
 409
 410   /**
 411    * Renders one of the available areas.
 412    *
 413    * @param string $area
 414    *   Identifier of the specific area to render.
 415    * @param bool $empty
 416    *   (optional) Indicator whether or not the view result is empty. Defaults to
 417    *   FALSE
 418    *
 419    * @return array
 420    *   A render array for the given area.
 421    */
 422   public function renderArea($area, $empty = FALSE);
 423
 424   /**
 425    * Determines if the user has access to this display of the view.
 426    */
 427   public function access(AccountInterface $account = NULL);
 428
 429   /**
 430    * Sets up any variables on the view prior to execution.
 431    *
 432    * These are separated from execute because they are extremely common
 433    * and unlikely to be overridden on an individual display.
 434    */
 435   public function preExecute();
 436
 437   /**
 438    * Calculates the display's cache metadata by inspecting each handler/plugin.
 439    *
 440    * @return \Drupal\Core\Cache\CacheableMetadata
 441    *   The cache metadata.
 442    */
 443   public function calculateCacheMetadata();
 444
 445   /**
 446    * Gets the cache metadata.
 447    *
 448    * @return \Drupal\Core\Cache\CacheableMetadata
 449    *   The cache metadata.
 450    */
 451   public function getCacheMetadata();
 452
 453   /**
 454    * Executes the view and returns data in the format required.
 455    *
 456    * The base class cannot be executed.
 457    */
 458   public function execute();
 459
 460
 461   /**
 462    * Builds a basic render array which can be properly render cached.
 463    *
 464    * In order to be rendered cached, it includes cache keys as well as the data
 465    * required to load the view on cache misses.
 466    *
 467    * @param string $view_id
 468    *   The view ID.
 469    * @param string $display_id
 470    *   The display ID.
 471    * @param array $args
 472    *   (optional) The view arguments.
 473    *
 474    * @return array
 475    *   The view render array.
 476    */
 477   public static function buildBasicRenderable($view_id, $display_id, array $args = []);
 478
 479   /**
 480    * Builds a renderable array of the view.
 481    *
 482    * Note: This does not yet contain the executed view, but just the loaded view
 483    * executable.
 484    *
 485    * @param array $args
 486    *   (optional) Arguments of the view.
 487    * @param bool $cache
 488    *   (optional) Specify FALSE in order to opt out of render caching.
 489    *
 490    * @return array
 491    *   The render array of a view.
 492    */
 493   public function buildRenderable(array $args = [], $cache = TRUE);
 494
 495   /**
 496    * Renders the display for the purposes of a live preview.
 497    *
 498    * Also might be used for some other AJAXy reason.
 499    */
 500   public function preview();
 501
 502   /**
 503    * Returns the display type that this display requires.
 504    *
 505    * This can be used for filtering views plugins. E.g. if a plugin category of
 506    * 'foo' is specified, only plugins with no 'types' declared or 'types'
 507    * containing 'foo'. If you have a type of bar, this plugin will not be used.
 508    * This is applicable for style, row, access, cache, and exposed_form plugins.
 509    *
 510    * @return string
 511    *   The required display type. Defaults to 'normal'.
 512    *
 513    * @see \Drupal\views\Views::fetchPluginNames()
 514    */
 515   public function getType();
 516
 517   /**
 518    * Make sure the display and all associated handlers are valid.
 519    *
 520    * @return
 521    *   Empty array if the display is valid; an array of error strings if it is
 522    *   not.
 523    */
 524   public function validate();
 525
 526   /**
 527    * Reacts on adding a display.
 528    *
 529    * @see \Drupal\views\Entity\View::newDisplay()
 530    */
 531   public function newDisplay();
 532
 533   /**
 534    * Reacts on deleting a display.
 535    */
 536   public function remove();
 537
 538   /**
 539    * Checks if the provided identifier is unique.
 540    *
 541    * @param string $id
 542    *   The id of the handler which is checked.
 543    * @param string $identifier
 544    *   The actual get identifier configured in the exposed settings.
 545    *
 546    * @return bool
 547    *   Returns whether the identifier is unique on all handlers.
 548    */
 549   public function isIdentifierUnique($id, $identifier);
 550
 551   /**
 552    * Is the output of the view empty.
 553    *
 554    * If a view has no result and neither the empty, nor the footer nor the header
 555    * does show anything return FALSE.
 556    *
 557    * @return bool
 558    *   Returns TRUE if the output is empty, else FALSE.
 559    */
 560   public function outputIsEmpty();
 561
 562   /**
 563    * Provides the block system with any exposed widget blocks for this display.
 564    */
 565   public function getSpecialBlocks();
 566
 567   /**
 568    * Renders the exposed form as block.
 569    *
 570    * @return string|null
 571    *   The rendered exposed form as string or NULL otherwise.
 572    */
 573   public function viewExposedFormBlocks();
 574
 575   /**
 576    * Provides help text for the arguments.
 577    *
 578    * @return array
 579    *   Returns an array which contains text for the argument fieldset:
 580    *   - filter value present: The title of the fieldset in the argument
 581    *     where you can configure what should be done with a given argument.
 582    *   - filter value not present: The title of the fieldset in the argument
 583    *     where you can configure what should be done if the argument does not
 584    *     exist.
 585    *   - description: A description about how arguments are passed
 586    *     to the display. For example blocks can't get arguments from url.
 587    */
 588   public function getArgumentText();
 589
 590   /**
 591    * Provides help text for pagers.
 592    *
 593    * @return array
 594    *   Returns an array which contains text for the items_per_page form
 595    *   element:
 596    *   - items per page title: The title text for the items_per_page form
 597    *     element.
 598    *   - items per page description: The description text for the
 599    *     items_per_page form element.
 600    */
 601   public function getPagerText();
 602
 603   /**
 604    * Merges default values for all plugin types.
 605    */
 606   public function mergeDefaults();
 607
 608   /**
 609    * Gets the display extenders.
 610    *
 611    * @return \Drupal\views\Plugin\views\display_extender\DisplayExtenderPluginBase[]
 612    */
 613   public function getExtenders();
 614
 615 }