www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/search/src/Plugin/SearchInterface.php

   1 <?php
   2
   3 namespace Drupal\search\Plugin;
   4
   5 use Drupal\Component\Plugin\PluginInspectionInterface;
   6 use Drupal\Core\Form\FormStateInterface;
   7
   8 /**
   9  * Defines a common interface for all SearchPlugin objects.
  10  */
  11 interface SearchInterface extends PluginInspectionInterface {
  12
  13   /**
  14    * Sets the keywords, parameters, and attributes to be used by execute().
  15    *
  16    * @param string $keywords
  17    *   The keywords to use in a search.
  18    * @param array $parameters
  19    *   Array of parameters as an associative array. This is expected to
  20    *   be the query string from the current request.
  21    * @param array $attributes
  22    *   Array of attributes, usually from the current request object.
  23    *
  24    * @return \Drupal\search\Plugin\SearchInterface
  25    *   A search plugin object for chaining.
  26    */
  27   public function setSearch($keywords, array $parameters, array $attributes);
  28
  29   /**
  30    * Returns the currently set keywords of the plugin instance.
  31    *
  32    * @return string
  33    *   The keywords.
  34    */
  35   public function getKeywords();
  36
  37   /**
  38    * Returns the current parameters set using setSearch().
  39    *
  40    * @return array
  41    *   The parameters.
  42    */
  43   public function getParameters();
  44
  45   /**
  46    * Returns the currently set attributes (from the request).
  47    *
  48    * @return array
  49    *   The attributes.
  50    */
  51   public function getAttributes();
  52
  53   /**
  54    * Verifies if the values set via setSearch() are valid and sufficient.
  55    *
  56    * @return bool
  57    *   TRUE if the search settings are valid and sufficient to execute a search,
  58    *   and FALSE if not.
  59    */
  60   public function isSearchExecutable();
  61
  62   /**
  63    * Returns the search index type this plugin uses.
  64    *
  65    * @return string|null
  66    *   The type used by this search plugin in the search index, or NULL if this
  67    *   plugin does not use the search index.
  68    *
  69    * @see search_index()
  70    * @see search_index_clear()
  71    */
  72   public function getType();
  73
  74   /**
  75    * Executes the search.
  76    *
  77    * @return array
  78    *   A structured list of search results.
  79    */
  80   public function execute();
  81
  82   /**
  83    * Executes the search and builds render arrays for the result items.
  84    *
  85    * @return array
  86    *   An array of render arrays of search result items (generally each item
  87    *   has '#theme' set to 'search_result'), or an empty array if there are no
  88    *   results.
  89    */
  90   public function buildResults();
  91
  92   /**
  93    * Provides a suggested title for a page of search results.
  94    *
  95    * @return string
  96    *   The translated suggested page title.
  97    */
  98   public function suggestedTitle();
  99
 100   /**
 101    * Returns the searching help.
 102    *
 103    * @return array
 104    *   Render array for the searching help.
 105    */
 106   public function getHelp();
 107
 108   /**
 109    * Alters the search form when being built for a given plugin.
 110    *
 111    * The core search module only invokes this method on active module plugins
 112    * when building a form for them in
 113    * \Drupal\search\Form\SearchPageForm::buildForm(). A plugin implementing this
 114    * will also need to implement the buildSearchUrlQuery() method.
 115    *
 116    * @param array $form
 117    *   Nested array of form elements that comprise the form.
 118    * @param \Drupal\Core\Form\FormStateInterface $form_state
 119    *   The current state of the form. The arguments that
 120    *   \Drupal::formBuilder()->getForm() was originally called with are
 121    *   available in the array $form_state->getBuildInfo()['args'].
 122    *
 123    * @see SearchInterface::buildSearchUrlQuery()
 124    */
 125   public function searchFormAlter(array &$form, FormStateInterface $form_state);
 126
 127   /**
 128    * Builds the URL GET query parameters array for search.
 129    *
 130    * When the search form is submitted, a redirect is generated with the
 131    * search input as GET query parameters. Plugins using the searchFormAlter()
 132    * method to add form elements to the search form will need to override this
 133    * method to gather the form input and add it to the GET query parameters.
 134    *
 135    * @param \Drupal\Core\Form\FormStateInterface $form_state
 136    *   The form state, with submitted form information.
 137    *
 138    * @return array
 139    *   An array of GET query parameters containing all relevant form values
 140    *   to process the search. The 'keys' element must be present in order to
 141    *   trigger generation of search results, even if it is empty or unused by
 142    *   the search plugin.
 143    *
 144    * @see SearchInterface::searchFormAlter()
 145    */
 146   public function buildSearchUrlQuery(FormStateInterface $form_state);
 147
 148 }