Skip to content

Latest commit

 

History

History
193 lines (149 loc) · 6.76 KB

search-widget.interface.md

File metadata and controls

193 lines (149 loc) · 6.76 KB
Raw
Title Added Status Last reviewed
Search widget interface
v2.4.0
Active
2018-06-12

Search widget interface

Specifies required properties for Search filter component widgets.

Contents

Basic usage

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 Settings for component properties
context SearchQueryBuilderService Instance of the Search Query Builder service to process the query

Details

The Search Filter component 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 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 interface:

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 Search Query Builder Service so that you component can access query related information, events and methods.

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

@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 Search Query Builder Service 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:

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

... AND (widget1) AND (some query) AND (widget2) AND ...

Registering a custom widget

You must register your custom widgets with the Search Filter service:

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:

{
    "search": {
        "categories": [
            {
                "id": "someUniqueId",
                "name": "String or i18n key",
                "enabled": true,
                "component": {
                    "selector": "my-widget",
                    "settings": {
                        "key1": "value1",
                        "key2": "value2",
                        "keyN": "valueN"
                    }
                }
            }
        ]
    }
}

See also