Skip to content

Commit 6cb6fec

Browse files
davisaglidavisagli
authored
Merge pull request plone#1498 from plone/content-types
Add content type intro and FTI reference
2 parents 6084168 + 8a1ab56 commit 6cb6fec

File tree

1 file changed

+223
-8
lines changed

1 file changed

+223
-8
lines changed

‎docs/backend/content-types/index.md‎

Lines changed: 223 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,230 @@ myst:
1212
# Content Types
1313

1414
```{seealso}
15-
See the chapter {ref}`training:dexterity1-label` from the Mastering Plone 6 Training.
15+
See the chapter {ref}`training:dexterity1-label` from the Mastering Plone 6 Training for a step-by-step tutorial to create a custom content type.
1616
```
1717

18-
```{todo}
19-
Contribute to this documentation!
20-
See issue [Backend > Content Types needs content](https://github.com/plone/documentation/issues/1303).
18+
## What is a content type?
19+
20+
Each item in a Plone site is an instance of a particular content type.
21+
We have different content types to reflect the different kinds of information about which we need to collect and display information.
22+
23+
Pages, news items, events, files (binary), and images are examples of content types.
24+
25+
Lots of things in Plone can be configured to work differently based on the content type. For example, each content type has:
26+
- a {ref}`schema <backend-fields-label>` specifying the fields which can be edited for the content type
27+
- a list of {ref}`behaviors <backend-behaviors-label>` which supply additional functionality that can be attached to the content types for which the behavior is enabled
28+
- a {ref}`workflow <backend-workflows-label>` controlling transitions between publishing states and associated permissions
29+
- a version policy controlling whether to store a revision history
30+
31+
It is common in developing a web site that you'll need customized versions of common content types, or perhaps even entirely new types.
32+
33+
## Factory Type Information
34+
35+
A content type is defined by creating a {term}`Factory Type Information` (FTI) object.
36+
37+
To create an FTI in a GenericSetup profile, add the content type to the list in `types.xml`. For example, this adds the standard Plone page (Document) content type:
38+
39+
```xml
40+
<object name="portal_types">
41+
<object name="Document" meta_type="Dexterity FTI" />
42+
</object>
43+
```
44+
45+
Then, add a file to the `types` directory with the same name.
46+
In this example, the file is `types/Document.xml` and contains this XML:
47+
48+
```xml
49+
<?xml version="1.0" encoding="utf-8"?>
50+
<object xmlns:i18n="http://xml.zope.org/namespaces/i18n"
51+
meta_type="Dexterity FTI"
52+
name="Document"
53+
i18n:domain="plone"
54+
>
55+
56+
<!-- Basic properties -->
57+
<property name="title"
58+
i18n:translate=""
59+
>Page</property>
60+
<property name="description"
61+
i18n:translate=""
62+
/>
63+
64+
<property name="allow_discussion">False</property>
65+
<property name="factory">Document</property>
66+
<property name="icon_expr">string:contenttype/document</property>
67+
68+
<!-- Hierarchy control -->
69+
<property name="allowed_content_types" />
70+
<property name="filter_content_types">True</property>
71+
<property name="global_allow">True</property>
72+
73+
<!-- Schema, class and security -->
74+
<property name="add_permission">plone.app.contenttypes.addDocument</property>
75+
<property name="klass">plone.app.contenttypes.content.Document</property>
76+
<property name="model_file">plone.app.contenttypes.schema:document.xml</property>
77+
<property name="model_source" />
78+
<property name="schema" />
79+
80+
<!-- Enabled behaviors -->
81+
<property name="behaviors"
82+
purge="false"
83+
>
84+
<element value="plone.namefromtitle" />
85+
<element value="plone.allowdiscussion" />
86+
<element value="plone.excludefromnavigation" />
87+
<element value="plone.shortname" />
88+
<element value="plone.dublincore" />
89+
<element value="plone.richtext" />
90+
<element value="plone.relateditems" />
91+
<element value="plone.versioning" />
92+
<element value="plone.tableofcontents" />
93+
<element value="plone.locking" />
94+
</property>
95+
96+
<!-- View information -->
97+
<property name="add_view_expr">string:${folder_url}/++add++Document</property>
98+
<property name="default_view">document_view</property>
99+
<property name="default_view_fallback">False</property>
100+
<property name="immediate_view">view</property>
101+
<property name="view_methods">
102+
<element value="document_view" />
103+
</property>
104+
105+
<!-- Method aliases -->
106+
<alias from="(Default)"
107+
to="(dynamic view)"
108+
/>
109+
<alias from="edit"
110+
to="@@edit"
111+
/>
112+
<alias from="sharing"
113+
to="@@sharing"
114+
/>
115+
<alias from="view"
116+
to="(selected layout)"
117+
/>
118+
119+
<!-- Actions -->
120+
<action action_id="view"
121+
category="object"
122+
condition_expr=""
123+
icon_expr="string:toolbar-action/view"
124+
title="View"
125+
url_expr="string:${object_url}"
126+
visible="True"
127+
i18n:attributes="title"
128+
>
129+
<permission value="View" />
130+
</action>
131+
<action action_id="edit"
132+
category="object"
133+
condition_expr="not:object/@@plone_lock_info/is_locked_for_current_user|python:True"
134+
icon_expr="string:toolbar-action/edit"
135+
title="Edit"
136+
url_expr="string:${object_url}/edit"
137+
visible="True"
138+
i18n:attributes="title"
139+
>
140+
<permission value="Modify portal content" />
141+
</action>
142+
143+
</object>
21144
```
22145

23-
```{todo}
24-
Describe how to add a content type (Python/XML) including FTI settings.
25-
Fields, Widgets, Vocabularies are also described in detail in their own chapters, and will be referenced from examples here.
26-
```
146+
The `name` attribute on the root element in the XML must match the name in the filename and the name listed in `types.xml`.
147+
148+
Set the `i18n:domain` to the i18n domain which includes translations for this content type. This is usually the same as the name of the Python package which contains the content type.
149+
150+
151+
(global-fti-properties-label)=
152+
153+
### Global FTI properties
154+
155+
The XML sets a number of FTI properties that are used globally, in both Classic UI and Volto:
156+
157+
`action` elements
158+
: Defines additional {doc}`actions </backend/portal-actions>` which are available for this content type.
159+
160+
`add_permission`
161+
: Id of the permission controlling whether the current user has permission to add this content type.
162+
163+
`allow_discussion`
164+
: Boolean.
165+
Controls whether Plone's commenting system is enabled by default for this content type.
166+
167+
`allowed_content_types`
168+
: List of content types which can be added inside this one.
169+
Only used if `filter_content_types` is True.
170+
171+
`behaviors`
172+
: List of {doc}`behaviors </backend/behaviors>` enabled for this content type.
173+
174+
`description`
175+
: Short description displayed in the UI.
176+
177+
`factory`
178+
: Name of the factory adapter used to create new instances of the content type.
179+
Usually the same as the content type name.
180+
181+
`filter_content_types`
182+
: Boolean.
183+
Controls which content types can be added inside this one.
184+
If `True`, allow only the types listed in `allowed_content_types`.
185+
If `False`, allow any content type that the user has permission to add.
186+
187+
`global_allow`
188+
: Boolean.
189+
Set to `True` to allow adding the content type anywhere in the site where the user has permission.
190+
Set to `False` to only allow adding it inside other content types that include this one in `allowed_content_types`.
191+
192+
`klass`
193+
: Dotted path to the Python class for this content type.
194+
195+
`model_file`
196+
: Location of an XML file to load as the content type's schema.
197+
This is an alternative to `schema` and `model_source`.
198+
199+
`model_source`
200+
: Inline XML schema for the content type.
201+
This is an alternative to `schema` and `model_file`.
202+
203+
`schema`
204+
: Dotted path to the Python schema for this content type.
205+
One of `model_file`, `model_source`, and `schema` must be set.
206+
`schema` is the most commonly used.
207+
208+
`title`
209+
: The name of the content type displayed in the UI.
210+
211+
212+
213+
(classic-ui-only-fti-properties-label)=
214+
215+
### Classic UI only FTI properties
216+
217+
The following FTI properties are used only in Classic UI:
218+
219+
`add_view_expr`
220+
: {term}`TALES` expression returning the URL for the form to add a new item of this content type.
221+
222+
`alias` elements
223+
: Controls a mapping from URL to views.
224+
It's not common to change this.
225+
226+
`default_view`
227+
: Name of the default view used to display this content type.
228+
229+
`default_view_fallback`
230+
: Boolean.
231+
If `True`, the `default_view` will be used if the assigned view is not found.
232+
233+
`icon_expr`
234+
: {term}`TALES` expression returning the name of one of the registered icons.
235+
See {doc}`/classic-ui/icons`.
236+
237+
`immediate_view`
238+
: Name of the view alias to display after a new item is added.
239+
240+
`view_methods`
241+
: List of views which can be selected to display this content type.

0 commit comments

Comments
 (0)