Merge pull request #791 from plone/Update-training-mastering-plone-de…

…velpment Update training mastering plone development
plone · Sep 25, 2023 · 807e01c · 807e01c
2 parents 6c8ca08 + 3a2560a
commit 807e01c
Show file tree

Hide file tree

Showing 44 changed files with 353 additions and 845 deletions.
diff --git a/docs/_static/patch_scrollToActive.js b/docs/_static/patch_scrollToActive.js
@@ -20,6 +20,9 @@ var sbRunWhenDOMLoaded = (cb) => {
     let active_navigation_item = [...document.querySelectorAll("li.current.active")].pop();
     if (active_navigation_item) {
       active_navigation_item.scrollIntoView();
+
+      let article = [...document.querySelectorAll("article")].pop();
+      article.scrollIntoView({inline: "start" });
     }
   };  
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -140,8 +140,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = [
-]
+exclude_patterns = []
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -242,8 +241,8 @@ def source_replace(app, docname, source):
 
 # Dict of replacements.
 source_replacements = {
-    "{PLONE_BACKEND_VERSION}": "6.0.6",
-    "{VOLTO_FRONTEND_VERSION}": "16.22.1",
+    "{PLONE_BACKEND_VERSION}": "6.0.7",
+    "{VOLTO_FRONTEND_VERSION}": "17.0.0-alpha.27",
 }
 
 

diff --git a/docs/index.md b/docs/index.md
@@ -9,7 +9,7 @@ myst:
 
 # Plone Training
 
-A collection of trainings developed and created by the Plone Community.
+A collection of trainings developed and created by the Plone community.
 
 ```{toctree}
 :caption: Trainings
@@ -43,11 +43,11 @@ teaching/index
 
 {ref}`mastering-plone-label`
 
-: Mastering Plone 6 teaches the best practices of Plone development. It covers frontend as well as backend development and Volto as well as Plone Classic.
+: `Mastering Plone 6 development training` teaches the best practices of Plone development.
 
 {ref}`mastering-plone5-label`
 
-: Mastering Plone 5 is a training intended for people who are new to Plone or want to learn about the best practices of Plone 5 development.
+: `Mastering Plone 5 development training` is the predecessor of the Plone 6 version. It includes also `Plone Classic` topics like viewlets, views, portlets, etc..
 
 {doc}`testing/index`
 

diff --git a/docs/mastering-plone-5/index.md b/docs/mastering-plone-5/index.md
@@ -9,7 +9,7 @@ myst:
 
 (mastering-plone5-label)=
 
-# Mastering Plone 5 Development
+# Mastering Plone 5 development
 
 This is the documentation for the "Mastering Plone 5" training.
 

diff --git a/docs/mastering-plone/_static/dexterity/dex1.png b/docs/mastering-plone/_static/dexterity/dex1.png
diff --git a/docs/mastering-plone/_static/dexterity/dex2.png b/docs/mastering-plone/_static/dexterity/dex2.png
diff --git a/docs/mastering-plone/_static/dexterity/dex3.png b/docs/mastering-plone/_static/dexterity/dex3.png
diff --git a/docs/mastering-plone/_static/dexterity/dex4.png b/docs/mastering-plone/_static/dexterity/dex4.png
diff --git a/docs/mastering-plone/_static/dexterity/dex5.png b/docs/mastering-plone/_static/dexterity/dex5.png
diff --git a/docs/mastering-plone/_static/dexterity/dex6.png b/docs/mastering-plone/_static/dexterity/dex6.png
diff --git a/docs/mastering-plone/_static/dexterity/dex7.png b/docs/mastering-plone/_static/dexterity/dex7.png
diff --git a/docs/mastering-plone/_static/dexterity/dex_number.png b/docs/mastering-plone/_static/dexterity/dex_number.png
diff --git a/docs/mastering-plone/_static/inspect_components.png b/docs/mastering-plone/_static/inspect_components.png
diff --git a/docs/mastering-plone/_static/inspect_components_1.png b/docs/mastering-plone/_static/inspect_components_1.png
diff --git a/docs/mastering-plone/_static/inspect_components_2.png b/docs/mastering-plone/_static/inspect_components_2.png
diff --git a/docs/mastering-plone/_static/upgrade_steps.png b/docs/mastering-plone/_static/upgrade_steps.png
diff --git a/docs/mastering-plone/about_mastering.md b/docs/mastering-plone/about_mastering.md
@@ -1,10 +1,10 @@
 ---
 myst:
   html_meta:
-    "description": ""
-    "property=og:description": ""
+    "description": "What to expect. Trainings on site. Training videos."
+    "property=og:description": "What to expect. Trainings on site. Training videos."
     "property=og:title": "About Mastering Plone development"
-    "keywords": ""
+    "keywords": "Plone, training, develop"
 ---
 
 (about-mastering-label)=

diff --git a/docs/mastering-plone/add-ons.md b/docs/mastering-plone/add-ons.md
@@ -11,10 +11,11 @@ myst:
 
 # Extending Plone with add-on packages
 
-````{sidebar} Plone Backend Chapter
+```{card}
+Backend chapter
 
 For frontend add-ons see chapter {ref}`volto-addon-label`
-````
+```
 
 
 Plone add-ons enrich the CMS by
@@ -39,7 +40,7 @@ Plone frontent add-ons provide
 - a theme to design the layout of a site
 - components independent of blocks like a dropdown navigation
 
-Both can be tightly coupled, if a frontend feature depends on an new or enriched content type or any other change needed in data structure.
+Both can be tightly coupled, if a frontend feature depends on a new content type, a new behavior or any other change needed in data structure.
 For example an add-on that has the goal to provide a bookmarking feature depends on a backend add-on that handels the storing of the bookmarks.
 
 Have a look at the curated lists of add-ons:  

diff --git a/docs/mastering-plone/api.md b/docs/mastering-plone/api.md
@@ -15,8 +15,7 @@ myst:
 % TODO Discuss plone.restapi
 
 
-```{sidebar} Plone Backend Chapter
-```
+```{card} Backend chapter
 
 In this part you will:
 
@@ -28,6 +27,8 @@ Topics covered:
 - {py:mod}`plone.api`
 - Portal tools
 - Debugging
+```
+
 
 (api-api-label)=
 
@@ -138,9 +139,12 @@ Products.PDBDebugMode
 
 Interactive debugger
 
-: Start your instance in debug mode with {command}`venv/bin/zconsole debug instance/etc/zope.conf`.
-You have an interactive debugger at your fingertips.
-`app.Plone` is your instance which you can inspect on the command line.
+: Start your instance in debug mode with  
+  ```shell
+  venv/bin/zconsole debug instance/etc/zope.conf
+  ```
+  You have an interactive debugger at your fingertips.
+  `app.Plone` is your Plone instance object which you can inspect on the command line.
 : To list the ids of the objects in a folderish object:
   ```shell
   >>> app.Plone.talks.keys()
@@ -153,6 +157,10 @@ You have an interactive debugger at your fingertips.
   >>> app.Plone.talks.contentItems()
   [('whats-new-in-python-3.10', <Talk at /Plone/talks/whats-new-in-python-3.10>), ('plone-7', <Talk at /Plone/talks/plone-7>), ('zope', <Talk at /Plone/talks/zope>), ('betty-white', <Talk at /Plone/talks/betty-white>), ('new-years-day', <Talk at /Plone/talks/new-years-day>), ('journey-band', <Talk at /Plone/talks/journey-band>)]
   ```
+: Setting the site with `setSite` is necessary because the root object when starting the interactive debugger is `app`, which can contain more than just one Plone instance object.
+We choose our Plone instance with id `Plone`.
+With setting the site to operate on, we have access to the Zope component registry.
+The component registry is needed for methods like `contentItems` which look up utilities and other components like in this case the `ITypesTool.`
 : Stop the interactive shell with {kbd}`ctrl d`.
 
 plone.app.debugtoolbar
@@ -204,7 +212,7 @@ The `app` object you encountered in the previous exercise can be seen as the roo
 `````{admonition} Solution
 :class: toggle
 
-`app.__dict__.keys()` will show `app`'s attribute names - there is one called `Plone`, this is your Plone site object. Use `app.Plone` to access and further explore it.
+`app.keys()` will show `app`'s attribute names - there is one called `Plone`, this is your Plone site object. Use `app.Plone` to access and further explore it.
 
 ```pycon
 >>> app
@@ -216,10 +224,12 @@ The `app` object you encountered in the previous exercise can be seen as the roo
 >>> setSite(portal)
 >>> portal
 <PloneSite at /Plone>
->>> app.Plone.keys()
-['portal_setup', 'MailHost', 'caching_policy_manager', 'content_type_registry', 'error_log', 'plone_utils', 'portal_actions', 'portal_catalog', 'portal_controlpanel', 'portal_diff', 'portal_groupdata', 'portal_groups', 'portal_memberdata', 'portal_membership', 'portal_migration', 'portal_password_reset', 'portal_properties', 'portal_quickinstaller', 'portal_registration', 'portal_skins', 'portal_types', 'portal_uidannotation', 'portal_uidgenerator', 'portal_uidhandler', 'portal_url', 'portal_view_customizations', 'portal_workflow', 'translation_service', 'portal_form_controller', 'mimetypes_registry', 'portal_transforms', 'portal_archivist', 'portal_historiesstorage', 'portal_historyidhandler', 'portal_modifier', 'portal_purgepolicy', 'portal_referencefactories', 'portal_repository', 'acl_users', 'portal_resources', 'portal_registry', 'HTTPCache', 'RAMCache', 'ResourceRegistryCache', 'training', 'schedule', 'location', 'sponsors', 'sprint']
->>> app['Plone']['news']
-<Folder at /Plone/news>
+>>> portal.keys()
+['portal_setup', 'MailHost', 'caching_policy_manager', 'content_type_registry', 'error_log', 'plone_utils', 'portal_actions', 'portal_catalog', 'portal_controlpanel', 'portal_diff', 'portal_groupdata', 'portal_groups', 'portal_memberdata', 'portal_membership', 'portal_migration', 'portal_password_reset', 'portal_properties', 'portal_registration', 'portal_skins', 'portal_types', 'portal_uidannotation', 'portal_uidgenerator', 'portal_uidhandler', 'portal_url', 'portal_view_customizations', 'portal_workflow', 'translation_service', 'mimetypes_registry', 'portal_transforms', 'portal_archivist', 'portal_historiesstorage', 'portal_historyidhandler', 'portal_modifier', 'portal_purgepolicy', 'portal_referencefactories', 'portal_repository', 'acl_users', 'portal_resources', 'portal_registry', 'HTTPCache', 'RAMCache', 'ResourceRegistryCache', 'talks', 'sponsors']
+>>> app['Plone']['talks']
+<Folder at /Plone/talks>
+>>> app.Plone.talks
+<FolderishDocument at /Plone/talks>
 ```
 
 
@@ -247,14 +257,13 @@ You have been warned.
 
 - Create a new BrowserView callable as `/@@demo_content` in a new file {file}`demo.py`.
 - The view should create five talks each time it is called.
-- Use the docs at {doc}`plone6docs:plone.api/content` to find out how to create new talks.
-- Use `plone.api.content.transition` to publish all new talks. Find the docs for that method.
+- Use the documentation at {doc}`plone6docs:plone.api/content` to find out how to create new talks.
+- Use `plone.api.content.transition` to publish all new talks. Find the documentation for this method.
 - Only managers should be able to use the view (the permission is called `cmf.ManagePortal`).
-- Switch to the frontpage after calling the view.
 - Display a message about the results (see {ref}`plone6docs:portal-show-message-example`).
 - For extra credits use the library [requests](https://requests.readthedocs.io/en/latest/) and [Wikipedia](https://www.mediawiki.org/wiki/Wikimedia_REST_API) to populate the talks with content.
 - Use the utility methods `cropText` from `Producs.CMFPlone` to crop the title after 20 characters.
-  Use the docs at {doc}`plone6docs:backend/global-utils` to find an overview of `plone_view` helpers.
+  Use the documentation at {doc}`plone6docs:backend/global-utils` to find an overview of `plone_view` helpers.
 
 ```{note}
 - Do not try everything at once, work in small iterations, restart your Plone instance to check your results frequently.

diff --git a/docs/mastering-plone/behaviors_1.md b/docs/mastering-plone/behaviors_1.md
@@ -11,25 +11,20 @@ myst:
 
 # Behaviors
 
-````{sidebar} Plone Backend Chapter
-
-Get the code! ({doc}`More info <code>`)
-
-Code for the beginning of this chapter:
+Enhance content types to be selectable for presentation on the front page.
 
-```shell
-git checkout talks
-```
+````{card} Backend chapter
 
-Code for the end of this chapter:
+Get the code: https://github.com/collective/ploneconf.site
 
 ```shell
 git checkout behaviors_1
 ```
-````
 
-Enhance content types to be selectable for presentation on the front page.
+More info in {doc}`code`
+````
 
+```{card}
 In this part you will:
 
 - Add a field to talks and other content types by using a behavior
@@ -39,6 +34,7 @@ Topics covered:
 
 - Behaviors
 - Catalog indexes and catalog metadata columns
+```
 
 ```{only} not presentation
 A first approach would be to extend the functionality of a content type by writing an adapter that adapts an object of this type to add an additional attribute or feature.

diff --git a/docs/mastering-plone/code.md b/docs/mastering-plone/code.md
@@ -7,12 +7,17 @@ myst:
     "keywords": ""
 ---
 
+(code-label)=
+
 # The code for the training
 
 You can get the complete code for this training from GitHub.
 - The backend add-on [ploneconf.site](https://github.com/collective/ploneconf.site)
 - The frontend Volto app [volto-ploneconf](https://github.com/collective/volto-ploneconf)
 
+The backend add-on is included in the backend setup of [Training setup Mastering Plone Development](https://github.com/collective/training_buildout).
+See chapter {ref}`installation-install-backend-label`.
+
 Further add-ons are build or used while stepping through advanced training chapters.
 For the sake of completion we are mentioning them here.
 There is no need to check them out as they are dependencies in backend or frontend.
@@ -83,40 +88,40 @@ This does two things:
 These are the tags of the backend add-on for which there is code:
 
 
-| Chapter                        | Tag-Name                 |
-| ------------------------------ | ------------------------ |
+| Chapter                        | Tag-Name                 | Package |
+| ------------------------------ | ------------------------ | --- |
 | {doc}`about_mastering` | |
 | {doc}`intro` | |
 | {doc}`case` | |
 | {doc}`what_is_plone` | |
 | {doc}`installation` | |
 | {doc}`features` | |
 | {doc}`configuring_customizing` | |
-| {doc}`volto_overrides` | |
-| {doc}`extending` | |
 | {doc}`add-ons` | |
-| {doc}`eggs1` | initial |
+| {doc}`extending` | |
 | {doc}`dexterity` | |
-| {doc}`dexterity_2_talk` | talks |
-| {doc}`volto_development` | |
-| {doc}`volto_talkview` | |
-| {doc}`behaviors_1` | behaviors_1 |
-| {doc}`volto_frontpage` | |
+| {doc}`dexterity_2_talk` | |
+| {doc}`dexterity_reference` | |
+| {doc}`volto_overrides` | overrides | volto-ploneconf |
+| {doc}`volto_talkview` | talkview | volto-ploneconf |
+| {doc}`volto_development` | 
+| {doc}`behaviors_1` | behaviors_1 | ploneconf.site |
+| {doc}`volto_frontpage` | frontpage | ploneconf.site |
 | {doc}`api` | |
-| {doc}`events` | event |
-| {doc}`registry` | registry |
+| {doc}`events` | base | ploneconf.site |
+| {doc}`registry` | vocabularies | ploneconf.site |
 | {doc}`custom_search` | |
-| {doc}`upgrade_steps` | upgrade_steps |
 | {doc}`volto_testing` | |
 | {doc}`thirdparty_behaviors` | |
-| {doc}`dexterity_3` | dexterity_3 |
+| {doc}`dexterity_3` |
+| {doc}`upgrade_steps` |
 | {doc}`volto_components_sponsors` | |
 | {doc}`volto_addon` | |
 | {doc}`volto_custom_addon` | |
 | {doc}`volto_custom_addon2` | |
 | {doc}`user_generated_content` | |
-| {doc}`relations` | |
-| {doc}`voting-story/index` | |
+| {doc}`relations` | relations |
+| {doc}`voting-story/index` | | training.votable, volto-training-votable |
 | {doc}`deployment_code` | |
 | {doc}`code` | |
 | {doc}`trainer` | |

diff --git a/docs/mastering-plone/custom_search.md b/docs/mastering-plone/custom_search.md
@@ -11,11 +11,9 @@ myst:
 
 # Custom Search
 
-## Custom Search in Volto
+Volto has a search block that allows you to build custom searches without additional addons.
 
-Volto has (since Volto 14) a search block that allows you to build custom searches without additional addons.
-
-### Exercise
+## Exercise
 
 Show talks on the talks page with a search block.
 The visitor should see a filter for the type of talk (Keynote, Talk, Lightning Talk).
@@ -29,8 +27,8 @@ Remember what we did to show featured content on the front page.
 :animate: fade-in-slide-down
 :icon: question
 
-- The field "type_of_talk" needs to be indexed in catalog.
-- "type_of_talk" needs to be a collection criterion
+- The field `type_of_talk` needs to be indexed in catalog.
+- `type_of_talk` needs to be a collection criterion.
 
 After adding an index and a criterion, and restarting the backend, and re-installing the add-on, the index is present in catalog but empty.
 
@@ -74,52 +72,3 @@ Check the entries by switching to "Browse" button.
 ```
 
 ````
-
-## Custom Search in Plone Classic
-
-If the Plone Classic chapters about Views ({doc}`/mastering-plone/views_2`) and catalog-searches (({doc}`/mastering-plone/views_3`)) seem complex, the custom search add-ons shown below might be a great alternative until you feel comfortable writing views and templates.
-
-Here are two add-ons that allow you to add custom searches and content listings through the web ("TTW", requiring no programming: only the web browser) in Plone.
-
-(customsearch-eea-label)=
-
-### eea.facetednavigation
-
-eea.facetednavigation is a full-featured and a very powerful add-on to improve search within large collections of items.
-No programming skills are required to configure it since the configuration is done TTW.
-
-It lets you gradually select and explore different facets (metadata/properties) of the site content and narrow down you search quickly
-and dynamically.
-
-- Install [eea.facetednavigation](https://pypi.org/project/eea.facetednavigation/)
-
-- Enable it on a new folder "Discover talks" by clicking on {guilabel}`Actions > Enable faceted navigation`.
-
-- Click on the {guilabel}`Faceted > Configure` to configure it TTW.
-
-  > - Select 'Talk' for _Portal type_, hide _Results per page_
-  > - Add a checkboxes widget to the left and use the catalog index _Audience_ for it.
-  > - Add a select widget for speaker
-  > - Add a radio widget for type_of_talk
-
-Examples:
-
-- <https://www.dipf.de/en/research/current-projects>
-- <https://www.mountaineers.org/courses/courses-clinics-seminars>
-- <https://www.dyna-jet.com/highpressurecleaner>
-
-```{seealso}
-We use the new catalog indexes to provide the data for the widgets and search the results.
-For other use cases we could also use either the built-in vocabularies (<https://pypi.org/project/plone.app.vocabularies>) or create custom vocabularies for this.
-
-- Custom vocabularies TTW using [collective.taxonomy](https://pypi.org/project/collective.taxonomy)
-- Programming using Vocabularies: <https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/vocabularies.html>
-```
-
-### collective.collectionfilter
-
-A more lightweight solution for custom searches and faceted navigation is [collective.collectionfilter](https://pypi.org/project/collective.collectionfilter).
-By default it allows you to search among the results of a collection and/or filter the results by keywords, author or type.
-
-It can also be extended quite easily to allow additional filters (like `audience`).
-