docs(advanced search): update naming to advanced search (DSP-1651) (#295

)

* docs(advanced search): update naming to advanced search

* docs(advanced search): update naming to advanced search

* docs(advanced search): explain comparison operators

* docs(advanced search): explain is like / regex

* docs(advanced search): explain is like / regex

* docs(advanced search): explain mactches

* docs(advanced search): explain matches for linking props

* docs(advanced search): explain matches

* Update advanced-search-user-docs.md

* docs(advanced search): fix typos

* docs(advanced search): fix typos

Co-authored-by: gautschr <41303890+gautschr@users.noreply.github.com>

README.md

@@ -34,7 +34,7 @@ The library consists of four Angular modules that are briefly described below.
 ### ➡ [DspSearchModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/search/)
 
 *Search panel for all kind of search queries*
-> DspSearchModule allows to make full text or extended searches in DSP-API. Filter by resource class and its properties related to an ontology.
+> DspSearchModule allows to make full text or advanced searches in DSP-API. Filter by resource class and its properties related to an ontology.
 
 ### ➡ [DspActionModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/action/)
 

docs/how-to-contribute/design-documentation.md

@@ -184,7 +184,7 @@ This is a fully-customizable panel that allows you to assemble the search compon
 - route: string; url-route for search results
 - filterbyproject: string; project iri to limit search results to a specific project
 - projectfilter: boolean; provides a drop-down menu of all available projects allowing the user to choose which project to search in
-- advanced: boolean; additional menu with advanced / extended search
+- advanced: boolean; additional menu with advanced search
 - expert: boolean;  additional menu with expert search / Gravsearch "editor"
 
 If everything is set to false or undefined, the search-panel will be a simple full-text search.

docs/how-to-use/search/advanced-search-user-docs.md

@@ -0,0 +1,65 @@
+# Advanced Search Component
+
+## Introduction
+
+The `AdvancedSearchComponent` allows for the creation of complex queries using a graphical widget.
+The widget's contents are then turned into a string representing a Gravsearch (SPARQL) query to be sent to DSP-API.
+
+A query consists of the following elements:
+- ontology (data model) selection
+- selection of a resource class belonging to the selected ontology (optional)
+- specification of properties, comparison operators, and values (optional).
+
+Although selection of a resource or a property or both are optional, either a resource class has to be selected or at least one property has to be specified,
+otherwise the query is not considered valid and cannot be submitted.
+
+## Comparison Operators
+
+Depending on the value type of the chosen property,
+one or more of the following comparison operators can be selected:
+
+- `is equal to`: value equality: same number, exact same string, overlap of date periods, same target resource.
+- `is not equal to`: value inequality: not same number, not exact same string, no overlap of date periods, not same target resource.
+- `is greater than`: value comparison: number is greater than search value, date period begins after search value.
+- `is greater than or equal to` value equality / value comparison: number is equal to or greater than search value, overlap of date periods or date period begins after search value.
+- `is less than`: value comparison: number is less than search value, date period ends before search value.
+- `is less than or equal to`: value equality / value comparison: number is equal to or less than search value, overlap of date periods or date period ends before search value.
+- `exists`: value for the given property exists.
+- `is like`: search value is contained in a text using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function (supports regular expressions).
+- `matches`: 
+   - text property: search value matches the text ([Lucene Query Parser Syntax](https://docs-api.dasch.swiss/08-lucene/lucene-query-parser-syntax/)). 
+   - linking property: matches the specified linked resource.
+
+## Search Examples
+
+### Regular Expressions (is like)
+
+The `is like` operator lets the user search for texts that are *like* the search value via the support of regular expressions
+In this example, all books are found whose title contains "Narrenschiff" followed by a space and some other characters like "(lat.)" or "(dt.)".
+
+For general information about regular expressions see this [interactive tutorial](https://regexone.com).
+
+![Advanced search panel with a search example](../../assets/images/advanced-search-regex.png)
+
+### Lucene Parser Syntax (matches)
+
+Used with a text property, the `matches` operator lets the user search for texts that *match* the search value,
+supporting [Lucene Query Parser Syntax](https://docs-api.dasch.swiss/08-lucene/lucene-query-parser-syntax/).
+In this example, all persons are found whose names contain "Ja" and "ob" with a character in between (represented by the wildcard "?").
+This search finds "Jacob" as well as "Jakob".
+
+**Note the difference between regular expressions and Lucene parser syntax!**
+
+![Advanced search panel with a search example](../../assets/images/advanced-search-match.png)
+
+### Specifying a Linked Resource (matches)
+
+Used with a linking property, the `matches` operator lets the user search for a linked resource that matches the specified properties. 
+In this example, the user writes a query looking for all letters that have an author that:
+1. was born after January 1st 1650
+2. whose family name is "Bernoulli"
+
+This is different from the "is equal to" operator that lets the user specify a certain person (selected from a list).
+
+![Advanced search panel with a search example](../../assets/images/advanced-search-linked-resource.png)
+

docs/how-to-use/search/advanced-search.md

@@ -0,0 +1,25 @@
+# Advanced search (Component)
+
+The advanced search allows you to filter by project, by source type (resource class), or by the metadata (properties) of source types. Each filter can be used individually or combined. The metadata field can be precisely filtered with criteria such as "contains", "like", "equals to", "exists" or in case of a date value with "before" or "after". In addition, for a metadata field that is connected to another source type, it's possible to filter by this second source type. If you are looking for the source type "Photograph" with the metadata field "Photographer", which is connected to source type "Person", you can search for photograph(s) taken by person(s) who is born before February 1970. The result of this request will be an intersection of the two source types.
+
+## Parameters
+
+Name | Type | Description
+ --- | --- | ---
+route | string | Route to navigate after search. This route path should contain a component for search results.
+toggleExtendedSearchForm | boolean | Trigger toggle for advanced search form.
+gravsearch | string | Send the gravsearch query back.
+
+## Examples
+
+Advanced search panel
+
+ ```html
+ <!-- param route is where the router-outlet is defined for search results -->
+
+<dsp-advanced-search [route]="'/search'"></dsp-advanced-search>
+
+ <router-outlet></router-outlet>
+ ```
+
+![Advanced search panel with a search example](../../assets/images/advanced-search.png)

docs/how-to-use/search/expert-search.md

@@ -6,13 +6,13 @@ The expert search is a textarea field in which Gravsearch queries can be written
 
 Name | Type | Description
 --- | --- | ---
-route (optionnal) | string | Route to navigate after search. This route path should contain a component for search results.
+route (optional) | string | Route to navigate after search. This route path should contain a component for search results.
 gravsearch | string | Send the gravsearch query back.
-toggleExpertSearchForm | boolean | Trigger toggle for extended search form.
+toggleExpertSearchForm | boolean | Trigger toggle for advanced search form.
 
 ## Examples
 
-Extended search panel
+Advanced search panel
 
 ```html
 <!-- param gravsearch is where the gravsearch query is cached or sent to DSP-API -->

docs/how-to-use/search/index.md

@@ -1,6 +1,6 @@
 # DSP-UI SEARCH module
 
-DspSearchModule allows to make simple searches or extended searches in DSP-API. In extended search, resource class and its properties related to one specific ontology are selected to create your query. It is also possible to write Gravsearch queries to target specific data with the expert search form.
+DspSearchModule allows to make simple searches or advanced searches in DSP-API. In advanced search, resource class and its properties related to one specific ontology are selected to create your query. It is also possible to write Gravsearch queries to target specific data with the expert search form.
 
 ## Prerequisites
 
@@ -14,7 +14,10 @@ DspSearchModule is part of @dasch-swiss/dsp-ui, follow [the installation guide](
 
 ## Components
 
-This module contains various components to search. The main component is the dsp-search-panel, which contains the dsp-fulltext-search, dsp-extended-search and dsp-expert-search. All of them can be used standalone or in combination in dsp-search-panel.
+This module contains various components to search.
+The main component is the dsp-search-panel, which contains the dsp-fulltext-search,
+dsp-advanced-search and dsp-expert-search.
+All of them can be used individually or in combination in dsp-search-panel.
 
 ### [Search panel](/developers/dsp-ui/documentation/search/search-panel)
 
@@ -23,7 +26,7 @@ Fully customizable panel. You can set the following parameters in dsp-search-pan
 - route: string; url-route for search results
 - filterbyproject: string; project iri to limit search results by project
 - projectfilter: boolean; selection of all projects to filter by
-- advanced: boolean; additional menu with advanced / extended search
+- advanced: boolean; additional menu with advanced search
 - expert: boolean;  additional menu with expert search / gravsearch "editor"
 
 If everything is set to false or undefined the search-panel is a simple full-text search. [Read more](modules/search/search-panel)
@@ -51,7 +54,7 @@ We suggest to define a route for the search-results in the app.routing
         ]
 ```
 
-### [Extended / advanced search](/developers/dsp-ui/documentation/search/extended-search)
+### [Advanced search](/developers/dsp-ui/documentation/search/advanced-search)
 
 Generic search filter tool to limit search results to ontology and resource class and / or properties.
 

docs/how-to-use/search/search-panel.md

@@ -1,6 +1,6 @@
 # Search panel (Component)
 
-The search-panel contains the list of projects to filter and dsp-fulltext-search and links to dsp-extended-search and dsp-expert-search.
+The search-panel contains the list of projects to filter and dsp-fulltext-search and links to dsp-advanced-search and dsp-expert-search.
 
 ## Parameters
 

docs/how-to-use/viewer/search-results.md

@@ -47,7 +47,7 @@ export class SearchResultsComponent {
 ### HTML file
 
 ```html
-<!-- example of an extended search where we pass a gravsearch query as search parameter -->
+<!-- example of an advanced search where we pass a gravsearch query as search parameter -->
 <dsp-search-results [searchMode]="'extended'" [searchQuery]="gravsearch"></dsp-search-results>
 ```
 

mkdocs.yml

@@ -18,7 +18,7 @@ nav:
         - Introduction Search: how-to-use/search/index.md
         - Search-panel: how-to-use/search/search-panel.md
         - Fulltext search: how-to-use/search/fulltext-search.md
-        - Extended search: how-to-use/search/extended-search.md
+        - Advanced search: how-to-use/search/advanced-search.md
         - Expert search: how-to-use/search/expert-search.md
       - Action module:
         - Introduction Action: how-to-use/action/index.md

projects/dsp-ui/src/lib/search/advanced-search/resource-and-property-selection/select-property/specify-property-value/operator-constants.ts

@@ -12,13 +12,13 @@ export class ComparisonOperatorConstants {
      static GreaterThanComparisonLabel = 'is greater than';
 
      static GreaterThanEqualsComparisonOperator = '>=';
-     static GreaterThanEqualsComparisonLabel = 'is greater than equals to';
+     static GreaterThanEqualsComparisonLabel = 'is greater than or equal to';
 
      static LessThanComparisonOperator = '<';
      static LessThanComparisonLabel = 'is less than';
 
      static LessThanEqualsComparisonOperator = '<=';
-     static LessThanQualsComparisonLabel = 'is less than equals to';
+     static LessThanQualsComparisonLabel = 'is less than or equal to';
 
      static ExistsComparisonOperator = 'E';
      static ExistsComparisonLabel = 'exists';

projects/dsp-ui/src/lib/search/services/advanced-search-params.service.spec.ts

@@ -20,7 +20,7 @@ describe('SearchParamsService', () => {
         expect(searchParams.generateGravsearch(0)).toBeFalsy();
     });
 
-    it('should set the parameters of an extended search', () => {
+    it('should set the parameters of an advanced search', () => {
         const testMethod1 = (offset: number) => {
             return 'test1';
         };

projects/dsp-ui/src/lib/search/services/advanced-search-params.service.ts

@@ -2,7 +2,7 @@ import { Injectable } from '@angular/core';
 import { BehaviorSubject } from 'rxjs';
 
 /*
- * Represents the parameters of an extended search.
+ * Represents the parameters of an advanced search.
  */
 export class AdvancedSearchParams {
 
@@ -34,16 +34,16 @@ export class AdvancedSearchParamsService {
     }
 
     /**
-     * Updates the parameters of an extended search.
+     * Updates the parameters of an advanced search.
      *
-     * @param searchParams new extended search params.
+     * @param searchParams new advanced search params.
      */
     changeSearchParamsMsg(searchParams: AdvancedSearchParams): void {
         this._currentSearchParams.next(searchParams);
     }
 
     /**
-     * Gets the search params of an extended search.
+     * Gets the search params of an advanced search.
      *
      */
     getSearchParams(): AdvancedSearchParams {

projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.spec.ts

@@ -212,17 +212,17 @@ describe('ListViewComponent', () => {
 
     });
 
-    it('should do extended search', () => {
+    it('should do advanced search', () => {
 
         const searchSpy = TestBed.inject(DspApiConnectionToken);
 
-        // do extended search count query
+        // do advanced search count query
         expect(searchSpy.v2.search.doExtendedSearchCountQuery).toHaveBeenCalledWith('fake query');
 
         // generate gravesearch query
         expect(searchParamsServiceSpy.getSearchParams).toHaveBeenCalled();
 
-        // do extended search
+        // do advanced search
         expect(searchSpy.v2.search.doExtendedSearch).toHaveBeenCalledWith('fake query OFFSET 0');
         expect(testHostComponent.listViewGravsearch.resources.resources.length).toBe(5);
 

projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.ts

@@ -141,7 +141,7 @@ export class ListViewComponent implements OnChanges {
                 );
             }
 
-            // perform extended search
+            // perform advanced search
             const gravsearch = this._advancedSearchParamsService.getSearchParams().generateGravsearch(this.pageEvent.pageIndex);
 
             if (typeof gravsearch === 'string') {