Skip to content

Commit d203370

Browse files
MrTangoMrTango
committed
add schemas section, add field reference, fix schema link in content-types
1 parent 18912a5 commit d203370

File tree

4 files changed

+719
-15
lines changed

4 files changed

+719
-15
lines changed

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

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,11 @@ We have different content types to reflect the different kinds of information ab
2222

2323
Pages, news items, events, files (binary), and images are examples of content types.
2424

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
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-schemas-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
3230

3331
It is common in developing a web site that you'll need customized versions of common content types, or perhaps even entirely new types.
3432

‎docs/backend/fields.md‎

Lines changed: 112 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,118 @@ myst:
1111

1212
# Fields
1313

14-
```{seealso}
15-
See the chapter {ref}`training:dexterity-reference-label` from the Mastering Plone 6 Training.
16-
```
17-
18-
```{todo}
19-
Contribute to this documentation!
20-
See issue [Backend > Fields needs content](https://github.com/plone/documentation/issues/1305).
21-
```
14+
This chapter describes the standard schema fields in Plone content types.
15+
16+
The following tables show the most common field types for use in Dexterity schemata.
17+
See the documentation on {ref}`creating schemata <backend-schemas-label>` for information about how to use these.
18+
19+
20+
## Field properties
21+
22+
Fields are initialized with properties passed in their constructors.
23+
To avoid having to repeat the available properties for each field, we'll list them once here, grouped into the interfaces that describe them.
24+
You'll see those interfaces again in the tables below that describe the various field types.
25+
Refer to the table below to see what properties a particular interface implies.
26+
27+
| Interface | Property | Type | Description |
28+
| - | - | - | - |
29+
| IField | title | int | The title of the field. Used in the widget. |
30+
| | `description` | unicode | A description for the field. Used in the widget. |
31+
| | `required` | bool | Whether or not the field is required. Used for form validation. The default is `True`. |
32+
| | `readonly` | bool | Whether or not the field is read only. Default is `False`. |
33+
| | `default` | | The default value for the field. Used in forms and sometimes as a fallback value. Must be a valid value for the field if set. The default is `None`. |
34+
| | `missing_value` | | A value that represents "this field is not set". Used by form validation. Defaults to `None`. For lists and tuples, it is sometimes useful to set this to an empty list or tuple. |
35+
| `IMinMaxLen` | `min_length` | int | The minimum required length or minimum number of elements. Used for `string`, sequence, mapping, or `set` fields. Default is `0`. |
36+
| | `max_length `| int | The maximum allowed length or maximum number of elements. Used for `string`, sequence, mapping, or `set` fields. Default is `None` (no check). |
37+
| `IMinMax` | `min` | | The minimum allowed value. Must be a valid value for the field, for example, an int field should be an integer. Default is `None` (no check). |
38+
| | `max` | | The maximum allowed value. Must be a valid value for the field, for example an int field should be an integer. Default is `None` (no check). |
39+
| `ICollection` | `value_type` | | Another `Field` instance that describes the allowable values in a list, tuple, or other collection. Must be set for any collection field. One common usage is to set this to a `Choice` to model a multi-selection field with a vocabulary. |
40+
| | `unique` | bool | Whether or not values in the collection must be unique. Usually not set directly. Use a `Set` or `Frozenset` to guarantee uniqueness in an efficient way. |
41+
| `IDict` | `key_type` | | Another `Field` instance that describes the allowable keys in a dictionary. Similar to the `value_type` of a collection. Must be set. |
42+
| | `value_type` | | Another `Field` instance that describes the allowable values in a dictionary. Similar to the `value_type` of a collection. Must be set. |
43+
| `IObject` | `schema` | `Interface` | An interface that must be provided by any object stored in this field. |
44+
| `IRichText` | `default_mime_type` | str | Default MIME type for the input text of a rich text field. Defaults to `text/html`. |
45+
| | `output_mime_type` | str | Default output MIME type for the transformed value of a rich text field. Defaults to `text/x-html-safe`. There must be a transformation chain in the `portal_transforms` tool that can transform from the input value to the `output` value for the output property of the `RichValue` object to contain a value. |
46+
| | `allowed_mime_types` | tuple | A list of allowed input MIME types. The default is `None`, in which case the site-wide settings from the {guilabel}`Markup` control panel will be used. |
47+
48+
49+
## Field types
50+
51+
The following tables describe the most commonly used field types, grouped by the module from which they can be imported.
52+
53+
54+
### Fields in `zope.schema`
55+
56+
| Name | Type | Description | Properties |
57+
| - | - | - | - |
58+
| Choice | N/A | Used to model selection from a vocabulary, which must be supplied. Often used as the `value_type` of a selection field. The value type is the value of the terms in the vocabulary. | See {doc}`../advanced/vocabularies`. |
59+
| Bytes | str | Used for binary data. | IField, IMinMaxLen |
60+
| ASCII | str | ASCII text (multi-line). | IField, IMinMaxLen |
61+
| BytesLine | str | A single line of binary data, in other words a `Bytes` with new lines disallowed. | IField, IMinMaxLen |
62+
| ASCIILine | str | A single line of ASCII text. | IField, IMinMaxLen |
63+
| Text | unicode | Unicode text (multi-line). Often used with a WYSIWYG widget, although the default is a text area. | IField, IMinMaxLen |
64+
| TextLine | unicode | A single line of Unicode text. | IField, IMinMaxLen |
65+
| Bool | bool | `True` or `False`. | IField |
66+
| Int | int, long | An integer number. Both ints and longs are allowed. | IField, IMinMax |
67+
| Float | float | A floating point number. | IField, IMinMax |
68+
| Tuple | tuple | A tuple (non-mutable). | IField, ICollection, IMinMaxLen |
69+
| List | list | A list. | IField, ICollection, IMinMaxLen |
70+
| Set | set | A set. | IField, ICollection, IMinMaxLen |
71+
| Frozenset | frozenset | A frozenset (non-mutable). | IField, ICollection, IMinMaxLen |
72+
| Password | unicode | Stores a simple string, but implies a password widget. | IField, IMinMaxLen |
73+
| Dict | dict | Stores a dictionary. Both `key_type` and `value_type` must be set to fields. | IField, IMinMaxLen, IDict |
74+
| Datetime | datetime | Stores a Python `datetime` (not a Zope 2 `DateTime`). | IField, IMinMax |
75+
| Date | date | Stores a python `date`. | IField, IMinMax |
76+
| Timedelta | timedelta | Stores a python `timedelta`. | IField, IMinMax |
77+
| SourceText | unicode | A textfield intended to store source text, such as HTML or Python code. | IField, IMinMaxLen |
78+
| Object | N/A | Stores a Python object that conforms to the interface given as the `schema`. There is no standard widget for this. | IField, IObject |
79+
| URI | str | A URI (URL) string. | IField, MinMaxLen |
80+
| Id | str | A unique identifier, either a URI or a dotted name. | IField, IMinMaxLen |
81+
| DottedName | str | A dotted name string. | IField, IMinMaxLen |
82+
| InterfaceField | Interface | A Zope interface. | IField |
83+
| Decimal | Decimal | Stores a Python `Decimal`. Requires version 3.4 or later of [`zope.schema`](https://pypi.org/project/zope.schema/). Not available by default in Zope 2.10. | IField, IMinMax |
84+
85+
86+
### Fields in `plone.namedfile.field`
87+
88+
See [`plone.namedfile`](https://pypi.org/project/plone.namedfile/) and [plone.formwidget.namedfile](https://pypi.org/project/plone.formwidget.namedfile/) for more details.
89+
90+
| Name | Type | Description | Properties |
91+
| - | - | - | - |
92+
| NamedFile | NamedFile | A binary uploaded file. Normally used with the widget from `plone.formwidget.namedfile`. | IField |
93+
| NamedImage | NamedImage | A binary uploaded image. Normally used with the widget from `plone.formwidget.namedfile`. | IField |
94+
| NamedBlobFile | NamedBlobFile | A binary uploaded file stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedFile`. | IField |
95+
| NamedBlobImage | NamedBlobImage | A binary uploaded image stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedImage`. | IField |
96+
97+
98+
### Fields in `z3c.relationfield.schema`
99+
100+
See [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/) for more details.
101+
102+
| Name | Type | Description | Properties |
103+
| -------------- | ------------- | ------------------------------------------------------------ | ------------ |
104+
| Relation | RelationValue | Stores a single `RelationValue`. | IField |
105+
| RelationList | list | A `List` field that defaults to `Relation` as the value type | See `List` |
106+
| RelationChoice | RelationValue | A `Choice` field intended to store `RelationValue`'s | See `Choice` |
107+
108+
109+
### Fields in `plone.app.textfield`
110+
111+
See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for more details.
112+
113+
| Name | Type | Description | Properties |
114+
| -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
115+
| RichText | RichTextValue | Stores a `RichTextValue`, which encapsulates a raw text value, the source MIME type, and a cached copy of the raw text transformed to the default output MIME type. | IField, IRichText |
116+
117+
118+
### Fields in `plone.schema`
119+
120+
See [`plone.schema`](https://pypi.org/project/plone.schema/) for more details.
121+
122+
| Name | Type | Description | Properties |
123+
| ----- | ---- | ----------------------------------- | ------------------ |
124+
| Email | str | A field containing an email address | IField, IMinMaxLen |
125+
22126

23127
(backend-fields-schema-label)=
24128

‎docs/backend/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ widgets
2929
global-utils
3030
portal-actions
3131
users-groups
32+
schemas
3233
security
3334
subscribers
3435
traversal-acquisition

0 commit comments

Comments
 (0)