Skip to content

Commit 940939d

Browse files
stevepiercystevepiercy
committed
Tidy form-schema-hints.md
1 parent 6296667 commit 940939d

File tree

1 file changed

+56
-55
lines changed

1 file changed

+56
-55
lines changed

‎plone.app.dexterity/reference/form-schema-hints.md‎

Lines changed: 56 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
11
---
22
myst:
33
html_meta:
4-
"description": ""
5-
"property=og:description": ""
6-
"property=og:title": ""
7-
"keywords": ""
4+
"description": "Form configuration with schema hints using directives in Plone"
5+
"property=og:description": "Form configuration with schema hints using directives in Plone"
6+
"property=og:title": "Form configuration with schema hints using directives in Plone"
7+
"keywords": "Plone, form, configuration, schema, hints, directives"
88
---
99

10-
# Form Configuration with Schema Hints using Directives
10+
# Form configuration with schema hints using directives
1111

12-
Dexterity uses the directives in [plone.autoform](http://pypi.python.org/pypi/plone.autoform) and [plone.supermodel](http://pypi.python.org/pypi/plone.supermodel) package to configure its [z3c.form](http://docs.zope.org/z3c.form)-based add and edit forms.
13-
A directive annotates a schema with “form hints”, which are used to configure the form when it gets generated from the schema.
12+
Dexterity uses the directives in [`plone.autoform`](https://pypi.org/project/plone.autoform/) and [`plone.supermodel`](https://pypi.org/project/plone.supermodel/) packages to configure its [`z3c.form`](https://z3cform.readthedocs.io/en/latest/)-based add and edit forms.
13+
A directive annotates a schema with "form hints", which are used to configure the form when it gets generated from the schema.
1414

15-
The easiest way to apply form hints in Python code is to use the directives from [plone.autoform](http://pypi.python.org/pypi/plone.autoform) and [plone.supermodel](http://pypi.python.org/pypi/plone.supermodel).
16-
For the directives to work, the schema must derive from *plone.supermodel.model.Schema*.
15+
The easiest way to apply form hints in Python code is to use the directives from [`plone.autoform`](https://pypi.org/project/plone.autoform/) and `plone.supermodel`.
16+
For the directives to work, the schema must derive from `plone.supermodel.model.Schema`.
1717

1818
Directives can be placed anywhere in the class body (annotations are made directly on the class).
19-
By convention they are kept next to the fields they apply to.
19+
By convention they are kept next to the fields to which they apply.
2020

21-
For example, here is a schema that omits a field:
21+
For example, here is a schema that omits a field.
2222

2323
```python
2424
from plone.autoform import directives
@@ -28,41 +28,41 @@ from zope import schema
2828

2929
class ISampleSchema(model.Schema):
3030

31-
title = schema.TextLine(title='Title')
31+
title = schema.TextLine(title="Title")
3232

33-
directives.omitted('additionalInfo')
33+
directives.omitted("additionalInfo")
3434
additionalInfo = schema.Bytes()
3535
```
3636

37-
The form directives are taking parameters in the form of a list of field names,
38-
or a set of field name/value pairs as keyword arguments.
37+
The form directives take parameters in the form of a list of field names, or a set of field name/value pairs as keyword arguments.
3938
Each directive can be used zero or more times.
4039

41-
There are two kinds of directives:
40+
There are two kinds of directives.
4241

43-
- appearance related directives
44-
- security related directives
42+
- Appearance related directives
43+
- Security related directives
4544

46-
## Appearance Related Directives
4745

48-
*plone.autoform.directives* provides these:
46+
## Appearance related directives
47+
48+
`plone.autoform.directives` provides the following.
4949

5050
| Name | Description |
51-
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
52-
| widget | Specify an alternate widget for a field. Pass the field name as a key and a widget as the value. The widget can either be a z3c.form widget instance or a string giving the dotted name to one. |
51+
| - | -|
52+
| widget | Specify an alternate widget for a field. Pass the field name as a key and a widget as the value. The widget can either be a `z3c.form` widget instance or a string giving the dotted name to one. |
5353
| omitted | Omit one or more fields from forms. Takes a sequence of field names as parameters. |
54-
| mode | Set the widget mode for one or more fields. Pass the field name as a key and the string ‘input’, ‘display’ or ‘hidden’ as the value. |
55-
| order_before | Specify that a given field should be rendered before another. Fields can only be ordered if they are in the same fieldset, otherwise order directive is ignored. Pass the field name as a key and name of the other field as a value. If the other field is in a supplementary schema (i.e. one from a behavior), its name will be e.g. `IOtherSchema.other_field_name`. If the other field is from the same schema, its name can be abbreviated by a leading dot e.g. `.other_field_name`. If the other field is is used without a prefix, its is looked up from the main schema e.g. `other_field_name`. Alternatively, pass the string “\*” to put a field first in the fieldsets form. |
56-
| order_after | The inverse of order_before(), putting a field after another. It works almost similar to `order_before`, except passing “\*” will put the field at the end of the fieldsets form. |
54+
| mode | Set the widget mode for one or more fields. Pass the field name as a key and the string `"input"`, `"display"`, or `"hidden"` as the value. |
55+
| order_before | Specify that a given field should be rendered before another. Fields can only be ordered if they are in the same fieldset, otherwise order directive is ignored. Pass the field name as a key and name of the other field as a value. If the other field is in a supplementary schema such as from a behavior, then its name will be, for example `IOtherSchema.other_field_name`. If the other field is from the same schema, its name can be abbreviated by a leading dot, for example `.other_field_name`. If the other field is is used without a prefix, it is looked up from the main schema, for example `other_field_name`. Alternatively, pass the string `*` to put a field first in the form's fieldset. |
56+
| order_after | The inverse of `order_before()`, putting a field after another. It works almost similar to `order_before`, except passing `*` will put the field at the end of the fieldsets form. |
5757

58-
*plone.supermodel.directives* provides these:
58+
`plone.supermodel.directives` provides the following.
5959

6060
| Name | Description |
6161
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
6262
| fieldset | Creates a new (or reuses an existing) fieldset (rendered in Plone as a tab on the edit form). |
6363
| primary | Designate a given field as the primary field in the schema. This is not used for form rendering, but is used for WebDAV marshaling of the content object. |
6464

65-
The code sample below illustrates each of these directives:
65+
The code sample below illustrates each of these directives.
6666

6767
```python
6868
from plone.autoform import directives
@@ -75,70 +75,71 @@ from zope import schema
7575

7676
class ISampleSchema(model.Schema):
7777

78-
# A fieldset with id 'extra' and label 'Extra information' containing
79-
# the 'footer' and 'dummy' fields. The label can be omitted if the
78+
# A fieldset with id "extra" and label "Extra information" containing
79+
# the "footer" and "dummy" fields. The label can be omitted if the
8080
# fieldset has already been defined.
8181

82-
fieldset('extra',
83-
label='Extra information',
84-
fields=['footer', 'dummy']
82+
fieldset("extra",
83+
label="Extra information",
84+
fields=["footer", "dummy"]
8585
)
8686

8787
# Here a widget is specified as a dotted name.
8888
# The body field is also designated as the primary field for this schema
8989

90-
directives.widget(body='plone.app.z3cform.wysiwyg.WysiwygFieldWidget')
91-
primary('body')
90+
directives.widget(body="plone.app.z3cform.wysiwyg.WysiwygFieldWidget")
91+
primary("body")
9292
body = schema.Text(
93-
title='Body text',
93+
title="Body text",
9494
required=False,
95-
default='Body text goes here'
95+
default="Body text goes here"
9696
)
9797

9898
# The widget can also be specified as an object
9999

100100
directives.widget(footer=WysiwygFieldWidget)
101101
footer = schema.Text(
102-
title='Footer text',
102+
title="Footer text",
103103
required=False
104104
)
105105

106106
# An omitted field.
107-
# Use directives.omitted('a', 'b', 'c') to omit several fields
107+
# Use directives.omitted("a", "b", "c") to omit several fields
108108

109-
directives.omitted('dummy')
109+
directives.omitted("dummy")
110110
dummy = schema.Text(
111-
title='Dummy'
111+
title="Dummy"
112112
)
113113

114-
# A field in 'hidden' mode
114+
# A field in "hidden" mode
115115

116-
directives.mode(secret='hidden')
116+
directives.mode(secret="hidden")
117117
secret = schema.TextLine(
118-
title='Secret',
119-
default='Secret stuff'
118+
title="Secret",
119+
default="Secret stuff"
120120
)
121121

122-
# This field is moved before the 'description' field of the standard
122+
# This field is moved before the "description" field of the standard
123123
# IDublinCore behavior, if this is in use.
124124

125-
directives.order_before(importantNote='IDublinCore.description')
125+
directives.order_before(importantNote="IDublinCore.description")
126126
importantNote = schema.TextLine(
127-
title='Important note',
127+
title="Important note",
128128
)
129129
```
130130

131+
131132
## Security related directives
132133

133-
The security directives in the *plone.autoform.directives* module are shown below.
134+
The security directives in the `plone.autoform.directives` module are shown below.
134135
Note that these are also used to control reading and writing of fields on content instances.
135136

136137
| Name | Description |
137138
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
138-
| read_permission | Set the name (zcml-style) of a permission required to read the field’s value. Pass the field name as a key and the permission name as a string value. Among other things, this controls the field’s appearance in display forms. |
139-
| write_permission | Set the name (zcml-style) of a permission required to write the field’s value. Pass the field name as a key and the permission name as a string value. Among other things, this controls the field’s appearance in add and edit forms. |
139+
| read_permission | Set the name (ZCML-style) of a permission required to read the field's value. Pass the field name as a key and the permission name as a string value. Among other things, this controls the field's appearance in display forms. |
140+
| write_permission | Set the name (ZCML-style) of a permission required to write the field's value. Pass the field name as a key and the permission name as a string value. Among other things, this controls the field's appearance in add and edit forms. |
140141

141-
The code sample below illustrates each of these directives:
142+
The code sample below illustrates each of these directives.
142143

143144
```python
144145
from plone.autoform import directives
@@ -147,13 +148,13 @@ from zope import schema
147148

148149
class ISampleSchema(model.Schema):
149150

150-
# This field requires the 'cmf.ReviewPortalContent' permission
151+
# This field requires the "cmf.ReviewPortalContent" permission
151152
# to be read and written
152153

153-
directives.read_permission(reviewNotes='cmf.ReviewPortalContent')
154-
directives.write_permission(reviewNotes='cmf.ReviewPortalContent')
154+
directives.read_permission(reviewNotes="cmf.ReviewPortalContent")
155+
directives.write_permission(reviewNotes="cmf.ReviewPortalContent")
155156
reviewNotes = schema.Text(
156-
title='Review notes',
157+
title="Review notes",
157158
required=False,
158159
)
159160
```

0 commit comments

Comments
 (0)