|
| 1 | +--- |
| 2 | +html_meta: |
| 3 | + "description": "Migrate to Volto" |
| 4 | + "property=og:description": "Migrate to Volto" |
| 5 | + "property=og:title": "Migrate to Volto" |
| 6 | + "keywords": "Migrating, Upgrading, Plone 6, Volto" |
| 7 | +--- |
| 8 | + |
| 9 | +(backend-migrate-to-volto-label)= |
| 10 | + |
| 11 | +# Migrate to Volto |
| 12 | + |
| 13 | +Plone 6 comes with a new default frontend called {term}`Volto`. |
| 14 | +Volto is written in React and uses {py:mod}`plone.restapi` to communicate with the backend. |
| 15 | + |
| 16 | +When creating a new Plone 6 site, you may choose between frontends. |
| 17 | + |
| 18 | +- Volto - {guilabel}`Create a new Plone site`, the default option |
| 19 | +- {term}`Classic UI` - {guilabel}`Create Classic Plone site` |
| 20 | +- {guilabel}`Advanced` |
| 21 | + |
| 22 | +This choice is presented because there are some non-trivial differences between their configurations. |
| 23 | +This document discusses these differences. |
| 24 | +It also informs administrators and developers of how to migrate their existing Plone 6 site with Classic UI to instead become compatible with Volto for its frontend. |
| 25 | + |
| 26 | +```{important} |
| 27 | +As a pre-requisite, your Plone site must be [upgraded to Plone 6](v60) before migrating to Volto for the frontend. |
| 28 | +``` |
| 29 | + |
| 30 | +Plone provides a form `/@@migrate_to_volto` that allows you to run all the required changes to your existing site to make it compatible with Volto. |
| 31 | + |
| 32 | +You can access this form in the browser when you are logged in as an administrator. |
| 33 | +Open `http://localhost:8080/Plone/@@migrate_to_volto`, where `localhost` is your hostname, `8080` is the port on which Plone runs, and `Plone` is the name of the Plone instance. |
| 34 | + |
| 35 | +Additionally, after upgrading an existing site to Plone 6 (see {doc}`v60`), a message will appear, **You can prepare your site for Volto, the default frontend of Plone 6!**, with a link to that form. |
| 36 | + |
| 37 | +```{warning} |
| 38 | +Test all migrations thoroughly before applying them on a production environment! |
| 39 | +
|
| 40 | +A site that is made compatible with Volto will be accessible with Plone Classic UI, but it will behave differently. |
| 41 | +For example, editors can only effectively work with the content using Volto because HTML is no longer editable in the TinyMCE editor used in Classic UI. |
| 42 | +``` |
| 43 | + |
| 44 | +The required steps are: |
| 45 | + |
| 46 | +1. **Install the packages {py:mod}`plone.volto` and {py:mod}`plone.restapi`.** |
| 47 | + |
| 48 | + {py:mod}`plone.restapi` is the RESTful API for Plone that allows the frontend Volto to communicate with the backend. |
| 49 | + {py:mod}`plone.volto` configures Plone to work with Volto, the new default frontend for Plone 6. |
| 50 | + |
| 51 | +1. **Migrate RichText fields to Volto blocks** |
| 52 | + |
| 53 | + Volto has a new editor called Slate, whereas Classic UI uses TinyMCE. |
| 54 | + This step converts the HTML stored in RichText fields to text blocks, allowing you to edit them in Volto. |
| 55 | + Images, links, and most kinds of HTML formatting are preserved. |
| 56 | + |
| 57 | + For this you need to have `blocks-conversion-tool` running on an accessible URL. |
| 58 | + The easiest way to have that running on your machine is to use Docker: |
| 59 | + |
| 60 | + ```shell |
| 61 | + docker run -it -p 5000:5000 plone/blocks-conversion-tool:latest |
| 62 | + ``` |
| 63 | + |
| 64 | + For more options read https://github.com/plone/blocks-conversion-tool. |
| 65 | + |
| 66 | +1. **Pages, News Items, and Events are made folderish** |
| 67 | + |
| 68 | + That means these types can contain other content such as Images or other Pages. |
| 69 | + When you create a new site in Plone 6, this setting is also applied automatically. |
| 70 | + But existing content remains non-folderish until this step is run. |
| 71 | + |
| 72 | +1. **Turn folders into folderish pages** |
| 73 | + |
| 74 | + In Volto adding Folders is disabled by default. |
| 75 | + Instead folderish pages are used to create folder structures. |
| 76 | + This step turns all folders into folderish pages. |
| 77 | + If the folder shows a listing of the content, an appropriate listing block will be added. |
| 78 | + If the folder shows a default page, then it will be handled in the next step. |
| 79 | + You can re-enable Folders by checking the box {guilabel}`Implicitly addable?` in ``/portal_types/Folder/manage_propertiesForm``. |
| 80 | + |
| 81 | +1. **Default Pages of Folders are merged with the Folderish Pages that replace the Folder** |
| 82 | + |
| 83 | + Volto does not have a concept of default pages. |
| 84 | + Instead folderish pages can show text, a listing of all the content inside that page, or both. |
| 85 | + This step takes the content of the default page (such as text or the query of a collection), and adds that to the folderish page that replaces the folder. |
| 86 | + Metadata (subjects, author, rights, and so on) and relations are moved to the folderish page. |
| 87 | + |
| 88 | + |
| 89 | +1. **Collections are migrated to Pages with Listing Blocks** |
| 90 | + |
| 91 | + In Volto adding Collections is disabled by default. |
| 92 | + Instead folderish pages with listing blocks are used. |
| 93 | + This step turns all collections into folderish pages. |
| 94 | + The criteria of the collection are used to configure a listing block in that page. |
| 95 | + |
| 96 | +It is recommended to use the default settings, but you can choose to skip some migration steps in the form. |
| 97 | + |
| 98 | +```{note} |
| 99 | +If you are migrating an existing site to Plone 6 using [{py:mod}`collective.exportimport`](https://pypi.org/project/collective.exportimport) and want to use Volto in the new site, then you do not need to use the form `@@migrate_to_volto`. |
| 100 | +
|
| 101 | +All the changes documented above can be done efficiently during export and import. |
| 102 | +[Read details](https://github.com/collective/collective.exportimport/issues/133). |
| 103 | +``` |
0 commit comments