Merge branch '6-dev' into behaviors

Author: jensens

docs/_static/backend/control-panel-action-edit-settings.png

@@ -1,13 +1,138 @@
 ---
 myst:
   html_meta:
-    "description": ""
-    "property=og:description": ""
-    "property=og:title": ""
-    "keywords": ""
+    "description": "Actions are links or buttons that allow users to perform specific actions on your site."
+    "property=og:description": "Actions are links or buttons that allow users to perform specific actions on your site."
+    "property=og:title": "Portal Actions"
+    "keywords": "Portal Actions, actions, Plone, backend"
 ---
 
 (backend-portal-actions-label)=
 
 # Portal Actions
 
+Actions are links or buttons that allow users to perform specific actions on your site.
+These actions can be anything from viewing a content item to editing a page, to accessing a specific feature of your site.
+
+```{note}
+Actions in Plone are provided by action providers.
+There are at least two providers for actions.
+
+-   Portal actions, provided by the actions tool named `portal_actions` in the ZMI
+-   Content type actions defined by the Factory Type Information (FTI) of the Types Tool, and named `portal_types` in the ZMI
+
+Here only the portal actions are described.
+```
+
+Portal actions are typically displayed in the site's navigation menu or toolbar and can be accessed by users with the appropriate permissions.
+
+Portal actions are managed using the {guilabel}`Portal Actions` control panel in Plone.
+This control panel allows you to add, edit, and delete actions, as well as organize them into categories and control where they are available on your site.
+
+```{note}
+We use the terms "Portal actions" and "Actions" in this documentation to mean the same thing.
+```
+
+## Anatomy of a Portal action
+
+A portal action in Plone consists of a few settings, including the category, title, description, URL, and control parameters.
+
+The action {guilabel}`Title` is the text that is displayed for the action in the site's navigation menu or toolbar.
+This text should be descriptive and indicate what the action does.
+The {guilabel}`Description` is used as an additional text shown when hovering over the link.
+The {guilabel}`Title` and {guilabel}`Description` can be translated using the translation system of Plone.
+Therefore the {guilabel}`I18n domain` can be set here.
+
+The {guilabel}`Action URL` is the address of the page or feature that the action will access when it is clicked.
+This can be an internal page on your site or an external page on another website.
+
+The {guilabel}`Condition` controls whether to show the action or not.
+
+You can use expressions in the URL of an action to make the action more dynamic and flexible.
+Expressions are also used for the {guilabel}`Condition`.
+
+The {guilabel}`Permissions` chosen also control the visibility of an action.
+
+The {guilabel}`Visible?` setting can be used to show or hide actions.
+This can be handy to disable default actions or temporarily disable actions.
+
+The {guilabel}`Position` setting is used to order actions within their category, and is numbered starting with `1`.
+
+Together, these components make up a portal action in Plone.
+
+You can use the {guilabel}`Portal actions` control panel to manage and organize your site's actions.
+
+## Action categories
+
+Several action categories are used for different purposes.
+These categories include:
+
+Object Actions
+: Actions that are available when viewing a specific content item.
+
+Object Buttons
+: Actions that are displayed as buttons when viewing a specific content item.
+
+Portal Tabs
+: Actions that are displayed as tabs on the top of the page.
+
+Site Actions
+: Actions that are available on every page of your site.
+
+User Actions
+: Actions that are available to users when they are logged in to your site.
+
+Each of these action categories serves a different purpose and is intended for use in specific areas of the site.
+For example, object actions are intended for actions that are specific to a particular content item, while site actions are intended for actions that are available on every page of your site.
+
+## Expressions
+
+An expression is a piece of code that is evaluated at runtime and can be used to insert dynamic values into the URL or provide the decision for the condition.
+
+```{todo}
+Contribute to this documentation!
+A chapter about expressions is missing. As soon as it exists a link to this chapter needs to be placed here.
+See issue [Backend > missing chapter Expressions needs content](https://github.com/plone/documentation/issues/1370).
+```
+
+## Adding or editing portal actions
+
+To add or edit portal actions, you can use the {guilabel}`Portal actions` control panel.
+To access this, log in to your Plone site as a user with the appropriate permissions.
+Then select the menu item {menuselection}`[username] > Site Setup`.
+From there, click on the {guilabel}`Actions` link in the {guilabel}`General` section.
+You can also select {menuselection}`General > Actions` from the Site Setup or any other control panel.
+
+Once you are on the {guilabel}`Portal actions` control panel, you will see a list of all the existing portal actions for your site.
+To inspect or edit an existing action's settings, click its {guilabel}`Edit` button.
+
+```{image} /_static/backend/control-panel-action-edit-settings.png
+:alt: Action Settings editing interface
+```
+
+To add a new action, click on the {guilabel}`Add new action` button at the top of the page.
+This will open a form where you can select its category and enter an arbitrary ID.
+Click the {guilabel}`Add` button to add the action.
+The new action should now appear in the actions listing under the selected category.
+You can now edit its settings by clicking its {guilabel}`Edit` button.
+
+It's important to note that the ability to add or edit portal actions is only available to users with the appropriate permissions.
+If you do not have the necessary permissions, you will not be able to access the {guilabel}`Portal actions` control panel.
+
+## Exporting or importing portal actions
+
+You can export action configuration to XML using the built-in Generic Setup Tool export.
+
+Then this XML can be imported again within a profile of an add-on package.
+Place the file as `actions.xml` in the profile of an add-on.
+You can cut out snippets from this file for creating `actions.xml` containing only changed or added parts.
+
+To export all actions:
+
+- Go to {guilabel}`Site Setup` and choose {guilabel}`Management Interface`.
+  You can also select {menuselection}`Advanced > Management Interface` from the Site Setup or any control panel.
+- Click {guilabel}`portal_setup`.
+- Click the tab {guilabel}`Export`.
+- Tick the checkbox {guilabel}`Actions Providers`.
+- Click the button {guilabel}`Export selected steps` at the end of the page.
+

docs/backend/portal-actions.md

@@ -9,64 +9,122 @@ myst:
 
 (overview-label)=
 
+
 # Overview
 
-````{todo}
-This page needs content.
-```{seealso}
-[Issue #1352](https://github.com/plone/documentation/issues/1352)
-```
-````
+Plone is a content management system (CMS) that is well-known for its user-friendly interface and robust security features. 
+With Plone, even non-technical users can easily create and manage the content for a public website or intranet using only a web browser. 
+Plone's intuitive interface and comprehensive set of features make it a popular choice for businesses, governments, universities, and any organization that needs a reliable and easy-to-use CMS.
+
+Plone has a long history and has been trusted by users around the world since its initial release on October 4, 2001. 
+Over the years, Plone has undergone many improvements and enhancements, making it a highly mature and stable CMS. 
+Additionally, Plone is supported by a strong community of users and developers who contribute to its ongoing success.
+
+Plone has the maturity, stability, and reliability of an application maintained by open source developers with decades of experience, while continually evolving and adapting to modern technology.
 
-(overview-2-label)=
+Lots of customizations can be made through-the-web, such as creating content types, themes, workflows, and much more.
+A full file system based development workflow is possible and recommended for team work and deployment, backed by source code repositories.
+Plone can be extended and used as a framework on which to build custom CMS-like solutions.
 
-## Key concepts of Plone
+Plone works as a:
 
+- Full-featured server-side rendered HTML CMS.
+- React-based frontend for editing and viewing content, backed by a server with a REST API.
+- Headless CMS server with a REST API, allowing a developer to build a custom frontend with their chosen technology.
 
 (overview-3-label)=
 
-### Web content management system
+## Key benefits
 
+Security is built into Plone's architecture from the ground up.
+Plone offers fine-grained permission control over content and actions.
 
-(overview-4-label)=
+Plone is easy to set up compared to other CMSs in its category, extremely flexible, and provides you with a system for managing web content that is ideal for project groups, communities, websites, extranets, and intranets.
 
-### Add-ons
+- **Plone empowers content editors and web application developers.**
+  The Plone Team includes usability experts who have made Plone easy and attractive for content managers to add, update, and maintain content.
 
+- **Plone is international.**
+  The Plone interface has more than 35 translations, and tools exist for managing multilingual content.
 
-(overview-5-label)=
+- **Plone follows standards and is inclusive.**
+  Plone carefully follows standards for usability and accessibility.
+  Plone is compliant with WCAG 2.1 level AA and aims for ATAG 2.0 level AA.
 
-### Traditional server side rendered HTML pages
+- **Plone is open source.**
+  Plone is licensed under the GNU General Public License, the same license used by Linux.
+  This gives you the right to use Plone without a license fee, and to improve upon the product.
 
+- **Plone is supported.**
+  There are over two hundred active developers in the Plone Development Team around the world, and a multitude of companies that specialize in Plone development and support.
 
-(overview-6-label)=
+- **Plone is extensible.**
+  There is a multitude of add-on products for Plone to add new features and content types.
+  In addition, Plone can be scripted using web standard solutions and open source languages.
 
-### Headless CMS with JavaScript frontend through a REST API
+- **Plone is technology neutral.**
+  Plone can interoperate with most relational database systems—both open source and commercial—and runs on many platforms, including Linux, Windows, macOS, and BSD.
 
 
-(overview-7-label)=
 
-### Explain frontend-backend terms
+(overview-4-label)=
 
+## High Level Overview for Developers
 
-(overview-8-label)=
+Plone is a content management platform with its backend written in Python.
+It is built on top of the open source Zope web application server and development system. 
+Plone makes use of the pluggable Zope Component Architecture (ZCA) to provide a highly modular and extensible system.
+Throughout its history, Plone has used server-side rendering to generate HTML-based content, with advanced resource management features for adding and bundling CSS and JavaScript. 
+Additionally, Plone's use of a component architecture makes it easy to extend and customize, allowing users to create unique, feature rich websites that are tailored to their specific needs.
 
-### Security
+With the release of Plone 6, you now have the option to choose from two different out-of-the-box supported configurations when setting up a new Plone website.
+The Python-based backend server in Plone can still be used alone to render content server-side and deliver HTML to the browser, a setup that is referred to in the Plone documentation as "Classic UI". 
+This configuration has been supported by Plone since its initial release and is still available in the latest version of the platform.
+For container-based deployment, only the `plone-backend` image is required.
+It may be used as a base image, adding customizations, to make a derivative image.
 
+The default and recommended configuration for new websites in Plone is the new React-based JavaScript frontend called "Volto".
+For this setup you still need to run the Python-based backend server, as well as enable the REST API, and update the configuration profile.
+These settings and profile are applied automatically when you select the {guilabel}`Create Plone Site` option in the Plone website creation form.
+In addition a separate NodeJS based frontend server will serve the JavaScript frontend resources and provide SSR with hydration.
+To deploy this setup using containers, you will need the `plone-frontend` image for the frontend server.
 
-(overview-9-label)=
+Beginning with Plone 6, we now support two programming language stacks, one each for Python and JavaScript.
+The documentation has been rewritten, but for this first release you will find some repetition of concepts in the documentation structure.
+See, for example, the development setup and information on deployment options.
+It will take some time until we find and can implement the best structure to explain these new possibilities and the expansion of Plone's capabilities.
+
+```{seealso}
+https://training.plone.org/mastering-plone/what_is_plone.html
+```
 
-### Accessibility (a11y)
 
+(overview-5-label)=
+## Deployment
 
-(overview-10-label)=
+To run a public Plone website in production, you will also need to configure and run a reverse proxy (or ingress), arrange for SSL certificates (either from Let's Encrypt or manually), guarantee persistence of the content database, and arrange backups.
+This is the domain of systems administrators and modern developer-operations professionals.
+Our documentation contains setup examples for these services, yet requires that the reader have some generic experience and knowledge of these domains.
 
-### Internationalization (i18n)
 
+(overview-6-label)=
+## Good to know / What to know
+
+One of the key benefits of the new React-based frontend for Plone 6 is that you can now customize and theme Plone extensively using HTML, CSS, and JavaScript using up-to-date frontend technologies without having to set up a local Python development environment.
+The Plone backend can be run on a local developer machine in a container.
+
+Basic familiarity with programming in Python and managing Python modules and packages using `virtualenv` and `pip` is required to work on the backend code.
+We use `virtualenv` and {term}`mxdev` to manage the source installation of packages in Plone 6.
+
+Similarly, to develop for the new React frontend, you need to have some experience with setting up NodeJS, using a tool like NVM (Node Version Manager) to isolate your setup, and familiarity with {term}`Yarn` and {term}`React`.
+
+If you are looking for more study material on these technologies beyond the documentation, see and follow one or more [Plone Trainings](https://training.plone.org).
+Our trainings are more verbose and contain extra clarification and examples.
 
 
 ```{toctree}
 :maxdepth: 2
 :hidden:
 
-history
+
 ```