You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**How to work with references between content objects**
12
+
This chapter describes how to work with references between content objects.
13
13
14
-
References are a way to maintain links between content that remain valid
15
-
even if one or both of the linked items are moved or renamed.
14
+
References are a way to maintain links between content that remain valid, even if one or both of the linked items are moved or renamed.
16
15
17
-
Under the hood, Dexterity’s reference system uses [five.intid], a Zope
18
-
2 integration layer for [zope.intid], to give each content item a unique
19
-
integer id. These are the basis for relationships maintained with the
20
-
[zc.relationship] package, which in turn is accessed via an API
21
-
provided by [z3c.relationfield], integrated into Zope 2 with
22
-
[plone.app.relationfield]. For most purposes, you need only to worry
23
-
about the `z3c.relationfield` API, which provides methods for finding
24
-
source and target objects for references and searching the relationship
25
-
catalog.
16
+
Under the hood, Dexterity's reference system uses [`five.intid`](https://pypi.org/project/five.intid/), a Zope 2 integration layer for [`zope.intid`](https://pypi.org/project/zope.intid/), to give each content item a unique integer ID.
17
+
These are the bases for relationships maintained with the [`zc.relationship`](https://pypi.org/project/zc.relationship/) package, which in turn is accessed via an API provided by [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/), integrated into Zope 2 with [`plone.app.relationfield`](https://pypi.org/project/plone.app.relationfield/).
18
+
For most purposes, you need only to worry about the `z3c.relationfield` API, which provides methods for finding source and target objects for references and searching the relationship catalog.
26
19
27
-
References are most commonly used in form fields with a selection or
28
-
content browser widget. Dexterity comes with a standard widget in
29
-
[plone.formwidget.contenttree] configured for the `RelationList` and
30
-
`RelationChoice` fields from `z3c.relationfield`.
20
+
References are most commonly used in form fields with a selection or content browser widget.
21
+
Dexterity comes with a standard widget in [`plone.formwidget.contenttree`](https://pypi.org/project/plone.formwidget.contenttree/) configured for the `RelationList` and `RelationChoice` fields from `z3c.relationfield`.
31
22
32
-
To illustrate the use of references, we will allow the user to create a
33
-
link between a `Session` and its `Presenter`. Since Dexterity already
34
-
ships with and installs `plone.formwidget.contenttree` and
35
-
`z3c.relationfield`, we do not need to add any further setup code, and
36
-
we can use the field directly in `session.py`:
37
-
38
-
```
39
-
...
23
+
To illustrate the use of references, we will allow the user to create a link between a `Session` and its `Presenter`.
24
+
Since Dexterity already ships with and installs `plone.formwidget.contenttree` and `z3c.relationfield`, we do not need to add any further setup code, and we can use the field directly in {file}`session.py`:
40
25
26
+
```python
41
27
from z3c.relationfield.schema import RelationChoice
42
28
from plone.formwidget.contenttree import ObjPathSourceBinder
43
-
...
44
29
45
30
from example.conference.presenter import IPresenter
46
31
47
32
classISession(form.Schema):
48
33
"""A conference session. Sessions are managed inside Programs.
Remeber that [plone.app.relationfield] needs to be installed to use any
61
-
RelationChoice or RelationList field.
62
-
:::
43
+
```{note}
44
+
Remeber that `plone.app.relationfield` needs to be installed to use any `RelationChoice` or `RelationList` field.
45
+
```
63
46
64
-
To allow multiple items to be selected, we could have used a
65
-
`RelationList` like:
47
+
To allow multiple items to be selected, we could have used a `RelationList` as shown:
66
48
67
-
```
49
+
```python
68
50
relatedItems = RelationList(
69
-
title=u"Related Items",
51
+
title="Related Items",
70
52
default=[],
71
-
value_type=RelationChoice(title=_(u"Related"),
53
+
value_type=RelationChoice(title=_("Related"),
72
54
source=ObjPathSourceBinder()),
73
55
required=False,
74
56
)
75
57
```
76
58
77
-
The `ObjPathSourceBinder` class is an `IContextSourceBinder` that returns
78
-
a vocabulary with content objects as values, object titles as term
79
-
titles and object paths as tokens.
59
+
The `ObjPathSourceBinder` class is an `IContextSourceBinder` that returns a vocabulary with content objects as values, object titles as term titles, and object paths as tokens.
80
60
81
-
You can pass keyword arguments to the constructor for
82
-
`ObjPathSourceBinder()` to restrict the selectable objects. Here, we
83
-
demand that the object must provide the `IPresenter` interface. The
84
-
syntax is the same as that used in a catalog search, except that only
85
-
simple values and lists are allowed (e.g. you can’t use a dict to
86
-
specify a range or values for a field index).
61
+
You can pass keyword arguments to the constructor for `ObjPathSourceBinder()` to restrict the selectable objects.
62
+
Here we demand that the object must provide the `IPresenter` interface.
63
+
The syntax is the same as that used in a catalog search, except that only simple values and lists are allowed (in other words, you can't use a dict to specify a range or values for a field index).
87
64
88
-
If you want to restrict the folders and other content shown in the
89
-
content browser, you can pass a dictionary with catalog search
90
-
parameters (and here, any valid catalog query will do) as the first
91
-
non-keyword argument (`navigation_tree_query`) to the
92
-
`ObjPathSourceBinder()` constructor.
65
+
If you want to restrict the folders and other content shown in the content browser, you can pass a dictionary with catalog search parameters (and here, any valid catalog query will do) as the first non-keyword argument (`navigation_tree_query`) to the `ObjPathSourceBinder()` constructor.
93
66
94
-
You can also create the fields in an XML schema, however you have to provide a
95
-
pre-baked source instance. If you are happy with not restricting folders shown,
96
-
you can use some that `plone.formwidget.contenttree` makes for you. For example:
67
+
You can also create the fields in an XML schema.
68
+
However you have to provide a pre-baked source instance.
69
+
If you are happy with not restricting folders shown, you can use those which `plone.formwidget.contenttree` makes for you.
@@ -105,49 +79,51 @@ you can use some that `plone.formwidget.contenttree` makes for you. For example:
105
79
</field>
106
80
```
107
81
108
-
:::{note}
109
-
The pre-baked source binders were added in plone.formwidget.contenttree
110
-
1.0.7, which ships with Plone 4.3.2+.
111
-
:::
82
+
```{versionadded} 4.3.2
83
+
The pre-baked source binders were added in `plone.formwidget.contenttree` 1.0.7, which ships with Plone 4.3.2+.
84
+
```
112
85
113
-
If you want to use a different widget, you can use the same source (or a
114
-
custom source that has content objects as values) with something like
115
-
the autocomplete widget. The following line added to the interface will
116
-
make the presenter selection similar to the `organizer` selection widget
117
-
we showed in the previous section:
86
+
If you want to use a different widget, you can use the same source (or a custom source that has content objects as values) with something such as the autocomplete widget.
87
+
The following line added to the interface will make the presenter selection similar to the `organizer` selection widget that we showed in the previous section.
To retrieve back-reference (all objects pointing to particular object using specified attribute) you can't simply use `from_object` or `from_path`, because source object is stored in the relation without acquisition wrappers.
150
-
You should use `from_id`and `helper`method, which search the object in the `IntId` catalog:
125
+
To retrieve back references (all objects pointing to a particular object using the specified attribute) you can't simply use `from_object` or `from_path`, because the source object is stored in the relation without acquisition wrappers.
126
+
You should use the `from_id` method, which searches the object in the `IntId` catalog:
0 commit comments