diff --git a/README.md b/README.md index 8921bf3..4767c39 100644 --- a/README.md +++ b/README.md @@ -294,29 +294,39 @@ You can enable Extended Dismax search on this module's configuration page at `admin/config/islandora/advanced_search`. This will affect all Advanced Search and Search blocks provided by this module. - - -## Configure Collection Search +## Configure Search Fields for Collection Search See "Requirements" for a discussion of the use of `field_member_of`. -To support collection based searches you need to index the `field_member_of` for -every node as well define a new Search API field that captures the full -hierarchy of `field_member_of` for each repository item. +In this section we set up fields in our Solr index (using Search API) +that index a node's parent ("Member of") and all its parents' parents, +recursively ("Descendant of"), the latter achieved by using Search API's +"Index hierarchy" processor. -Add a new `Content` Search API field `field_decedent_of` to the index at -`admin/config/search/search-api/index/[your default index]/fields`. +First ensure that your hierarchy field (assumed for convenience to be `field_member_of`) +is indexed at `admin/config/search/search-api/index/[your default index]/fields`. +We will assume that the Search API field's name is "Member of". The field type +should be "Integer". -![image](./docs/field_decedent_of.png) +Next, create a second Search API field, based on the same Drupal field. We'll +call this one "Descendant of". It is also an Integer. -Then under `admin/config/search/search-api/index/[your default index]/processors` -enable `Index hierarchy` and setup the new field to index the hierarchy. -![image](./docs/enable_index_hierarchy.png) +![Search fields Member of and Descendant of set up](./docs/field_descendant_of.png) -![image](./docs/enable_index_hierarchy_processor.png) +Then, under the Processors tab (`admin/config/search/search-api/index/[your default index]/processors`) +enable the checkbox for `Index hierarchy` and at the bottom of the page, setup the processor +to index hierarchy for "Descendant of" (but not "Member of"). + +!["Index hierarchy" checkbox selected](./docs/enable_index_hierarchy.png) + +!["Decendant of" selected under Index Hierarchy processor settings.](./docs/enable_index_hierarchy_processor.png) + + +This "Descendant of" field now contains a list of all its ancestors, so can +be used as a contextual filter on views, thereby allowing the view to display all +descendants of a given node. -The field can now be used limit a search to all the decedents of a given object. See the section below, "Collection search", to finish configuring your site for collection and sub-collection search. @@ -324,16 +334,16 @@ for collection and sub-collection search. ## Configure Views -Create a Search API view that uses your index. - -The configuration of views is outside of the scope of this document, please read -the [Drupal Documentation](https://www.drupal.org/docs/8/core/modules/views), as +Detailed instruction on the configuration of views is outside of the scope of this document. +Please read the [Drupal Documentation](https://www.drupal.org/docs/8/core/modules/views), as well as the [Search API Documentation](https://www.drupal.org/docs/contributed-modules/search-api). -However, do NOT add the "Fulltext search" filter, despite that it is the "usual" way of -setting up a Search view. All fulltext searching (and fielded searching) will -be handled by blocks provided by this module. +To use the Advanced Search module, you will need to create at least one view that +is based on Search API and uses Solr. However, do NOT add the "Fulltext search" +filter, despite that being the "usual" way of setting up a Search view. All +fulltext searching (and fielded searching) will be handled by blocks provided +by this module. ### Exposed Form @@ -348,7 +358,7 @@ The Advanced Search Block requires that if present the Exposed forms `Input Required` will prevent any search from occurring unless the user puts an additional query in the Exposed form as well. -![Form Style](./docs/basic-input.png) +![Exposed Form set to Basic.](./docs/basic-exposed-form.png) ### Collection Search @@ -357,24 +367,27 @@ This module's "Advanced Search" block can be set up on a that can contain other entities). This block allows the user to select whether they want the search to include sub-collections. -![image](./docs/include_subcollections.png) +!["Include Sub-collections" checkbox in the Advanced Search Block.](./docs/include_subcollections.png) The following instructions describe how to set up this feature. -![image](./docs/view_advanced_setting.png) +First, in your Search API view, set up **two** contextual filters: -Here a relationship is setup with `Member Of` field and we have **two** -contextual filters: +1. "Member of" (Direct descendants only) +2. "Descendant of" (All descendants) -1. `field_member_of` (Direct decedents of the Entity) -2. `field_decedent_of` (All decedents of the Entity) -Both of these filters are configured the exact same way. +![Views config showing two contextual filters.](./docs/view_advanced_setting.png) -![image](./docs/contextual_filter_settings.png) +Both of these filters are configured the exact same way. The only configuration +to set is "When the filter value is NOT available" then "Provide default value". +Under Type, select "Content ID from URL". -These filters are toggled by the Advanced Search block to allow the search to -include all decedents or just direct decedents (*documented below*). +![Contextual filter showing "Content ID from URL" selected.](./docs/contextual_filter_settings.png) + +These two contextual filters are used by the Advanced Search block to +expose the toggle to search direct descendants or all descendants +(documented under "Advanced Search Block", below). ### Paging @@ -481,12 +494,13 @@ the models you want to display the search on, e.g: ### Advanced Search Block -For any valid search field, you can drag / drop and reorder the fields to +For any valid Search API field, you can drag / drop and reorder the fields to display in the advanced search form on. The configuration resides on the block -so this can differ across views / displays if need be. Additionally if the View -the block was derived from has multiple contextual filters you can choose which -one corresponds to direct children, this will enable the recursive search -checkbox. +so this can differ across views / displays if need be. + +If the view this block is attached to has *two* exposed filters, then you can +choose which one corresponds to direct descendants. This will enable the +"Include Sub-Collections" search checkbox on the Advanced Search block. ![image](./docs/advanced_search_block_settings.png) diff --git a/docs/advanced_search_block_settings.png b/docs/advanced_search_block_settings.png index 039a5fa..fab0be6 100644 Binary files a/docs/advanced_search_block_settings.png and b/docs/advanced_search_block_settings.png differ diff --git a/docs/basic-exposed-form.png b/docs/basic-exposed-form.png new file mode 100644 index 0000000..12ed40b Binary files /dev/null and b/docs/basic-exposed-form.png differ diff --git a/docs/basic-input.png b/docs/basic-input.png deleted file mode 100644 index 758c2e8..0000000 Binary files a/docs/basic-input.png and /dev/null differ diff --git a/docs/contextual_filter_settings.png b/docs/contextual_filter_settings.png index dca49ae..4924bdc 100644 Binary files a/docs/contextual_filter_settings.png and b/docs/contextual_filter_settings.png differ diff --git a/docs/enable_index_hierarchy.png b/docs/enable_index_hierarchy.png index f9f9619..a13c0c1 100644 Binary files a/docs/enable_index_hierarchy.png and b/docs/enable_index_hierarchy.png differ diff --git a/docs/enable_index_hierarchy_processor.png b/docs/enable_index_hierarchy_processor.png index 9d9c1a2..fe0a311 100644 Binary files a/docs/enable_index_hierarchy_processor.png and b/docs/enable_index_hierarchy_processor.png differ diff --git a/docs/field_decedent_of.png b/docs/field_decedent_of.png deleted file mode 100644 index 623ffa0..0000000 Binary files a/docs/field_decedent_of.png and /dev/null differ diff --git a/docs/field_descendant_of.png b/docs/field_descendant_of.png new file mode 100644 index 0000000..8a1a854 Binary files /dev/null and b/docs/field_descendant_of.png differ diff --git a/docs/view_advanced_setting.png b/docs/view_advanced_setting.png index 4237026..02bc96c 100644 Binary files a/docs/view_advanced_setting.png and b/docs/view_advanced_setting.png differ