1<?php
2
3namespace Drupal\Core\Entity;
4
5use Drupal\Core\Field\FieldItemInterface;
6use Drupal\Core\Field\FieldItemListInterface;
7
8/**
9 * Defines an interface for entity view builders.
10 *
11 * @ingroup entity_api
12 */
13interface 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}
155