|
9 | 9 |
|
10 | 10 | (backend-content-types-label)= |
11 | 11 |
|
12 | | -# Content Types |
| 12 | +# Content types |
| 13 | + |
| 14 | +This part of the documentation describes how to develop content types in Plone. |
| 15 | +Content types are implemented through the {term}`Dexterity` framework. |
| 16 | + |
| 17 | + |
| 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. |
| 26 | +For example, each content type has: |
| 27 | + |
| 28 | +- a {ref}`schema <backend-fields-label>` specifying the fields which can be edited for the content type |
| 29 | +- 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 |
| 30 | +- a {ref}`workflow <backend-workflows-label>` controling transitions between publishing states and associated permissions |
| 31 | +- a version policy controling whether to store a revision history |
| 32 | + |
| 33 | +It is common in developing a web site that you'll need customized versions of common content types, or perhaps even entirely new types. |
| 34 | + |
| 35 | + |
| 36 | +## Topics |
| 37 | + |
| 38 | +This part of the documentation will cover the following topics. |
| 39 | + |
| 40 | +- Some basic design techniques for solving problems with content types in Plone |
| 41 | +- Setting up a Dexterity development environment |
| 42 | +- Creating a package to house your types |
| 43 | +- Building a custom type based on a schema |
| 44 | +- Creating custom views and forms for your type |
| 45 | +- Advanced customization, including workflow and security |
| 46 | +- Testing your types |
| 47 | +- A quick reference to common fields, widgets, and APIs |
13 | 48 |
|
14 | 49 | ```{seealso} |
15 | | -See the chapter {ref}`training:dexterity1-label` from the Mastering Plone 6 Training. |
| 50 | +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. |
16 | 51 | ``` |
17 | 52 |
|
18 | | -```{todo} |
19 | | -Contribute to this documentation! |
20 | | -See issue [Backend > Content Types needs content](https://github.com/plone/documentation/issues/1303). |
| 53 | +```{toctree} |
| 54 | +:maxdepth: 2 |
21 | 55 | ``` |
| 56 | +% Uncomment each of the following and move into the toctree above when migrated from Plone 5 documentation |
| 57 | +% designing |
| 58 | +% prerequisite |
| 59 | +% schema-driven-types |
| 60 | +% model-driven-types |
| 61 | +% custom-views |
| 62 | +% advanced/index |
| 63 | +% testing/index |
| 64 | +% reference/index |
| 65 | + |
| 66 | + |
| 67 | +## Factory Type Information |
22 | 68 |
|
23 | 69 | ```{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 | | -``` |
| 70 | +Find a new home for this section. |
| 71 | +This page is an introduction, whereas FTI is a topic unto itself. |
| 72 | +``` |
| 73 | + |
| 74 | +A content type is defined by creating a {term}`Factory Type Information` (FTI) object. |
| 75 | + |
| 76 | +To create an FTI in a `GenericSetup` profile, add the content type to the list in `types.xml`. |
| 77 | +For example, this adds the standard Plone page (`Document`) content type: |
| 78 | + |
| 79 | +```xml |
| 80 | +<object name="portal_types"> |
| 81 | + <object name="Document" meta_type="Dexterity FTI" /> |
| 82 | +</object> |
| 83 | +``` |
| 84 | + |
| 85 | +Then, add a file to the `types` directory with the same name. |
| 86 | +In this example, the file is `types/Document.xml` and contains this XML: |
| 87 | + |
| 88 | +```xml |
| 89 | +<?xml version="1.0" encoding="utf-8"?> |
| 90 | +<object xmlns:i18n="http://xml.zope.org/namespaces/i18n" |
| 91 | + meta_type="Dexterity FTI" |
| 92 | + name="Document" |
| 93 | + i18n:domain="plone" |
| 94 | +> |
| 95 | + |
| 96 | + <!-- Basic properties --> |
| 97 | + <property name="title" |
| 98 | + i18n:translate="" |
| 99 | + >Page</property> |
| 100 | + <property name="description" |
| 101 | + i18n:translate="" |
| 102 | + /> |
| 103 | + |
| 104 | + <property name="allow_discussion">False</property> |
| 105 | + <property name="factory">Document</property> |
| 106 | + <property name="icon_expr">string:contenttype/document</property> |
| 107 | + |
| 108 | + <!-- Hierarchy control --> |
| 109 | + <property name="allowed_content_types" /> |
| 110 | + <property name="filter_content_types">True</property> |
| 111 | + <property name="global_allow">True</property> |
| 112 | + |
| 113 | + <!-- Schema, class and security --> |
| 114 | + <property name="add_permission">plone.app.contenttypes.addDocument</property> |
| 115 | + <property name="klass">plone.app.contenttypes.content.Document</property> |
| 116 | + <property name="model_file">plone.app.contenttypes.schema:document.xml</property> |
| 117 | + <property name="model_source" /> |
| 118 | + <property name="schema" /> |
| 119 | + |
| 120 | + <!-- Enabled behaviors --> |
| 121 | + <property name="behaviors" |
| 122 | + purge="false" |
| 123 | + > |
| 124 | + <element value="plone.namefromtitle" /> |
| 125 | + <element value="plone.allowdiscussion" /> |
| 126 | + <element value="plone.excludefromnavigation" /> |
| 127 | + <element value="plone.shortname" /> |
| 128 | + <element value="plone.dublincore" /> |
| 129 | + <element value="plone.richtext" /> |
| 130 | + <element value="plone.relateditems" /> |
| 131 | + <element value="plone.versioning" /> |
| 132 | + <element value="plone.tableofcontents" /> |
| 133 | + <element value="plone.locking" /> |
| 134 | + </property> |
| 135 | + |
| 136 | + <!-- View information --> |
| 137 | + <property name="add_view_expr">string:${folder_url}/++add++Document</property> |
| 138 | + <property name="default_view">document_view</property> |
| 139 | + <property name="default_view_fallback">False</property> |
| 140 | + <property name="immediate_view">view</property> |
| 141 | + <property name="view_methods"> |
| 142 | + <element value="document_view" /> |
| 143 | + </property> |
| 144 | + |
| 145 | + <!-- Method aliases --> |
| 146 | + <alias from="(Default)" |
| 147 | + to="(dynamic view)" |
| 148 | + /> |
| 149 | + <alias from="edit" |
| 150 | + to="@@edit" |
| 151 | + /> |
| 152 | + <alias from="sharing" |
| 153 | + to="@@sharing" |
| 154 | + /> |
| 155 | + <alias from="view" |
| 156 | + to="(selected layout)" |
| 157 | + /> |
| 158 | + |
| 159 | + <!-- Actions --> |
| 160 | + <action action_id="view" |
| 161 | + category="object" |
| 162 | + condition_expr="" |
| 163 | + icon_expr="string:toolbar-action/view" |
| 164 | + title="View" |
| 165 | + url_expr="string:${object_url}" |
| 166 | + visible="True" |
| 167 | + i18n:attributes="title" |
| 168 | + > |
| 169 | + <permission value="View" /> |
| 170 | + </action> |
| 171 | + <action action_id="edit" |
| 172 | + category="object" |
| 173 | + condition_expr="not:object/@@plone_lock_info/is_locked_for_current_user|python:True" |
| 174 | + icon_expr="string:toolbar-action/edit" |
| 175 | + title="Edit" |
| 176 | + url_expr="string:${object_url}/edit" |
| 177 | + visible="True" |
| 178 | + i18n:attributes="title" |
| 179 | + > |
| 180 | + <permission value="Modify portal content" /> |
| 181 | + </action> |
| 182 | + |
| 183 | +</object> |
| 184 | +``` |
| 185 | + |
| 186 | +The `name` attribute on the root element in the XML must match the name in the filename and the name listed in `types.xml`. |
| 187 | + |
| 188 | +Set the `i18n:domain` to the i18n domain which includes translations for this content type. |
| 189 | +This is usually the same as the name of the Python package which contains the content type. |
| 190 | + |
| 191 | + |
| 192 | +(global-fti-properties-label)= |
| 193 | + |
| 194 | +### Global FTI properties |
| 195 | + |
| 196 | +The XML sets a number of FTI properties that are used globally, in both Classic UI and Volto: |
| 197 | + |
| 198 | +`action` elements |
| 199 | +: Defines additional {doc}`actions </backend/portal-actions>` which are available for this content type. |
| 200 | + |
| 201 | +`add_permission` |
| 202 | +: Id of the permission controlling whether the current user has permission to add this content type. |
| 203 | + |
| 204 | +`allow_discussion` |
| 205 | +: Boolean. |
| 206 | + Controls whether Plone's commenting system is enabled by default for this content type. |
| 207 | + |
| 208 | +`allowed_content_types` |
| 209 | +: List of content types which can be added inside this one. |
| 210 | + Only used if `filter_content_types` is True. |
| 211 | + |
| 212 | +`behaviors` |
| 213 | +: List of {doc}`behaviors </backend/behaviors>` enabled for this content type. |
| 214 | + |
| 215 | +`description` |
| 216 | +: Short description displayed in the UI. |
| 217 | + |
| 218 | +`factory` |
| 219 | +: Name of the factory adapter used to create new instances of the content type. |
| 220 | + Usually the same as the content type name. |
| 221 | + |
| 222 | +`filter_content_types` |
| 223 | +: Boolean. |
| 224 | + Controls which content types can be added inside this one. |
| 225 | + If `True`, allow only the types listed in `allowed_content_types`. |
| 226 | + If `False`, allow any content type that the user has permission to add. |
| 227 | + |
| 228 | +`global_allow` |
| 229 | +: Boolean. |
| 230 | + Set to `True` to allow adding the content type anywhere in the site where the user has permission. |
| 231 | + Set to `False` to only allow adding it inside other content types that include this one in `allowed_content_types`. |
| 232 | + |
| 233 | +`klass` |
| 234 | +: Dotted path to the Python class for this content type. |
| 235 | + |
| 236 | +`model_file` |
| 237 | +: Location of an XML file to load as the content type's schema. |
| 238 | + This is an alternative to `schema` and `model_source`. |
| 239 | + |
| 240 | +`model_source` |
| 241 | +: Inline XML schema for the content type. |
| 242 | + This is an alternative to `schema` and `model_file`. |
| 243 | + |
| 244 | +`schema` |
| 245 | +: Dotted path to the Python schema for this content type. |
| 246 | + One of `model_file`, `model_source`, and `schema` must be set. |
| 247 | + `schema` is the most commonly used. |
| 248 | + |
| 249 | +`title` |
| 250 | +: The name of the content type displayed in the UI. |
| 251 | + |
| 252 | + |
| 253 | +(classic-ui-only-fti-properties-label)= |
| 254 | + |
| 255 | +### Classic UI only FTI properties |
| 256 | + |
| 257 | +The following FTI properties are used only in Classic UI: |
| 258 | + |
| 259 | +`add_view_expr` |
| 260 | +: {term}`TALES` expression returning the URL for the form to add a new item of this content type. |
| 261 | + |
| 262 | +`alias` elements |
| 263 | +: Controls a mapping from URL to views. |
| 264 | + It's not common to change this. |
| 265 | + |
| 266 | +`default_view` |
| 267 | +: Name of the default view used to display this content type. |
| 268 | + |
| 269 | +`default_view_fallback` |
| 270 | +: Boolean. |
| 271 | + If `True`, the `default_view` will be used if the assigned view is not found. |
| 272 | + |
| 273 | +`icon_expr` |
| 274 | +: {term}`TALES` expression returning the name of one of the registered icons. |
| 275 | + See {doc}`/classic-ui/icons`. |
| 276 | + |
| 277 | +`immediate_view` |
| 278 | +: Name of the view alias to display after a new item is added. |
| 279 | + |
| 280 | +`view_methods` |
| 281 | +: List of views which can be selected to display this content type. |
0 commit comments