From b5f346aa8fdb717a3012af52b96f12c898ae645a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Fastr=C3=A9?= <julien.fastre@champs-libres.coop>
Date: Thu, 2 May 2019 23:13:38 +0200
Subject: [PATCH] documentation for new options in search

---
 source/development/searching.rst | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/source/development/searching.rst b/source/development/searching.rst
index c033c0e17..023d16a6e 100644
--- a/source/development/searching.rst
+++ b/source/development/searching.rst
@@ -100,7 +100,7 @@ The SearchInterface class
 
        // indicate which domain you support
        // you may respond TRUE to multiple domain, according to your logic
-       public function supports($domain)
+       public function supports($domain, $format='html')
        {
            return 'person' === $domain;
        }
@@ -121,7 +121,7 @@ The SearchInterface class
        // This is where your search logic should be executed. 
        // This method must return an HTML string (a string with HTML tags)
        // see below about the structure of the $term array
-       public function renderResult(array $terms, $start = 0, $limit = 50, array $options = array())
+       public function renderResult(array $terms, $start = 0, $limit = 50, array $options = array(), $format = 'html')
        {  
            return $this->container->get('templating')->render('ChillPersonBundle:Person:list.html.twig', 
                    array( 
@@ -137,6 +137,17 @@ The SearchInterface class
    }
 
 
+Values for :code:`$options`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:code:`$options` is an array with the following keys: 
+
+- :code:`SearchInterface::SEARCH_PREVIEW_OPTION` (bool): if the current view is a preview (the first 5 results) or not ;
+- :code:`SearchInterface::REQUEST_QUERY_PARAMETERS` (bool): some parameters added to the query (under the key :code:`SearchInterface::REQUEST_QUERY_KEY_ADD_PARAMETERS`) and that can be interpreted. Used, for instance, when calling a result in json format when searching for interactive picker form.
+
+
+
+
 Structure of array `$term`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -161,6 +172,21 @@ The original search would have been : `@person argument1:value argument2:(my val
 .. warning::
    The search values are always unaccented.
 
+Returning a result in json
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The json format is mainly used by "select2" widgets.
+
+When returning a result in json, the SearchInterface should only return an array with following keys:
+
+- :code:`more` (bool): if the search has more result than the current page ;
+- :code:`results` (array): a list of result, where: 
+
+    - :code:`text` (string): the text that should be displayed in browser ;
+    - :code:`id` (string): the id of the entity.
+
+
+
 Register the service
 --------------------