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

   1 <?php
   2
   3 namespace Drupal\views\Plugin\views\exposed_form;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6 use Drupal\views\Plugin\views\ViewsPluginInterface;
   7
   8 /**
   9  * @defgroup views_exposed_form_plugins Views exposed form plugins
  10  * @{
  11  * Plugins that handle validation, submission, and rendering of exposed forms.
  12  *
  13  * Exposed forms are used for filters, sorts, and pager settings that are
  14  * exposed to site visitors. Exposed form plugins handle the rendering,
  15  * validation, and submission of exposed forms, and may add additional form
  16  * elements.
  17  *
  18  * To define a Exposed Form Plugin in a module you need to:
  19  * - Implement
  20  *   \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface.
  21  * - Usually you will want to extend the
  22  *   \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase class.
  23  * - Exposed form plugins are annotated with
  24  *   \Drupal\views\Annotation\ViewsExposedForm annotation. See the
  25  *   @link annotation Annotations topic @endlink for more information about
  26  *   annotations.
  27  * - They must be in namespace directory Plugin\views\exposed_form.
  28  */
  29
  30 /**
  31  * Interface for exposed filter form plugins.
  32  *
  33  * Exposed form plugins handle the rendering, validation, and submission
  34  * of exposed forms, and may add additional form elements. These plugins can
  35  * also alter the view query. See
  36  * \Drupal\views\Plugin\views\exposed_form\InputRequired as an example of
  37  * that functionality.
  38  *
  39  * @see \Drupal\views\Annotation\ViewsExposedForm
  40  * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase
  41  */
  42 interface ExposedFormPluginInterface extends ViewsPluginInterface {
  43
  44   /**
  45    * Renders the exposed form.
  46    *
  47    * This method iterates over each handler configured to expose widgets
  48    * to the end user and attach those widgets to the exposed form.
  49    *
  50    * @param bool $block
  51    *   (optional) TRUE if the exposed form is being rendered as part of a
  52    *   block; FALSE (default) if not.
  53    *
  54    * @return array
  55    *   Form build array. This method returns an empty array if the form is
  56    *   being rendered as a block.
  57    *
  58    * @see \Drupal\views\ViewExecutable::build()
  59    */
  60   public function renderExposedForm($block = FALSE);
  61
  62   /**
  63    * Runs before the view is rendered.
  64    *
  65    * Implement if your exposed form needs to run code before the view is
  66    * rendered.
  67    *
  68    * @param \Drupal\views\ResultRow[] $values
  69    *   An array of all ResultRow objects returned from the query.
  70    *
  71    * @see \Drupal\views\ViewExecutable::render()
  72    */
  73   public function preRender($values);
  74
  75   /**
  76    * Runs after the view has been rendered.
  77    *
  78    * Implement if your exposed form needs to run code after the view is
  79    * rendered.
  80    *
  81    * @param string $output
  82    *   The rendered output of the view display.
  83    *
  84    * @see \Drupal\views\ViewExecutable::render()
  85    */
  86   public function postRender(&$output);
  87
  88   /**
  89    * Runs before the view has been executed.
  90    *
  91    * Implement if your exposed form needs to run code before query execution.
  92    *
  93    * @see \Drupal\views\Plugin\views\display\DisplayPluginBase::preExecute()
  94    */
  95   public function preExecute();
  96
  97   /**
  98    * Runs after the view has been executed.
  99    *
 100    * Implement if your exposed form needs to run code after query execution.
 101    */
 102   public function postExecute();
 103
 104   /**
 105    * Alters the exposed form.
 106    *
 107    * The exposed form is built by calling the renderExposedForm() method on
 108    * this class, and then letting each exposed filter and sort handler add
 109    * widgets to the form. After that is finished, this method is called to
 110    * let the class alter the finished form.
 111    *
 112    * @param array $form
 113    *   An associative array containing the structure of the form.
 114    * @param \Drupal\Core\Form\FormStateInterface $form_state
 115    *   The current state of the form.
 116    *
 117    * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface::renderExposedForm()
 118    * @see \Drupal\views\Form\ViewsExposedForm::buildForm()
 119    */
 120   public function exposedFormAlter(&$form, FormStateInterface $form_state);
 121
 122   /**
 123    * Validates the exposed form submission.
 124    *
 125    * @param array $form
 126    *   An associative array containing the structure of the form.
 127    * @param \Drupal\Core\Form\FormStateInterface $form_state
 128    *   The current state of the form.
 129    *
 130    * @see \Drupal\views\Form\ViewsExposedForm::validateForm()
 131    */
 132   public function exposedFormValidate(&$form, FormStateInterface $form_state);
 133
 134   /**
 135    * Submits the exposed form.
 136    *
 137    * @param array $form
 138    *   An associative array containing the structure of the form.
 139    * @param \Drupal\Core\Form\FormStateInterface $form_state
 140    *   The current state of the form.
 141    * @param array $exclude
 142    *   Array of keys that will not appear in $view->exposed_raw_input; for
 143    *   example, 'form_build_id'.
 144    *
 145    * @see \Drupal\views\Form\ViewsExposedForm::submitForm()
 146    */
 147   public function exposedFormSubmit(&$form, FormStateInterface $form_state, &$exclude);
 148
 149 }
 150
 151 /**
 152  * @}
 153  */