Skip to content

Commit c0aff8b

Browse files
bobdenotterbobdenotter
authored
Merge pull request #1274 from doenietzomoeilijk/relations-directions
WIP: Add documentation for relation direactionality
2 parents 925e1ee + c1e54ce commit c0aff8b

File tree

7 files changed

+107
-43
lines changed

7 files changed

+107
-43
lines changed

‎docs/contenttypes/relationships.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,58 @@ To get the related records in twig, use the _filter_ `related`.
5959
</ul>
6060
{% endif %}
6161
```
62+
63+
Relations and directions
64+
------------------------
65+
Relationships have a direction; they point _from_ a content record _to_ another.
66+
This directionality comes into play when fetching related records.
67+
68+
For example, you may have a contenttype `entries` that has a relation to
69+
`entries` itself; this allows you to show hand-selected "related posts".
70+
71+
When you edit record A, and select record B as a relation in the Relations tab,
72+
the relation will be _from_ A _to_ B.
73+
74+
The directionality in relations allows you to either select _all_ records with a
75+
relation to the current record, in any direction, or you can specify that you
76+
only want one of the directions.
77+
78+
Let's take this example:
79+
80+
```yaml
81+
entries:
82+
name: Entries
83+
singular_name: Entry
84+
fields:
85+
[..]
86+
relations:
87+
entries:
88+
multiple: true
89+
required: false
90+
label: Select one or more related entries
91+
order: -id
92+
[..]
93+
```
94+
95+
Then, after adding some content and making relations between the entries, we can
96+
display them in the templates using the `related()` method. If you'd use the
97+
previous example of Twig code, you'd get _all_ related records for the current
98+
record, regardless of contenttype or direction.
99+
100+
Using the second parameter of the `related()` method, you can specify which
101+
relations you want to see. For instance, to only display relations to other
102+
records of the `entries` contenttype, that the current record is the "from" end
103+
for, you'd do this:
104+
105+
```twig
106+
{% set relatedrecords = record|related("entries", "from") %}
107+
{% if relatedrecords is not empty %}
108+
<p>Related content:</p>
109+
<ul>
110+
{% for related in relatedrecords %}
111+
<li><a href="{{ related|link }}">{{ related.title }}</a></li>
112+
{% endfor %}
113+
</ul>
114+
{% endif %}
115+
```
116+

‎docs/twig-components/filters.md

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -295,12 +295,12 @@ add the `raw` modifier.
295295

296296
Returns an array of records that are related to the given record.
297297

298-
| Parameter | Description |
299-
|----------------|-------------|
300-
| `name` | The related content's name or contenttype. If not set, it will fetch all related records. |
301-
| `bidirectional`| Performs bidirectional search. Default is `true` |
302-
| `limit` | Limits the number of related records that are returned. |
303-
| `publishedOnly`| Return only related records that are published. Default is `true` |
298+
| Parameter | Description |
299+
| ---------------- | ------------- |
300+
| `name` | The related content's name or contenttype. If not set, it will fetch all related records. |
301+
| `direction` | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
302+
| `limit` | Limits the number of related records that are returned. |
303+
| `publishedOnly` | Return only related records that are published. Default is `true` |
304304

305305
```twig
306306
{% set relatedrecords = record|related() %}
@@ -324,21 +324,21 @@ Returns a two-dimensional array of related records, where the first key is the c
324324
]
325325
```
326326

327-
| Parameter | Description |
328-
|----------------|-------------|
329-
| `bidirectional`| Performs bidirectional search. Default is `true` |
330-
| `limit` | Limits the number of related records that are returned. |
331-
| `publishedOnly`| Return only related records that are published. Default is `true` |
327+
| Parameter | Description |
328+
| ---------------- | ------------- |
329+
| `direction` | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
330+
| `limit` | Limits the number of related records that are returned. |
331+
| `publishedOnly` | Return only related records that are published. Default is `true` |
332332

333333
## related_first
334334

335335
Returns the first of the returned related records.
336336

337-
| Parameter | Description |
338-
|----------------|-------------|
339-
| `name` | The related content's name or contenttype. If not set, it will fetch all related records. |
340-
| `bidirectional`| Performs bidirectional search. Default is `true` |
341-
| `publishedOnly`| Return only related records that are published. Default is `true` |
337+
| Parameter | Description |
338+
| ---------------- | ------------- |
339+
| `name` | The related content's name or contenttype. If not set, it will fetch all related records. |
340+
| `direction` | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
341+
| `publishedOnly` | Return only related records that are published. Default is `true` |
342342

343343
## round, ceil and floor
344344

@@ -665,3 +665,4 @@ instead. For example: <code>{{ app.request.get('foo') }}</code>.</p>
665665
[switch]: http://php.net/manual/en/control-structures.switch.php
666666
[extras]: ./extras
667667
[popup_function]: ./functions#popup-magnific-popup
668+
[direction]: ../contenttypes/relationships#relations-and-directions

‎docs/twig-components/method/related.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# related
22

3-
`related(name = null, bidirectional = true, limit = null, publishedOnly = true)` is a Twig filter to return an array of
3+
`related(name = null, direction = true, limit = null, publishedOnly = true)` is a Twig filter to return an array of
44
records that are related to the given record.
55

6-
|Parameter |Description
7-
|---|---
8-
|name |The related content's name or contenttype. If not set, it will fetch all related records.
9-
|bidirectional |Performs bidirectional search. Default is true
10-
|limit |Limits the number of related records that are returned.
11-
|publishedOnly |Return only related records that are published. Default is true
6+
| Parameter | Description |
7+
| --- | --- |
8+
| name | The related content's name or contenttype. If not set, it will fetch all related records. |
9+
| direction | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
10+
| limit | Limits the number of related records that are returned. |
11+
| publishedOnly | Return only related records that are published. Default is true |
1212

1313
```twig
1414
{% set relatedrecords = record|related() %}
@@ -20,3 +20,5 @@ records that are related to the given record.
2020
</ul>
2121
</p>
2222
```
23+
24+
[direction]: ../../contenttypes/relationships#relations-and-directions

‎docs/twig-components/method/related_by_type.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# related_by_type
22

3-
`related_by_type(bidirectional = true, limit = null, publishedOnly = true)` is a Twig filter to return a two-dimensional
3+
`related_by_type(direction = "both", limit = null, publishedOnly = true)` is a Twig filter to return a two-dimensional
44
array of related records, where the first key is the contenttype.
55

66
```twig
@@ -10,8 +10,10 @@ array of related records, where the first key is the contenttype.
1010
]
1111
```
1212

13-
|Parameter |Description
14-
|---|---
15-
|bidirectional |Performs bidirectional search. Default is true
16-
|limit |Limits the number of related records that are returned.
17-
|publishedOnly |Return only related records that are published. Default is true
13+
| Parameter | Description |
14+
| --- | --- |
15+
| direction | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
16+
| limit | Limits the number of related records that are returned. |
17+
| publishedOnly | Return only related records that are published. Default is true |
18+
19+
[direction]: ../../contenttypes/relationships#relations-and-directions

‎docs/twig-components/method/related_content.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
`related_content(content, name = null, bidirectional = true, limit = null, publishedOnly = true)`
44

5-
See [related filter](https://docs.boltcms.io/5.0/twig-components/filters#related)
5+
See [related filter](../filters#related)

‎docs/twig-components/method/related_content_by_type.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# related_content_by_type
22

3-
`related_content_by_type(content, bidirectional = true, limit = null, publishedOnly = true)` is a Twig filter to return a two-dimensional
3+
`related_content_by_type(content, direction = "both", limit = null, publishedOnly = true)` is a Twig filter to return a two-dimensional
44
array of related records, grouped by the contenttype.
55

66
```twig
@@ -10,9 +10,11 @@ array of related records, grouped by the contenttype.
1010
]
1111
```
1212

13-
|Parameter |Description
14-
|---|---
15-
|content |The related content's name or contenttype. If not set, it will fetch all related records.
16-
|bidirectional |Performs bidirectional search. Default is true
17-
|limit |Limits the number of related records that are returned.
18-
|publishedOnly |Return only related records that are published. Default is true
13+
| Parameter | Description |
14+
| --- | --- |
15+
| content | The related content's name or contenttype. If not set, it will fetch all related records. |
16+
| direction | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
17+
| limit | Limits the number of related records that are returned. |
18+
| publishedOnly | Return only related records that are published. Default is true |
19+
20+
[direction]: ../../contenttypes/relationships#relations-and-directions

‎docs/twig-components/method/related_first.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# related_first
22

3-
`related_first(name = null, publishedOnly = true)` is a Twig filter to return the first of the returned related records.
3+
`related_first(name = null, direction = "both" publishedOnly = true)` is a Twig filter to return the first of the returned related records.
44

5-
|Parameter |Description
6-
|---|---
7-
|name |The related content's name or contenttype. If not set, it will fetch all related records.
8-
|bidirectional |Performs bidirectional search. Default is true
9-
|publishedOnly |Return only related records that are published. Default is true
5+
| Parameter | Description |
6+
| --- | --- |
7+
| name | The related content's name or contenttype. If not set, it will fetch all related records. |
8+
| direction | Limit relations to a direction. Default is "both"; see [Relations and directions][direction] for more info. |
9+
| publishedOnly | Return only related records that are published. Default is true |
10+
11+
[direction]: ../../contenttypes/relationships#relations-and-directions

0 commit comments

Comments
 (0)