diff --git a/README.md b/README.md index 30da38086..60a8b35dd 100644 --- a/README.md +++ b/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/) diff --git a/docs/assets/images/advanced-search-linked-resource.png b/docs/assets/images/advanced-search-linked-resource.png new file mode 100644 index 000000000..02a5fc4b2 Binary files /dev/null and b/docs/assets/images/advanced-search-linked-resource.png differ diff --git a/docs/assets/images/advanced-search-match.png b/docs/assets/images/advanced-search-match.png new file mode 100644 index 000000000..5151e0e2f Binary files /dev/null and b/docs/assets/images/advanced-search-match.png differ diff --git a/docs/assets/images/advanced-search-regex.png b/docs/assets/images/advanced-search-regex.png new file mode 100644 index 000000000..4cb9ecff9 Binary files /dev/null and b/docs/assets/images/advanced-search-regex.png differ diff --git a/docs/assets/images/extended-search.png b/docs/assets/images/advanced-search.png similarity index 100% rename from docs/assets/images/extended-search.png rename to docs/assets/images/advanced-search.png diff --git a/docs/how-to-contribute/design-documentation.md b/docs/how-to-contribute/design-documentation.md index ed1176ac5..273bc9c28 100644 --- a/docs/how-to-contribute/design-documentation.md +++ b/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. diff --git a/docs/how-to-use/search/advanced-search-user-docs.md b/docs/how-to-use/search/advanced-search-user-docs.md new file mode 100644 index 000000000..be340661a --- /dev/null +++ b/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) + diff --git a/docs/how-to-use/search/advanced-search.md b/docs/how-to-use/search/advanced-search.md new file mode 100644 index 000000000..8c0502158 --- /dev/null +++ b/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 + + + + + + ``` + +![Advanced search panel with a search example](../../assets/images/advanced-search.png) diff --git a/docs/how-to-use/search/expert-search.md b/docs/how-to-use/search/expert-search.md index 1186bd610..b90774d83 100644 --- a/docs/how-to-use/search/expert-search.md +++ b/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 diff --git a/docs/how-to-use/search/extended-search.md b/docs/how-to-use/search/extended-search.md deleted file mode 100644 index 34716505b..000000000 --- a/docs/how-to-use/search/extended-search.md +++ /dev/null @@ -1,25 +0,0 @@ -# Extended search (Component) - -The extended search allows you to filter by project, by source type (resource class), or by the metadata (properties) of source types. Each filter can be standalone 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 extended search form. -gravsearch | string | Send the gravsearch query back. - -## Examples - -Extended search panel - -```html - - - - - -``` - -![Advanced search panel with a search example](../../assets/images/extended-search.png) diff --git a/docs/how-to-use/search/index.md b/docs/how-to-use/search/index.md index 13fd3e457..4bdb3933c 100644 --- a/docs/how-to-use/search/index.md +++ b/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. diff --git a/docs/how-to-use/search/search-panel.md b/docs/how-to-use/search/search-panel.md index cb5925141..88fd70696 100644 --- a/docs/how-to-use/search/search-panel.md +++ b/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 diff --git a/docs/how-to-use/viewer/search-results.md b/docs/how-to-use/viewer/search-results.md index 8878217a6..1a7353625 100644 --- a/docs/how-to-use/viewer/search-results.md +++ b/docs/how-to-use/viewer/search-results.md @@ -47,7 +47,7 @@ export class SearchResultsComponent { ### HTML file ```html - + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 41950bb21..9b2dd8d60 100644 --- a/mkdocs.yml +++ b/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 diff --git a/projects/dsp-ui/src/lib/search/advanced-search/resource-and-property-selection/select-property/specify-property-value/operator-constants.ts b/projects/dsp-ui/src/lib/search/advanced-search/resource-and-property-selection/select-property/specify-property-value/operator-constants.ts index 0378d86fa..f4b2b2395 100644 --- a/projects/dsp-ui/src/lib/search/advanced-search/resource-and-property-selection/select-property/specify-property-value/operator-constants.ts +++ b/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'; diff --git a/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.spec.ts b/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.spec.ts index 828015010..be6b645d5 100644 --- a/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.spec.ts +++ b/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'; }; diff --git a/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.ts b/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.ts index 5246d4bcc..850b11dbf 100644 --- a/projects/dsp-ui/src/lib/search/services/advanced-search-params.service.ts +++ b/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 { diff --git a/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.spec.ts b/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.spec.ts index 8efcf241b..3d02b7092 100644 --- a/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.spec.ts +++ b/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); diff --git a/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.ts b/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.ts index 7d7cfcec2..88db79250 100644 --- a/projects/dsp-ui/src/lib/viewer/views/list-view/list-view.component.ts +++ b/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') {