Skip to content

Commit d04ca83

Browse files
stevepiercystevepiercy
committed
Minor style guide, grammar, and syntax improvements
1 parent b0115ad commit d04ca83

File tree

1 file changed

+56
-52
lines changed

1 file changed

+56
-52
lines changed

‎docs/backend/fields.md‎

Lines changed: 56 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,24 @@ myst:
1313

1414
This chapter describes the standard schema fields for Plone forms and content types.
1515

16-
The following tables show the most common field types for use in {ref}`classic-ui-forms-label` and Dexterity {ref}`backend-content-types-label`.
17-
See {ref}`schemas <backend-schemas-label>` for information about how fields compose a schema for a form or content type data model.
16+
The following tables show the most common field types for use in {doc}`/classic-ui/forms` and Dexterity {doc}`/backend/content-types/index`.
17+
See {doc}`schemas </backend/schemas>` for information about how fields compose a schema for a form or content type data model.
1818

19-
```{note}
20-
In VS Code editor, you can install the [Plone Snippets](https://marketplace.visualstudio.com/items?itemName=Derico.plone-vs-snippets) extension. This will give you snippets for most fields, widgets and autoform directives in Python and XML based schemas.
19+
```{tip}
20+
In VS Code editor, you can install the [Plone Snippets](https://marketplace.visualstudio.com/items?itemName=Derico.plone-vs-snippets) extension.
21+
This will give you snippets for most fields, widgets, and autoform directives in Python and XML based schemas.
2122
```
2223

2324
## Field properties
2425

25-
Fields are initialized with properties passed in their constructors.
26-
To avoid having to repeat the available properties for each field, we'll list them once here, grouped into the interfaces that describe them.
26+
You can initialize fields by passing properties into their constructors.
27+
To avoid repeating the available properties for each field, we'll list them once here, grouped into the interfaces that describe them.
2728
You'll see those interfaces again in the tables below that describe the various field types.
2829
Refer to the table below to see what properties a particular interface implies.
2930

3031
| Interface | Property | Type | Description |
3132
| - | - | - | - |
32-
| IField | title | int | The title of the field. Used in the widget. |
33+
| `IField` | `title` | int | The title of the field. Used in the widget. |
3334
| | `description` | unicode | A description for the field. Used in the widget. |
3435
| | `required` | bool | Whether or not the field is required. Used for form validation. The default is `True`. |
3536
| | `readonly` | bool | Whether or not the field is read only. Default is `False`. |
@@ -38,54 +39,57 @@ Refer to the table below to see what properties a particular interface implies.
3839
| | `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. |
3940
| `IMinMaxLen` | `min_length` | int | The minimum required length or minimum number of elements. Used for `string`, sequence, mapping, or `set` fields. Default is `0`. |
4041
| | `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). |
41-
| `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). |
42-
| | `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). |
43-
| `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 {ref}`vocabulary <backend-vocabularies-label>`. |
42+
| `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). |
43+
| | `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). |
44+
| `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 {doc}`vocabulary </backend/vocabularies>`. |
4445
| | `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. |
45-
| `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. |
46-
| | `value_type` | | Another `Field` instance that describes the allowable values in a dictionary. Similar to the `value_type` of a collection. Must be set. |
46+
| `IDict` | `key_type` | | Another `Field` instance that describes the allowable keys in a dictionary. Similar to the `value_type` of a collection. Must be a `Set`. |
47+
| | `value_type` | | Another `Field` instance that describes the allowable values in a dictionary. Similar to the `value_type` of a collection. Must be a `Set`. |
4748
| `IObject` | `schema` | `Interface` | An interface that must be provided by any object stored in this field. |
4849
| `IRichText` | `default_mime_type` | str | Default MIME type for the input text of a rich text field. Defaults to `text/html`. |
49-
| | `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. |
50+
| | `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. |
5051
| | `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. |
5152

5253
See [IField interface](https://zopeschema.readthedocs.io/en/latest/api.html#zope.schema.interfaces.IField) and [field implementation](https://zopeschema.readthedocs.io/en/latest/api.html#field-implementations) in `zope.schema` documentation for details.
5354

55+
5456
## Field types
5557

5658
The following tables describe the most commonly used field types, grouped by the module from which they can be imported.
5759

5860

61+
(fields-in-zope-schema-label)=
62+
5963
### Fields in `zope.schema`
6064

6165
| Name | Type | Description | Properties |
6266
| - | - | - | - |
63-
| 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 {ref}`backend-vocabularies-label`. |
64-
| Bytes | str | Used for binary data. | IField, IMinMaxLen |
65-
| ASCII | str | ASCII text (multi-line). | IField, IMinMaxLen |
66-
| BytesLine | str | A single line of binary data, in other words a `Bytes` with new lines disallowed. | IField, IMinMaxLen |
67-
| ASCIILine | str | A single line of ASCII text. | IField, IMinMaxLen |
68-
| Text | unicode | Unicode text (multi-line). Often used with a WYSIWYG widget, although the default is a text area. | IField, IMinMaxLen |
69-
| TextLine | unicode | A single line of Unicode text. | IField, IMinMaxLen |
70-
| Bool | bool | `True` or `False`. | IField |
71-
| Int | int, long | An integer number. Both ints and longs are allowed. | IField, IMinMax |
72-
| Float | float | A floating point number. | IField, IMinMax |
73-
| Tuple | tuple | A tuple (non-mutable). | IField, ICollection, IMinMaxLen |
74-
| List | list | A list. | IField, ICollection, IMinMaxLen |
75-
| Set | set | A set. | IField, ICollection, IMinMaxLen |
76-
| Frozenset | frozenset | A frozenset (non-mutable). | IField, ICollection, IMinMaxLen |
77-
| Password | unicode | Stores a simple string, but implies a password widget. | IField, IMinMaxLen |
78-
| Dict | dict | Stores a dictionary. Both `key_type` and `value_type` must be set to fields. | IField, IMinMaxLen, IDict |
79-
| Datetime | datetime | Stores a Python `datetime` (not a Zope 2 `DateTime`). | IField, IMinMax |
80-
| Date | date | Stores a python `date`. | IField, IMinMax |
81-
| Timedelta | timedelta | Stores a python `timedelta`. | IField, IMinMax |
82-
| SourceText | unicode | A textfield intended to store source text, such as HTML or Python code. | IField, IMinMaxLen |
83-
| 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 |
84-
| URI | str | A URI (URL) string. | IField, MinMaxLen |
85-
| Id | str | A unique identifier, either a URI or a dotted name. | IField, IMinMaxLen |
86-
| DottedName | str | A dotted name string. | IField, IMinMaxLen |
87-
| InterfaceField | Interface | A Zope interface. | IField |
88-
| 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 |
67+
| `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}`/backend/vocabularies`. |
68+
| `Bytes` | str | Used for binary data. | `IField`, `IMinMaxLen` |
69+
| `ASCII` | str | ASCII text (multi-line). | `IField`, `IMinMaxLen` |
70+
| `BytesLine` | str | A single line of binary data, in other words a `Bytes` with new lines disallowed. | `IField`, `IMinMaxLen` |
71+
| `ASCIILine` | str | A single line of ASCII text. | `IField`, `IMinMaxLen` |
72+
| `Text` | unicode | Unicode text (multi-line). Often used with a WYSIWYG widget, although the default is a text area. | `IField`, `IMinMaxLen` |
73+
| `TextLine` | unicode | A single line of Unicode text. | `IField`, `IMinMaxLen` |
74+
| `Bool` | bool | `True` or `False`. | `IField` |
75+
| `Int` | int, long | An integer number. Both ints and longs are allowed. | `IField`, `IMinMax` |
76+
| `Float` | float | A floating point number. | `IField`, `IMinMax` |
77+
| `Tuple` | tuple | A tuple (non-mutable). | `IField`, `ICollection`, `IMinMaxLen` |
78+
| `List` | list | A list. | `IField`, `ICollection`, `IMinMaxLen` |
79+
| `Set` | set | A set. | `IField`, `ICollection`, `IMinMaxLen` |
80+
| `Frozenset` | frozenset | A frozenset (non-mutable). | `IField`, `ICollection`, `IMinMaxLen` |
81+
| `Password` | unicode | Stores a simple string, but implies a password widget. | `IField`, `IMinMaxLen` |
82+
| `Dict` | dict | Stores a dictionary. Both `key_type` and `value_type` must be set to fields. | `IField`, `IMinMaxLen`, `IDict` |
83+
| `Datetime` | datetime | Stores a Python `datetime` (not a Zope 2 `DateTime`). | `IField`, `IMinMax` |
84+
| `Date` | date | Stores a Python `date`. | `IField`, `IMinMax` |
85+
| `Timedelta` | timedelta | Stores a Python `timedelta`. | `IField`, `IMinMax` |
86+
| `SourceText` | unicode | A textfield intended to store source text, such as HTML or Python code. | `IField`, `IMinMaxLen` |
87+
| `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` |
88+
| `URI` | str | A URI (URL) string. | `IField`, `MinMaxLen` |
89+
| `Id` | str | A unique identifier, either a URI or a dotted name. | `IField`, `IMinMaxLen` |
90+
| `DottedName` | str | A dotted name string. | `IField`, `IMinMaxLen` |
91+
| `InterfaceField` | Interface | A Zope interface. | `IField` |
92+
| `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` |
8993

9094

9195
### Fields in `plone.namedfile.field`
@@ -94,40 +98,40 @@ See [`plone.namedfile`](https://pypi.org/project/plone.namedfile/) and [plone.fo
9498

9599
| Name | Type | Description | Properties |
96100
| - | - | - | - |
97-
| NamedFile | NamedFile | A binary uploaded file. Normally used with the widget from `plone.formwidget.namedfile`. | IField |
98-
| NamedImage | NamedImage | A binary uploaded image. Normally used with the widget from `plone.formwidget.namedfile`. | IField |
99-
| NamedBlobFile | NamedBlobFile | A binary uploaded file stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedFile`. | IField |
100-
| NamedBlobImage | NamedBlobImage | A binary uploaded image stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedImage`. | IField |
101+
| `NamedFile` | `NamedFile` | A binary uploaded file. Normally used with the widget from `plone.formwidget.namedfile`. | `IField` |
102+
| `NamedImage` | `NamedImage` | A binary uploaded image. Normally used with the widget from `plone.formwidget.namedfile`. | `IField` |
103+
| `NamedBlobFile` | `NamedBlobFile` | A binary uploaded file stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedFile`. | `IField` |
104+
| `NamedBlobImage` | `NamedBlobImage` | A binary uploaded image stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedImage`. | `IField` |
101105

102106

103107
### Fields in `z3c.relationfield.schema`
104108

105109
See [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/) for more details.
106110

107111
| Name | Type | Description | Properties |
108-
| -------------- | ------------- | ------------------------------------------------------------ | ------------ |
109-
| Relation | RelationValue | Stores a single `RelationValue`. | IField |
110-
| RelationList | list | A `List` field that defaults to `Relation` as the value type | See `List` |
111-
| RelationChoice | RelationValue | A `Choice` field intended to store `RelationValue`'s | See `Choice` |
112+
| - | - | - | - |
113+
| `Relation` | `RelationValue` | Stores a single `RelationValue`. | `IField` |
114+
| `RelationList` | `list` | A `List` field that defaults to `Relation` as the value type | See {ref}`List <fields-in-zope-schema-label>` |
115+
| `RelationChoice` | `RelationValue` | A `Choice` field intended to store `RelationValue`s | See {ref}`Choice <fields-in-zope-schema-label>` |
112116

113117

114118
### Fields in `plone.app.textfield`
115119

116120
See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for more details.
117121

118122
| Name | Type | Description | Properties |
119-
| -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
120-
| 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 |
123+
| - | - | - | - |
124+
| `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` |
121125

122126

123127
### Fields in `plone.schema`
124128

125129
See {ref}`backend-ploneschema-label` for more details.
126130

127131
| Name | Type | Description | Properties |
128-
| ----- | ---- | ----------------------------------- | ------------------ |
129-
| Email | str | A field containing an email address | IField, IMinMaxLen |
130-
| JSON | | | |
132+
| - | - | - | - |
133+
| `Email` | str | A field containing an email address | `IField`, `IMinMaxLen` |
134+
| `JSON` | | | |
131135

132136

133137
(backend-fields-schema-label)=

0 commit comments

Comments
 (0)