Skip to content

Latest commit

 

History

History
327 lines (269 loc) · 12.7 KB

search-filter.component.md

File metadata and controls

327 lines (269 loc) · 12.7 KB
Added Status Last reviewed
v2.3.0
Active
2018-06-12

Search Filter component

Represents a main container component for custom search and faceted search settings.

Contents

Basic usage

<adf-search-filter #settings></adf-search-filter>

Details

The component UI uses dynamically created widgets to specify the search query and its options. It then uses the Search Query Builder service to build and execute the query.

You may find it useful to check out the following resources for background information before customizing the search UI:

Configuration

You can configure the component using the search entry in the app.config.json file. A typical configuration is shown below:

{
    "search": {
        "sorting": {
            "options": [
                { "key": "name", "label": "Name", "type": "FIELD", "field": "cm:name", "ascending": true },
                { "key": "content.sizeInBytes", "label": "Size", "type": "FIELD", "field": "content.size", "ascending": true },
                { "key": "description", "label": "Description", "type": "FIELD", "field": "cm:description", "ascending": true }
            ],
            "defaults": [
                { "key": "name", "type": "FIELD", "field": "cm:name", "ascending": true }
            ]
        },
        "filterQueries": [
            { "query": "TYPE:'cm:folder' OR TYPE:'cm:content'" },
            { "query": "NOT cm:creator:System" }
        ],
        "facetFields": {
          "expanded": true,
          "fields": [
            { "field": "content.mimetype", "mincount": 1, "label": "Type" },
            { "field": "content.size", "mincount": 1, "label": "Size" },
            { "field": "creator", "mincount": 1, "label": "Creator" },
            { "field": "modifier", "mincount": 1, "label": "Modifier" }
          ]
        },
        "facetQueries": {
            "label": "My facet queries",
            "pageSize": 4,
            "queries": [
                { "query": "created:2018", "label": "Created This Year" },
                { "query": "content.mimetype", "label": "Type" },
                { "query": "content.size:[0 TO 10240]", "label": "Size: xtra small"},
                { "query": "content.size:[10240 TO 102400]", "label": "Size: small"},
                { "query": "content.size:[102400 TO 1048576]", "label": "Size: medium" },
                { "query": "content.size:[1048576 TO 16777216]", "label": "Size: large" },
                { "query": "content.size:[16777216 TO 134217728]", "label": "Size: xtra large" },
                { "query": "content.size:[134217728 TO MAX]", "label": "Size: XX large" }
            ]
        },
        "categories": [
            {
                "id": "queryName",
                "name": "Name",
                "enabled": true,
                "expanded": true,
                "component": {
                    "selector": "adf-search-text",
                    "settings": {
                        "pattern": "cm:name:'(.*?)'",
                        "field": "cm:name",
                        "placeholder": "Enter the name"
                    }
                }
            }
        ]
    }
}

The 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. This array is a list of extra data fields to be added to the search results:

{
    "search": {
        "include": ["path", "allowableOperations"]
    }
}

You can also provide a set of queries that are always executed alongside the user-defined settings:

{
    "search": {
        "filterQueries": [
            { "query": "TYPE:'cm:folder' OR TYPE:'cm:content'" },
            { "query": "NOT cm:creator:System" }
        ]
    }
}

Note that the entries of the filterQueries array are joined using the AND operator.

Sorting

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
{
    "search": {
        "sorting": {
            "options": [
                { "key": "name", "label": "Name", "type": "FIELD", "field": "cm:name", "ascending": true },
                { "key": "content.sizeInBytes", "label": "Size", "type": "FIELD", "field": "content.size", "ascending": true },
                { "key": "description", "label": "Description", "type": "FIELD", "field": "cm:description", "ascending": true }
            ],
            "defaults": [
                { "key": "name", "type": "FIELD", "field": "cm:name", "ascending": true }
            ]
        }
    }
}

The properties of the options objects are as follows:

Name Type Description
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.
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 defined as true for ascending order and false for descending order

See the Sort element in the ACS Search API for further details.

Categories and widgets

The Search Settings component and Query Builder require a categories section in the configuration.

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.

export interface SearchCategory {
    id: string;
    name: string;
    enabled: boolean;
    expanded: boolean;
    component: {
        selector: string;
        settings: SearchWidgetSettings;
    };
}

The interface above also describes entries in the search.query.categories section for the app.config.json file.

Search Categories

Note: you must provide at least one category field in order to execute the query, so that filters and selected facets are applied.

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:

Widget name Selector Description
Check List check-list Toggles individual query fragments for the search
Date Range date-range Specifies a range f dates that a field may contain
Number Range number-range Specifies a range of numeric values that a field may contain
Radio List radio Selects one query fragment from a list of options
Slider slider Selects a single numeric value in a given range that a field may contain
Text 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 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 a widget using the SearchWidgetSettings interface:

export interface SearchWidgetSettings {
    field: string;
    [indexer: string]: any;
}

Facet Fields

{
    "search": {
        "facetFields": [
            { "field": "content.mimetype", "mincount": 1, "label": "Type" },
            { "field": "content.size", "mincount": 1, "label": "Size" },
            { "field": "creator", "mincount": 1, "label": "Creator" },
            { "field": "modifier", "mincount": 1, "label": "Modifier" },
            { "field": "created", "mincount": 1, "label": "Created" }
        ]
    }
}

Every field declared within the facetFields group is presented by a separate collapsible category at runtime.

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

FacetField Properties

Name Type Default Description
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

These provide custom categories based on admin-defined facet queries.

{
    "search": {
        "facetQueries": {
            "label": "Facet queries",
            "pageSize": 5,
            "expanded": true,
            "queries": [
                { "query": "created:2018", "label": "Created This Year" },
                { "query": "content.mimetype", "label": "Type" },
                { "query": "content.size:[0 TO 10240]", "label": "Size: xtra small"},
                { "query": "content.size:[10240 TO 102400]", "label": "Size: small"},
                { "query": "content.size:[102400 TO 1048576]", "label": "Size: medium" },
                { "query": "content.size:[1048576 TO 16777216]", "label": "Size: large" },
                { "query": "content.size:[16777216 TO 134217728]", "label": "Size: xtra large" },
                { "query": "content.size:[134217728 TO MAX]", "label": "Size: XX large" }
            ]
        }
    }
}

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. 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 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

See also