SearchInterface.php 4.31 KB
Newer Older
1
2
3
4
5
<?php

namespace Drupal\search\Plugin;

use Drupal\Component\Plugin\PluginInspectionInterface;
6
use Drupal\Core\Form\FormStateInterface;
7
8
9
10
11
12
13
14
15
16
17
18

/**
 * Defines a common interface for all SearchPlugin objects.
 */
interface SearchInterface extends PluginInspectionInterface {

  /**
   * Sets the keywords, parameters, and attributes to be used by execute().
   *
   * @param string $keywords
   *   The keywords to use in a search.
   * @param array $parameters
19
   *   Array of parameters as an associative array. This is expected to
20
21
   *   be the query string from the current request.
   * @param array $attributes
22
   *   Array of attributes, usually from the current request object.
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
   *
   * @return \Drupal\search\Plugin\SearchInterface
   *   A search plugin object for chaining.
   */
  public function setSearch($keywords, array $parameters, array $attributes);

  /**
   * Returns the currently set keywords of the plugin instance.
   *
   * @return string
   *   The keywords.
   */
  public function getKeywords();

  /**
   * Returns the current parameters set using setSearch().
   *
   * @return array
   *   The parameters.
   */
  public function getParameters();

  /**
   * Returns the currently set attributes (from the request).
   *
   * @return array
   *   The attributes.
   */
  public function getAttributes();

  /**
   * Verifies if the values set via setSearch() are valid and sufficient.
   *
   * @return bool
   *   TRUE if the search settings are valid and sufficient to execute a search,
   *   and FALSE if not.
   */
  public function isSearchExecutable();

62
63
64
65
66
67
68
69
70
71
72
73
  /**
   * Returns the search index type this plugin uses.
   *
   * @return string|null
   *   The type used by this search plugin in the search index, or NULL if this
   *   plugin does not use the search index.
   *
   * @see search_index()
   * @see search_index_clear()
   */
  public function getType();

74
75
76
77
78
79
80
81
82
  /**
   * Executes the search.
   *
   * @return array
   *   A structured list of search results.
   */
  public function execute();

  /**
83
   * Executes the search and builds render arrays for the result items.
84
85
   *
   * @return array
86
87
88
   *   An array of render arrays of search result items (generally each item
   *   has '#theme' set to 'search_result'), or an empty array if there are no
   *   results.
89
90
91
   */
  public function buildResults();

92
93
94
95
96
97
98
99
  /**
   * Provides a suggested title for a page of search results.
   *
   * @return string
   *   The translated suggested page title.
   */
  public function suggestedTitle();

100
101
102
103
104
105
106
107
  /**
   * Returns the searching help.
   *
   * @return array
   *   Render array for the searching help.
   */
  public function getHelp();

108
109
110
111
  /**
   * Alters the search form when being built for a given plugin.
   *
   * 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
117
   *
   * @param array $form
   *   Nested array of form elements that comprise the form.
118
119
120
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form. The arguments that
   *   \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
129
130
131
132
133
134
  /**
   * Builds the URL GET query parameters array for search.
   *
   * When the search form is submitted, a redirect is generated with the
   * search input as GET query parameters. Plugins using the searchFormAlter()
   * method to add form elements to the search form will need to override this
   * method to gather the form input and add it to the GET query parameters.
   *
135
   * @param \Drupal\Core\Form\FormStateInterface $form_state
136
137
138
139
140
141
142
143
144
145
   *   The form state, with submitted form information.
   *
   * @return array
   *   An array of GET query parameters containing all relevant form values
   *   to process the search. The 'keys' element must be present in order to
   *   trigger generation of search results, even if it is empty or unused by
   *   the search plugin.
   *
   * @see SearchInterface::searchFormAlter()
   */
146
  public function buildSearchUrlQuery(FormStateInterface $form_state);
147

148
}