More documentation

docs/reference/query_types.rst

@@ -1,7 +1,9 @@
 Query Types
 ===========
 
-Site API Query Types expand upon Query Type feature from eZ Publish Kernel, using the same basic interfaces. That will enable using your existing Query Types, but how Site API integrates them with the rest of the system differs from eZ Publish Kernel.
+Site API Query Types expand upon Query Type feature from eZ Publish Kernel, using the same basic
+interfaces. That will enable using your existing Query Types, but how Site API integrates them with
+the rest of the system differs from eZ Publish Kernel.
 
 Built-in Query Types
 --------------------
@@ -26,7 +28,9 @@ Location hierarchy
 Query Type configuration
 --------------------------------------------------------------------------------
 
-Query Types have their own semantic configuration under ``queries`` key in configuration for a particular Content view. Under this key separate queries are defined under their own identifier keys, which are later used to reference the configured query from the Twig templates.
+Query Types have their own semantic configuration under ``queries`` key in configuration for a
+particular Content view. Under this key separate queries are defined under their own identifier
+keys, which are later used to reference the configured query from the Twig templates.
 
 Available parameters and their default values are:
 
@@ -37,7 +41,8 @@ Available parameters and their default values are:
 - ``use_filter: true`` - whether to use ``FilterService`` or ``FindService`` for executing the query
 - ``parameters: []`` - contains the actual Query Type parameters
 
-Parameters ``query_type`` and ``named_query`` are mutually exclusive, you are allowed to set only one or the other. But they are also mandatory - you will have to set one of them.
+Parameters ``query_type`` and ``named_query`` are mutually exclusive, you are allowed to set only
+one or the other. But they are also mandatory - you will have to set one of them.
 
 Example below shows how described configuration looks in practice:
 
@@ -76,7 +81,10 @@ Example below shows how described configuration looks in practice:
 Named Query Type configuration
 ------------------------------
 
-As hinted above with ``named_query`` parameter, it is possible to define "named queries", which can be referenced in query configuration for a particular content view. They are configured under ``ng_named_query``, which is a top section of a siteaccess configuration, on the same level as ``ng_content_view``:
+As hinted above with ``named_query`` parameter, it is possible to define "named queries", which can
+be referenced in query configuration for a particular content view. They are configured under
+``ng_named_query``, which is a top section of a siteaccess configuration, on the same level as
+``ng_content_view``:
 
 .. code-block:: yaml
 
@@ -111,7 +119,8 @@ As hinted above with ``named_query`` parameter, it is possible to define "named
 
 .. note:: You can override some of the parameters from the referenced named query.
 
-You can notice that there are two ways of referencing a named query. In case when there are no other parameters, you can do it directly like this:.
+You can notice that there are two ways of referencing a named query. In case when there are no other
+parameters, you can do it directly like this:.
 
 .. code-block:: yaml
 
@@ -126,7 +135,9 @@ The example above is really just a shortcut to the example below:
         children:
             named_query: 'children_named_query'
 
-You can also notice that it's possible to override parameters from the referenced named query. This is limited to first level keys from the main configuration and also first level keys under the ``parameters`` key.
+You can also notice that it's possible to override parameters from the referenced named query. This
+is limited to first level keys from the main configuration and also first level keys under the
+``parameters`` key.
 
 Language expressions
 --------------------------------------------------------------------------------
@@ -136,11 +147,16 @@ TODO
 Accessing the configured queries from Twig
 --------------------------------------------------------------------------------
 
-Configured queries will be available in Twig templates, through ``ng_query`` or ``ng_raw_query``. The difference it that the former will return a ``Pagerfanta`` instance, while the latter will return an instance of ``SerachResult``. That also means ``ng_query`` will use ``max_per_page`` and ``page`` parameters to configure the pager, while ``ng_raw_query`` ignores them and executes the configured query directly.
+Configured queries will be available in Twig templates, through ``ng_query`` or ``ng_raw_query``.
+The difference it that the former will return a ``Pagerfanta`` instance, while the latter will
+return an instance of ``SerachResult``. That also means ``ng_query`` will use ``max_per_page`` and
+``page`` parameters to configure the pager, while ``ng_raw_query`` ignores them and executes the
+configured query directly.
 
 .. note:: Queries are only executed as you access them through ``ng_query`` or ``ng_raw_query``. If you don't call those functions on any of the configured queries, none of them will be executed.
 
-Both ``ng_query`` and ``ng_raw_query`` accept a single argument. This is the identifier of the query, which is the key under the ``queries`` section, under which the query is configured.
+Both ``ng_query`` and ``ng_raw_query`` accept a single argument. This is the identifier of the
+query, which is the key under the ``queries`` section, under which the query is configured.
 
 Example usage of ``ng_query``:
 

docs/reference/query_types/content_relations_all_tag_fields.rst

@@ -30,8 +30,63 @@ Examples
 
 Own conditions
 --------------------------------------------------------------------------------
-.. include:: /reference/query_types/parameters/query_type/content.rst.inc
-.. include:: /reference/query_types/parameters/query_type/exclude_self_content.rst.inc
+
+``content``
+~~~~~~~~~~~~
+
+Defines the source (from) relation Content, which is the one containing tag fields.
+
+.. note:: This condition is required.
+
+- **value type**: ``Content``
+- **value format**: ``single``
+- **operators**: none
+- **target**: none
+- **required**: ``true``
+- **default**: not defined
+
+  If used through view builder configuration, value will be automatically set to the ``Content`` instance resolved by the view builder.
+
+Examples:
+
+.. code-block:: yaml
+
+    # this is also automatically set when using from view builder configuration
+    location: '@=content'
+
+.. code-block:: yaml
+
+    # fetch relations from Content's main Location parent Location's Content
+    location: '@=content.mainLocation.parent.content'
+
+.. code-block:: yaml
+
+    # fetch relations from Content's main Location parent Location's parent Location's Content
+    location: '@=content.mainLocation.parent.parent.content'
+
+``exclude_self``
+~~~~~~~~~~~~~~~~
+
+Defines whether to include Content defined by the ``content`` condition in the result set.
+
+- **value type**: ``boolean``
+- **value format**: ``single``
+- **operators**: none
+- **target**: none
+- **required**: ``false``
+- **default**: ``true``
+
+Examples:
+
+.. code-block:: yaml
+
+    # do not include the source relation Content, this is also the default behaviour
+    exclude_self: true
+
+.. code-block:: yaml
+
+    # include the source relation Content
+    exclude_self: false
 
 .. include:: /reference/query_types/parameters/common_content_parameters.rst.inc
 .. include:: /reference/query_types/parameters/common_query_parameters.rst.inc

docs/reference/query_types/content_relations_forward_fields.rst

@@ -28,8 +28,61 @@ Examples
 
 Own conditions
 --------------------------------------------------------------------------------
-.. include:: /reference/query_types/parameters/query_type/content.rst.inc
-.. include:: /reference/query_types/parameters/query_type/relation_field.rst.inc
+
+``content``
+~~~~~~~~~~~~
+
+Defines the source (from) relation Content, which is the one containing relation type fields.
+
+.. note:: This condition is required.
+
+- **value type**: ``Content``
+- **value format**: ``single``
+- **operators**: none
+- **target**: none
+- **required**: ``true``
+- **default**: not defined
+
+  If used through view builder configuration, value will be automatically set to the ``Content`` instance resolved by the view builder.
+
+Examples:
+
+.. code-block:: yaml
+
+    # this is also automatically set when using from view builder configuration
+    location: '@=content'
+
+.. code-block:: yaml
+
+    # fetch relations from Content's main Location parent Location's Content
+    location: '@=content.mainLocation.parent.content'
+
+.. code-block:: yaml
+
+    # fetch relations from Content's main Location parent Location's parent Location's Content
+    location: '@=content.mainLocation.parent.parent.content'
+
+``relation_field``
+~~~~~~~~~~~~~~~~~~
+
+Defines Content fields to take into account for determining relations.
+
+- **value type**: ``string``
+- **value format**: ``single``, ``array``
+- **operators**: none
+- **target**: none
+- **required**: ``true``
+- **default**: not defined
+
+Examples:
+
+.. code-block:: yaml
+
+    relation_field: appellation
+
+.. code-block:: yaml
+
+    relation_field: [head, heart, base]
 
 .. include:: /reference/query_types/parameters/common_content_parameters.rst.inc
 .. include:: /reference/query_types/parameters/common_query_parameters.rst.inc

docs/reference/query_types/content_relations_reverse_fields.rst

@@ -26,10 +26,103 @@ This Query Type is used to build ....
 Examples
 --------------------------------------------------------------------------------
 
+Content of type ``article`` has relation field ``authors`` which is used to define relations to
+``author`` type Content. On full view for ``author`` fetch all articles authored by that author,
+sort them by title and paginate them by 10 per page using URL query parameter ``page``:
+
+.. code-block:: yaml
+
+    ezpublish:
+        system:
+            frontend_group:
+                ngcontent_view:
+                    full:
+                        author:
+                            template: '@ezdesign/content/full/author.html.twig'
+                            match:
+                                Identifier\ContentType: author
+                            queries:
+                                authored_articles:
+                                    query_type: SiteAPI:Content/Relations/ReverseFields
+                                    max_per_page: 10
+                                    page: '@=queryParam("page", 1)'
+                                    parameters:
+                                        relation_field: authors
+                                        content_type: article
+                                        sort: 'field/article/title asc'
+.. code-block:: twig
+
+    <h3>Author's articles:</h3>
+
+    <ul>
+    {% for article in ng_query( 'authored_articles' ) %}
+        <li>{{ article.name }}</li>
+    {% endfor %}
+    </ul>
+
+    {{ pagerfanta( children, 'twitter_bootstrap' ) }}
+
 Own parameters
 --------------------------------------------------------------------------------
-.. include:: /reference/query_types/parameters/query_type/content.rst.inc
-.. include:: /reference/query_types/parameters/query_type/relation_field.rst.inc
+
+``content``
+~~~~~~~~~~~~
+
+Defines the destination (to) relation Content.
+
+.. note:: This condition is required.
+
+.. note:: This is about **reverse** relations, which means that Content defined by this condition is
+          **not** the one containing relation type fields referenced by ``relation_field``, it's the
+          one receiving relations from Content containing those fields.
+
+- **value type**: ``Content``
+- **value format**: ``single``
+- **operators**: none
+- **target**: none
+- **required**: ``true``
+- **default**: not defined
+
+  If used through view builder configuration, value will be automatically set to the ``Content`` instance resolved by the view builder.
+
+Examples:
+
+.. code-block:: yaml
+
+    # this is also automatically set when using from view builder configuration
+    location: '@=content'
+
+.. code-block:: yaml
+
+    # fetch relations to Content's main Location parent Location's Content
+    location: '@=content.mainLocation.parent.content'
+
+.. code-block:: yaml
+
+    # fetch relations to Content's main Location parent Location's parent Location's Content
+    location: '@=content.mainLocation.parent.parent.content'
+
+``relation_field``
+~~~~~~~~~~~~~~~~~~
+
+Defines Content fields to take into account for determining relations.
+
+- **value type**: ``string``
+- **value format**: ``single``, ``array``
+- **operators**: none
+- **target**: none
+- **required**: ``true``
+- **default**: not defined
+
+Examples:
+
+.. code-block:: yaml
+
+    relation_field: authors
+
+.. code-block:: yaml
+
+    relation_field: [color, size]
 
 .. include:: /reference/query_types/parameters/common_content_parameters.rst.inc
 .. include:: /reference/query_types/parameters/common_query_parameters.rst.inc