EntityViewBuilderInterface.php 6.08 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Entity\EntityViewBuilderInterface.
6 7 8 9
 */

namespace Drupal\Core\Entity;

10 11 12
use Drupal\Core\Field\FieldItemInterface;
use Drupal\Core\Field\FieldItemListInterface;

13
/**
14
 * Defines an interface for entity view builders.
15 16
 *
 * @ingroup entity_api
17
 */
18
interface EntityViewBuilderInterface {
19

20
  /**
21
   * Builds the component fields and properties of a set of entities.
22
   *
23 24
   * @param &$build
   *   The renderable array representing the entity content.
25 26 27
   * @param \Drupal\Core\Entity\EntityInterface[] $entities
   *   The entities whose content is being built.
   * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface[] $displays
28
   *   The array of entity view displays holding the display options
29
   *   configured for the entity components, keyed by bundle name.
30
   * @param string $view_mode
31
   *   The view mode in which the entity is being viewed.
32 33 34 35
   * @param string $langcode
   *   (optional) For which language the entity should be build, defaults to
   *   the current content language.
   */
36
  public function buildComponents(array &$build, array $entities, array $displays, $view_mode, $langcode = NULL);
37 38 39 40

  /**
   * Returns the render array for the provided entity.
   *
41
   * @param \Drupal\Core\Entity\EntityInterface $entity
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
   *   The entity to render.
   * @param string $view_mode
   *   (optional) The view mode that should be used to render the entity.
   * @param string $langcode
   *   (optional) For which language the entity should be rendered, defaults to
   *   the current content language.
   *
   * @return array
   *   A render array for the entity.
   *
   * @throws \InvalidArgumentException
   *   Can be thrown when the set of parameters is inconsistent, like when
   *   trying to view a Comment and passing a Node which is not the one the
   *   comment belongs to, or not passing one, and having the comment node not
   *   be available for loading.
   */
  public function view(EntityInterface $entity, $view_mode = 'full', $langcode = NULL);

  /**
   * Returns the render array for the provided entities.
   *
   * @param array $entities
   *   An array of entities implementing EntityInterface to view.
   * @param string $view_mode
   *   (optional) The view mode that should be used to render the entity.
   * @param string $langcode
   *   (optional) For which language the entity should be rendered, defaults to
   *   the current content language.
   *
   * @return
   *   A render array for the entities, indexed by the same keys as the
   *   entities array passed in $entities.
   *
   * @throws \InvalidArgumentException
   *   Can be thrown when the set of parameters is inconsistent, like when
   *   trying to view Comments and passing a Node which is not the one the
   *   comments belongs to, or not passing one, and having the comments node not
   *   be available for loading.
   */
  public function viewMultiple(array $entities = array(), $view_mode = 'full', $langcode = NULL);
82 83 84 85

  /**
   * Resets the entity render cache.
   *
86 87
   * @param \Drupal\Core\Entity\EntityInterface[] $entities
   *   (optional) If specified, the cache is reset for the given entities only.
88
   */
89
  public function resetCache(array $entities = NULL);
90

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
  /**
   * Returns a renderable array for the value of a single field in an entity.
   *
   * The resulting output is a fully themed field with label and multiple
   * values.
   *
   * This function can be used by third-party modules that need to output an
   * isolated field.
   * - Do not use inside node (or any other entity) templates; use
   *   render($content[FIELD_NAME]) instead.
   * - The FieldItemInterface::view() method can be used to output a single
   *   formatted field value, without label or wrapping field markup.
   *
   * The function takes care of invoking the prepare_view steps. It also
   * respects field access permissions.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $items
   *   FieldItemList containing the values to be displayed.
   * @param array $display_options
   *  Can be either:
   *   - The name of a view mode. The field will be displayed according to the
112
   *     display settings specified for this view mode in the $field
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
   *     definition for the field in the entity's bundle. If no display settings
   *     are found for the view mode, the settings for the 'default' view mode
   *     will be used.
   *   - An array of display options. The following key/value pairs are allowed:
   *     - label: (string) Position of the label. The default 'field' theme
   *       implementation supports the values 'inline', 'above' and 'hidden'.
   *       Defaults to 'above'.
   *     - type: (string) The formatter to use. Defaults to the
   *       'default_formatter' for the field type. The default formatter will
   *       also be used if the requested formatter is not available.
   *     - settings: (array) Settings specific to the formatter. Defaults to the
   *       formatter's default settings.
   *     - weight: (float) The weight to assign to the renderable element.
   *       Defaults to 0.
   *
   * @return array
   *   A renderable array for the field values.
   *
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
   */
  public function viewField(FieldItemListInterface $items, $display_options = array());

  /**
   * Returns a renderable array for a single field item.
   *
   * @param \Drupal\Core\Field\FieldItemInterface $item
   *   FieldItem to be displayed.
   * @param array $display_options
   *   Can be either the name of a view mode, or an array of display settings.
   *   See EntityViewBuilderInterface::viewField() for more information.
   *
   * @return array
   *   A renderable array for the field item.
   *
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
   */
  public function viewFieldItem(FieldItemInterface $item, $display_options = array());

151 152 153 154 155 156 157 158 159 160 161
  /**
   * The cache tag associated with this entity view builder.
   *
   * An entity view builder is instantiated on a per-entity type basis, so the
   * cache tags are also per-entity type.
   *
   * @return array
   *   An array of cache tags.
   */
  public function getCacheTag();

162
}