Merge branch '6.0' into linkcheck-news-volto

Author: stevepiercy

.gitmodules

@@ -1,7 +1,7 @@
 [submodule "submodules/volto"]
 	path = submodules/volto
 	url = https://github.com/plone/volto.git
-	branch = master
+	branch = main
 [submodule "submodules/plone.restapi"]
 	path = submodules/plone.restapi
 	url = https://github.com/plone/plone.restapi.git

docs/backend/content-types/index.md

@@ -9,11 +9,11 @@ myst:
 
 (backend-content-types-label)=
 
-# Content Types
+# Content types
+
+This part of the documentation describes how to develop content types in Plone.
+Content types are implemented through the {term}`Dexterity` framework.
 
-```{seealso}
-See the chapter {ref}`training:dexterity1-label` from the Mastering Plone 6 Training for a step-by-step tutorial to create a custom content type.
-```
 
 ## What is a content type?
 
@@ -22,19 +22,59 @@ We have different content types to reflect the different kinds of information ab
 
 Pages, news items, events, files (binary), and images are examples of content types.
 
-Lots of things in Plone can be configured to work differently based on the content type. For example, each content type has:
-- a {ref}`schema <backend-fields-label>` specifying the fields which can be edited for the content type
-- 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
-- a {ref}`workflow <backend-workflows-label>` controlling transitions between publishing states and associated permissions
-- a version policy controlling whether to store a revision history
+Lots of things in Plone can be configured to work differently based on the content type.
+For example, each content type has:
+
+-   a {ref}`schema <backend-fields-label>` specifying the fields which can be edited for the content type
+-   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
+-   a {ref}`workflow <backend-workflows-label>` controling transitions between publishing states and associated permissions
+-   a version policy controling whether to store a revision history
 
 It is common in developing a web site that you'll need customized versions of common content types, or perhaps even entirely new types.
 
+
+## Topics
+
+This part of the documentation will cover the following topics.
+
+-   Some basic design techniques for solving problems with content types in Plone
+-   Setting up a Dexterity development environment
+-   Creating a package to house your types
+-   Building a custom type based on a schema
+-   Creating custom views and forms for your type
+-   Advanced customization, including workflow and security
+-   Testing your types
+-   A quick reference to common fields, widgets, and APIs
+
+```{seealso}
+See the chapter {ref}`training:dexterity1-label` from the Mastering Plone 6 Training for a step-by-step tutorial to create a custom content type.
+```
+
+```{toctree}
+:maxdepth: 2
+```
+% Uncomment each of the following and move into the toctree above when migrated from Plone 5 documentation
+% designing
+% prerequisite
+% schema-driven-types
+% model-driven-types
+% custom-views
+% advanced/index
+% testing/index
+% reference/index
+
+
 ## Factory Type Information
 
+```{todo}
+Find a new home for this section.
+This page is an introduction, whereas FTI is a topic unto itself.
+```
+
 A content type is defined by creating a {term}`Factory Type Information` (FTI) object.
 
-To create an FTI in a GenericSetup profile, add the content type to the list in `types.xml`. For example, this adds the standard Plone page (Document) content type:
+To create an FTI in a `GenericSetup` profile, add the content type to the list in `types.xml`.
+For example, this adds the standard Plone page (`Document`) content type:
 
 ```xml
 <object name="portal_types">
@@ -145,7 +185,8 @@ In this example, the file is `types/Document.xml` and contains this XML:
 
 The `name` attribute on the root element in the XML must match the name in the filename and the name listed in `types.xml`.
 
-Set the `i18n:domain` to the i18n domain which includes translations for this content type. This is usually the same as the name of the Python package which contains the content type.
+Set the `i18n:domain` to the i18n domain which includes translations for this content type.
+This is usually the same as the name of the Python package which contains the content type.
 
 
 (global-fti-properties-label)=
@@ -209,7 +250,6 @@ The XML sets a number of FTI properties that are used globally, in both Classic
 :   The name of the content type displayed in the UI.
 
 
-
 (classic-ui-only-fti-properties-label)=
 
 ### Classic UI only FTI properties

docs/classic-ui/images.md

@@ -199,15 +199,15 @@ Or you can get the HTML tag back, and replace the current tag with it:
 
 ```xml
 <div tal:define="scale_view context/@@images">
-  <img tal:replace="structured python: scale_view.tag('image', 'mini')">
+  <img tal:replace="structure python: scale_view.tag('image', 'mini')">
 </div>
 ```
 
 You can also provide the following keyword arguments to set `title`, `alt`, or `css_class` for the generated tag:
 
 ```xml
 <div tal:define="scale_view context/@@images">
-  <img tal:replace="structured python: scale_view.tag('banner', 'mini', title='The Banner', alt='Alternative text', css_class='banner')">
+  <img tal:replace="structure python: scale_view.tag('banner', 'mini', title='The Banner', alt='Alternative text', css_class='banner')">
 </div>
 ```
 
@@ -460,3 +460,53 @@ This will result in a `srcset` as in the following example for a medium image:
 Please note that this example has the `resolve_uid_and_caption` filter disabled to see the scale names better.
 The real `src` URLs look more like `http://localhost:8080/Plone50/dsc04791.jpg/@@images/778f9c06-36b0-485d-ab80-12c623dc4bc3.jpeg`.
 ```
+
+## Image scales from catalog brain
+
+For all `NamedBlobImage` fields, we can get existing scale information directly from the catalog brain.
+
+Given a content type with a `NamedBlobField` named `picture`, we can get the following information by calling the `image_scales` attribute on the catalog brain.
+
+```python
+(Pdb) pp brain.image_scales
+{'picture': [{'content-type': 'image/jpeg',
+              'download': '@@images/picture-800-ddae07fbc46b293155bd6fcda7f2572a.jpeg',
+              'filename': 'my-picture.jpg',
+              'height': 800,
+              'scales': {'icon': {'download': '@@images/picture-32-f2f815374aa5434e06fb3a95306527fd.jpeg',
+                                  'height': 32,
+                                  'width': 32},
+                         'large': {'download': '@@images/picture-800-4dab3b3cc42abb6fad29258c7430070a.jpeg',
+                                   'height': 800,
+                                   'width': 800},
+                         'listing': {'download': '@@images/picture-16-d3ac2117158cf38d0e15c5f5feb8b75d.jpeg',
+                                     'height': 16,
+                                     'width': 16},
+                         'mini': {'download': '@@images/picture-200-3de96ae4288dfb18f5589c89b861ecc1.jpeg',
+                                  'height': 200,
+                                  'width': 200},
+                         'preview': {'download': '@@images/picture-400-60f60942c8e4ddd7dcdfa90527a8bae0.jpeg',
+                                     'height': 400,
+                                     'width': 400},
+                         'teaser': {'download': '@@images/picture-600-1ada88b8af6748e9cbe18a34c3127443.jpeg',
+                                    'height': 600,
+                                    'width': 600},
+                         'thumb': {'download': '@@images/picture-128-80fce253497f7a745315f58f3e8f3a0c.jpeg',
+                                   'height': 128,
+                                   'width': 128},
+                         'tile': {'download': '@@images/picture-64-220d6703eac104c59774a379a8276e76.jpeg',
+                                  'height': 64,
+                                  'width': 64}},
+              'size': 238977,
+              'width': 800}]}
+```
+
+This information shows we have everything we need to generate our image URLs, without waking up any objects.
+
+```xml
+<li tal:define="preview python: brain.image_scales['picture'][0]['scales']['preview']">
+  <img src="${brain/getURL}/${python: preview['download']}"
+    width="${python: preview['width']}"
+    height="${python: preview['height']}" />
+</li>
+```

docs/classic-ui/layers.md

@@ -58,12 +58,8 @@ Then views and viewlets from your product can be enabled on the site instance us
 ### Unconditional overrides
 
 If you want to override a view or a viewlet unconditionally for all sites without the add-on product installer support, you need to use `overrides.zcml`.
-
-```{todo}
-Explain how to use an `overrides.zcml`.
-
-See https://github.com/plone/documentation/issues/1426
-```
+You can override classes and templates in this file.
+To do this, you put the ZCML registration in a file called `overrides.zcml` in the package root, next to the top-most `configure.zcml`.
 
 
 (classic-ui-creating-a-layer-label)=

docs/classic-ui/views.md

@@ -173,7 +173,7 @@ You need to declare the `browser` namespace in your `configure.zcml` to use `bro
 ```
 
 The view in question is registered against a {ref}`layer <classic-ui-layers-label>`.
-It will be available after restart, after running the {ref}`GenericSetup profile <backend-configuration-registry-generic-setup-label>`.
+It will be available after restart and running the {ref}`GenericSetup profile <backend-configuration-registry-generic-setup-label>`, or enabling the add-on.
 
 
 (classic-ui-page-template-label)=
@@ -432,7 +432,7 @@ Since one Zope application server can contain multiple Plone sites, layers are u
 A layer is in use when either:
 
 -   a theme which defines that layer is active, or
--   if a specific add-on product which defines that layer is installed.
+-   if a specific add-on product which defines that layer is installed in the Plone site.
 
 You should register your views against a certain layer in your own code.
 
@@ -637,11 +637,11 @@ This way you also have a test for the generated view.
 
 ## Guided information
 
-The Mastering Plone Training has several chapters on views.
+The Mastering Plone 5 Training has several chapters on views.
 
-- {ref}`training:views1-label`
-- {ref}`training:views2-label`
-- {ref}`training:views3-label`
+-   {doc}`training:mastering-plone-5/views_1`
+-   {doc}`training:mastering-plone-5/views_2`
+-   {doc}`training:mastering-plone-5/views_3`
 
 
 (classic-ui-anatomy-of-a-view-label)=

docs/conf.py

@@ -91,6 +91,8 @@
     r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main",  # plone.restapi
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
     r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0",  # volto
+    # Ignore unreliable sites
+    r"https://web.archive.org/",  # volto
 ]
 linkcheck_anchors = True
 linkcheck_timeout = 5
@@ -324,7 +326,7 @@ def source_replace(app, docname, source):
 # Dict of replacements.
 source_replacements = {
     "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
-    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.6",
+    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.7",
     "{NVM_VERSION}": "0.39.3",
 }
 

docs/glossary.md

@@ -121,7 +121,8 @@ Diazo
     Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology.
 
 Dexterity
-    [Dexterity](https://github.com/plone/plone.dexterity), the base framework for building content types, both through-the-web and as filesystem code for Zope.
+    [Dexterity](https://github.com/plone/plone.dexterity) is the base framework for building content types, both through-the-web and as filesystem code.
+     It is aimed at Plone, although this package should work with plain Zope + CMF systems.
 
 Dublin Core
     The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, etc.), as well as physical resources such as books or CDs, and objects like artworks.
@@ -515,7 +516,7 @@ Zope Component Architecture
     It can be used for developing any Python application.
     Maybe it should be called Python Component Architecture.
     ```{seealso}
-    See also https://muthukadan.net/docs/zca.html.
+    See also https://zopecomponent.readthedocs.io/en/latest/index.html.
     ```
 
 browser layer

docs/i18n-l10n/index.md

@@ -62,7 +62,7 @@ language tag
 :   A language tag is a string used as an identifier for a language.
     A language tag may have one or more subtags.
     The basic form of a language tag is `LANGUAGE-[SUBTAG]`.
-    
+
     ```{seealso}
     -   W3C article [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
     -   W3C Working Draft [Language Tags and Locale Identifiers for the World Wide Web](https://www.w3.org/TR/ltli/)
@@ -145,6 +145,7 @@ These differences depend upon the programming language, either Python or JavaScr
 
 translating-text-strings
 language-negotiation
+language-negotiation-volto
 translating-content
 contributing-translations
 resync-translations

docs/i18n-l10n/language-negotiation-volto.md

@@ -0,0 +1,34 @@
+---
+myst:
+  html_meta:
+    "description": "Accessing and changing the language state of Plone programmatically."
+    "property=og:description": "Accessing and changing the language state of Plone programmatically."
+    "property=og:title": "Language negotiation in Volto"
+    "keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization, volto"
+---
+
+(language-negotiation-volto-label)=
+
+# Language negotiation in Volto
+
+Volto does not rely on the configuration set in Plone's Language Control Panel to handle the redirection from the root of the site to the Language Root Folder.
+
+Volto has a setting in its own configuration stating whether a site is multilingual or not: `isMultilingual`.
+
+First of all, you need to set that setting to `true`.
+
+Then you need to add the list of supported languages to the `supportedLanguages` setting, and match them with the languages configured in Plone's Language Control Panel.
+
+As a last thing, you need to set your site's `defaultLanguage` to one of the `supportedLanguages`.
+
+When all these settings are configured, Volto's [`MultilingualRedirector`](https://github.com/plone/volto/blob/main/src/components/theme/MultilingualRedirector/MultilingualRedirector.jsx) will handle the language negotiation and the redirect.
+
+In its configuration, the component tries to match the `I18N_LANGUAGE` cookie set in the user's browser with the list of supported languages, and if the match does not succeed, it selects the default language configured in Volto.
+
+After that it does the redirection to the matched Language Root Folder.
+
+If the site is not configured to be multilingual, Volto doesn't do any redirect.
+
+## Overriding the default behavior
+
+To do so, you need to provide your own `MultilingualRedirector` component {doc}`customizing it </volto/recipes/customizing-components>`.