inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-07-24 17:32:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ADF-2824] Reviewed search docs for 2.4 (#3477)

Browse Source 
* [ADF-2824] Moved search widget docs into separate pages

* [ADF-2824] Separated search widget page and added search filter service docs

* [ADF-2824] Updated new search docs with doc tools
This commit is contained in:
Andy Stark
2018-06-13 12:46:33 +01:00
committed by Eugenio Romano
parent c66573939f
commit 992cd38216
11 changed files with 777 additions and 503 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/content-services/search-check-list.component.md Normal file
View File

@@ -0,0 +1,77 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search check list component
Implements a checklist widget for the [Search Filter component](../content-services/search-filter.component.md).
![Check list widget screenshot](../docassets/images/search-check-list.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "checkList",
"name": "Check List",
"enabled": true,
"component": {
"selector": "check-list",
"pageSize": 5,
"settings": {
"operator": "OR",
"options": [
{ "name": "Folder", "value": "TYPE:'cm:folder'" },
{ "name": "Document", "value": "TYPE:'cm:content'" }
]
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| operator | `string` | Logical operator to combine query fragments. Can be 'AND' or 'OR'. |
| options | `array` | Array of objects with `name` and `value` properties. Each object defines a checkbox, labelled with `name`, that adds the query fragment in `value` to the query when enabled. |
## Details
This widget displays a list of checkboxes, each of which toggles a particular query fragment
in the search. See the [Search filter component](../content-services/search-filter.component.md) for full details of how to use the widgets
in a search query.
In the settings, the `options` array, defines the checkboxes that toggle the supplied query
fragments and the `operator` selects logical `AND` or `OR` to combine the fragments.
In the example above, if the user checks both boxes then the following fragment will be added
to the query:
```text
... (TYPE:'cm:folder' OR TYPE:'cm:content') ...
```
The component can be set to split a long checklist into separate pages of checkboxes
using the `pageSize` value as the number of boxes to show per page (default is 5).
When there is more than one page, the widget will display "Show more" and "Show less"
buttons as appropriate.
A "Clear all" button is also displayed at the bottom of the widget to clear all checked
items in the list.
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)

82
docs/content-services/search-date-range.component.md Normal file
View File

@@ -0,0 +1,82 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search date range component
Implements a date range widget for the [Search Filter component](../content-services/search-filter.component.md).
![Date Range Widget](../docassets/images/search-date-range.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "createdDateRange",
"name": "Created Date (range)",
"enabled": true,
"component": {
"selector": "date-range",
"settings": {
"field": "cm:created"
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| field | string | Field to apply the query to. Required value |
| dateFormat | string | Date format. Dates used by the datepicker are [Moment.js](https://momentjs.com/docs/#/parsing/string-format/) instances, so you can use any date format supported by Moment. Default is 'DD/MM/YYYY'. |
## Details
This component lets the user select a range between two dates based on the particular `field`.
See the [Search filter component](../content-services/search-filter.component.md) for full details of how to use widgets
in a search query.
### Custom date format
You can set the date range picker to work with any date format your app requires. You can use
any date format supported by [Moment.js](https://momentjs.com/docs/#/parsing/string-format/)
in the `dateFormat` setting:
```json
{
"search": {
"categories": [
{
"id": "createdDateRange",
"name": "Created Date (range)",
"enabled": true,
"component": {
"selector": "date-range",
"settings": {
"field": "cm:created",
"dateFormat": "DD-MMM-YY"
}
}
}
]
}
}
```
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)

562
docs/content-services/search-filter.component.md
View File

@@ -1,7 +1,7 @@
---
Added: v2.3.0
Status: Active
Last reviewed: 2018-04-16
Last reviewed: 2018-06-12
---
# Search Filter component
@@ -17,28 +17,10 @@ Represents a main container component for custom search and faceted search setti
- [Configuration](#configuration)
- [Extra fields and filter queries](#extra-fields-and-filter-queries)
- [Sorting](#sorting)
- [Categories](#categories)
- [Settings](#settings)
- [Categories and widgets](#categories-and-widgets)
- [Facet Fields](#facet-fields)
- [Facet Queries](#facet-queries)
- [Widgets](#widgets)
- [Check List Widget](#check-list-widget)
- [Date Range Widget](#date-range-widget)
- [Number Range Widget](#number-range-widget)
- [Radio List Widget](#radio-list-widget)
- [Slider Widget](#slider-widget)
- [Resetting slider value](#resetting-slider-value)
- [Text Widget](#text-widget)
- [Custom Widgets](#custom-widgets)
- [Implementing custom widget](#implementing-custom-widget)
- [Reading external settings](#reading-external-settings)
- [Updating final query](#updating-final-query)
- [Registering custom widget](#registering-custom-widget)
- [See also](#see-also)
## Basic usage
@@ -49,10 +31,12 @@ Represents a main container component for custom search and faceted search setti
## Details
The component is based on dynamically created widgets to modify the resulting query and options,
and the [Search Query Builder service](search-query-builder.service.md)\` to build and execute the search queries.
The component UI uses dynamically created widgets to specify the search query and its
options. It then uses the [Search Query Builder service](search-query-builder.service.md)
to build and execute the query.
Before you begin with customizations, check also the following articles:
You may find it useful to check out the following resources for background information
before customizing the search UI:
- [Search API](https://docs.alfresco.com/5.2/concepts/search-api.html)
- [Alfresco Full Text Search Reference](https://docs.alfresco.com/5.2/concepts/rm-searchsyntax-intro.html)
@@ -60,9 +44,8 @@ Before you begin with customizations, check also the following articles:
### Configuration
The configuration should be provided via the `search` entry in the `app.config.json` file.
Below is an example configuration:
You can configure the component using the `search` entry in the `app.config.json` file.
A typical configuration is shown below:
```json
{
@@ -121,11 +104,15 @@ Below is an example configuration:
}
```
Please refer to the [schema.json](https://github.com/Alfresco/alfresco-ng2-components/blob/master/lib/core/app-config/schema.json) to get more details on available settings, values and formats.
The
[schema.json](https://github.com/Alfresco/alfresco-ng2-components/blob/master/lib/core/app-config/schema.json)
file for the app config has further details about available settings, values and formats for
the configuration options.
### Extra fields and filter queries
You can explicitly define the `include` section for the query from within the application configuration file.
You can explicitly define the `include` section for the query from within the application configuration file. This array is a list of extra data fields to be added to the search
results:
```json
{
@@ -135,7 +122,8 @@ You can explicitly define the `include` section for the query from within the ap
}
```
In addition, it is also possible to provide a set of queries that are always executed alongside user-defined settings:
You can also provide a set of queries that are always executed alongside the user-defined
settings:
```json
{
@@ -152,9 +140,10 @@ Note that the entries of the `filterQueries` array are joined using the `AND` op
### Sorting
The Sorting configuration section consists of two blocks:
`options` that holds a list of items that users can select from,
and `defaults` that contains predefined sorting to use by default.
The Sorting configuration section consists of two blocks:
- `options`: a list of items that users can select from
- `defaults`: predefined sorting to use by default
```json
{
@@ -173,26 +162,28 @@ and `defaults` that contains predefined sorting to use by default.
}
```
#### Sorting Definition Attributes
The properties of the `options` objects are as follows:
| Name | Type | Description |
| ---- | ---- | ----------- |
| key | string | Unique key to identify the entry, can also be used to map DataColumn instances. |
| label | string | Display text, can also be an i18n resource key. |
| type | string | This specifies how to order - either by using a field or based on the position of the document in the index, or by score/relevance. |
| key | string | Unique key to identify the entry. This can also be used to map DataColumn instances. |
| label | string | Display text, which can also be an [i18n resource key](../user-guide/internationalization.md). |
| type | string | This specifies how to order the results. It can be based on a field, based on the position of the document in the index, or by score/relevance. |
| field | string | The name of the field. |
| ascending | boolean | The sorting order. |
| ascending | boolean | The sorting order defined as `true` for ascending order and `false` for descending order |
See also:
See the [Sort](https://docs.alfresco.com/5.2/concepts/search-api-sort.html)
element in the [ACS Search API](https://docs.alfresco.com/5.2/concepts/search-api.html)
for further details.
- Alfresco Content Services API Reference / Search Api / [Sort](https://docs.alfresco.com/5.2/concepts/search-api-sort.html)
### Categories and widgets
### Categories
The Search Settings component and Query Builder require a `categories` section in the
configuration.
The Search Settings component and Query Builder require a `categories` section provided within the configuration.
Categories are needed to build widgets so that users can modify the search query at runtime.
Every Category can be represented by a single Angular component, which can be either a simple one or a composite one.
Categories are used to configure the UI widgets that let the user edit the search query
at runtime. Every category is represented by a single Angular component, which can be
either a simple one or a composite one.
```ts
export interface SearchCategory {
@@ -211,15 +202,33 @@ The interface above also describes entries in the `search.query.categories` sect
![Search Categories](../docassets/images/search-categories-01.png)
> **Important note: you need at least one category field to be provided in order to execute the query,
> so that filters and selected facets are applied.**
> **Note:** you must provide at least one category field in order to execute the query,
> so that filters and selected facets are applied.
### Settings
The Search Filter supports a number of widgets out of the box, each implemented
by an ADF component. The `selector` property specifies which widget is used for
a category:
Every use case will have a different set of settings.
| Widget name | Selector | Description |
| ----------- | -------- | ----------- |
| [Check List](search-check-list.component.md) | `check-list` | Toggles individual query fragments for the search |
| [Date Range](search-date-range.component.md) | `date-range` | Specifies a range f dates that a field may contain |
| [Number Range](search-number-range.component.md) | `number-range` | Specifies a range of numeric values that a field may contain |
| [Radio List](search-radio.component.md) | `radio` | Selects one query fragment from a list of options |
| [Slider](search-slider.component.md) | `slider` | Selects a single numeric value in a given range that a field may contain |
| [Text](search-text.component.md) | `text` | Specifies a text value that a field may contain |
See the individual search widget pages for full details of their usage and settings.
You can also implement your own custom search widgets. See the [`SearchWidget`](../../lib/content-services/search/search-widget.interface.ts) interface
page for full details of how to do this.
#### Widget settings
Each type of widget has its own settings.
For example Number editors may parse minimum and maximum values, while Text editors can support value formats or length constraints.
You can use `component.settings` to pass any information to your custom widget using the
You can use `component.settings` to pass any information to a widget using the
[`SearchWidgetSettings`](../../lib/content-services/search/search-widget-settings.interface.ts) interface:
```ts
@@ -247,8 +256,9 @@ export interface SearchWidgetSettings {
Every field declared within the `facetFields` group is presented by a separate collapsible category at runtime.
By default, users see only top 5 entries.
If there are more than 5 entries, the "Show more" button is displayed to allow displaying next block of results.
By default, users see only the top 5 entries.
If there are more than 5 entries, the "Show more" button is displayed to let the user move to
the next block of results.
![Facet Fields](../docassets/images/search-facet-fields.png)
@@ -256,17 +266,17 @@ If there are more than 5 entries, the "Show more" button is displayed to allow d
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| field | string | | This specifies the facet field. |
| mincount | number | 1 | This specifies the minimum count required for a facet field to be included in the response. The default value is 1. |
| label | string | | This specifies the label to include in place of the facet field. |
| prefix | string | | This restricts the possible constraints to only indexed values with a specified prefix. |
| field | string | | Specifies the facet field. |
| mincount | number | 1 | Specifies the minimum count required for a facet field to be included in the response. The default value is 1. |
| label | string | | Specifies the label to include in place of the facet field. |
| prefix | string | | Restricts the possible constraints to only indexed values with a specified prefix. |
| limit | number | | Maximum number of results |
| pageSize | number | 5 | Display page size |
| offset | number | | Offset position |
### Facet Queries
Provides a custom category based on admin-defined facet queries.
These provide custom categories based on admin-defined facet queries.
```json
{
@@ -292,442 +302,26 @@ Provides a custom category based on admin-defined facet queries.
The queries declared in the `facetQueries` are collected into a single collapsible category.
Only the queries that have 1 or more response entries are displayed at runtime.
Based on the `pageSize` value, the component provides a `Show more` button to display more items.
The component provides a `Show more` button to display more items if the number of items
exceeds the `pageSize` value.
You can also provide a custom `label` (or i18n resource key) for the resulting collapsible category.
The `pageSize` property allows you to define the amount of results to display.
Users will see `Show more` or `Show less` buttons depending on the result set.
The default page size is `5`, it is going to be used in case you set the value to `0` or omit the value entirely.
The `pageSize` property allows you to define the number of results to display.
Users will see `Show more` or `Show less` buttons as appropriate for the result set.
The default page size of 5 will be used if you set the value to 0 or omit it entirely.
![Facet Queries](../docassets/images/search-facet-queries.png)
## Widgets
You can use external application configuration to define a set of Angular components (aka Search Filter Widgets)
that provide extra features and/or behaviour for the [Search Filter component](../content-services/search-filter.component.md).
The Search Filter supports the following widgets out of the box:
- Check List (`check-list`)
- Date Range (`date-range`)
- Number Range (`number-range`)
- Radio List (`radio`)
- Slider (`slider`)
- Text (`text`)
At runtime, ADF uses `selector` attribute values to map and create corresponding Angular element.
### Check List Widget
Provides you with a list of check-boxes, each backed by a particular query fragment.
You can choose a `label` (or i18n resources key) and a `value`, alongside the conditional `operator` (either `AND` or `OR`).
```json
{
"search": {
"categories": [
{
"id": "checkList",
"name": "Check List",
"enabled": true,
"component": {
"selector": "check-list",
"pageSize": 5,
"settings": {
"operator": "OR",
"options": [
{ "name": "Folder", "value": "TYPE:'cm:folder'" },
{ "name": "Document", "value": "TYPE:'cm:content'" }
]
}
}
}
]
}
}
```
![Check List Widget](../docassets/images/search-check-list.png)
If user checks both boxes, the underlying query will get the following fragment:
```text
... (TYPE:'cm:folder' OR TYPE:'cm:content') ...
```
It is possible to set the size of the page to display items. The default size is 5.
If all items fit a single page, then a "Clear all" action button is displayed at the bottom of the widget.
In case there are more than one page three icon buttons will be displayed to allow:
- clear all values
- show more items (if applicable)
- show less items (if applicable)
### Date Range Widget
Provides ability to select a range between two Dates based on the particular `field`.
```json
{
"search": {
"categories": [
{
"id": "createdDateRange",
"name": "Created Date (range)",
"enabled": true,
"component": {
"selector": "date-range",
"settings": {
"field": "cm:created"
}
}
}
]
}
}
```
![Date Range Widget](../docassets/images/search-date-range.png)
#### Widget Settings
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| field | string | `undefined` | Field to to use. Required value |
| dateFormat | string | 'DD/MM/YYYY' | Date format. Dates used by the datepicker are Moment.js instances, so please check the documentation on [Moment](https://momentjs.com/docs/#/parsing/string-format/) so you can set your required date format. |
#### Custom date format
You can set the date range picker to work with any date format your app requires. Just set the wanted value for the 'dateFormat' like this:
```json
{
"search": {
"categories": [
{
"id": "createdDateRange",
"name": "Created Date (range)",
"enabled": true,
"component": {
"selector": "date-range",
"settings": {
"field": "cm:created",
"dateFormat": "DD-MMM-YY"
}
}
}
]
}
}
```
### Number Range Widget
Provides ability to select a range between two Numbers based on the particular `field`.
```json
{
"search": {
"categories": [
{
"id": "contentSizeRange",
"name": "Content Size (range)",
"enabled": true,
"component": {
"selector": "number-range",
"settings": {
"field": "cm:content.size",
"format": "[{FROM} TO {TO}]"
}
}
}
]
}
}
```
![Number Range Widget](../docassets/images/search-number-range.png)
#### Widget Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| field | string | Field to to use |
| format | string | Value format. Uses string substitution to allow all sorts of [range queries](https://docs.alfresco.com/5.2/concepts/rm-searchsyntax-ranges.html). |
#### Range query format
For more details on the range search format please refer to the "[Search for ranges](https://docs.alfresco.com/5.2/concepts/rm-searchsyntax-ranges.html)" article.
The widget uses `{FROM}` and `{TO}` values together with the required target format of the query.
You can use any type of the query pattern, the widget automatically substitutes the values, for example:
```json
"settings": {
"field": "cm:content.size",
"format": "[{FROM} TO {TO}]"
}
```
The format above may result in the following query at runtime:
```text
cm:content.size:[0 TO 100]
```
Other format examples:
| Format | Example |
| ------ | ------- |
| `[{FROM} TO {TO}]` | `[0 TO 5]` |
| `<{FROM} TO {TO}]` | `<0 TO 5]` |
| `[{FROM} TO {TO}>` | `[0 TO 5>` |
| `<{FROM} TO {TO}>` | `<0 TO 5>` |
### Radio List Widget
Provides you with a list of radio-boxes, each backed by a particular query fragment.
The behaviour is very similar to those of the `check-list` except `radio` allows selecting only one item.
```json
{
"search": {
"categories": [
{
"id": "queryType",
"name": "Type",
"enabled": true,
"component": {
"selector": "radio",
"settings": {
"field": null,
"pageSize": 5,
"options": [
{ "name": "None", "value": "", "default": true },
{ "name": "All", "value": "TYPE:'cm:folder' OR TYPE:'cm:content'" },
{ "name": "Folder", "value": "TYPE:'cm:folder'" },
{ "name": "Document", "value": "TYPE:'cm:content'" }
]
}
}
}
]
}
}
```
![Radio Widget](../docassets/images/search-radio.png)
It is possible to set the size of the page to display items. The default size is 5.
In case there are more than one page three icon buttons will be displayed to allow:
- show more items (if applicable)
- show less items (if applicable)
### Slider Widget
Provides ability to select a numeric range based on `min` and `max` values in the form of horizontal slider.
```json
{
"search": {
"categories": [
{
"id": "contentSize",
"name": "Content Size",
"enabled": true,
"component": {
"selector": "slider",
"settings": {
"field": "cm:content.size",
"min": 0,
"max": 18,
"step": 1,
"thumbLabel": true
}
}
}
]
}
}
```
![Slider Widget](../docassets/images/search-slider.png)
### Resetting slider value
Slider widget comes with a `Clear` button that allows users to reset selected value to the initial state.
This helps to undo changes for scenarios where minimal value (like 0 or predefined number) still should not be used in a query.
Upon clicking the `Clear` button slider will be reset to the `min` value or `0`, and underlying fragment is removed from the resulting query.
### Text Widget
```json
{
"search": {
"categories": [
{
"id": "queryName",
"name": "Name",
"enabled": true,
"expanded": true,
"component": {
"selector": "text",
"settings": {
"pattern": "cm:name:'(.*?)'",
"field": "cm:name",
"placeholder": "Enter the name"
}
}
}
]
}
}
```
![Text Widget](../docassets/images/search-text.png)
> **Important note: you need at least one category field to be provided in order to execute the query,
> so that filters and selected facets are applied.**
## Custom Widgets
### Implementing custom widget
It is possible to create custom Angular components that display and/or modify resulting search query.
You start creating a Search Filter widget by generating a blank Angular component that implements [`SearchWidget`](../../lib/content-services/search/search-widget.interface.ts) interface:
```ts
export interface SearchWidget {
id: string;
settings?: SearchWidgetSettings;
context?: SearchQueryBuilderService;
}
```
Every widget implementation must have an `id`, and may also support external `settings`.
At runtime, every time a new instance of the widget is created, it also receives a reference to the [`SearchQueryBuilderService`](../content-services/search-query-builder.service.md)
so that you component can access query related information, events and methods.
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
id: string;
settings: SearchWidgetSettings;
context: SearchQueryBuilderService;
key1: string;
key2: string;
}
```
### Reading external settings
At runtime, ADF provides every Search Filter widget with the `settings` instance, based on the JSON data
that administrator has provided for your widget in the external configuration file.
It is your responsibility to parse the `settings` property values, convert types or setup defaults.
ADF does not provide any validation of the objects, it only reads from the configuration and passes data to your component instance.
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
id: string;
settings: SearchWidgetSettings;
context: SearchQueryBuilderService;
key1: string;
key2: string;
ngOnInit() {
if (this.settings) {
this.key1 = this.settings['key1'];
this.key2 = this.settings['key2'];
}
}
}
```
### Updating final query
The [`SearchQueryBuilderService`](../content-services/search-query-builder.service.md) keeps track on all query fragments populated by widgets
and composes them together alongside other settings when performing a final query.
Every query fragment is stored/retrieved using widget `id`.
It is your responsibility to format the query correctly.
Once your value is ready, update the context and run `update` method to let other components know the query has been changed:
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
...
onUIChanged() {
this.context.queryFragments[this.id] = `some query`;
this.context.update();
}
}
```
When executed, your fragment will be injected into the resulting query based on the category order in the application configuration file.
```text
... AND (widget1) AND (some query) AND (widget2) AND ...
```
### Registering custom widget
You can register your own Widgets by utilizing the [`SearchFilterService`](../../lib/content-services/search/components/search-filter/search-filter.service.ts) service:
```ts
import { MyComponent } from './my-component.ts'
@Component({...})
export class MyAppOrComponent {
constructor(searchFilterService: SearchFilterService) {
searchFilterService.widgets['my-widget'] = MyComponent;
}
}
```
That allows you to declare your widget in the external configuration
and pass custom attributes in case your component supports them:
```json
{
"search": {
"categories": [
{
"id": "someUniqueId",
"name": "String or i18n key",
"enabled": true,
"component": {
"selector": "my-widget",
"settings": {
"key1": "value1",
"key2": "value2",
"keyN": "valueN"
}
}
}
]
}
}
```
## See also
- [Search Query Builder service](search-query-builder.service.md)
- [Search Chip List Component](search-chip-list.component.md)
- [Search Sorting Picker Component](search-sorting-picker.component.md)
- [`SearchWidget`](../../lib/content-services/search/search-widget.interface.ts)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)

36
docs/content-services/search-filter.service.md Normal file
View File

@@ -0,0 +1,36 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-12
---
# Search filter service
Registers widgets for use with the [Search Filter component](../content-services/search-filter.component.md).
## Details
This component keeps track of all widgets registered for use with the
[Search Filter component](../content-services/search-filter.component.md). All the built-in widgets are registered by default
but you should register any new custom widgets you create explicitly:
```ts
import { MyComponent } from './my-component.ts'
@Component({...})
export class MyAppOrComponent {
constructor(searchFilterService: SearchFilterService) {
searchFilterService.widgets['my-widget'] = MyComponent;
}
}
```
See the Search Widget interface page for details about creating your own
custom search widgets.
## See also
- [`SearchWidget`](../../lib/content-services/search/search-widget.interface.ts)
- [Search Filter component](../content-services/search-filter.component.md)

78
docs/content-services/search-number-range.component.md Normal file
View File

@@ -0,0 +1,78 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search number range component
Implements a number range widget for the [Search Filter component](../content-services/search-filter.component.md).
![Number Range Widget](../docassets/images/search-number-range.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "contentSizeRange",
"name": "Content Size (range)",
"enabled": true,
"component": {
"selector": "number-range",
"settings": {
"field": "cm:content.size",
"format": "[{FROM} TO {TO}]"
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| field | string | Field to to use |
| format | string | Value format. Uses string substitution to allow all sorts of [range queries](https://docs.alfresco.com/5.2/concepts/rm-searchsyntax-ranges.html). |
## Details
This component lets the user specify a range between two predefined numbers based on the
particular `field`. See the [Search filter component](../content-services/search-filter.component.md) for full details of how to use widgets
in a search query.
#### Range query format
See the [Search for ranges](https://docs.alfresco.com/5.2/concepts/rm-searchsyntax-ranges.html) page in the ACS docs for more information about the date range format.
The `format` setting specifies how the date is displayed textually. Most of the format is
displayed as-is but you can use `{FROM}` and `{TO}` markers to interpolate the range limits
into the format string:
```json
"settings": {
"field": "cm:content.size",
"format": "[{FROM} TO {TO}]"
}
```
The format above would be displayed at runtime as follows:
```text
cm:content.size:[0 TO 100]
```
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)

48
docs/content-services/search-query-builder.service.md
View File

@@ -1,59 +1,64 @@
---
Added: v2.3.0
Status: Active
Last reviewed: 2018-06-12
---
# Search Query Builder service
Stores information from all the custom search and faceted search widgets, compiles and runs the final Search query.
Stores information from all the custom search and faceted search widgets, compiles and runs the final search query.
## Class members
### Methods
- **addFilterQuery**(query: `string` = `null`)<br/>
- _query:_ `string` -
Adds a new filter query.
- _query:_ `string` - Text of the query to add
- **buildQuery**(): `QueryBody`<br/>
Builds a new query using the added elements.
- **Returns** `QueryBody` - The resulting query
- **Returns** `QueryBody` -
- **execute**(): `Promise<void>`<br/>
- **Returns** `Promise<void>` -
- **execute**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)`<void>`<br/>
Executes the query.
- **Returns** [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)`<void>` - Notification of query completion
- **getFacetField**(label: `string` = `null`): [`FacetField`](../../lib/content-services/search/facet-field.interface.ts)<br/>
- _label:_ `string` -
- **Returns** [`FacetField`](../../lib/content-services/search/facet-field.interface.ts) -
Gets the details of a facet field.
- _label:_ `string` - Identifying label of the facet field
- **Returns** [`FacetField`](../../lib/content-services/search/facet-field.interface.ts) - Facet field details
- **getFacetQuery**(label: `string` = `null`): [`FacetQuery`](../../lib/content-services/search/facet-query.interface.ts)<br/>
- _label:_ `string` -
- **Returns** [`FacetQuery`](../../lib/content-services/search/facet-query.interface.ts) -
Gets the details of a facet query
- _label:_ `string` - Identifying label of the facet query
- **Returns** [`FacetQuery`](../../lib/content-services/search/facet-query.interface.ts) - Details of the facet query
- **getPrimarySorting**(): [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts)<br/>
Returns primary sorting definition.
- **Returns** [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts) -
- **Returns** [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts) - Sorting definition
- **getSortingOptions**(): [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts)`[]`<br/>
Returns all pre-configured sorting options that users can choose from.
- **Returns** [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts)`[]` -
- **Returns** [`SearchSortingDefinition`](../../lib/content-services/search/search-sorting-definition.interface.ts)`[]` - List of available sorting options
- **removeFilterQuery**(query: `string` = `null`)<br/>
- _query:_ `string` -
Removes a previously added filter query.
- _query:_ `string` - The query to remove
- **update**()<br/>
Builds the query and notifies subscribers when complete.
## Details
See the [Search filter component](search-filter.component.md) page for full details about the format of queries,
facet fields, and sorting options.
The Query Builder is UI agnostic and does not rely on Angular components.
You can reuse it with multiple component implementations.
You can use custom widgets to populate and edit the following parts of the resulting query:
- categories
- query fragments that form query expression
- query fragments that form a query expression
- include fields
- scope settings
- filter queries
@@ -73,3 +78,8 @@ constructor(queryBuilder: SearchQueryBuilderService) {
}
```
## See also
- [Search filter component](search-filter.component.md)
- [Search Widget interface](search-widget.interface.md)

67
docs/content-services/search-radio.component.md Normal file
View File

@@ -0,0 +1,67 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search radio component
Implements a radio button list widget for the [Search Filter component](../content-services/search-filter.component.md).
![Radio Widget screenshot](../docassets/images/search-radio.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "queryType",
"name": "Type",
"enabled": true,
"component": {
"selector": "radio",
"settings": {
"field": null,
"pageSize": 5,
"options": [
{ "name": "None", "value": "", "default": true },
{ "name": "All", "value": "TYPE:'cm:folder' OR TYPE:'cm:content'" },
{ "name": "Folder", "value": "TYPE:'cm:folder'" },
{ "name": "Document", "value": "TYPE:'cm:content'" }
]
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| options | `array` | Array of objects with `name` and `value` properties. Each object defines a radio button, labelled with `name`, that adds the query fragment in `value` to the query when enabled. Set the `default` property to `true` for one item to have it selected initially when the widget is displayed. |
## Details
This component displays a list of radio buttons, each of which toggles a particular
query fragment in the search. This behaviour is very similar to that of the
[Search check list component](../content-services/search-check-list.component.md) except only one item at a time can be selected. See the
[Search filter component](../content-services/search-filter.component.md) for full details of how to use the widgets in a search query.
The component can be set to split a long list of buttons into separate pages
using the `pageSize` value as the number of buttons to show per page (default is 5).
When there is more than one page, the widget will display "Show more" and "Show less"
buttons as appropriate.
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)

74
docs/content-services/search-slider.component.md Normal file
View File

@@ -0,0 +1,74 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search slider component
Implements a numeric slider widget for the [Search Filter component](../content-services/search-filter.component.md).
![Slider Widget](../docassets/images/search-slider.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "contentSize",
"name": "Content Size",
"enabled": true,
"component": {
"selector": "slider",
"settings": {
"field": "cm:content.size",
"min": 0,
"max": 18,
"step": 1,
"thumbLabel": true
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| field | string | Field to apply the query fragment to. Required value |
| min | number | Minimum numeric value at the left end of the slider |
| max | number | Maximum numeric value at the right end of the slider |
| step | number | The step between adjacent positions on the slider |
| thumbLabel | boolean | Toggles whether the "thumb" of the slider should show the current value |
## Details
This component lets the user select from a range between two predefined numbers based on the
particular `field`. See the [Search filter component](../content-services/search-filter.component.md) for full
details of how to use widgets in a search query.
### Resetting the slider value
The query fragment represented by the slider will not be added to the query until a value is
selected by the user. However, once the slider has been moved, there is no way to use it to
go back to the initial state (ie, the query fragment will be present regardless of the final
value of the slider). This can be a problem in cases where even a zero or minimum value can
affect the query.
To handle this situation, the slider comes with a `Clear` button to reset the value to the
initial state. When the user clicks this button, the slider control is set to the `min` value
or zero and the corresponsing query fragment is removed from the query.
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search text component](../content-services/search-text.component.md)

59
docs/content-services/search-text.component.md Normal file
View File

@@ -0,0 +1,59 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-11
---
# Search text component
Implements a text input widget for the [Search Filter component](../content-services/search-filter.component.md).
![Text Widget](../docassets/images/search-text.png)
## Basic usage
```json
{
"search": {
"categories": [
{
"id": "queryName",
"name": "Name",
"enabled": true,
"expanded": true,
"component": {
"selector": "text",
"settings": {
"pattern": "cm:name:'(.*?)'",
"field": "cm:name",
"placeholder": "Enter the name"
}
}
}
]
}
}
```
### Settings
| Name | Type | Description |
| ---- | ---- | ----------- |
| field | string | Field to apply the query fragment to. Required value |
| pattern | string | Regular expression pattern to restrict the format of the input text |
| placeholder | string | Text displayed in the widget when the input string is empty |
## Details
This component lets the user add a text value to search for in the specified
`field`. See the [Search filter component](../content-services/search-filter.component.md) for full
details of how to use widgets in a search query.
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)

196
docs/content-services/search-widget.interface.md Normal file
View File

@@ -0,0 +1,196 @@
---
Added: v2.4.0
Status: Active
Last reviewed: 2018-06-12
---
# Search widget interface
Specifies required properties for [Search filter component](../content-services/search-filter.component.md) widgets.
## Contents
- [Basic usage](#basic-usage)
- [Properties](#properties)
- [Details](#details)
- [Implementing a custom widget](#implementing-a-custom-widget)
- [Reading external settings](#reading-external-settings)
- [Updating the final query](#updating-the-final-query)
- [Registering a custom widget](#registering-a-custom-widget)
- [See also](#see-also)
## Basic usage
```ts
export interface SearchWidget {
id: string;
settings?: SearchWidgetSettings;
context?: SearchQueryBuilderService;
}
```
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| id | `string` | | Unique identifying value for the widget |
| settings | [`SearchWidgetSettings`](../../lib/content-services/search/search-widget-settings.interface.ts) | | Settings for component properties |
| context | [`SearchQueryBuilderService`](../content-services/search-query-builder.service.md) | | Instance of the Search Query Builder service to process the query |
## Details
The [Search Filter component](../content-services/search-filter.component.md) uses widgets to provide the UI that lets the user customize the
search. ADF provides a number of widgets out of the box (see the [See Also](#see-also) section
for a full list) but you can also implement your own. Both built-in and custom widgets must
implement the Search Widget interface to operate with the Search Filter component.
### Implementing a custom widget
To create a custom Search Filter widget, start by generating a blank Angular component
that implements the
[`SearchWidget`](../../lib/content-services/search/search-widget.interface.ts)
interface:
```ts
export interface SearchWidget {
id: string;
settings?: SearchWidgetSettings;
context?: SearchQueryBuilderService;
}
```
Every widget implementation must have an `id`, and may also support external `settings`.
At runtime, every time a new instance of the widget is created, it also receives a reference to the [`SearchQueryBuilderService`](../content-services/search-query-builder.service.md)
so that you component can access query related information, events and methods.
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
id: string;
settings: SearchWidgetSettings;
context: SearchQueryBuilderService;
key1: string;
key2: string;
}
```
### Reading external settings
At runtime, ADF provides every search filter widget with a `settings` instance,
based on the JSON data that the administrator has provided for your widget in the
`app.config.json` file.
It is your responsibility to parse the `settings` property values and also to
convert types and set up defaults as necessary. ADF does not provide any validation
of the objects. It only reads from the configuration and passes the data to your component
instance.
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
id: string;
settings: SearchWidgetSettings;
context: SearchQueryBuilderService;
key1: string;
key2: string;
ngOnInit() {
if (this.settings) {
this.key1 = this.settings['key1'];
this.key2 = this.settings['key2'];
}
}
}
```
### Updating the final query
The [`SearchQueryBuilderService`](../content-services/search-query-builder.service.md) keeps track of all query fragments that have been added by search widgets.
When the query is complete, it composes the fragments together alongside other settings
that will be used when performing the actual query.
Every query fragment is stored and retrieved using its widget `id`.
It is your responsibility to format the query correctly.
Once your change to the query is finished, update the context and call the `update` method
to inform other components about the change:
```ts
@Component({...})
export class MyComponent implements SearchWidget, OnInit {
...
onUIChanged() {
this.context.queryFragments[this.id] = `some query`;
this.context.update();
}
}
```
When executed, your fragment will be injected into the resulting query based on the category order in the application configuration file.
```text
... AND (widget1) AND (some query) AND (widget2) AND ...
```
### Registering a custom widget
You must register your custom widgets with the [Search Filter service](../content-services/search-filter.service.md):
```ts
import { MyComponent } from './my-component.ts'
@Component({...})
export class MyAppOrComponent {
constructor(searchFilterService: SearchFilterService) {
searchFilterService.widgets['my-widget'] = MyComponent;
}
}
```
When you have done this, you can declare your widget in `app.config.json`
and pass custom attributes, if your component supports them:
```json
{
"search": {
"categories": [
{
"id": "someUniqueId",
"name": "String or i18n key",
"enabled": true,
"component": {
"selector": "my-widget",
"settings": {
"key1": "value1",
"key2": "value2",
"keyN": "valueN"
}
}
}
]
}
}
```
## See also
- [Search filter component](../content-services/search-filter.component.md)
- [Search check list component](../content-services/search-check-list.component.md)
- [Search date range component](../content-services/search-date-range.component.md)
- [Search number range component](../content-services/search-number-range.component.md)
- [Search radio component](../content-services/search-radio.component.md)
- [Search slider component](../content-services/search-slider.component.md)
- [Search text component](../content-services/search-text.component.md)