aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/EntityViewBuilderInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity;
   4
   5 use Drupal\Core\Field\FieldItemInterface;
   6 use Drupal\Core\Field\FieldItemListInterface;
   7
   8 /**
   9  * Defines an interface for entity view builders.
  10  *
  11  * @ingroup entity_api
  12  */
  13 interface EntityViewBuilderInterface {
  14
  15   /**
  16    * Builds the component fields and properties of a set of entities.
  17    *
  18    * @param &$build
  19    *   The renderable array representing the entity content.
  20    * @param \Drupal\Core\Entity\EntityInterface[] $entities
  21    *   The entities whose content is being built.
  22    * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface[] $displays
  23    *   The array of entity view displays holding the display options
  24    *   configured for the entity components, keyed by bundle name.
  25    * @param string $view_mode
  26    *   The view mode in which the entity is being viewed.
  27    */
  28   public function buildComponents(array &$build, array $entities, array $displays, $view_mode);
  29
  30   /**
  31    * Builds the render array for the provided entity.
  32    *
  33    * @param \Drupal\Core\Entity\EntityInterface $entity
  34    *   The entity to render.
  35    * @param string $view_mode
  36    *   (optional) The view mode that should be used to render the entity.
  37    * @param string $langcode
  38    *   (optional) For which language the entity should be rendered, defaults to
  39    *   the current content language.
  40    *
  41    * @return array
  42    *   A render array for the entity.
  43    *
  44    * @throws \InvalidArgumentException
  45    *   Can be thrown when the set of parameters is inconsistent, like when
  46    *   trying to view a Comment and passing a Node which is not the one the
  47    *   comment belongs to, or not passing one, and having the comment node not
  48    *   be available for loading.
  49    */
  50   public function view(EntityInterface $entity, $view_mode = 'full', $langcode = NULL);
  51
  52   /**
  53    * Builds the render array for the provided entities.
  54    *
  55    * @param array $entities
  56    *   An array of entities implementing EntityInterface to view.
  57    * @param string $view_mode
  58    *   (optional) The view mode that should be used to render the entity.
  59    * @param string $langcode
  60    *   (optional) For which language the entity should be rendered, defaults to
  61    *   the current content language.
  62    *
  63    * @return
  64    *   A render array for the entities, indexed by the same keys as the
  65    *   entities array passed in $entities.
  66    *
  67    * @throws \InvalidArgumentException
  68    *   Can be thrown when the set of parameters is inconsistent, like when
  69    *   trying to view Comments and passing a Node which is not the one the
  70    *   comments belongs to, or not passing one, and having the comments node not
  71    *   be available for loading.
  72    */
  73   public function viewMultiple(array $entities = [], $view_mode = 'full', $langcode = NULL);
  74
  75   /**
  76    * Resets the entity render cache.
  77    *
  78    * @param \Drupal\Core\Entity\EntityInterface[] $entities
  79    *   (optional) If specified, the cache is reset for the given entities only.
  80    */
  81   public function resetCache(array $entities = NULL);
  82
  83   /**
  84    * Builds a renderable array for the value of a single field in an entity.
  85    *
  86    * The resulting output is a fully themed field with label and multiple
  87    * values.
  88    *
  89    * This function can be used by third-party modules that need to output an
  90    * isolated field.
  91    * - Do not use inside node (or any other entity) templates; use
  92    *   render($content[FIELD_NAME]) instead.
  93    * - The FieldItemInterface::view() method can be used to output a single
  94    *   formatted field value, without label or wrapping field markup.
  95    *
  96    * The function takes care of invoking the prepare_view steps. It also
  97    * respects field access permissions.
  98    *
  99    * @param \Drupal\Core\Field\FieldItemListInterface $items
 100    *   FieldItemList containing the values to be displayed.
 101    * @param string|array $display_options
 102    *   Can be either:
 103    *   - The name of a view mode. The field will be displayed according to the
 104    *     display settings specified for this view mode in the $field
 105    *     definition for the field in the entity's bundle. If no display settings
 106    *     are found for the view mode, the settings for the 'default' view mode
 107    *     will be used.
 108    *   - An array of display options. The following key/value pairs are allowed:
 109    *     - label: (string) Position of the label. The default 'field' theme
 110    *       implementation supports the values 'inline', 'above' and 'hidden'.
 111    *       Defaults to 'above'.
 112    *     - type: (string) The formatter to use. Defaults to the
 113    *       'default_formatter' for the field type. The default formatter will
 114    *       also be used if the requested formatter is not available.
 115    *     - settings: (array) Settings specific to the formatter. Defaults to the
 116    *       formatter's default settings.
 117    *     - weight: (float) The weight to assign to the renderable element.
 118    *       Defaults to 0.
 119    *
 120    * @return array
 121    *   A renderable array for the field values.
 122    *
 123    * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
 124    */
 125   public function viewField(FieldItemListInterface $items, $display_options = []);
 126
 127   /**
 128    * Builds a renderable array for a single field item.
 129    *
 130    * @param \Drupal\Core\Field\FieldItemInterface $item
 131    *   FieldItem to be displayed.
 132    * @param string|array $display_options
 133    *   Can be either the name of a view mode, or an array of display settings.
 134    *   See EntityViewBuilderInterface::viewField() for more information.
 135    *
 136    * @return array
 137    *   A renderable array for the field item.
 138    *
 139    * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
 140    */
 141   public function viewFieldItem(FieldItemInterface $item, $display_options = []);
 142
 143   /**
 144    * The cache tag associated with this entity view builder.
 145    *
 146    * An entity view builder is instantiated on a per-entity type basis, so the
 147    * cache tags are also per-entity type.
 148    *
 149    * @return array
 150    *   An array of cache tags.
 151    */
 152   public function getCacheTags();
 153
 154 }