Editing your project#

There are some changes possible in the project without writing code by just editing the configuration. A popular change is adding an add-on.

About Add-ons#

Both Plone Frontend and Plone Backend allow adding add-ons. Depending on the add-on, it could apply to only one of Plone Backend or Plone Frontend, or both working together. If the latter is the case, then these would be two different components.

Plone Frontend add-ons are written in JavaScript and are released as NPM packages. The Plone community maintains a curated list of Plone Frontend add-ons named Awesome Volto.

Plone Backend add-ons are written in Python and are released on the Python Package Index (PyPI). The Plone community maintains a curated list of Plone Backend and Plone Classic UI add-ons named Awesome Plone.

Starting the servers#

After a new project was created, let's check that everything runs as expected.

Frontend#

In a terminal, run the following code to start the frontend server:

make start-frontend

After a while you should see:

yarn run v1.22.19
$ razzle start
 WAIT  Compiling...


✔ Client
  Compiled successfully in 620.55ms

✔ Server
  Compiled successfully in 25.64s

✅  Server-side HMR Enabled!
sswp> Handling Hot Module Reloading
Volto is running in SEAMLESS mode
Using internal proxy: http://localhost:3000 -> http://localhost:8080/Plone
🎭 Volto started at 0.0.0.0:3000 🚀

Backend#

In a second terminal, run the following code to start the backend server:

make start-backend

After a while you should see:

INFO    [waitress:486][MainThread] Serving on http://0.0.0.0:8080

Check local access#

Visit the Plone site at the following URL:

http://plone-conference.localhost:3000

Stopping the servers#

In both terminals, press Ctrl-C.

Add OAuth support#

As an example of adding an add-on for this training, we will add a new authentication method, login with GitHub.

We will do this twice: once for Classic UI, and again for Volto.

Important

You should use two web browsers, one for logging in as an Administrator and the other for logging in as your GitHub username via OAuth. Always stay logged in as an Administrator in your primary web browser, and use your secondary web browser for OAuth authentication.

Create a GitHub OAuth application#

Both Plone user interfaces require the creation of a GitHub OAuth application. Follow the GitHub documentation Creating an OAuth App.

You can configure the GitHub OAuth application to use only one Plone user interface at a time, but you can switch back and forth by changing the values. We will start with Classic UI configuration. After we get OAuth via GitHub working in Classic UI, we will switch to Volto.

Classic UI GitHub OAuth app configuration#

Use the following values when creating your GitHub OAuth application.

Application name: plone-conference
Homepage URL: http://localhost:8080/Plone
Application description: Plone Conference
Authorization callback URL: http://localhost:8080/Plone/authomatic-handler/

Get your GitHub client ID and secret#

After creating the GitHub OAuth application, you will have a client ID. Save this for the next section Activate and configure the add-on, where its value will be used for the consumer_key.

Now you can generate a client secret by clicking Generate a client secret. Save this for the next section Activate and configure the add-on, where its value will be used for the consumer_secret.

These two values will work for both Plone user interfaces.

Install `pas.plugins.authomatic` add-on#

Go to the folder backend.

Open the file requirements.txt, and append pas.plugins.authomatic. This installs the package, too, when installing Plone.

Edit the file instance.yaml. There is a line package_includes: ['plone_conference']. This loads the package configuration when starting Plone Backend. Append pas.plugins.authomatic to the array. Afterward it should look like the following:

default_context:
    initial_user_name: 'admin'
    initial_user_password: 'admin'

    load_zcml:
        package_includes: ['plone_conference', 'pas.plugins.authomatic']

    db_storage: direct

To activate the settings, run make build-backend in the root folder of the project.

Finally, restart the backend with make start-backend.

Activate and configure the add-on#

In your primary browser, login to Plone Classic UI as Administrator at http://localhost:8080/Plone/login/.

At the bottom of the menu on the left, choose admin > Site Setup. Select the Add-ons control panel. Then install pas.plugins.authomatic by clicking the Install button for Authomatic PAS Plugin.

Now configure the plugin by adding the GitHub configuration as JSON. Navigate to Users > Authomatic (OAuth2/OpenID) from anywhere in the Site Setup.

Copy the following JSON configuration, and replace the two values from GitHub. The client ID will be the value for consumer_key. The client secret will be the value for consumer_secret. Replace the existing JSON configuration in the control panel with your new configuration.

{
    "github": {
        "display": {
            "title": "GitHub",
            "cssclasses": {
                "button": "btn btn-default",
                "icon": "glypicon glyphicon-github"
            },
            "as_form": false
        },
        "propertymap": {
            "email": "email",
            "link": "home_page",
            "location": "location",
            "name": "fullname",
            "picture": "avatar_url"
        },
        "class_": "authomatic.providers.oauth2.GitHub",
        "consumer_key": "KEYHERE",
        "consumer_secret": "SECRETHERE",
        "access_headers": {
            "User-Agent": "Plone (pas.plugins.authomatic)"
        }
    }
}

Click Save, and all is set. Test it in your secondary browser by visiting http://localhost:8080/Plone/login/. You should be prompted to log in with GitHub.

Configure the OAuth user permissions#

You can assign the OAuthed user to groups and grant permissions. This is useful if you expect this user to perform the same functions as an Administrator.

Back in the primary browser as Administrator, visit the control panel Users > Users. For the User name row, check appropriate permissions. For the purpose of this training, check Manager, then click Apply changes.

Change the GitHub OAuth application configuration for Volto#

Now that we have OAuth via GitHub working in Classic UI, let's switch to using Volto.

We can reuse the client ID and secret from Get your GitHub client ID and secret and that we entered into the pas.plugins.authomatic add-on's control panel configuration in Activate and configure the add-on as is.

We will repeat some of the above steps, but with a few differences.

Volto GitHub OAuth app configuration#

Following what we did previously in Classic UI GitHub OAuth app configuration, we will change two values, Homepage URL and Authorization callback URL. Use the following values.

Application name: plone-conference
Homepage URL: http://localhost:3000/
Application description: Plone Conference
Authorization callback URL: http://localhost:3000/login-authomatic

Click Update application to save the changes.

Install `volto-authomatic` add-on#

Go to the folder frontend, and edit the file package.json.

Append @plone-collective/volto-authomatic to the list addons.

"addons": [
  "@plone-collective/volto-authomatic"
],

Append the key/value pair "@plone-collective/volto-authomatic": "*" to the dictionary dependencies.

"dependencies": {
  "@plone-collective/volto-authomatic": "*"
}

To activate the settings, run make build-frontend in the root folder of the project.

Finally, restart the frontend with make start-frontend.