www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Field/FieldItemListInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use Drupal\Core\Entity\FieldableEntityInterface;
   6 use Drupal\Core\Form\FormStateInterface;
   7 use Drupal\Core\Session\AccountInterface;
   8 use Drupal\Core\Access\AccessibleInterface;
   9 use Drupal\Core\TypedData\ListInterface;
  10
  11 /**
  12  * Interface for fields, being lists of field items.
  13  *
  14  * This interface must be implemented by every entity field, whereas contained
  15  * field items must implement the FieldItemInterface.
  16  * Some methods of the fields are delegated to the first contained item, in
  17  * particular get() and set() as well as their magic equivalences.
  18  *
  19  * Optionally, a typed data object implementing
  20  * Drupal\Core\TypedData\TypedDataInterface may be passed to
  21  * ArrayAccess::offsetSet() instead of a plain value.
  22  *
  23  * When implementing this interface which extends Traversable, make sure to list
  24  * IteratorAggregate or Iterator before this interface in the implements clause.
  25  *
  26  * @see \Drupal\Core\Field\FieldItemInterface
  27  */
  28 interface FieldItemListInterface extends ListInterface, AccessibleInterface {
  29
  30   /**
  31    * Gets the entity that field belongs to.
  32    *
  33    * @return \Drupal\Core\Entity\EntityInterface
  34    *   The entity object.
  35    */
  36   public function getEntity();
  37
  38   /**
  39    * Sets the langcode of the field values held in the object.
  40    *
  41    * @param string $langcode
  42    *   The langcode.
  43    */
  44   public function setLangcode($langcode);
  45
  46   /**
  47    * Gets the langcode of the field values held in the object.
  48    *
  49    * @return string
  50    *   The langcode.
  51    */
  52   public function getLangcode();
  53
  54   /**
  55    * Gets the field definition.
  56    *
  57    * @return \Drupal\Core\Field\FieldDefinitionInterface
  58    *   The field definition.
  59    */
  60   public function getFieldDefinition();
  61
  62   /**
  63    * Returns the array of field settings.
  64    *
  65    * @return array
  66    *   An array of key/value pairs.
  67    */
  68   public function getSettings();
  69
  70   /**
  71    * Returns the value of a given field setting.
  72    *
  73    * @param string $setting_name
  74    *   The setting name.
  75    *
  76    * @return mixed
  77    *   The setting value.
  78    */
  79   public function getSetting($setting_name);
  80
  81   /**
  82    * Contains the default access logic of this field.
  83    *
  84    * See \Drupal\Core\Entity\EntityAccessControlHandlerInterface::fieldAccess() for
  85    * the parameter documentation.
  86    *
  87    * @return \Drupal\Core\Access\AccessResultInterface
  88    *   The access result.
  89    */
  90   public function defaultAccess($operation = 'view', AccountInterface $account = NULL);
  91
  92   /**
  93    * Filters out empty field items and re-numbers the item deltas.
  94    *
  95    * @return $this
  96    */
  97   public function filterEmptyItems();
  98
  99   /**
 100    * Magic method: Gets a property value of to the first field item.
 101    *
 102    * @see \Drupal\Core\Field\FieldItemInterface::__set()
 103    */
 104   public function __get($property_name);
 105
 106   /**
 107    * Magic method: Sets a property value of the first field item.
 108    *
 109    * @see \Drupal\Core\Field\FieldItemInterface::__get()
 110    */
 111   public function __set($property_name, $value);
 112
 113   /**
 114    * Magic method: Determines whether a property of the first field item is set.
 115    *
 116    * @see \Drupal\Core\Field\FieldItemInterface::__unset()
 117    */
 118   public function __isset($property_name);
 119
 120   /**
 121    * Magic method: Unsets a property of the first field item.
 122    *
 123    * @see \Drupal\Core\Field\FieldItemInterface::__isset()
 124    */
 125   public function __unset($property_name);
 126
 127   /**
 128    * Defines custom presave behavior for field values.
 129    *
 130    * This method is called during the process of saving an entity, just before
 131    * item values are written into storage.
 132    *
 133    * @see \Drupal\Core\Field\FieldItemInterface::preSave()
 134    */
 135   public function preSave();
 136
 137   /**
 138    * Defines custom post-save behavior for field values.
 139    *
 140    * This method is called during the process of saving an entity, just after
 141    * item values are written into storage.
 142    *
 143    * @param bool $update
 144    *   Specifies whether the entity is being updated or created.
 145    *
 146    * @return bool
 147    *   Whether field items should be rewritten to the storage as a consequence
 148    *   of the logic implemented by the custom behavior.
 149    *
 150    * @see \Drupal\Core\Field\FieldItemInterface::postSave()
 151    */
 152   public function postSave($update);
 153
 154   /**
 155    * Defines custom delete behavior for field values.
 156    *
 157    * This method is called during the process of deleting an entity, just before
 158    * values are deleted from storage.
 159    */
 160   public function delete();
 161
 162   /**
 163    * Defines custom revision delete behavior for field values.
 164    *
 165    * This method is called from during the process of deleting an entity
 166    * revision, just before the field values are deleted from storage. It is only
 167    * called for entity types that support revisioning.
 168    */
 169   public function deleteRevision();
 170
 171   /**
 172    * Returns a renderable array for the field items.
 173    *
 174    * @param array $display_options
 175    *   Can be either the name of a view mode, or an array of display settings.
 176    *   See EntityViewBuilderInterface::viewField() for more information.
 177    *
 178    * @return array
 179    *   A renderable array for the field values.
 180    *
 181    * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
 182    * @see \Drupal\Core\Field\FieldItemInterface::view()
 183    */
 184   public function view($display_options = []);
 185
 186   /**
 187    * Populates a specified number of field items with valid sample data.
 188    *
 189    * @param int $count
 190    *   The number of items to create.
 191    */
 192   public function generateSampleItems($count = 1);
 193
 194   /**
 195    * Returns a form for the default value input.
 196    *
 197    * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
 198    * administrators to configure instance-level default value.
 199    *
 200    * @param array $form
 201    *   The form where the settings form is being included in.
 202    * @param \Drupal\Core\Form\FormStateInterface $form_state
 203    *   The form state of the (entire) configuration form.
 204    *
 205    * @return array
 206    *   The form definition for the field default value.
 207    */
 208   public function defaultValuesForm(array &$form, FormStateInterface $form_state);
 209
 210   /**
 211    * Validates the submitted default value.
 212    *
 213    * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
 214    * administrators to configure instance-level default value.
 215    *
 216    * @param array $element
 217    *   The default value form element.
 218    * @param array $form
 219    *   The form where the settings form is being included in.
 220    * @param \Drupal\Core\Form\FormStateInterface $form_state
 221    *   The form state of the (entire) configuration form.
 222    */
 223   public function defaultValuesFormValidate(array $element, array &$form, FormStateInterface $form_state);
 224
 225   /**
 226    * Processes the submitted default value.
 227    *
 228    * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
 229    * administrators to configure instance-level default value.
 230    *
 231    * @param array $element
 232    *   The default value form element.
 233    * @param array $form
 234    *   The form where the settings form is being included in.
 235    * @param \Drupal\Core\Form\FormStateInterface $form_state
 236    *   The form state of the (entire) configuration form.
 237    *
 238    * @return array
 239    *   The field default value.
 240    */
 241   public function defaultValuesFormSubmit(array $element, array &$form, FormStateInterface $form_state);
 242
 243   /**
 244    * Processes the default value before being applied.
 245    *
 246    * Defined or configured default values of a field might need some processing
 247    * in order to be a valid runtime value for the field type; e.g., a date field
 248    * could process the defined value of 'NOW' to a valid date.
 249    *
 250    * @param array $default_value
 251    *   The unprocessed default value defined for the field, as a numerically
 252    *   indexed array of items, each item being an array of property/value pairs.
 253    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
 254    *   The entity for which the default value is generated.
 255    * @param \Drupal\Core\Field\FieldDefinitionInterface $definition
 256    *   The definition of the field.
 257    *
 258    * @return array
 259    *   The return default value for the field.
 260    */
 261   public static function processDefaultValue($default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition);
 262
 263   /**
 264    * Determines equality to another object implementing FieldItemListInterface.
 265    *
 266    * @param \Drupal\Core\Field\FieldItemListInterface $list_to_compare
 267    *   The field item list to compare to.
 268    *
 269    * @return bool
 270    *   TRUE if the field item lists are equal, FALSE if not.
 271    */
 272   public function equals(FieldItemListInterface $list_to_compare);
 273
 274 }