Ninja Party Manager

    @plone/volto

    16.0.0-rc.1 • Public • Published

    Volto

    Volto logo png

    Volto logo png

    NPM Unit Tests Acceptance Tests Build Status Docs

    Introduction

    Volto is a ReactJS-based frontend for the Plone Content Management System. It will become the default UI for the upcoming Plone 6 release.

    Plone is a CMS built on Python with more than 20 years of history and experience.

    Plone has very interesting features that appeal to developers and users alike, such as customizable content types, hierarchical URL object traversing and a sophisticated content workflow powered by a granular permissions model. This allows you to build anything from simple websites to enterprise-grade intranets.

    Volto exposes all these features and communicates with Plone via its REST API. Volto has the ability of being easily extensible, themeable, and customizable.

    It features the Pastanaga editor, a modern block-based content layout editor. It is extensible and customizable, so you can adapt the default blocks provided to match your requirements, or build new ones to cover them.

    Volto is extensible using add-ons. You can build your own or choose from the community released ones:

    Demo

    You can try a Volto online demo in https://6.demo.plone.org/

    Try the demo locally

    If you want to give Volto a quick try and you have Docker installed in your computer, bootstrap the demo using docker-compose:

    git clone https://github.com/plone/volto.git
    cd volto
    docker-compose up

    Go to http://localhost:3000 in your browser.

    Quick Start

    First get all the requirements installed on your system.

    Prerequisites

    UPDATE 2022-10-25: Since 2022-10-25, NodeJS 18 is in LTS state (https://github.com/nodejs/release#release-schedule). However, due to changes in internal SSL libraries, some Volto dependencies have been deprecated and need to be updated in order to continue working in NodeJS 18, mainly Webpack 4 (see: https://github.com/webpack/webpack/issues/14532#issuecomment-947525539 for further information). You can still use it, but NodeJS should be run under a special flag: NODE_OPTIONS=--openssl-legacy-provider. See also Volto's PR: https://github.com/plone/volto/pull/3699 for more information.

    The versions of Python that are supported in Volto depend on the version of Plone that you use.

    Plone Python Volto
    5.2 2.7, 3.6-3.8 15.0
    6.0 (beta) 3.8-3.10 16.0 (alpha)

    At the time of this writing, Volto 16 is still in alpha status, and Plone 6 is in beta status.

    Create a Volto project using the generator

    Create a new Volto project by using the @plone/generator-volto utility.

    It will bootstrap a Volto project in a folder of your choice with all the required boilerplate to start customizing your Volto site.

    npm install -g yo @plone/generator-volto
    yo @plone/volto
    

    follow the prompts questions, provide myvoltoproject as project name then, when it finishes:

    cd myvoltoproject
    

    Bootstrap the Plone API backend

    You can bootstrap a ready Docker Plone container with all the dependencies and ready for Volto use. We recommend to use the Plone docker builds based in pip plone/plone-backend image:

    docker run -it --rm --name=plone -p 8080:8080 -e SITE=Plone -e PROFILES="plone.volto:default-homepage" plone/plone-backend:6.0.0b3

    or as an alternative if you have experience with Plone and you have all the dependencies installed on your system, you can use the supplied convenience buildout in the api folder by issuing the command:

    make build-backend

    Recommended Plone version

    Volto is the default UI for Plone 6, so it will work for all Plone 6 released versions.

    For the Plone 5 series, the latest released version of Plone 5 (with Python 3) is recommended (at the time of writing 5.2.9).

    KGS (known good set of versions) for backend packages

    On Plone 6, we recommend using the known good set (KGS) of package versions that are specified in the Plone release.

    On Plone 5, Volto is currently tested with the following packages pinned to specific versions, and we recommend using the same versions, which are:

    • plone.restapi 8.30.0
    • plone.rest 2.0.0a5
    • plone.volto 4.0.0a13

    This would be the docker command to spawn a Plone 5 container with the right KGS versions:

    docker run -it --rm --name=plone -p 8080:8080 -e SITE=Plone -e ADDONS="plone.restapi==8.30.0 plone.volto==4.0.0a13 plone.rest==2.0.0a5 plone.app.iterate==4.0.2 plone.app.vocabularies==4.3.0" -e PROFILES="plone.volto:default-homepage" plone/plone-backend

    Start Volto

    yarn start

    Browsing

    Go to http://localhost:3000 in your browser.

    Volto in Production

    Volto is actively developed since 2017 and used in production since 2018 on the following websites:

    Please create a new issue or pull request to add your Volto-site here!

    Documentation

    You can find the latest (in-progress) documentation in https://6.dev-docs.plone.org/

    Training

    On the Plone Trainings Website you'll find Volto-dedicated open training materials, plus React and other JavaScript-centered trainings.

    Talks

    Plone Conference Ferrara 2019

    Víctor Fernández de Alba - Plone Beyond 2020: Jump into Volto today!

    Rob Gietema - How to create your own Volto site!

    Timo Stollenwerk - On the Road - Plone 6 and Beyond

    Rodrigo Ferreira de Souza - Data migration to Plone 5.2 and Volto

    Nicola Zambello - A Volto story: building a website by prototyping

    Luca Pisani - Plone and React.js: An interview to Volto

    Plone Conference Tokyo 2018

    Rob Gietema - Volto

    Rob Gietema / Víctor Fernández de Alba - Volto Extensibility Story

    Víctor Fernández de Alba - Theming Volto

    Timo Stollenwerk / Víctor Fernández de Alba / Ramon Navarro - Volto Case Studies

    Timo Stollenwerk - Reinventing Plone, Roadmap to the Modern Web

    Node Support

    • Node 16: Supported since Volto 14
    • Node 14: Supported since Volto 8.8.0
    • Node 12: Deprecated from Volto 16 onwards. It was supported since Volto 4
    • Node 10: Deprecated from Volto 13 onwards. It was supported since Volto 1 (and its predecessor "plone-react")

    Browser support

    Volto works well with any modern (evergreen) browser, including their mobile flavors: Chrome, Firefox, Safari, Edge.

    We do not guarantee that deprecated browsers (e.g., Internet Explorer 11) are supported by Volto. Although proven possible, it's too great an effort to maintain. It is left to the integrator to provide support for it.

    Upgrades

    You can find the upgrade guide here: https://6.dev-docs.plone.org/volto/upgrade-guide/index.html

    Volto Development

    For Volto development you need all the requirements already mentioned on the Quick Start section.

    Checkout the Volto repository

    git clone https://github.com/plone/volto.git

    Install dependencies

    yarn

    Install Plone backend

    Either using a Docker command:

    docker run -it --rm --name=plone -p 8080:8080 -e SITE=Plone -e PROFILES="plone.volto:default-homepage" plone/plone-backend:6.0.0b3

    or using the convenience makefile command:

    make start-backend-docker

    or running Plone on your machine (advanced), additional dependencies might be required, only for Plone experienced integrators/developers. Check the Plone Installation Documentation.

    make build-backend

    Run frontend

    Either using a Docker command:

    docker run -it --rm --name=volto --link backend -p 3000:3000 -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone plone/plone-frontend:latest

    or using the convenience makefile command:

    make start-frontend-docker

    or from the local repository code:

    yarn && yarn start

    Browsing

    Browse to http://localhost:3000 in your browser.

    Testing

    yarn test

    Releasing

    For ease the release process, we use release-it utility that helps with the process.

    https://www.npmjs.com/package/release-it

    For using it and start a release you need to fulfill the requirements:

    • Have permissions to push on master branch
    • Have permissions on the @plone org on npmjs.com
    • Have a environment variable (GITHUB_TOKEN) with a GitHub personal token with permissions to write the Volto Release page on GitHub (https://www.npmjs.com/package/release-it#github-releases)

    Then the command for release:

    yarn release

    a dry-release command for testing the output is also available:

    yarn dry-release

    and alpha release can also be cut using:

    yarn release-alpha

    Acceptance testing

    Here you can find a guide on how acceptance testing is done in Volto:

    https://6.dev-docs.plone.org/volto/developer-guidelines/acceptance-tests.html

    Translations

    If you would like contribute to translate Volto into several languages, please, read the Internationalization (i18n) guide.

    Contributors

    Alternative backends

    Volto also supports other APIs like Guillotina, a Python resource management system, inspired by Plone and using the same basic concepts like traversal, content types, and permissions model.

    Last but not least, it also supports a Volto Node.js-based backend reference API implementation that demos how other systems could also use Volto to display and create content through it.

    Run a Guillotina backend

    Disclaimer: Guillotina doesn't support the full API/features that Plone provides. Contributors are welcome.

    docker-compose -f g-api/docker-compose.yml up -d

    or using the convenience makefile command:

    make start-backend-docker-guillotina

    Running the acceptance tests with Guillotina backend

    If you want to use Guillotina as a backend to run the tests you should run:

    yarn ci:start-api-plone-guillotina

    License

    MIT License. Copyrights hold the Plone Foundation.

    See LICENSE.md for details.

    Install

    npm i @plone/volto@16.0.0-rc.1

    Homepage

    plone.org

    Version

    16.0.0-rc.1

    License

    MIT

    Unpacked Size

    16.2 MB

    Total Files

    1731

    Last publish

    Collaborators

    • mrtango
    • petschki
    • mauritsvanrees
    • thet
    • ericof
    • agitator
    • timostollenwerk
    • ramonnb
    • ebrehault
    • robgietema
    • sneridagh