plugins/facetapi/url_processor.inc

   1 <?php
   2
   3 /**
   4  * @file
   5  * Base url processor plugin class.
   6  */
   7
   8 /**
   9  * Abstract class extended by url processor plugins.
  10  *
  11  * Url processor plugins provide a pluggable method of retrieving facet data.
  12  * Most commonly facet data is retrieved from a query string variable via $_GET,
  13  * however custom plugis can be written to retrieve data from the path as well.
  14  * In addition to facet data retrieval, the url processor plugin is also
  15  * responsible for building facet links and setting breadcrumb trails.
  16  *
  17  * Each adapter instance is associated with a single url processor plugin. The
  18  * plugin is associated with the adapter via hook_facetapi_searcher_info()
  19  * implementations.
  20  */
  21 abstract class FacetapiUrlProcessor {
  22
  23   /**
  24    * The adapter that the url processor plugin is associated with.
  25    *
  26    * @var FacetapiAdapter
  27    */
  28   protected $adapter;
  29
  30   /**
  31    * An array of facet params, usually $_GET.
  32    *
  33    * @var array.
  34    */
  35   protected $params = array();
  36
  37   /**
  38    * The array key in FacetapiUrlProcessor::params containing the facet data.
  39    *
  40    * @var string
  41    */
  42   protected $filterKey = 'f';
  43
  44   /**
  45    * Constructs a FacetapiUrlProcessor object.
  46    *
  47    * @param FacetapiAdapter $adapter
  48    *   The adapter that the url processor plugin is associated with.
  49    */
  50   public function __construct(FacetapiAdapter $adapter) {
  51     $this->adapter = $adapter;
  52   }
  53
  54   /**
  55    * Fetches parameters from the source, usually $_GET.
  56    *
  57    * This method is invoked in FacetapiAdapter::__construct().
  58    *
  59    * @return array
  60    *   An associative array containing the params, usually $_GET.
  61    */
  62   abstract public function fetchParams();
  63
  64   /**
  65    * Normalizes the array returned by FacetapiAdapter::fetchParams().
  66    *
  67    * When extracting data from a source such as $_GET, there are certain items
  68    * that you might nor want, for example the "q" or "page" keys. This method is
  69    * useful for filtering those out. In addition, plugins that do not get data
  70    * from $_GET can use this method to normalize the data into an associative
  71    * array that closely matches the data structure of $_GET.
  72    *
  73    * @param array $params
  74    *   An array of keyed params, usually as $_GET.
  75    * @param string $filter_key
  76    *   The array key in $params containing the facet data, defaults to "f".
  77    *
  78    * @return array
  79    *   An associative array containing the normalized params.
  80    */
  81   abstract public function normalizeParams(array $params, $filter_key = 'f');
  82
  83   /**
  84    * Returns the query string variables for a facet item.
  85    *
  86    * The return array must be able to be passed as the "query" key of the
  87    * options array passed as the second argument to the url() function. See
  88    * http://api.drupal.org/api/drupal/includes%21common.inc/function/url/7 for
  89    * more details.
  90    *
  91    * @param array $facet
  92    *   The facet definition as returned by facetapi_facet_load().
  93    * @param array $values
  94    *   An array containing the item's values being added to or removed from the
  95    *   query string dependent on whether or not the item is active.
  96    * @param int $active
  97    *   An integer flagging whether the item is active or not. 1 if the item is
  98    *   active, 0 if it is not.
  99    *
 100    * @return array
 101    *   The query string variables.
 102    */
 103   abstract public function getQueryString(array $facet, array $values, $active);
 104
 105   /**
 106    * Returns the path for a facet item.
 107    *
 108    * @param array $facet
 109    *   The facet definition.
 110    * @param array $values
 111    *   An array containing the item's values being added to or removed from the
 112    *   query string dependent on whether or not the item is active.
 113    * @param int $active
 114    *   An integer flagging whether the item is active or not.
 115    *
 116    * @return string
 117    *   The path of the facet.
 118    */
 119   public function getFacetPath(array $facet, array $values, $active) {
 120     return $this->adapter->getSearchPath();
 121   }
 122
 123   /**
 124    * Sets the breadcrumb trail for active searches.
 125    *
 126    * This method is called by FacetapiAdapter::processFacets(), which is called
 127    * directly by the backend to search the chain of Facet API events.
 128    */
 129   abstract public function setBreadcrumb();
 130
 131   /**
 132    * Sets the normalized parameters.
 133    *
 134    * This method is usually called by FacetapiAdapter::setParams() and is very
 135    * rarely called directly.
 136    *
 137    * @param array $params
 138    *   An array of normalized params hat have already been passed through
 139    *   FacetapiUrlProcessor::normalizeParams().
 140    * @param string $filter_key
 141    *   The array key in $params containing the facet data, defaults to "f".
 142    *
 143    * @return FacetapiUrlParser
 144    *   An instance of this class.
 145    */
 146   public function setParams(array $params, $filter_key = 'f') {
 147     $this->params = $params;
 148     $this->filterKey = $filter_key;
 149     if (!isset($this->params[$this->filterKey]) || !is_array($this->params[$this->filterKey])) {
 150       $this->params[$this->filterKey] = array();
 151     }
 152     return $this;
 153   }
 154
 155   /**
 156    * Returns the params.
 157    *
 158    * @return array
 159    *   An array containing the params.
 160    */
 161   public function getParams() {
 162     return $this->params;
 163   }
 164
 165   /**
 166    * Removes an item from the $this->params array.
 167    *
 168    * @param int $pos
 169    *   The zero-based position of the value in the source data.
 170    */
 171   public function removeParam($pos) {
 172     unset($this->params[$this->filterKey][$pos]);
 173   }
 174
 175   /**
 176    * Returns the filter key.
 177    *
 178    * @return string
 179    *   A string containing the filter key.
 180    */
 181   public function getFilterKey() {
 182     return $this->filterKey;
 183   }
 184 }