alfresco-ng2-components/docs/content-services/interfaces/search-widget.interface.md

Title, Added, Status, Last reviewed

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
  • Properties
• Details
  • Implementing a custom widget
  • Reading external settings
  • Updating the final query
  • Registering a custom widget
• See also

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

• Search filter component
• Search check list component
• Search date range tabbed component
• Search number range component
• Search radio component
• Search slider component
• Search text component