yaffs.net Git - yaffs-website/blob - web/core/lib/Drupal/Core/Field/FormatterInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6
   7 /**
   8  * Interface definition for field formatter plugins.
   9  *
  10  * @ingroup field_formatter
  11  */
  12 interface FormatterInterface extends PluginSettingsInterface {
  13
  14   /**
  15    * Returns a form to configure settings for the formatter.
  16    *
  17    * Invoked from \Drupal\field_ui\Form\EntityDisplayFormBase to allow
  18    * administrators to configure the formatter. The field_ui module takes care
  19    * of handling submitted form values.
  20    *
  21    * @param array $form
  22    *   The form where the settings form is being included in.
  23    * @param \Drupal\Core\Form\FormStateInterface $form_state
  24    *   The current state of the form.
  25    *
  26    * @return array
  27    *   The form elements for the formatter settings.
  28    */
  29   public function settingsForm(array $form, FormStateInterface $form_state);
  30
  31   /**
  32    * Returns a short summary for the current formatter settings.
  33    *
  34    * If an empty result is returned, a UI can still be provided to display
  35    * a settings form in case the formatter has configurable settings.
  36    *
  37    * @return string[]
  38    *   A short summary of the formatter settings.
  39    */
  40   public function settingsSummary();
  41
  42   /**
  43    * Allows formatters to load information for field values being displayed.
  44    *
  45    * This should be used when a formatter needs to load additional information
  46    * from the database in order to render a field, for example a reference
  47    * field that displays properties of the referenced entities such as name or
  48    * type.
  49    *
  50    * This method operates on multiple entities. The $entities_items parameter
  51    * is an array keyed by entity ID. For performance reasons, information for
  52    * all involved entities should be loaded in a single query where possible.
  53    *
  54    * Changes or additions to field values are done by directly altering the
  55    * items.
  56    *
  57    * @param \Drupal\Core\Field\FieldItemListInterface[] $entities_items
  58    *   An array with the field values from the multiple entities being rendered.
  59    */
  60   public function prepareView(array $entities_items);
  61
  62   /**
  63    * Builds a renderable array for a fully themed field.
  64    *
  65    * @param \Drupal\Core\Field\FieldItemListInterface $items
  66    *   The field values to be rendered.
  67    * @param string $langcode
  68    *   (optional) The language that should be used to render the field. Defaults
  69    *   to the current content language.
  70    *
  71    * @return array
  72    *   A renderable array for a themed field with its label and all its values.
  73    */
  74   public function view(FieldItemListInterface $items, $langcode = NULL);
  75
  76   /**
  77    * Builds a renderable array for a field value.
  78    *
  79    * @param \Drupal\Core\Field\FieldItemListInterface $items
  80    *   The field values to be rendered.
  81    * @param string $langcode
  82    *   The language that should be used to render the field.
  83    *
  84    * @return array
  85    *   A renderable array for $items, as an array of child elements keyed by
  86    *   consecutive numeric indexes starting from 0.
  87    */
  88   public function viewElements(FieldItemListInterface $items, $langcode);
  89
  90   /**
  91    * Returns if the formatter can be used for the provided field.
  92    *
  93    * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
  94    *   The field definition that should be checked.
  95    *
  96    * @return bool
  97    *   TRUE if the formatter can be used, FALSE otherwise.
  98    */
  99   public static function isApplicable(FieldDefinitionInterface $field_definition);
 100
 101 }