aleph1.co.uk Git - yaffs-website/blob - web/core/modules/views/src/Plugin/views/field/FieldHandlerInterface.php

   1 <?php
   2
   3 namespace Drupal\views\Plugin\views\field;
   4
   5 use Drupal\views\ResultRow;
   6 use Drupal\views\Plugin\views\ViewsHandlerInterface;
   7
   8 /**
   9  * Base field handler that has no options and renders an unformatted field.
  10  */
  11 interface FieldHandlerInterface extends ViewsHandlerInterface {
  12
  13   /**
  14    * Adds an ORDER BY clause to the query for click sort columns.
  15    *
  16    * @param string $order
  17    *   Either ASC or DESC
  18    */
  19   public function clickSort($order);
  20
  21   /**
  22    * Determines if this field is click sortable.
  23    *
  24    * @return bool
  25    *   The value of 'click sortable' from the plugin definition, this defaults
  26    *   to TRUE if not set.
  27    */
  28   public function clickSortable();
  29
  30   /**
  31    * Gets this field's label.
  32    */
  33   public function label();
  34
  35   /**
  36    * Returns an HTML element based upon the field's element type.
  37    *
  38    * @param bool $none_supported
  39    *   Whether or not this HTML element is supported.
  40    * @param bool $default_empty
  41    *   Whether or not this HTML element is empty by default.
  42    * @param bool $inline
  43    *   Whether or not this HTML element is inline.
  44    */
  45   public function elementType($none_supported = FALSE, $default_empty = FALSE, $inline = FALSE);
  46
  47   /**
  48    * Returns an HTML element for the label based upon the field's element type.
  49    *
  50    * @param bool $none_supported
  51    *   Whether or not this HTML element is supported.
  52    * @param bool $default_empty
  53    *   Whether or not this HTML element is empty by default.
  54    */
  55   public function elementLabelType($none_supported = FALSE, $default_empty = FALSE);
  56
  57   /**
  58    * Returns an HTML element for the wrapper based upon the field's element type.
  59    *
  60    * @param bool $none_supported
  61    *   Whether or not this HTML element is supported.
  62    * @param bool $default_empty
  63    *   Whether or not this HTML element is empty by default.
  64    */
  65   public function elementWrapperType($none_supported = FALSE, $default_empty = FALSE);
  66
  67   /**
  68    * Provides a list of elements valid for field HTML.
  69    *
  70    * This function can be overridden by fields that want more or fewer
  71    * elements available, though this seems like it would be an incredibly
  72    * rare occurrence.
  73    */
  74   public function getElements();
  75
  76   /**
  77    * Returns the class of the field.
  78    *
  79    * @param bool $row_index
  80    *   The index of current row.
  81    */
  82   public function elementClasses($row_index = NULL);
  83
  84   /**
  85    * Replaces a value with tokens from the last field.
  86    *
  87    * This function actually figures out which field was last and uses its
  88    * tokens so they will all be available.
  89    *
  90    * @param string $value
  91    *   The raw string.
  92    * @param bool $row_index
  93    *   The index of current row.
  94    */
  95   public function tokenizeValue($value, $row_index = NULL);
  96
  97   /**
  98    * Returns the class of the field's label.
  99    *
 100    * @param bool $row_index
 101    *   The index of current row.
 102    */
 103   public function elementLabelClasses($row_index = NULL);
 104
 105   /**
 106    * Returns the class of the field's wrapper.
 107    *
 108    * @param bool $row_index
 109    *   The index of current row.
 110    */
 111   public function elementWrapperClasses($row_index = NULL);
 112
 113   /**
 114    * Gets the entity matching the current row and relationship.
 115    *
 116    * @param \Drupal\views\ResultRow $values
 117    *   An object containing all retrieved values.
 118    *
 119    * @return \Drupal\Core\Entity\EntityInterface|null
 120    *   Returns the entity matching the values or NULL if there is no matching
 121    *   entity.
 122    */
 123   public function getEntity(ResultRow $values);
 124
 125   /**
 126    * Gets the value that's supposed to be rendered.
 127    *
 128    * This api exists so that other modules can easy set the values of the field
 129    * without having the need to change the render method as well.
 130    *
 131    * @param \Drupal\views\ResultRow $values
 132    *   An object containing all retrieved values.
 133    * @param string $field
 134    *   Optional name of the field where the value is stored.
 135    */
 136   public function getValue(ResultRow $values, $field = NULL);
 137
 138   /**
 139    * Determines if this field will be available as an option to group the result
 140    * by in the style settings.
 141    *
 142    * @return bool
 143    *   TRUE if this field handler is groupable, otherwise FALSE.
 144    */
 145   public function useStringGroupBy();
 146
 147   /**
 148    * Runs before any fields are rendered.
 149    *
 150    * This gives the handlers some time to set up before any handler has
 151    * been rendered.
 152    *
 153    * @param \Drupal\views\ResultRow[] $values
 154    *   An array of all ResultRow objects returned from the query.
 155    */
 156   public function preRender(&$values);
 157
 158   /**
 159    * Renders the field.
 160    *
 161    * @param \Drupal\views\ResultRow $values
 162    *   The values retrieved from a single row of a view's query result.
 163    *
 164    * @return string|\Drupal\Component\Render\MarkupInterface
 165    *   The rendered output. If the output is safe it will be wrapped in an
 166    *   object that implements MarkupInterface. If it is empty or unsafe it
 167    *   will be a string.
 168    */
 169   public function render(ResultRow $values);
 170
 171   /**
 172    * Runs after every field has been rendered.
 173    *
 174    * This is meant to be used mainly to deal with field handlers whose output
 175    * cannot be cached at row level but can be cached at display level. The
 176    * typical example is the row counter. For completely uncacheable field output
 177    * placeholders should be used.
 178    *
 179    * @param \Drupal\views\ResultRow $row
 180    *   An array of all ResultRow objects returned from the query.
 181    * @param $output
 182    *   The field rendered output.
 183    *
 184    * @return string[]
 185    *   An associative array of post-render token values keyed by placeholder.
 186    *
 187    * @see \Drupal\views\Plugin\views\field\UncacheableFieldHandlerTrait
 188    */
 189   public function postRender(ResultRow $row, $output);
 190
 191   /**
 192    * Renders a field using advanced settings.
 193    *
 194    * This renders a field normally, then decides if render-as-link and
 195    * text-replacement rendering is necessary.
 196    *
 197    * @param \Drupal\views\ResultRow $values
 198    *   The values retrieved from a single row of a view's query result.
 199    *
 200    * @return string|\Drupal\Component\Render\MarkupInterface
 201    *   The advanced rendered output. If the output is safe it will be wrapped in
 202    *   an object that implements MarkupInterface. If it is empty or unsafe
 203    *   it will be a string.
 204    */
 205   public function advancedRender(ResultRow $values);
 206
 207   /**
 208    * Checks if a field value is empty.
 209    *
 210    * @param $value
 211    *   The field value.
 212    * @param bool $empty_zero
 213    *   Whether or not this field is configured to consider 0 as empty.
 214    * @param bool $no_skip_empty
 215    *   Whether or not to use empty() to check the value.
 216    *
 217    * @return bool
 218    *   TRUE if the value is considered empty, FALSE otherwise.
 219    */
 220   public function isValueEmpty($value, $empty_zero, $no_skip_empty = TRUE);
 221
 222   /**
 223    * Performs an advanced text render for the item.
 224    *
 225    * This is separated out as some fields may render lists, and this allows
 226    * each item to be handled individually.
 227    *
 228    * @param array $alter
 229    *   The alter array of options to use.
 230    *     - max_length: Maximum length of the string, the rest gets truncated.
 231    *     - word_boundary: Trim only on a word boundary.
 232    *     - ellipsis: Show an ellipsis (…) at the end of the trimmed string.
 233    *     - html: Make sure that the html is correct.
 234    *
 235    * @return string|\Drupal\Component\Render\MarkupInterface
 236    *   The rendered output. If the output is safe it will be wrapped in an
 237    *   object that implements MarkupInterface. If it is empty or unsafe it
 238    *   will be a string.
 239    */
 240   public function renderText($alter);
 241
 242   /**
 243    * Gets the 'render' tokens to use for advanced rendering.
 244    *
 245    * This runs through all of the fields and arguments that
 246    * are available and gets their values. This will then be
 247    * used in one giant str_replace().
 248    *
 249    * @param mixed $item
 250    *   The item to render.
 251    *
 252    * @return array
 253    *   An array of available tokens
 254    */
 255   public function getRenderTokens($item);
 256
 257   /**
 258    * Passes values to drupal_render() using $this->themeFunctions() as #theme.
 259    *
 260    * @param \Drupal\views\ResultRow $values
 261    *   Holds single row of a view's result set.
 262    *
 263    * @return string|\Drupal\Component\Render\MarkupInterface
 264    *   Returns rendered output of the given theme implementation. If the output
 265    *   is safe it will be wrapped in an object that implements
 266    *   MarkupInterface. If it is empty or unsafe it will be a string.
 267    */
 268   public function theme(ResultRow $values);
 269
 270 }