From 3f214f7cce938e8cf367260b680a7558f198ec19 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sat, 2 Nov 2024 22:51:51 +0530 Subject: [PATCH] refactor: volto customization for JS beginners --- docs/volto_customization/blocks.md | 5 +- docs/volto_customization/custom_block.md | 8 +- docs/volto_customization/extending_teasers.md | 2 +- docs/volto_customization/installation.md | 270 +++++++++--------- docs/volto_customization/intro.md | 6 +- docs/volto_customization/schema.md | 2 +- 6 files changed, 150 insertions(+), 143 deletions(-) diff --git a/docs/volto_customization/blocks.md b/docs/volto_customization/blocks.md index e8f3f698c..33c4b26d6 100644 --- a/docs/volto_customization/blocks.md +++ b/docs/volto_customization/blocks.md @@ -21,7 +21,7 @@ Instead of shadowing components we can: Let us first change the View of the teaser block which we already have in volto core by changing the block-configuration. In our addon `volto-teaser-tutorial` we will step by step extend each component that we have in volto core. -The most simple customization is the View of the Teaser. The volto core teaser block configration (in `omelette/src/config/Blocks.jsx`) looks like: +The most simple customization is the View of the Teaser. The volto core teaser block configration (in `/frontend/core/packages/volto/src/config/Blocks.jsx`) looks like: ```js teaser: { @@ -62,10 +62,9 @@ export default applyConfig; ``` Of course we need to add our custom `MyTeaserView` component in our addon. -From the root of the project that is `src/addon/volto-teaser-tutorial/src/components/Blocks/Teaser/View.jsx`: +From the root of the project that is `packages/volto-teaser-tutorial/src/components/Blocks/Teaser/View.jsx`: ```jsx -import React from "react"; import TeaserBody from "@plone/volto/components/manage/Blocks/Teaser/Body"; import { withBlockExtensions } from "@plone/volto/helpers"; diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index bb8537822..bd484b699 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -9,9 +9,9 @@ myst: # Volto Weather Block (custom block) -Let's create a volto block that will display weather information for Eibar. For this we can use Open-Meteo API. Open-Meteo is an open-source weather API and offers free access for non-commercial use. No API key required. +Let's create a volto block that will display weather information for Brasilia. For this we can use Open-Meteo API. Open-Meteo is an open-source weather API and offers free access for non-commercial use. No API key required. -Creating a basic block in Volto involves several steps. Below, I'll outline the steps to create a Volto block that displays the weather forecast in Eibar. +Creating a basic block in Volto involves several steps. Below, I'll outline the steps to create a Volto block that displays the weather forecast in Brasilia. 1. **Setup Your Volto Project:** If you haven't already, set up a Volto project. You can use the instructions presented in [Installation -> Bootstrap a new Volto project](installation.md) section. @@ -47,7 +47,7 @@ export const weatherBlockSchema = (props) => { location: { title: "Location", description: - "Enter the name of the location for which you want to display the weather (e.g., Eibar, Basque Country).", + "Enter the name of the location for which you want to display the weather (e.g., Brasilia, Brazil).", widget: "text", }, }, @@ -65,7 +65,7 @@ import React, { useEffect, useState } from "react"; const View = (props) => { const { data = {} } = props; - const location = data.location || "Eibar, Basque Country"; + const location = data.location || "Brasilia, Brazil"; const [weatherData, setWeatherData] = useState(null); useEffect(() => { diff --git a/docs/volto_customization/extending_teasers.md b/docs/volto_customization/extending_teasers.md index c2339cb1c..108132020 100644 --- a/docs/volto_customization/extending_teasers.md +++ b/docs/volto_customization/extending_teasers.md @@ -7,7 +7,7 @@ myst: "keywords": "Volto, Block, Variations" --- -# Extending Teasers per type +# Extending Teasers per type(Advanced topic) The basic scenario is to add variations to a block so that it can give control over its look and feel. Sometimes its also possible for a need to have control over individual elements. For instance, Consider we have a teaaser grid in which we can have a base variation of its layout. Then we would left with styling and adjusting individual teasers. This is where extensions come into play. diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 128ebd9d5..9f1c64ded 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -19,191 +19,197 @@ Getting started with Volto involves setting up a development environment, unders Before you start working with Volto, ensure you have the following prerequisites: -- Node.js LTS (16.x) - (see instructions for installation) +- Node.js LTS (<=20.x) - (see instructions for installation) - Python - See below for specific versions. +- pipx +- nvm +- GNU make - Docker (if using the Plone docker images - see instructions for installation and usage) The versions of Python that are supported in Volto depend on the version of Plone that you use. | Plone | Python | Volto | | ----- | ------------ | ------------ | -| 6.0 | 3.8-3.11 | 16.0 or 17.0 | +| 6.0 | 3.8-3.12 | 17.0 or 18.0 | | 5.2 | 2.7, 3.6-3.8 | 15.0 | Depending on the operating system that you are using, some of the following pre-requisites might change. They assume you have a macOS/Linux machine. -## Bootstrap a new Volto project +### Python -To bootstrap a new Volto project, you can use Yeoman [@plone/generator-volto](https://github.com/plone/generator-volto). -First, install it as a global tool (see instructions for installation): +Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, pyenv, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -```shell -npm install -g yo -npm install -g @plone/generator-volto -``` +Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. + +### pipx -Then you can bootstrap the project with: +Install [pipx](https://pipx.pypa.io/stable/). ```shell -yo @plone/volto volto-tutorial-project +pip install pipx + ``` -The yo-based generator partially integrates add-ons (it can generate a -`package.json` with add-ons and workspaces already specified). When prompted -to add add-ons, choose `false`. +### Node.js -Now you can start your newly created Volto project: +1. Install or update the supported LTS versions of Node.js, then activate the version supported in Volto. -```shell -cd volto-tutorial-project -yarn start -``` + ```shell + nvm install --lts + nvm use --lts + ``` -You can then login with admin/admin at http://localhost:3000/login. +2. Verify that the supported version of Node.js is activated. + + ```shell + node -v + ``` + +### Make -## Bootstrap an add-on +`Make` comes installed on most Linux distributions. +On macOS, you must first [install Xcode](https://developer.apple.com/xcode/resources/), then install its command line tools. +On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), which will include `make`. -Let's start creating an add-on. We'll create a new package: -`volto-teaser-tutorial`. Inside your Volto project, bootstrap -the add-on by running (in the Volto project root): +Finally, it is a good idea to update your system's version of `make`, because some distributions, especially macOS, have an outdated version. +Use your favorite search engine or trusted online resource for how to update `make`. + +## Bootstrap a new Plone stack + +To bootstrap a new Plone project(with both backend and frontend), you can use [Cookieplone](https://github.com/plone/cookieplone). +You can use pipx to run cookieplone (see instructions for installation): ```shell -yo @plone/volto:addon +pipx run cookieplone tutorial-project ``` -Note: You can also use the namespace like `@plone-collective/volto-teaser-tutorial` (or any other) is not required and is -optional. We're using namespaces for scoped package under some organisation. +You will be presented with a series of prompts. You can also specify the addons you want to install along with the project. You can type `volto-teaser-tutorial` when prompted for the addons. -Use `volto-teaser-tutorial` as the package name. After the -scaffolding of the add-on completes, you can check the created files in -`src/addons/volto-teaser-tutorial`. +```shell +[11/17] Volto Addon Name (volto-project-title): volto-teaser-tutorial +``` -Back to the project, you can edit `jsconfig.json` and add your add-on: +You can accept the rest of the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. +For the training, we will use the default values for the rest of the prompts. -```json -{ - "compilerOptions": { - "baseUrl": "src", - "paths": { - "volto-teaser-tutorial": ["addons/volto-teaser-tutorial/src"] - } - } -} +```{tip} +See the cookiecutter's README for how to [Use options to avoid prompts](https://github.com/collective/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). ``` -```{note} -The `jsconfig.json` file is needed by Volto to identify development -packages. You are not strictly limited to Volto add-ons in its use, you -could, for example, use this to make it easier to debug third-party -JavaScript packages that are shipped transpiled. -``` +## Install the project -### Volto addon script +To work on your project, you need to install both the frontend and backend. -Alternatively, if you already have an addon pushed to a remote repository and you want to create a volto development stack with it, you can use our addon script to easily scaffold a dev environment without creating a project externally. +Change your current working directory to `tutorial-project`. ```shell -npx -p @plone/scripts addon clone [options] [destination] +cd tutorial-project ``` -This command downloads the volto-teaser-tutorial add-on from its git repository's main branch, and will generate a project with the latest Volto version. +To install both the Plone backend and frontend, use the following command. ```shell -npx -p @plone/scripts addon clone https://github.com/kitconcept/volto-teaser-tutorial.git --branch main +make install ``` -### (Optional) Use mrs-developer to sync add-on to GitHub +## Start Plone + +Plone 6 has two servers: one for the frontend, and one for the backend. +As such, we need to maintain two active shell sessions, one for each server, to start your Plone site. -You can also immediately push the package to GitHub, then use `[mrs-developer]` -to manage the package and `jsconfig.json` changes. +### Start Plone backend -Install mrs-developer as a development dependency by running: +In the currently open session, issue the following command. ```shell -yarn add -W -D mrs-developer +make backend-start ``` -Create a `mrs.developer.json` in your project with the following content (adjust it according -to your names and repository location): +The Plone backend server starts up and emits messages to the console. + +```console +2024-09-25 16:47:15,699 INFO [chameleon.config:39][MainThread] directory cache: //backend/instance/var/cache. +2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for //backend/instance/var/filestorage/Data.fs +2024-09-25 16:47:16,508 INFO [plone.restapi.patches:16][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. +2024-09-25 16:47:17,018 INFO [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes. +2024-09-25 16:47:17,760 INFO [Zope:42][MainThread] Ready to handle requests +Starting server in PID 20912. +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://[::1]:8080 +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080 +``` -```json -{ - "volto-teaser-tutorial": { - "url": "https://github.com//volto-teaser-tutorial.git", - "path": "src", - "package": "volto-teaser-tutorial", - "branch": "main" - } -} +### Start Plone frontend + +Create a second shell session in a new window. +Start the Plone frontend with the following command. + +```shell +make frontend-start ``` -Then run `yarn develop`, which will bring the package in `src/addons` and -adjust `jsconfig.json`. +The Plone frontend server starts up and emits messages to the console, and should end with the following. -### Add the add-on as workspace +```console +webpack 5.90.1 compiled successfully in 11004 ms +sswp> Handling Hot Module Reloading +Using volto.config.js in: //frontend/volto.config.js +✅ Server-side HMR Enabled! +Volto is running in SEAMLESS mode +Proxying API requests from http://localhost:3000/++api++ to http://localhost:8080/Plone +🎭 Volto started at 0.0.0.0:3000 🚀 +``` -The Volto project becomes a monorepo, with the Volto project being the "workspace root" and each add-on needs to be a "workspace", so that yarn knows that it should include that add-on location as a package and install its dependencies. +Open a browser at the following URL to visit your Plone site. -You could treat workspaces as major "working environment" for your project. So a yarn install would also install dependencies from `src/addons/*` +http://localhost:3000 -Change the Volto project's `package.json` to include something like: +You can then login with admin/admin at http://localhost:3000/login. -```json -{ - "private": "true", - "workspaces": [ - "src/addons/volto-teaser-tutorial" // or simply src/addons/* - ] -} -``` +## Volto addon + +Using Cookieplone we should already have a working Volto project with provided addon. You can find the addon in packages/volto-teaser-tutorial. ```{note} -Don't be scared by that `"private": "true"` in the Volto project `package.json`. -It's only needed to make sure you can't accidentally publish the package to NPM. +You might have noticed that we have `volto.config.js` in the root of the project. This is the volto configuration file allowing us to configure Volto and register addons.The addons list points to the addon we just installed. Cookieplone takes care of registering the addon for us. ``` -### Managing add-on dependencies +## Workspaces -To be able to add dependencies to the add-on, you need to add them via the -workspaces machinery by running something like (at the Volto project root): +pnpm workspaces are a way to manage multiple packages in a single repository. Volto is a monorepo, so we use workspaces to manage the Volto project and its addons along with other packages. -```shell -yarn workspaces info -yarn workspace volto-teaser-tutorial add papaparse -``` +We can define workspaces directly in the package.json file of a our project. However, it's common practice to use the `pnpm-workspace.yaml` file for more complex workspace configurations. This is taken care for us by Cookieplone. -````{note} -There are several other add-on templates, such as -voltocli or -eea/volto-addon-template. -You could very well decide not to use any of them, and instead bootstrap a new -add-on by running: - -```shell -mkdir -p src/addons/volto-teaser-tutorial -cd src/addons/volto-teaser-tutorial -npm init +```yaml +packages: + # all packages in direct subdirs of packages/ + - "core/packages/*" + - "packages/*" ``` -Remember, an add-on is just a JavaScript package that exports -a configuration loader. Just make sure to point the `main` in -`package.json` to `src/index.js`. +All the packages in the `packages` directory will be included in the workspace. -```` +The dependencies section maps the package names to the workspace. The `workspace:*` specifier tells pnpm to resolve these dependencies from other packages within the same workspace rather than fetching them from the npm registry. -### Load the add-on in Volto +```json + "dependencies": { + "@plone/volto": "workspace:*", + "@plone/registry": "workspace:*", + "volto-teaser-tutorial": "workspace:*" + }, +``` -To tell Volto about our new add-on, add it to the `addons` key of the Volto -project `package.json`: +### Managing add-on dependencies -```js -// ... -"addons": ["volto-teaser-tutorial"] -// ... +To be able to add dependencies to the add-on, you need to add them via the +workspaces machinery by running something like (at the Volto project root): + +```shell +pnpm workspaces info +pnpm workspace volto-teaser-tutorial add papaparse ``` -## Add-ons - first look +## Addons - first look Volto add-ons are just plain JavaScript packages with an additional feature: they provide helper functions that mutate Volto's @@ -219,31 +225,29 @@ export default (config) => { }; ``` -**Pro-Tip 💡** +### typescript configuration -```{note} -If you want to register a specific profile of an addon, wrap the configuration in a function and provide it after a colon(:) next to addon name. You can also provde a comma seperated multiple loaders profiles. Note the main configuration will be loaded always. -``` +Every addon supports custom typescript configuration using `tsconfig.json` in the root of the addon package. This file defines how the typeScript compiler should process the code in our addon. -```js -export function simpleLink(config) { - return installSimpleLink(config); -} +You can inspect the tsconfig.json file in the volto-teaser-tutorial package. -export function tableButton(config) { - return installTableButton(config); +The basic ones are self explanatory. Note that we have path mapping inside `compilerOptions` for all the packages that this addon depends on. + +```js +{ + "compilerOptions": { + "paths": { + "@plone/volto/*": ["../../core/packages/volto/src/*"], + "volto-teaser-tutorial/*": ["./src/*"] + } + }, } ``` -```js - ... -"addons": [ - "volto-slate:tableButton,simpleLink", - "@eeacms/volto-tabs-block", -] -... +This option allows you to set up module resolution paths. The mappings provided allow typescript to resolve modules using custom paths: -``` +`@plone/volto/*` maps to files in ../../core/packages/volto/src/_, allowing us to import from this directory using the @plone/volto prefix. +volto-teaser-tutorial/_ maps to ./src/\*, allowing local imports from the src directory of the volto-teaser-tutorial package. ## Documentation and Resources @@ -254,3 +258,7 @@ Join the Volto community, participate in discussions, and ask questions on the V ```{warning} Getting started with Volto may seem complex at first, but with practice and exploration, you'll become more comfortable with its features and capabilities. It offers a powerful and flexible platform for building modern web applications with React and Plone. ``` + +``` + +``` diff --git a/docs/volto_customization/intro.md b/docs/volto_customization/intro.md index ebed63877..2a2808da0 100644 --- a/docs/volto_customization/intro.md +++ b/docs/volto_customization/intro.md @@ -29,7 +29,7 @@ Some technologies and tools we use during the training: - Yarn https://yarnpkg.com - JSX - Volto https://github.com/plone/volto -- Volto Generator +- Cookieplone https://github.com/plone/cookieplone - Plone 6! Before we dive into the content of this training, I'd like to make a helpful suggestion. If you're new to Volto and React or feel like you could benefit from a refresher, it might be a great idea to explore some existing Volto and React training resources that can provide you with a solid foundation. These resources can serve as valuable supplements to what we'll cover here. @@ -44,7 +44,7 @@ Of course, if you're already familiar with Volto and React, that's fantastic, an To follow the training as smoothly as possible it is recommended that you have the following software installed on your computer: -- node.js >= 16 -- yarn +- node.js >= 20 +- pnpm - node version manager - docker diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index 8050b9ca0..cc36b30c7 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -11,7 +11,7 @@ myst: In the previous chapter we just replaced or enhanced our View component by directly mutating the View in the Blocks engine. Now since all the blocks in principle should be schema based and should use `BlockDataForm` we do have another concept of extending Blocks with respect to schema. -The `BlockDataForm` renders a schemaEnhanced form ready to be used along with the variations support. +The `BlockDataForm` renders a schemaEnhanced form ready to be used with support for validations and variations. The variations are various "View" mode options that your block might have whether its layout, the designs or a completely enhanced form of a block.