Issue #2642598 by dagmar, shabirahmad, tim.plunkett, jhodgdon: Create an...

Issue #2642598 by dagmar, shabirahmad, tim.plunkett, jhodgdon: Create an interface for the public methods on ExposedFormPluginBase

core/modules/views/src/Annotation/ViewsExposedForm.php

@@ -5,6 +5,7 @@
 /**
  * Defines a Plugin annotation object for views exposed form plugins.
  *
+ * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface
  * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase
  *
  * @ingroup views_exposed_form_plugins

core/modules/views/src/Form/ViewsExposedForm.php

@@ -114,7 +114,7 @@ public function buildForm(array $form, FormStateInterface $form_state) {
     $form['#theme'] = $view->buildThemeFunctions('views_exposed_form');
     $form['#id'] = Html::cleanCssIdentifier('views_exposed_form-' . $view->storage->id() . '-' . $display['id']);
 
-    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase $exposed_form_plugin */
+    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form_plugin */
     $exposed_form_plugin = $view->display_handler->getPlugin('exposed_form');
     $exposed_form_plugin->exposedFormAlter($form, $form_state);
 
@@ -137,7 +137,7 @@ public function validateForm(array &$form, FormStateInterface $form_state) {
         $handlers[$key]->validateExposed($form, $form_state);
       }
     }
-    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase $exposed_form_plugin */
+    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form_plugin */
     $exposed_form_plugin = $view->display_handler->getPlugin('exposed_form');
     $exposed_form_plugin->exposedFormValidate($form, $form_state);
   }
@@ -159,7 +159,7 @@ public function submitForm(array &$form, FormStateInterface $form_state) {
     $view->exposed_raw_input = [];
 
     $exclude = array('submit', 'form_build_id', 'form_id', 'form_token', 'exposed_form_plugin', 'reset');
-    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase $exposed_form_plugin */
+    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form_plugin */
     $exposed_form_plugin = $view->display_handler->getPlugin('exposed_form');
     $exposed_form_plugin->exposedFormSubmit($form, $form_state, $exclude);
 

core/modules/views/src/Plugin/views/display/DisplayPluginBase.php

@@ -1339,6 +1339,7 @@ public function optionsSummary(&$categories, &$options) {
       );
     }
 
+    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form_plugin */
     $exposed_form_plugin = $this->getPlugin('exposed_form');
     if (!$exposed_form_plugin) {
       // Default to the no cache control plugin.
@@ -2250,6 +2251,7 @@ public function preExecute() {
     }
     $this->view->initHandlers();
     if ($this->usesExposed()) {
+      /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form */
       $exposed_form = $this->getPlugin('exposed_form');
       $exposed_form->preExecute();
     }
@@ -2546,6 +2548,7 @@ public function viewExposedFormBlocks() {
     $this->view->initHandlers();
 
     if ($this->usesExposed() && $this->getOption('exposed_block')) {
+      /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form */
       $exposed_form = $this->getPlugin('exposed_form');
       return $exposed_form->renderExposedForm(TRUE);
     }

core/modules/views/src/Plugin/views/exposed_form/ExposedFormPluginBase.php

@@ -9,32 +9,21 @@
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\views\Plugin\views\PluginBase;
 
-/**
- * @defgroup views_exposed_form_plugins Views exposed form plugins
- * @{
- * Plugins that handle validation, submission, and rendering of exposed forms.
- *
- * Exposed forms are used for filters, sorts, and pager settings that are
- * exposed to site visitors. Exposed form plugins handle the rendering,
- * validation, and submission of exposed forms, and may add additional form
- * elements.
- *
- * Exposed form plugins extend
- * \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase. They must be
- * annotated with \Drupal\views\Annotation\ViewsExposedForm annotation,
- * and they must be in namespace directory Plugin\views\exposed_form.
- */
-
 /**
  * Base class for Views exposed filter form plugins.
+ *
+ * @ingroup views_exposed_form_plugins
  */
-abstract class ExposedFormPluginBase extends PluginBase implements CacheableDependencyInterface {
+abstract class ExposedFormPluginBase extends PluginBase implements CacheableDependencyInterface, ExposedFormPluginInterface {
 
   /**
    * {@inheritdoc}
    */
   protected $usesOptions = TRUE;
 
+  /**
+   * {@inheritdoc}
+   */
   protected function defineOptions() {
     $options = parent::defineOptions();
     $options['submit_button'] = array('default' => $this->t('Apply'));
@@ -47,6 +36,9 @@ protected function defineOptions() {
     return $options;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function buildOptionsForm(&$form, FormStateInterface $form_state) {
     parent::buildOptionsForm($form, $form_state);
     $form['submit_button'] = array(
@@ -115,11 +107,7 @@ public function buildOptionsForm(&$form, FormStateInterface $form_state) {
   }
 
   /**
-   * Render the exposed filter form.
-   *
-   * This actually does more than that; because it's using FAPI, the form will
-   * also assign data to the appropriate handlers for use in building the
-   * query.
+   * {@inheritdoc}
    */
   public function renderExposedForm($block = FALSE) {
     // Deal with any exposed filters we may have, before building.
@@ -154,6 +142,9 @@ public function renderExposedForm($block = FALSE) {
     }
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function query() {
     $view = $this->view;
     $exposed_data = isset($view->exposed_data) ? $view->exposed_data : array();
@@ -179,21 +170,28 @@ public function query() {
     }
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function preRender($values) { }
 
+  /**
+   * {@inheritdoc}
+   */
   public function postRender(&$output) { }
 
+  /**
+   * {@inheritdoc}
+   */
   public function preExecute() { }
 
+  /**
+   * {@inheritdoc}
+   */
   public function postExecute() { }
 
   /**
-   * Alters the view exposed form.
-   *
-   * @param $form
-   *   The form build array. Passed by reference.
-   * @param $form_state
-   *   The form state. Passed by reference.
+   * {@inheritdoc}
    */
   public function exposedFormAlter(&$form, FormStateInterface $form_state) {
     if (!empty($this->options['submit_button'])) {
@@ -273,6 +271,9 @@ public function exposedFormAlter(&$form, FormStateInterface $form_state) {
     }
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function exposedFormValidate(&$form, FormStateInterface $form_state) {
     if ($pager_plugin = $form_state->get('pager_plugin')) {
       $pager_plugin->exposedFormValidate($form, $form_state);
@@ -280,15 +281,7 @@ public function exposedFormValidate(&$form, FormStateInterface $form_state) {
   }
 
   /**
-   * This function is executed when exposed form is submitted.
-   *
-   * @param $form
-   *   Nested array of form elements that comprise the form.
-   * @param $form_state
-   *   The current state of the form.
-   * @param $exclude
-   *   Nested array of keys to exclude of insert into
-   *   $view->exposed_raw_input
+   * {@inheritdoc}
    */
   public function exposedFormSubmit(&$form, FormStateInterface $form_state, &$exclude) {
     if (!$form_state->isValueEmpty('op') && $form_state->getValue('op') == $this->options['reset_button_label']) {
@@ -300,6 +293,17 @@ public function exposedFormSubmit(&$form, FormStateInterface $form_state, &$excl
     }
   }
 
+  /**
+   * Resets all the states of the exposed form.
+   *
+   * This method is called when the "Reset" button is triggered. Clears
+   * user inputs, stored session, and the form state.
+   *
+   * @param array $form
+   *   An associative array containing the structure of the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   */
   public function resetForm(&$form, FormStateInterface $form_state) {
     // _SESSION is not defined for users who are not logged in.
 
@@ -373,7 +377,3 @@ public function getCacheTags() {
   }
 
 }
-
-/**
- * @}
- */

core/modules/views/src/Plugin/views/exposed_form/ExposedFormPluginInterface.php

+<?php
+
+namespace Drupal\views\Plugin\views\exposed_form;
+
+use Drupal\Core\Form\FormStateInterface;
+use Drupal\views\Plugin\views\ViewsPluginInterface;
+
+/**
+ * @defgroup views_exposed_form_plugins Views exposed form plugins
+ * @{
+ * Plugins that handle validation, submission, and rendering of exposed forms.
+ *
+ * Exposed forms are used for filters, sorts, and pager settings that are
+ * exposed to site visitors. Exposed form plugins handle the rendering,
+ * validation, and submission of exposed forms, and may add additional form
+ * elements.
+ *
+ * To define a Exposed Form Plugin in a module you need to:
+ * - Implement
+ *   \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface.
+ * - Usually you will want to extend the
+ *   \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase class.
+ * - Exposed form plugins are annotated with
+ *   \Drupal\views\Annotation\ViewsExposedForm annotation. See the
+ *   @link annotation Annotations topic @endlink for more information about
+ *   annotations.
+ * - They must be in namespace directory Plugin\views\exposed_form.
+ */
+
+/**
+ * Interface for exposed filter form plugins.
+ *
+ * Exposed form plugins handle the rendering, validation, and submission
+ * of exposed forms, and may add additional form elements. These plugins can
+ * also alter the view query. See
+ * \Drupal\views\Plugin\views\exposed_form\InputRequired as an example of
+ * that functionality.
+ *
+ * @see \Drupal\views\Annotation\ViewsExposedForm
+ * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase
+ */
+interface ExposedFormPluginInterface extends ViewsPluginInterface {
+
+  /**
+   * Renders the exposed form.
+   *
+   * This method iterates over each handler configured to expose widgets
+   * to the end user and attach those widgets to the exposed form.
+   *
+   * @param bool $block
+   *   (optional) TRUE if the exposed form is being rendered as part of a
+   *   block; FALSE (default) if not.
+   *
+   * @return array
+   *   Form build array. This method returns an empty array if the form is
+   *   being rendered as a block.
+   *
+   * @see \Drupal\views\ViewExecutable::build()
+   */
+  public function renderExposedForm($block = FALSE);
+
+  /**
+   * Runs before the view is rendered.
+   *
+   * Implement if your exposed form needs to run code before the view is
+   * rendered.
+   *
+   * @param \Drupal\views\ResultRow[] $values
+   *   An array of all ResultRow objects returned from the query.
+   *
+   * @see \Drupal\views\ViewExecutable::render()
+   */
+  public function preRender($values);
+
+  /**
+   * Runs after the view has been rendered.
+   *
+   * Implement if your exposed form needs to run code after the view is
+   * rendered.
+   *
+   * @param string $output
+   *   The rendered output of the view display.
+   *
+   * @see \Drupal\views\ViewExecutable::render()
+   */
+  public function postRender(&$output);
+
+  /**
+   * Runs before the view has been executed.
+   *
+   * Implement if your exposed form needs to run code before query execution.
+   *
+   * @see \Drupal\views\Plugin\views\display\DisplayPluginBase::preExecute()
+   */
+  public function preExecute();
+
+  /**
+   * Runs after the view has been executed.
+   *
+   * Implement if your exposed form needs to run code after query execution.
+   */
+  public function postExecute();
+
+  /**
+   * Alters the exposed form.
+   *
+   * The exposed form is built by calling the renderExposedForm() method on
+   * this class, and then letting each exposed filter and sort handler add
+   * widgets to the form. After that is finished, this method is called to
+   * let the class alter the finished form.
+   *
+   * @param array $form
+   *   An associative array containing the structure of the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   *
+   * @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface::renderExposedForm()
+   * @see \Drupal\views\Form\ViewsExposedForm::buildForm()
+   */
+  public function exposedFormAlter(&$form, FormStateInterface $form_state);
+
+  /**
+   * Validates the exposed form submission.
+   *
+   * @param array $form
+   *   An associative array containing the structure of the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   *
+   * @see \Drupal\views\Form\ViewsExposedForm::validateForm()
+   */
+  public function exposedFormValidate(&$form, FormStateInterface $form_state);
+
+  /**
+   * Submits the exposed form.
+   *
+   * @param array $form
+   *   An associative array containing the structure of the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   * @param array $exclude
+   *   Array of keys that will not appear in $view->exposed_raw_input; for
+   *   example, 'form_build_id'.
+   *
+   * @see \Drupal\views\Form\ViewsExposedForm::submitForm()
+   */
+  public function exposedFormSubmit(&$form, FormStateInterface $form_state, &$exclude);
+
+}
+
+/**
+ * @}
+ */

core/modules/views/src/ViewExecutable.php

@@ -1192,6 +1192,7 @@ public function build($display_id = NULL) {
     $this->_preQuery();
 
     if ($this->display_handler->usesExposed()) {
+      /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form */
       $exposed_form = $this->display_handler->getPlugin('exposed_form');
       $this->exposed_widgets = $exposed_form->renderExposedForm();
       if (FormState::hasAnyErrors() || !empty($this->build_info['abort'])) {
@@ -1419,6 +1420,7 @@ public function render($display_id = NULL) {
       return;
     }
 
+    /** @var \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface $exposed_form */
     $exposed_form = $this->display_handler->getPlugin('exposed_form');
     $exposed_form->preRender($this->result);
 

core/modules/views/tests/src/Kernel/Plugin/DisplayKernelTest.php

@@ -6,7 +6,7 @@
 use Drupal\Tests\views\Kernel\ViewsKernelTestBase;
 use Drupal\views\Plugin\views\style\StylePluginBase;
 use Drupal\views\Plugin\views\access\AccessPluginBase;
-use Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase;
+use Drupal\views\Plugin\views\exposed_form\ExposedFormPluginInterface;
 use Drupal\views\Plugin\views\pager\PagerPluginBase;
 use Drupal\views\Plugin\views\query\QueryPluginBase;
 use Drupal\views\Plugin\views\cache\CachePluginBase;
@@ -96,7 +96,7 @@ public function testGetPlugin() {
 
     $this->assertTrue($display_handler->getPlugin('access') instanceof AccessPluginBase, 'An access plugin instance was returned.');
     $this->assertTrue($display_handler->getPlugin('cache') instanceof CachePluginBase, 'A cache plugin instance was returned.');
-    $this->assertTrue($display_handler->getPlugin('exposed_form') instanceof ExposedFormPluginBase, 'An exposed_form plugin instance was returned.');
+    $this->assertTrue($display_handler->getPlugin('exposed_form') instanceof ExposedFormPluginInterface, 'An exposed_form plugin instance was returned.');
     $this->assertTrue($display_handler->getPlugin('pager') instanceof PagerPluginBase, 'A pager plugin instance was returned.');
     $this->assertTrue($display_handler->getPlugin('query') instanceof QueryPluginBase, 'A query plugin instance was returned.');
     $this->assertTrue($display_handler->getPlugin('row') instanceof RowPluginBase, 'A row plugin instance was returned.');