[TASK] Add the rest of the documentation to rst. (#547)

Fixes: #546

Documentation/Backend/ConnectionManager.rst

@@ -0,0 +1,23 @@
+ConnectionManager
+=================
+
+In EXT:solr all the configuration, including options affecting backend functions, are done in TypoScript. The clear cache menu provides an entry to initialize the Solr connections configured in TypoScript.
+
+How it works
+------------
+
+* Configure the Solr connection in TypoScript under plugin.tx_solr.solr, providing host, port, and path.
+* On your site's root page set the flag Use as Root Page on the Behaviour tab.
+* Initialize the Solr connections through the clear cache menu
+
+.. figure:: ../Images/GettingStarted/typo3-initialize-connections.png
+
+    Initialize all solr connections
+
+When initializing the Solr connections the extensions looks for all the pages with the root flag set, generates the TypoScript configuration for that page like in the frontend and reads the Solr connection parameters.
+
+The extension also repeats that process for each language configured on the installation's root (uid = 0). This way you can configure different Solr cores for each language by using regular conditions that change the path of the Solr connection depending on the currently selected language.
+
+Once all the configured Solr connections in the installation are found, they're stored in TYPO3's registry so that they can easily be retrieved without needing to reevaluate the TypoScript configuration every time we connect to Solr.
+
+All that magic happens in class source:Classes/ConnectionManager.php. The connection manager and it's public API actually must be used whenever a Solr connection is needed.

Documentation/Backend/Index.rst

@@ -28,7 +28,8 @@ In this chapter we want to go deeper and learn how to write more complex indexin
 	:maxdepth: 5
 	:glob:
 
-    	IndexQueue
-    	BackendModule
-    	IndexInspector
-    	Scheduler
+    ConnectionManager
+    IndexQueue
+    BackendModule
+    IndexInspector
+    Scheduler

Documentation/FAQ/Index.rst

@@ -83,6 +83,13 @@ Example:
 
 |
 
+
+**The extension is indexing into the wrong core for multi-language sites. What's wrong?**
+
+When indexing pages the page indexer retrieves the core from the TypoScript configuration. That configuration is determined by the language (GET L parameter). However, when the indexer tries to index a page that has not been translated TYPO3 will by default still render the page but falling back to the default language page. By that TYPO3 will also use the TypoScript configuration for the default language which usually points to a different Solr core.
+
+Solution: Make sure you have configured config.sys_language_mode to use content_fallback. This way TYPO3 will fall back to the configured language's content, but will use the TypoScript configuration for the requested language.
+
 **When i change a record, no update is detected. What's wrong?**
 
 Are your records inside of your site root? EXT:solr record monitor processes records that belong to your site, which means they need to be below your site root.
@@ -147,4 +154,66 @@ You can use the backend module synonyms (:ref:`Synonyms`) to maintain synonyms a
 
 *Ask DKD support*
 
-Beside that, there are more options to tune. The DKD support can help you, to analyze and tune your search results. Call +49 (0)69 - 247 52 18-0.
+Beside that, there are more options to tune. The DKD support can help you, to analyze and tune your search results. Call +49 (0)69 - 247 52 18-0.
+
+**Non ASCII characters like german umlauts do not work when i search, how do I fix that?**
+
+To allow search with umlauts Tomcat needs to be configured to use UTF-8 encoded urls. Go to apache-tomcat/conf/server.xml and change the URIEncoding parameter:
+
+
+|
+
+.. code-block:: xml
+
+    <Connector port="8080" protocol="HTTP/1.1"
+        connectionTimeout="20000" redirectPort="8443"
+        URIEncoding="UTF-8" />
+
+**How can I change Solr's schema and add custom fields?**
+
+Please do not change the shipped solr schema. There are a lot of dynamic fields (:ref:`appendix-dynamic-fields`) that can be used to index any kind of datatype.
+
+**I am using varnish before my site. How can i index pages properly?**
+
+SOLR Indexer might have some issues, when the page to index is behind a Varnish Proxy. We have collected two ways of solving this issue
+
+*Bypassing varnish:*
+
+Bypass when X-Tx-Solr-Iq is present
+
+The SOLR indexer request send the header X-Tx-Solr-Iq.
+
+To have bypass the Varnish caching, put this into your sub vcl_recv part of the configuration
+
+
+|
+
+::
+
+    if (req.http.X-Tx-Solr-Iq) {
+        return(pipe);
+    }
+
+
+*Using Cache-Control:*
+
+Put this into your sub vcl_fetch part of the configuration
+
+|
+
+::
+
+    if (req.http.Cache-Control ~ "no-cache") {
+        set beresp.ttl = 0s;
+        #Make sure ESI includes are processed!
+        esi;
+        set beresp.http.X-Cacheable = "NO:force-reload";
+        #Make sure that We remove alle cache headers, so the Browser does not cache it for us!
+        remove beresp.http.Cache-Control;
+        remove beresp.http.Expires;
+        remove beresp.http.Last-Modified;
+        remove beresp.http.ETag;
+        remove beresp.http.Pragma;
+
+          return (deliver);
+    }

Documentation/Frontend/Facets.rst

@@ -0,0 +1,245 @@
+.. This file will be replaced from solrfluid later
+
+======
+Facets
+======
+
+The goal of a good search is, that the user will find what he is looking for as fast as possible.
+To support this goal you can give information from the results to the user to "drill down" or "filter" the results
+up to a point where he exactly finds what he was looking for. This concept is called "faceting".
+
+Imagine a user in an online shoe shop is searching for the term "shoe", wouldn't it be useful to allow
+the user to filter by "gender", "color" and "brand" to find exactly the model where he is looking for?
+
+In the following paragraphs we will get an overview about the different facet types that can be created on a solr field
+just by adding a few lines of configuration.
+
+Facet Types
+===========
+
+A solr field can contain different type of data, where different facets make sence. The simplest facet is an option "facet".
+The "options facet" just contains a list of values and the user can choose one or many of them. A more complex type
+could be a "range facet" on a price field. A facet like this needs to allow to filter on a range of a minimum and a maximum value.
+
+The "type" of a facet can be controlled with the "type" property. When nothing is configured there, the facet will be threated
+as option facet.
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search.faceting.facets.[faceName].type = [typeName]
+
+
+|
+
+Valid types could be: options | queryGroup | hierarchy | dateRange | numericRange
+
+In the following paragraphs we will introduce the available facet types in EXT:solr and show how to configure them.
+
+Option
+------
+
+The simplest and most often used facet type is the options facet. It renders the items that could be filtered as a simple list.
+
+To setup an simple options facet you can use the following TypoScript snipped:
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search {
+        faceting = 1
+        faceting {
+            facets {
+                contentType {
+                    label = Content Type
+                    field = type
+                }
+            }
+        }
+    }
+
+|
+
+By using this configuration you create an options facet on the solr field "type" with the name "contentType". This field represents the record type, that was
+indexed into solr. Shown in the frontend it will look like this:
+
+.. image:: ../Images/Frontend/Facets/options_facet.png
+
+
+Query Group
+-----------
+
+The query group facet renders an option list, compareable to the options facet, but the single options are not created from
+plain solr field values. They are created from dynamic queries.
+
+A typical usecase could be, when you want to offer the possiblity to filter on the creation date and want to offer options like "yesterday", "last year" or "more then five years".
+
+With the following example you can configure a query facet:
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search {
+        faceting = 1
+        faceting {
+            facets {
+                 age {
+                    label = Age
+                    field = created
+                    type = queryGroup
+                    queryGroup {
+                        week.query = [NOW/DAY-7DAYS TO *]
+                        old.query = [* TO NOW/DAY-7DAYS]
+                    }
+                }
+            }
+        }
+    }
+
+|
+
+The example above will generate an options facet with the output "week" (for items from the last week) and "old" (for items older then one week).
+
+The output in the frontend will look like this:
+
+.. image:: ../Images/Frontend/Facets/queryGroup_facet.png
+
+
+Hierarchical
+------------
+
+With the hierarchical facets you can render a tree view in the frontend. A common usecase is to render a category tree where a document belongs to.
+
+With the following example you render a very simple rootline tree in TYPO3:
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search {
+        faceting = 1
+        faceting {
+            facets {
+                pageHierarchy {
+                    field = rootline
+                    label = Rootline
+                    type = hierarchy
+                }
+             }
+        }
+    }
+
+|
+
+The example above just shows a simple example tree that is just rendering the uid's of the rootline as a tree:
+
+
+.. image:: ../Images/Frontend/Facets/hierarchy_facet.png
+
+
+**Technical solr background:**
+
+Technically the hierarchical facet for solr is the same as a flat options facet. The support of hierarchies is implemented,
+by writing and reading the facet options by a convention:
+
+|
+
+.. code-block:: typoscript
+
+    [depth]-/Level1Label/Level2Label
+
+|
+
+When you follow this convention by writing date into a solr field you can render it as hierarchical facet. As example you can check indexing configuration in EXT:solr (EXT:solr/Configuration/ TypoScript/Solr/setup.txt)
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr {
+        index {
+            fieldProcessingInstructions {
+                rootline = pageUidToHierarchy
+            }
+        }
+    }
+
+|
+
+In this case the "fieldProcessingInstruction" "pageUidToHierarchy" is used to create the rootline for solr in the conventional way.
+
+
+Date Range
+----------
+
+When you want to provide a range filter on a date field in EXT:solr, you can use the type **"dateRange"**.
+
+The default partial generates a markup with all needed values in data attributes. Together with the provided jQuery ui implementation you can
+create an out-of-the-box date range facet.
+
+With the following typoscript you create a date range facet:
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search {
+        faceting = 1
+        faceting {
+            creationDateRange {
+                label = Created Between
+                field = created
+                type = dateRange
+            }
+        }
+    }
+
+|
+
+
+When you include this template a date range facet will be shown in the frontend that we look like this:
+
+.. image:: ../Images/Frontend/Facets/dateRange_facet.png
+
+
+Numeric Range
+-------------
+
+Beside dates ranges are also usefull for numeric values. A typical usecase could be a price slider for a products page.
+With the user interface you should be able to filter the documents for a certain price range.
+
+In the default partial, we also ship a partial with data attributes here to support any custom implementation.
+By default we will use the current implementation from EXT:solr based on jQueryUi.
+
+The following example configures a **numericRange** facet for the field **"pid"**:
+
+|
+
+.. code-block:: typoscript
+
+    plugin.tx_solr.search {
+        faceting = 1
+        faceting {
+            pidRangeRange {
+                field = pid
+                label = Pid Range
+                type = numericRange
+                numericRange {
+                    start = 0
+                    end = 100
+                    gap = 1
+                }
+            }
+        }
+    }
+
+|
+
+When you configure a facet on the pid field like this, the frontend will output the following facet:
+
+.. image:: ../Images/Frontend/Facets/numericRange_facet.png
+
+