Skip to content

Commit 8aa3a90

Browse files
petschkipetschki
committed
Move content to the right place.
1 parent 6594061 commit 8aa3a90

File tree

4 files changed

+264
-313
lines changed

4 files changed

+264
-313
lines changed

‎docs/backend/fields.md

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -136,19 +136,45 @@ See {ref}`backend-ploneschema-label` for more details.
136136

137137
(backend-fields-schema-label)=
138138

139-
## schema
139+
## Schema
140140

141+
With `plone.autoform` and `plone.supermodel` we can use directives to add information to the schema fields.
141142

142-
(backend-fields-schema-autoform-label)=
143143

144-
### `autoform` (directives) schema ordering, filtering, and permissions
144+
(backend-fields-schema-autoform-permission)=
145145

146+
### Protect a field with a permission
146147

147-
(backend-fields-supermodel-label)=
148+
By default, fields are included in the form regardless of the user's permissions.
149+
Fields can be protected using the `read_permission` and `write_permission` directives.
150+
The read permission is checked when the field is in display mode, and the write permission is checked when the field is in input mode.
151+
The permission should be given with its Zope 3-style name (i.e. cmf.ManagePortal rather than 'Manage portal').
148152

149-
## `supermodel` (XML)
153+
In this example, the `secret` field is protected by the
154+
`cmf.ManagePortal` permission as both a read and write permission.
155+
This means that in both display and input modes, the field will
156+
only be included in the form for users who have that permission:
150157

158+
```python
159+
from plone.supermodel import model
160+
from plone.autoform import directives as form
151161

152-
(backend-fields-supermodel-autoform-label)=
162+
class IMySchema(model.Schema):
163+
form.read_permission(secret='cmf.ManagePortal')
164+
form.write_permission(secret='cmf.ManagePortal')
165+
secret = schema.TextLine(
166+
title = u'Secret',
167+
)
168+
```
169+
170+
In supermodel XML the directives are `security:read-permission` and
171+
`security:write-permission`:
153172

154-
### `autoform` (directives) supermodel ordering, filtering, and permissions
173+
```xml
174+
<field type="zope.schema.TextLine"
175+
name="secret"
176+
security:read-permission="cmf.ManagePortal"
177+
security:write-permission="cmf.ManagePortal">
178+
<title>Secret</title>
179+
</field>
180+
```

‎docs/backend/schemas.md

Lines changed: 142 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,148 @@ Note this won't have behavior fields added to it at this stage, only the fields
217217
- {doc}`reference list of fields used in Plone </backend/fields>`
218218

219219

220+
(backend-schemas-directives-label)=
221+
222+
## Using schema directives
223+
224+
With `plone.autoform` and `plone.supermodel` we can use directives to add information to the schema fields.
225+
226+
227+
### Omitting fields
228+
229+
A field can be omitted entirely from all forms, or from some forms, using the `omitted` and `no_omit` directives.
230+
In this example, the `dummy` field is omitted from all forms, and the `edit_only` field is omitted from all forms except those that provide the IEditForm interface:
231+
232+
```{code-block} python
233+
:emphasize-lines: 7,12,13
234+
:linenos:
235+
236+
from z3c.form.interfaces import IEditForm
237+
from plone.supermodel import model
238+
from plone.autoform import directives as form
239+
240+
class IMySchema(model.Schema):
241+
242+
form.omitted('dummy')
243+
dummy = schema.Text(
244+
title=u"Dummy"
245+
)
246+
247+
form.omitted('edit_only')
248+
form.no_omit(IEditForm, 'edit_only')
249+
edit_only = schema.TextLine(
250+
title = u'Only included on edit forms',
251+
)
252+
```
253+
254+
In supermodel XML, this can be specified as:
255+
256+
```{code-block} xml
257+
:emphasize-lines: 3,9
258+
259+
<field type="zope.schema.TextLine"
260+
name="dummy"
261+
form:omitted="true">
262+
<title>Dummy</title>
263+
</field>
264+
265+
<field type="zope.schema.TextLine"
266+
name="edit-only"
267+
form:omitted="z3c.form.interfaces.IForm:true z3c.form.interfaces.IEditForm:false">
268+
<title>Only included on edit form</title>
269+
</field>
270+
```
271+
272+
`form:omitted` may be either a single boolean value, or a space-separated list of form_interface:boolean pairs.
273+
274+
275+
### Re-ordering fields
276+
277+
A field's position in the form can be influenced using the `order_before` and `order_after` directives.
278+
In this example, the `not_last` field is placed before the `summary` field even though it is defined afterward:
279+
280+
```{code-block} python
281+
:emphasize-lines: 12
282+
:linenos:
283+
284+
from plone.supermodel import model
285+
from plone.autoform import directives as form
286+
287+
class IMySchema(model.Schema):
288+
289+
summary = schema.Text(
290+
title=u"Summary",
291+
description=u"Summary of the body",
292+
readonly=True
293+
)
294+
295+
form.order_before(not_last='summary')
296+
not_last = schema.TextLine(
297+
title=u"Not last",
298+
)
299+
```
300+
301+
The value passed to the directive may be either '*' (indicating before or after all fields) or the name of another field.
302+
Use `'.fieldname'` to refer to field in the current schema or a base schema.
303+
Prefix with the schema name (e.g. `'IDublinCore.title'`) to refer to a field in another schema.
304+
Use an unprefixed name to refer to a field in the current or the default schema for the form.
305+
306+
In supermodel XML, the directives are called `form:before` and `form:after`.
307+
For example:
308+
309+
```{code-block} xml
310+
:emphasize-lines: 3
311+
312+
<field type="zope.schema.TextLine"
313+
name="not_last"
314+
form:before="*">
315+
<title>Not last</title>
316+
</field>
317+
```
318+
319+
320+
### Organizing fields into fieldsets
321+
322+
Fields can be grouped into fieldsets, which will be rendered within an HTML `<fieldset>` tag.
323+
In this example the `footer` and `dummy` fields are placed within the `extra` fieldset:
324+
325+
```{code-block} python
326+
:emphasize-lines: 6,7,8,9
327+
:linenos:
328+
329+
from plone.supermodel import model
330+
from plone.autoform import directives as form
331+
332+
class IMySchema(model.Schema):
333+
334+
model.fieldset('extra',
335+
label=u"Extra info",
336+
fields=['footer', 'dummy']
337+
)
338+
339+
footer = schema.Text(
340+
title=u"Footer text",
341+
)
342+
343+
dummy = schema.Text(
344+
title=u"Dummy"
345+
)
346+
```
347+
348+
In supermodel XML fieldsets are specified by grouping fields within a `<fieldset>` tag:
349+
350+
```xml
351+
<fieldset name="extra" label="Extra info">
352+
<field name="footer" type="zope.schema.TextLine">
353+
<title>Footer text</title>
354+
</field>
355+
<field name="dummy" type="zope.schema.TextLine">
356+
<title>Dummy</title>
357+
</field>
358+
</fieldset>
359+
```
360+
361+
220362
## Advanced
221363

222364
```{note}
@@ -588,17 +730,4 @@ def fields(self):
588730
f.field = schema_field
589731
```
590732

591-
#### Don't use dict `{}` or list `[]` as a default value
592-
593-
Because of how Python object construction works, giving `[]` or `{}` as a default value will make all created field values share this same object.
594-
595-
```{seealso}
596-
[The Hitchhiker's Guide to Python, Common Gotchas](https://docs.python-guide.org/writing/gotchas)
597-
```
598-
599-
Use value adapters instead.
600-
601-
```{seealso}
602-
[`plone.directives.form` documentation of Value adapters](https://pypi.org/project/plone.directives.form/#value-adapters)
603-
```
604733

‎docs/backend/widgets.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,75 @@ The main widgets are:
6363
- DateTime Picker
6464

6565

66+
(backend-widgets-fields-display-label)=
67+
68+
## Changing a field's display mode
69+
70+
A field's widget can be displayed in several modes:
71+
72+
`input`
73+
: Allows the user to enter data into the field
74+
75+
`display`
76+
: A read-only indication of the field's value
77+
78+
`hidden`
79+
: A record of the field's value that is included only in the HTML source
80+
81+
82+
### `plone.autoform` `mode` directive
83+
84+
85+
```{code-block} python
86+
:emphasize-lines: 6,7
87+
:linenos:
88+
89+
from plone.supermodel import model
90+
from plone.autoform import directives as form
91+
92+
class IMySchema(model.Schema):
93+
94+
form.mode(secret='hidden')
95+
form.mode(IEditForm, secret='input')
96+
secret = schema.TextLine(
97+
title=u"Secret",
98+
default=u"Secret stuff (except on edit forms)"
99+
)
100+
```
101+
102+
In this case the mode for the `secret` field is set to 'hidden' for most forms, but 'input' for forms that provide the IEditForm interface.
103+
104+
The corresponding supermodel XML directive is `form:mode`:
105+
106+
```{code-block} xml
107+
:emphasize-lines: 3
108+
109+
<field type="zope.schema.TextLine"
110+
name="secret"
111+
form:mode="z3c.form.interfaces.IForm:hidden z3c.form.interfaces.IEditForm:input">
112+
<title>Secret</title>
113+
<description>Secret stuff (except on edit forms)</description>
114+
</field>
115+
```
116+
117+
The mode can be specified briefly if it should be the same for all forms:
118+
119+
```{code-block} xml
120+
:emphasize-lines: 3
121+
122+
<field type="zope.schema.TextLine"
123+
name="secret"
124+
form:mode="hidden">
125+
<title>Secret</title>
126+
<description>Secret stuff</description>
127+
</field>
128+
```
129+
130+
In other words, `form:mode` may be either a single mode, or a space-separated list of form_interface:mode pairs.
131+
132+
133+
(backend-widgets-fields-widget-label)=
134+
66135
## Changing a field's widget
67136

68137
You can change the widget that you use for a field in several ways.

0 commit comments

Comments
 (0)