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

* [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

docs/content-services/search-widget.interface.md

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