add docs for output channels

dachcom-digital · Dec 7, 2021 · 4b2f275 · 4b2f275
1 parent 8a3ab37
commit 4b2f275
Show file tree

Hide file tree

Showing 4 changed files with 233 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -49,10 +49,10 @@ The Dynamic Search Bundle allows you to redefine your search strategy. It's base
 - [Data Creation](#)
     - [Enable automatic Update / Insert / Delete Service](#)
 - [Data Fetching](#)
-    - [Output Channels](#)
-        - [Create Output Channel](#)
+    - [Output Channels](docs/30_OutputChannels.md)
+        - [Create Output Channel](docs/300_CreateOutputChannel.md)
         - [Multi Search Channels](#)
-        - [Channel Filter / Actions](#)
+        - [Channel Filter / Actions](docs/302_ChannelFilterActions.md)
     - [Filter (Faceted Search / Aggregation)](#)
         - [Create Filter Definition](#)
 - [API](#)

diff --git a/docs/300_CreateOutputChannel.md b/docs/300_CreateOutputChannel.md
@@ -0,0 +1,116 @@
+# Create Output Channel
+
+## Basic steps
+- create a service tagged with `name`: `dynamic_search.output_channel` and a meaningful `identifer`
+- register your service:
+    ```yaml
+    dynamic_search:
+        context:
+            default:
+                output_channels:
+                    my_output:
+                        service: <your-identifer>
+    ```
+- your service must implement `DynamicSearchBundle\OutputChannel\OutputChannelInterface`
+  - add your implementation in `getQuery` and `getResult`
+  - optional: define `options` for your output channel
+
+## Example
+
+**app/config/services.yaml**
+```yaml
+services:
+    AppBundle\DynamicSearch\OutputChannel\MyOutputChannel:
+        tags:
+            - { name: dynamic_search.output_channel, identifier: my_output_channel }
+```
+
+**app/config/config.yaml**
+  ```yaml
+dynamic_search:
+    context:
+        default:
+            output_channels:
+                my_output:
+                    service: 'my_output_channel'
+                    use_frontend_controller: true
+                    options:
+                        query_option: true
+                        result_option: false
+```
+
+**AppBundle/DynamicSearch/OutputChannel/MyOutputChannel.php** 
+```php
+
+namespace AppBundle\DynamicSearch\OutputChannel;
+
+use DynamicSearchBundle\EventDispatcher\OutputChannelModifierEventDispatcher;
+use DynamicSearchBundle\OutputChannel\Context\OutputChannelContextInterface;
+use DynamicSearchBundle\OutputChannel\OutputChannelInterface;
+use DynamicSearchBundle\OutputChannel\Query\SearchContainerInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+class MyOutputChannel implements OutputChannelInterface
+{
+    // properties, getters and setters of OutputChannelInterface go here
+    // omitted in this example ...
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function configureOptions(OptionsResolver $optionsResolver)
+    {
+        // define your options
+        $optionsResolver->setRequired([
+            'query_option'
+        ]);
+
+        $optionsResolver->setDefaults([
+            'query_option' => false,
+            'result_option' => true
+        ]);
+
+        $optionsResolver->setAllowedTypes('query_option', ['bool']);
+        $optionsResolver->setAllowedTypes('result_option', ['bool']);
+    }
+    
+    /**
+     * {@inheritdoc}
+     */
+    public function getQuery()
+    {        
+        $queryTerm = $this->outputChannelContext->getRuntimeQueryProvider()->getUserQuery();
+        
+        // create your query
+        $query = ...
+        
+        // respect your options
+        if ($this->options['query_option']) {
+            // do something with $query
+        }
+        
+        return $query;
+    }
+    
+    /**
+     * {@inheritdoc}
+     */
+    public function getResult(SearchContainerInterface $searchContainer): SearchContainerInterface
+    {
+        $query = $searchContainer->getQuery();
+
+        // get your results
+        $result = ...
+        
+        // respect your options
+        if ($this->options['result_option']) {
+            // do something with $result
+        }
+
+        $searchContainer->result->setData($result);
+        $searchContainer->result->setHitCount(count($result));
+
+        return $searchContainer;
+    }
+}
+```
diff --git a/docs/302_ChannelFilterActions.md b/docs/302_ChannelFilterActions.md
@@ -0,0 +1,69 @@
+# Output Channel Filters / Actions
+
+## Filters
+
+@todo
+
+## Actions
+
+For most scenarios, especially when using an index provider bundle with existing output channel implementations, it is not required to create a new output channel if you want to modify the search behaviour (fields, boosting, etc.).
+Dynamic search offers the ability to modify the query by listening to actions.
+
+### Basic steps
+
+- create a service tagged with
+  - `name`: `dynamic_search.output_channel.modifier.action`
+  - `output_channel_service_identifier`: `all` to hook into all registered output channels, or the service identifier of one specific output channel.
+  - `action`: the action (event) to which the modifier should listen. for valid action identifiers, check the docs of the package which is providing the output channel  
+    you are using (implementation of `OutputChannelInterface`), or search for `$this->eventDispatcher->dispatchAction` in the output channel implementation  
+  - `priority`: the priority, default `0`
+- your modifier must implement `OutputChannelModifierActionInterface`
+- add your implementation for `dispatchAction`, e.g. modify the query in `OutputModifierEvent`
+
+### Example
+
+The following example shows how to modify the query in the `SearchOutputChannel` of the [elastic search](https://github.com/dachcom-digital/pimcore-dynamic-search-index-provider-elasticsearch) package:
+
+**app/config/services.yaml**
+```yaml
+    AppBundle\DynamicSearch\OutputChannel\Action\Search\MySearchAction:
+        tags:
+            - { name: dynamic_search.output_channel.modifier.action, output_channel_service_identifier: all, action: post_query_build }
+```
+
+**AppBundle/DynamicSearch/OutputChannel/Action/Search/MySearchAction.php**
+```php
+<?php
+
+namespace AppBundle\DynamicSearch\OutputChannel\Action\Search;
+
+use DynamicSearchBundle\Event\OutputModifierEvent;
+use DynamicSearchBundle\OutputChannel\Allocator\OutputChannelAllocatorInterface;
+use DynamicSearchBundle\OutputChannel\Modifier\OutputChannelModifierActionInterface;
+
+class MySearchAction implements OutputChannelModifierActionInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function dispatchAction(string $action, OutputChannelAllocatorInterface $outputChannelAllocator, OutputModifierEvent $event): OutputModifierEvent
+    {
+        /** @var Search $query */
+        $query = $event->getParameter('query');
+        $term = $event->getParameter('term');
+        $outputChannelName = $outputChannelAllocator->getOutputChannelName();
+
+        if ($outputChannelName !== 'search') {
+            return $event;
+        }
+        if ($action !== 'post_query_build') {
+            return $event;
+        }
+
+        // modify query here, e.g. $query->addQuery(...) 
+
+        $event->setParameter('query', $query);
+
+        return $event;
+    }
+```
diff --git a/docs/30_OutputChannels.md b/docs/30_OutputChannels.md
@@ -0,0 +1,45 @@
+# Output Channels
+
+Output channels in general control how data is fetched, as well as the output of the retrieved data.
+The concept of output channels offers high flexibility since there's no limitation regarding the search index provider and how data is queried and output.
+
+## Configuration
+
+### General
+`dynamic_search.context.default.output_channels.<output-channel-name>`
+
+| property                   | description                                                                                                                       | default                                                |
+|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
+| `multiple`                 | wether this output channel is a composition of multiple search containers                                                         | `false`                                                |
+| `service`                  | service for the output channel. must implement `OutputChannelInterface` or `MultiOutputChannelInterface`, if `multiple` is `true` | `null`                                                 |
+| `use_frontend_controller`  | wether to use the `SearchFrontendController` for twig output, or the `SearchController` for json output                           | `false`                                                |
+| `view_name`                | name of the view to use. only effective if `use_frontend_controller` is `true`                                                    | `MultiList` if `multiple` is `true`, `List` otherwise. |
+| `runtime_query_provider`   | service for query provider. must implement `RuntimeQueryProviderInterface`                                                        | `default`                                              |
+| `runtime_options_builder`  | service for options builder. must implement `RuntimeOptionsBuilderInterface`                                                      | `default`                                              |
+| `internal`                 | for internal use                                                                                                                  | `false`                                                |
+
+### Options
+`dynamic_search.context.default.output_channels.<output-channel-name>.options`
+
+options for the output channel go here
+
+### Paginator
+`dynamic_search.context.default.output_channels.<output-channel-name>.paginator`
+
+| property        | description                                                         | default                                                      |
+|-----------------|---------------------------------------------------------------------|--------------------------------------------------------------|
+| `enabled`       | wether paging is enabled                                            | `false`                                                      |
+| `adapter_class` | implementation to use for paging. must implement `AdapterInterface` | `DynamicSearchBundle\Paginator\Adapter\DynamicSearchAdapter` |
+| `max_per_page`  | max results per page                                                | `10`                                                         |
+
+### Normalizer
+
+| property      | description                                                                                  | default |
+|---------------|----------------------------------------------------------------------------------------------|---------|
+| `service`     | service to use as normalizer for each document. Must implement `DocumentNormalizerInterface` | `null`  |
+
+## Further reading
+
+Check out the following implementations of `OutputChannelInterface`:
+- [SearchOutputChannel](https://github.com/dachcom-digital/pimcore-dynamic-search-index-provider-elasticsearch/blob/master/src/DsElasticSearchBundle/OutputChannel/SearchOutputChannel.php) of `pimcore-dynamic-search-index-provider-elasticsearch`
+- [SearchOutputChannel](https://github.com/dachcom-digital/pimcore-dynamic-search-index-provider-lucene/blob/master/src/DsLuceneBundle/OutputChannel/SearchOutputChannel.php) of `pimcore-dynamic-search-index-provider-lucene`