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

   1 <?php
   2
   3 namespace Drupal\Core\TypedData;
   4
   5 use Drupal\Core\Session\AccountInterface;
   6
   7 /**
   8  * Interface for retrieving all possible and settable values.
   9  *
  10  * While possible values specify which values existing data might have, settable
  11  * values define the values that are allowed to be set by a user.
  12  *
  13  * For example, in an workflow scenario, the settable values for a state field
  14  * might depend on the currently set state, while possible values are all
  15  * states. Thus settable values would be used in an editing context, while
  16  * possible values would be used for presenting filtering options in a search.
  17  *
  18  * For convenience, lists of both settable and possible values are also provided
  19  * as structured options arrays that can be used in an Options widget such as a
  20  * select box or checkboxes.
  21  *
  22  * Note that this interface is mostly applicable for primitive data values, but
  23  * can be used on complex data structures if a (primitive) main property is
  24  * specified. In that case, the allowed values and options apply to the main
  25  * property only.
  26  *
  27  * @see \Drupal\options\Plugin\Field\FieldWidget\OptionsWidgetBase
  28  */
  29 interface OptionsProviderInterface {
  30
  31   /**
  32    * Returns an array of possible values.
  33    *
  34    * If the optional $account parameter is passed, then the array is filtered to
  35    * values viewable by the account.
  36    *
  37    * @param \Drupal\Core\Session\AccountInterface $account
  38    *   (optional) The user account for which to filter the possible values. If
  39    *   omitted, all possible values are returned.
  40    *
  41    * @return array
  42    *   An array of possible values.
  43    */
  44   public function getPossibleValues(AccountInterface $account = NULL);
  45
  46   /**
  47    * Returns an array of possible values with labels for display.
  48    *
  49    * If the optional $account parameter is passed, then the array is filtered to
  50    * values viewable by the account.
  51    *
  52    * @param \Drupal\Core\Session\AccountInterface $account
  53    *   (optional) The user account for which to filter the possible options.
  54    *   If omitted, all possible options are returned.
  55    *
  56    * @return array
  57    *   An array of possible options for the object that may be used in an
  58    *   Options widget, for example when existing data should be filtered. It may
  59    *   either be a flat array of option labels keyed by values, or a
  60    *   two-dimensional array of option groups (array of flat option arrays,
  61    *   keyed by option group label). Note that labels should NOT be sanitized.
  62    */
  63   public function getPossibleOptions(AccountInterface $account = NULL);
  64
  65   /**
  66    * Returns an array of settable values.
  67    *
  68    * If the optional $account parameter is passed, then the array is filtered to
  69    * values settable by the account.
  70    *
  71    * @param \Drupal\Core\Session\AccountInterface $account
  72    *   (optional) The user account for which to filter the settable values. If
  73    *   omitted, all settable values are returned.
  74    *
  75    * @return array
  76    *   An array of settable values.
  77    */
  78   public function getSettableValues(AccountInterface $account = NULL);
  79
  80   /**
  81    * Returns an array of settable values with labels for display.
  82    *
  83    * If the optional $account parameter is passed, then the array is filtered to
  84    * values settable by the account.
  85    *
  86    * @param \Drupal\Core\Session\AccountInterface $account
  87    *   (optional) The user account for which to filter the settable options. If
  88    *   omitted, all settable options are returned.
  89    *
  90    * @return array
  91    *   An array of settable options for the object that may be used in an
  92    *   Options widget, usually when new data should be entered. It may either be
  93    *   a flat array of option labels keyed by values, or a two-dimensional array
  94    *   of option groups (array of flat option arrays, keyed by option group
  95    *   label). Note that labels should NOT be sanitized.
  96    */
  97   public function getSettableOptions(AccountInterface $account = NULL);
  98
  99 }