diff --git a/contrib/search_api_views/README.txt b/contrib/search_api_views/README.txt index bae140f..9bb99f4 100644 --- a/contrib/search_api_views/README.txt +++ b/contrib/search_api_views/README.txt @@ -24,6 +24,20 @@ When these are present, the normal keywords should be ignored and the related items be returned as results instead. Sorting, filtering and range restriction should all work normally. +"Random sort" feature +--------------------- +This module implements "Random sort" feature (feature key: "search_api_random_sort") +that allows to randomly sort the results returned a search. With a server +supporting this, you can use the "Global: random" sort to display a list of items +randomly sorted. Every time the query is run a different sorting will be provided. + +For developers: +A service class that wants to support this feature has to check for a +"search_api_random_sort" field in the sort() method, specific sorting options +may be present in the query option named "search_api_random_sort", it will be +an array containing the key: +- seed: A seed value for the random sorting. + "Facets block" display ---------------------- Most features should be clear to users of Views. However, the module also diff --git a/contrib/search_api_views/includes/query.inc b/contrib/search_api_views/includes/query.inc index ee551bb..1b66b67 100644 --- a/contrib/search_api_views/includes/query.inc +++ b/contrib/search_api_views/includes/query.inc @@ -122,13 +122,16 @@ class SearchApiViewsQuery extends views_plugin_query { } /** - * Add a sort to the query. + * Adds a sort to the query. * - * @param $selector + * @param string $selector * The field to sort on. All indexed fields of the index are valid values. - * In addition, the special fields 'search_api_relevance' (sort by - * relevance) and 'search_api_id' (sort by item id) may be used. - * @param $order + * In addition, these special fields may be used: + * - search_api_relevance: sort by relevance; + * - search_api_id: sort by item id; + * - search_api_random_sort: random sort (available only if the server + * supports the "search_api_random_sort" feature). + * @param string $order * The order to sort items in - either 'ASC' or 'DESC'. Defaults to 'ASC'. */ public function add_selector_orderby($selector, $order = 'ASC') { @@ -136,6 +139,47 @@ class SearchApiViewsQuery extends views_plugin_query { } /** + * Provides a sorting method as present in the Views default query plugin. + * + * This is provided so that the "Global: Random" sort included in Views will + * work properly with Search API Views. Random sorting is only supported if + * the active search server supports the "search_api_random_sort" feature, + * though, otherwise the call will be ignored. + * + * This method can only be used to sort randomly, as would be done with the + * default query plugin. All other calls are ignored. + * + * @param string|null $table + * Only "rand" is recognized here, all other calls are ignored. + * @param string|null $field + * Is ignored and only present for compatibility reasons. + * @param string $order + * Either "ASC" or "DESC". + * @param string|null $alias + * Is ignored and only present for compatibility reasons. + * @param array $params + * The following optional parameters are recognized: + * - seed: a predefined seed for the random generator. + * + * @see views_plugin_query_default::add_orderby() + */ + public function add_orderby($table, $field = NULL, $order = 'ASC', $alias = '', $params = array()) { + $server = $this->getIndex()->server(); + if ($table == 'rand') { + if ($server->supportsFeature('search_api_random_sort')) { + $this->add_selector_orderby('search_api_random_sort', $order); + if ($params) { + $this->setOption('search_api_random_sort', $params); + } + } + else { + $variables['%server'] = $server->label(); + watchdog('search_api_views', 'Tried to sort results randomly on server %server which does not support random sorting.', $variables, WATCHDOG_WARNING); + } + } + } + + /** * Defines the options used by this query plugin. * * Adds some access options. diff --git a/includes/query.inc b/includes/query.inc index b005cf7..771446e 100644 --- a/includes/query.inc +++ b/includes/query.inc @@ -153,7 +153,9 @@ interface SearchApiQueryInterface { * * @param string $field * The field to sort by. The special fields 'search_api_relevance' (sort by - * relevance) and 'search_api_id' (sort by item id) may be used. + * relevance) and 'search_api_id' (sort by item id) may be used. Also, if + * the search server supports the "search_api_random_sort" feature, the + * "search_api_random_sort" special field can be used to sort randomly. * @param string $order * The order to sort items in - either 'ASC' or 'DESC'. * @@ -586,6 +588,10 @@ class SearchApiQuery implements SearchApiQueryInterface { 'search_api_relevance' => array('type' => 'decimal'), 'search_api_id' => array('type' => 'integer'), ); + if ($this->getIndex()->server()->supportsFeature('search_api_random_sort')) { + $fields['search_api_random_sort'] = array('type' => 'integer'); + } + if (empty($fields[$field])) { throw new SearchApiException(t('Trying to sort on unknown field @field.', array('@field' => $field))); }