Merge branch '6.0' into backend-richtextfield

Author: MrTango

docs/backend/fields.md

@@ -323,19 +323,43 @@ See {ref}`backend-ploneschema-label` for more details.
 
 (backend-fields-schema-label)=
 
-## schema
+## Schema
 
+With `plone.autoform` and `plone.supermodel` we can use directives to add information to the schema fields.
 
-(backend-fields-schema-autoform-label)=
 
-### `autoform` (directives) schema ordering, filtering, and permissions
+(backend-fields-schema-autoform-permission)=
 
+### Protect a field with a permission
 
-(backend-fields-supermodel-label)=
+By default, fields are included in the form regardless of the user's permissions.
+Fields can be protected using the `read_permission` and `write_permission` directives.
+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.
+The permission should be given with its Zope 3-style name, such as `cmf.ManagePortal` instead of `Manage portal`.
 
-## `supermodel` (XML)
+In this example, the `secret` field is protected by the `cmf.ManagePortal` permission as both a read and write permission.
+This means that in both display and input modes, the field will only be included in the form for users who have that permission:
 
+```python
+from plone.supermodel import model
+from plone.autoform import directives as form
+
+class IMySchema(model.Schema):
+    form.read_permission(secret="cmf.ManagePortal")
+    form.write_permission(secret="cmf.ManagePortal")
+    secret = schema.TextLine(
+        title = "Secret",
+        )
+```
 
-(backend-fields-supermodel-autoform-label)=
+In supermodel XML, the directives are `security:read-permission` and
+`security:write-permission`:
 
-### `autoform` (directives) supermodel ordering, filtering, and permissions
+```xml
+<field type="zope.schema.TextLine"
+        name="secret"
+        security:read-permission="cmf.ManagePortal"
+        security:write-permission="cmf.ManagePortal">
+    <title>Secret</title>
+</field>
+```

docs/backend/schemas.md

@@ -217,6 +217,148 @@ Note this won't have behavior fields added to it at this stage, only the fields
 - {doc}`reference list of fields used in Plone </backend/fields>`
 
 
+(backend-schemas-directives-label)=
+
+## Schema directives
+
+With `plone.autoform` and `plone.supermodel`, we can use directives to add information to the schema fields.
+
+
+### Omit fields
+
+A field can be omitted entirely from all forms, or from some forms, using the `omitted` and `no_omit` directives.
+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:
+
+```{code-block} python
+:emphasize-lines: 7,12,13
+:linenos:
+
+from z3c.form.interfaces import IEditForm
+from plone.supermodel import model
+from plone.autoform import directives as form
+
+class IMySchema(model.Schema):
+
+    form.omitted("dummy")
+    dummy = schema.Text(
+        title="Dummy"
+        )
+
+    form.omitted("edit_only")
+    form.no_omit(IEditForm, "edit_only")
+    edit_only = schema.TextLine(
+        title = "Only included on edit forms",
+        )
+```
+
+In supermodel XML, this can be specified as:
+
+```{code-block} xml
+:emphasize-lines: 3,9
+
+<field type="zope.schema.TextLine"
+        name="dummy"
+        form:omitted="true">
+    <title>Dummy</title>
+</field>
+
+<field type="zope.schema.TextLine"
+        name="edit-only"
+        form:omitted="z3c.form.interfaces.IForm:true z3c.form.interfaces.IEditForm:false">
+    <title>Only included on edit form</title>
+</field>
+```
+
+`form:omitted` may be either a single boolean value, or a space-separated list of `<form_interface>:<boolean>` pairs.
+
+
+### Reorder fields
+
+A field's position in the form can be influenced using the `order_before` and `order_after` directives.
+In this example, the `not_last` field is placed before the `summary` field, even though it is defined afterward:
+
+```{code-block} python
+:emphasize-lines: 12
+:linenos:
+
+from plone.supermodel import model
+from plone.autoform import directives as form
+
+class IMySchema(model.Schema):
+
+    summary = schema.Text(
+        title="Summary",
+        description="Summary of the body",
+        readonly=True
+        )
+
+    form.order_before(not_last="summary")
+    not_last = schema.TextLine(
+        title="Not last",
+        )
+```
+
+The value passed to the directive may be either `*`, indicating before or after all fields, or the name of another field.
+Use `.<fieldname>` to refer to the field in the current schema or a base schema.
+Prefix with the schema name, such as `IDublinCore.title`, to refer to a field in another schema.
+Use an unprefixed name to refer to a field in either the current or default schema for the form.
+
+In supermodel XML, the directives are called `form:before` and `form:after`.
+For example:
+
+```{code-block} xml
+:emphasize-lines: 3
+
+<field type="zope.schema.TextLine"
+        name="not_last"
+        form:before="*">
+    <title>Not last</title>
+</field>
+```
+
+
+### Organizing fields into fieldsets
+
+Fields can be grouped into fieldsets, which will be rendered within an HTML `<fieldset>` tag.
+In this example the `footer` and `dummy` fields are placed within the `extra` fieldset:
+
+```{code-block} python
+:emphasize-lines: 6-9
+:linenos:
+
+from plone.supermodel import model
+from plone.autoform import directives as form
+
+class IMySchema(model.Schema):
+
+    model.fieldset("extra",
+        label="Extra info",
+        fields=["footer", "dummy"]
+        )
+
+    footer = schema.Text(
+        title="Footer text",
+        )
+
+    dummy = schema.Text(
+        title="Dummy"
+        )
+```
+
+In supermodel XML, fieldsets are specified by grouping fields within a `<fieldset>` tag:
+
+```xml
+<fieldset name="extra" label="Extra info">
+    <field name="footer" type="zope.schema.TextLine">
+        <title>Footer text</title>
+    </field>
+    <field name="dummy" type="zope.schema.TextLine">
+        <title>Dummy</title>
+    </field>
+</fieldset>
+```
+
+
 ## Advanced
 
 ```{note}
@@ -588,17 +730,4 @@ def fields(self):
             f.field = schema_field
 ```
 
-#### Don't use dict `{}` or list `[]` as a default value
-
-Because of how Python object construction works, giving `[]` or `{}` as a default value will make all created field values share this same object.
-
-```{seealso}
-[The Hitchhiker's Guide to Python, Common Gotchas](https://docs.python-guide.org/writing/gotchas)
-```
-
-Use value adapters instead.
-
-```{seealso}
-[`plone.directives.form` documentation of Value adapters](https://pypi.org/project/plone.directives.form/#value-adapters)
-```
 

docs/backend/upgrading/version-specific-migration/index.md

@@ -26,5 +26,6 @@ upgrade-to-52
 upgrade-to-python3
 upgrade-zodb-to-python3
 upgrade-to-60
+upgrade-to-61
 migrate-to-volto
 ```

docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md

@@ -26,7 +26,7 @@ To upgrade add-ons to Plone 5, see also {doc}`upgrade-addons-to-50`.
 -   Always upgrade from the latest version of 4.x to the latest version of 5.x (4.3.20 to 5.2.9 at the time of writing).
     This will resolve many migration-specific issues.
 -   If you have problems, ask for help on https://community.plone.org.
--   The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube.com/watch?t=1m17s&v=bQ-IpO-7F00&feature=youtu.be) and [slides](https://de.slideshare.net/derschmock/upgrade-to-plone-5).
+-   The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube.com/watch?t=1m17s&v=bQ-IpO-7F00&feature=youtu.be) and [slides](https://www.slideshare.net/slideshow/upgrade-to-plone-5/54040952).
 
 
 (upgrading-plone-4.x-to-5.0-changes-due-to-implemented-plips-label)=

docs/backend/upgrading/version-specific-migration/upgrade-to-60.md

@@ -600,7 +600,7 @@ The following example {file}`registry.xml` may be used for configuring TinyMCE w
 Please make sure you write valid JSON for the `template` option.
 
 ```{seealso}
-See also the [TinyMCE 4 to 5 upgrade guide](https://www.tiny.cloud/docs/migration-from-4x/).
+See also [Migrating from TinyMCE 4 to TinyMCE 5](https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/).
 ```
 
 ## Viewlets

docs/backend/upgrading/version-specific-migration/upgrade-to-61.md

@@ -0,0 +1,88 @@
+---
+myst:
+  html_meta:
+    "description": "How to upgrade to Plone 6.1"
+    "property=og:description": "How to upgrade to Plone 6.1"
+    "property=og:title": "How to upgrade to Plone 6.1"
+    "keywords": "Upgrade, Plone 6"
+---
+
+(backend-upgrade-plone-v61-label)=
+
+# Upgrade Plone 6.0 to 6.1
+
+Plone 6.1 has seen the following major changes.
+Some may require changes in your setup.
+
+
+## Drop Python 3.8 and 3.9
+
+We only support Python 3.10, 3.11, and 3.12.
+
+
+## TinyMCE upgraded in Classic UI
+
+In Plone 6.0, the Classic UI frontend uses TinyMCE 5, a rich text editor for websites.
+TinyMCE 5 reached its end of support on April 20, 2023.
+For Plone 6.1, Classic UI upgraded TinyMCE from version 5 to 7.
+
+If you upgrade a site using Classic UI from Plone 6.0 to 6.1, you do not need to take any action, unless you implemented custom plugins, or you use a plugin which got removed or moved to premium in TinyMCE versions 6 or 7.
+To upgrade your plugin implementation to TinyMCE 7, see the [upgrade guides](https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/#plugins).
+
+
+### Enable the TinyMCE accordion plugin
+
+1.  Go to the {guilabel}`Site Setup > General > TinyMCE` control panel to manage TinyMCE settings.
+1.  Under the {guilabel}`Plugins and Toolbar` tab, check {guilabel}`accordion` to enable the accordion plugin.
+1.  Under the same tab, add a menu entry `accordion` for TinyMCE in the control panel by editing the `items` key as shown.
+
+    ```json
+    {
+      "insert": {
+        "title": "Insert",
+        "items": "link media | template hr | accordion"
+      },
+    }
+    ```
+
+1.  Click the {guilabel}`Save` button to save your settings.
+1.  In the {guilabel}`Security > HTML filtering` control panel, add two new tags to {guilabel}`Valid tags`.
+
+    -   `summary`
+    -   `details`
+
+1.  Also in the {guilabel}`Security > HTML filtering` control panel, add a new attribute to {guilabel}`Custom attributes`.
+
+    -   `open`
+
+1.  For a transform to valid markup of the Bootstrap 5 accordion, use an output filter.
+
+    ```{seealso}
+    -   [Addon collective.outputfilters.tinymceaccordion](https://github.com/collective/collective.outputfilters.tinymceaccordion)
+    ```
+
+
+## `z3c.form` and `plone.app.z3cform`
+
+````{todo}
+This is a placeholder.
+
+-   Update deprecated imports
+-   New widget templates
+
+```{seealso}
+https://github.com/plone/plone.app.z3cform/pull/181
+```
+````
+
+
+## `plone.app.multilingual` is a core add-on
+
+`plone.app.multilingual` is the package that adds multilingual support to Plone, allowing the storage and display of content in multiple languages.
+In Plone 6.0 and earlier, this was a dependency of `Products.CMFPlone`, making it available for installation in all Plone sites.
+In Plone 6.1 it is now a dependency of the `Plone` package.
+
+If your project or your add-on needs this package, and you only depend on `Products.CMFPlone` until now, you should add `plone.app.multilingual` as a dependency.
+Then your project or add-on will keep working in both Plone 6.0 and 6.1.
+
+The goal of turning more of the current core packages into core add-ons is to make the core smaller, and in some cases solve circular dependencies.