Add documentation for Location::getFirstChild()

netgen · Nov 21, 2019 · 4fb2d15 · 4fb2d15
1 parent f0d124d
commit 4fb2d15
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 0 deletions.
diff --git a/docs/reference/objects.rst b/docs/reference/objects.rst
@@ -558,6 +558,33 @@ children returned and defaults to ``25``.
 |                                        |                                                                                    |
 +----------------------------------------+------------------------------------------------------------------------------------+
 
+``getFirstChild``
+.................
+
+Get the first child of the Location.
+
+First child will be returned from children sorted as is defined by their parent Location, which is
+the Location the method is called on. The single optional parameter of this method is
+``$contentTypeIdentifier``, which returned Location must match.
+
++----------------------------------------+------------------------------------------------------------------------------------+
+| **Parameters**                         | ``?string $contentTypeIdentifier = null``                                          |
++----------------------------------------+------------------------------------------------------------------------------------+
+| **Returns**                            | First child `Location`_ or ``null`` if there are no children Locations             |
++----------------------------------------+------------------------------------------------------------------------------------+
+| **Sorting method**                     | As is defined by the Location                                                      |
++----------------------------------------+------------------------------------------------------------------------------------+
+| **Example in PHP**                     | .. code-block:: php                                                                |
+|                                        |                                                                                    |
+|                                        |     $firstChild = $location->getFirstChild('article');                             |
+|                                        |                                                                                    |
++----------------------------------------+------------------------------------------------------------------------------------+
+| **Example in Twig**                    | .. code-block:: twig                                                               |
+|                                        |                                                                                    |
+|                                        |     {% set first_child = location.firstChild('article') %}                         |
+|                                        |                                                                                    |
++----------------------------------------+------------------------------------------------------------------------------------+
+
 ``filterChildren``
 ..................
 

diff --git a/docs/reference/templating.rst b/docs/reference/templating.rst
@@ -430,6 +430,32 @@ Location children
     {% endfor %}
     </ul>
 
+- **Accessing the first child of a Location**
+
+  This is done by calling the method ``getFirstChild()``, also available as ``firstChild()`` in
+  Twig. It has one optional parameter, which is a ContentType identifier that returned Location must
+  match. In our example, the ContentType identifier is ``blog_post``. Returned Location will be
+  the first one from the children Locations sorted as is defined by their parent Location, which is
+  the Location the method is called on.
+
+  .. code-block:: twig
+
+    {% set first_child = location.firstChild('blog_post') %}
+
+    {% if first_child is not null %}
+        <p>
+            First blog post, as sorted by the parent Location:
+            <a href="{{ path(first_child) }}">{{ first_child.content.name }}</a>
+        </p>
+    {% else %}
+        <p>There are no blog posts under this Location</p>
+    {% endif %}
+
+  .. note::
+
+    If the Location doesn't contain any children, optionally limited by the the given ContentType,
+    the method will return ``null``. Make sure to check if that's the case.
+
 - **Filtering through Location's children**
 
   This is done by calling the method ``filterChildren()``, which returns a Pagerfanta instance