implementing pagination api on search, and creating a "preview" of results

The search controller return a subset of the 5 first results. If the user want to
see more, the services implementing SearchInterface should add a link "see more",
and make use of the Pagination API to paginate.

Search/SearchInterface.php

@@ -31,6 +31,9 @@ namespace Chill\MainBundle\Search;
  */
 interface SearchInterface
 {
+
+    const SEARCH_PREVIEW_OPTION = '_search_preview';
+
    /** 
     * return the result in a html string. The string will be inclued (as raw)
     * into a global view.
@@ -39,6 +42,16 @@ interface SearchInterface
     * {% for result as resultsFromDifferentSearchInterface %}
     *    {{ result|raw }}
     * {% endfor %}
+    * 
+    * **available options** :
+    * - SEARCH_PREVIEW_OPTION (boolean) : if renderResult should return a "preview" of 
+    * the results. In this case, a subset of results should be returned, and,
+    * if the query return more results, a button "see all results" should be
+    * displayed at the end of the list.
+    * 
+    * **Interaction between `start` and `limit` and pagination : you should 
+    * take only the given parameters into account; the results from pagination 
+    * should be ignored. (Most of the time, it should be the same). 
     *
     * @param array  $terms   the string to search
     * @param int    $start   the first result (for pagination)