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