From 3f214f7cce938e8cf367260b680a7558f198ec19 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sat, 2 Nov 2024 22:51:51 +0530 Subject: [PATCH 01/14] 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. From f044b3af7f8a3176befecc838abd875835b3c20c Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sat, 2 Nov 2024 23:32:14 +0530 Subject: [PATCH 02/14] remove some chapters,fix grammer --- docs/volto_customization/extending_teasers.md | 594 ------------------ docs/volto_customization/index.md | 2 - docs/volto_customization/installation.md | 10 +- docs/volto_customization/listing_block.md | 227 ------- docs/volto_customization/schema.md | 14 +- docs/volto_customization/shadowing.md | 2 +- docs/volto_customization/teaser_variations.md | 9 +- docs/volto_customization/voltosettings.md | 2 +- 8 files changed, 23 insertions(+), 837 deletions(-) delete mode 100644 docs/volto_customization/extending_teasers.md delete mode 100644 docs/volto_customization/listing_block.md diff --git a/docs/volto_customization/extending_teasers.md b/docs/volto_customization/extending_teasers.md deleted file mode 100644 index 108132020..000000000 --- a/docs/volto_customization/extending_teasers.md +++ /dev/null @@ -1,594 +0,0 @@ ---- -myst: - html_meta: - "description": "How to support extensions per teaser block" - "property=og:description": "How to support extensions per teaser block" - "property=og:title": "Block Extensions" - "keywords": "Volto, Block, Variations" ---- - -# 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. - -In this chapter we will tweak our newly created variation to also support extensions per teaser block and then later we will add grid support to teasers. - -## Block Extensions - -Block extensions are the way to display a new form of your block for a particular block type. For instance if you have a teaserGrid, with block extensions you can control the styling and behaviour of individual teasers. The split of responsibilites is as follows: "the variation will control how the teasers layout and extension will control the individual rendering." - -We already learn about the block variation in the former chapters. We will now add the teaser block extensions the same way we do for variations. - -```js -import TeaserBlockImageDefault from "volto-teaser-tutorial/components/extensions/TeaserBlockImageDefault"; -import TeaserBlockImageRight from "volto-teaser-tutorial/components/extensions/TeaserBlockImageRight"; -import TeaserBlockImageOverlay from "volto-teaser-tutorial/components/extensions/TeaserBlockImageOverlay"; - -config.blocks.blocksConfig.teaser.extensions = { - ...(config.blocks.blocksConfig.teaser.extensions || {}), - cardTemplates: { - items: [ - { - id: "card", - isDefault: true, - title: "Card (default)", - template: TeaserBlockImageDefault, - }, - { - id: "imageOnRight", - isDefault: false, - title: "Image Right", - template: TeaserBlockImageRight, - }, - { - id: "imageOverlay", - isDefault: false, - title: "Image Overlay", - template: TeaserBlockImageOverlay, - }, - ], - }, -}; -``` - -As for the training we created only three extensions namely `TeaserBlockImageDefault`, `TeaserBlockImageRight` and `TeaserBlockImageOverlay` into our addons `components/extensions` folder. - -In order to support these extension first we need to add a special fieldset to our variation schema so that we can seperate the concerns about individual teasers and put these extensions under it. - -Luckily, In order to do that we have a helper in volto which automatic adds a select field where we want in the schema to display variations/extensions from a particualar block. As its a standalone method we can also add a variation from a completely different block like we do in SearchBlock in volto. - -Go ahead and register that in index.js in our variation schemaEnhancer: - -```jsx -import { addExtensionFieldToSchema } from '@plone/volto/helpers/Extensions/withBlockSchemaEnhancer'; - -config.blocks.blocksConfig.teaser.variations = [ - ...config.blocks.blocksConfig.teaser.variations, - { - id: 'image-top-variation', - title: 'Image(Top) variation', - template: TeaserBlockImageVariation, - isDefault: false, - schemaEnhancer: ({ schema, FormData, intl }) => { - const extension = 'cardTemplates'; - schema.fieldsets.push({ - id: 'Cards', - title: 'Cards', - fields: [], - }); - addExtensionFieldToSchema({ - schema, - name: extension, - items: config.blocks.blocksConfig.teaser.extensions[extension]?.items, - intl, - title: { id: 'Card Type' }, - insertFieldToOrder: (schema, extension) => { - const cardFieldSet = schema.fieldsets.find( - (item) => item.id === 'Cards', - ).fields; - if (cardFieldSet.indexOf(extension) === -1) - cardFieldSet.unshift(extension); - }, - }); - ... -``` - -Notice first we added a new fieldSet where our extensions will recide and the method `addExtensionFieldToSchema` imported volto core. This method as mentioned above adds a new field in the given fieldSet with the given extenionName `cardTemplates`. - -```{note} -By default `addExtensionFieldToSchema` adds the extewnsion field to default fieldSet, in order to ovverride that you can pass `insertFieldToOrder` method to specifiy where it should be added. - -``` - -Woot. We will now have our extensions loaded into the schema. We will have to refactor our intial Variation code to adapt the extension now. - -```{note} -The concept of extensions are only possible if the code of your block allows it. That is the reason why we created a variation out of a teaser block at the first place. -``` - -So our `TeaserBlockImageVariation` can be simplified now as: - -```jsx -import React from "react"; -import PropTypes from "prop-types"; -import { useIntl } from "react-intl"; -import cloneDeep from "lodash/cloneDeep"; -import config from "@plone/volto/registry"; - -const TeaserBlockImageVariation = (props) => { - const { data, extension = "cardTemplates" } = props; - const intl = useIntl(); - - const teaserExtenstions = - config.blocks.blocksConfig?.teaser?.extensions[extension].items; - let activeItem = teaserExtenstions.find( - (item) => item.id === data[extension] - ); - const extenionSchemaEnhancer = activeItem?.schemaEnhancer; - if (extenionSchemaEnhancer) - extenionSchemaEnhancer({ - schema: cloneDeep(config.blocks.blocksConfig?.teaser?.blockSchema), - data, - intl, - }); - const ExtensionToRender = activeItem?.template; - - return ExtensionToRender ? ( -
- -
- ) : null; -}; - -TeaserBlockImageVariation.propTypes = { - data: PropTypes.objectOf(PropTypes.any).isRequired, - isEditMode: PropTypes.bool, -}; - -export default TeaserBlockImageVariation; -``` - -We have added the "active extension" logic to this code and removed the templating code to their individual components under `extensions/` folder. -Notice that we can also add more schema Enhancers to our base variation schema if each extensions can provide it. - -The `ExtensionToRender` will be selected extensions from `extensions/` folder. - -Create a folder named `extensions/` within `components` and add three components provided below: - -TeaserBlockImageDefault: - -```jsx -import React from "react"; -import PropTypes from "prop-types"; -import { Message } from "semantic-ui-react"; -import { defineMessages, useIntl } from "react-intl"; - -import imageBlockSVG from "@plone/volto/components/manage/Blocks/Image/block-image.svg"; - -import { - flattenToAppURL, - isInternalURL, - addAppURL, -} from "@plone/volto/helpers"; -import { MaybeWrap } from "@plone/volto/components"; -import { formatDate } from "@plone/volto/helpers/Utils/Date"; -import { UniversalLink } from "@plone/volto/components"; -import cx from "classnames"; -import config from "@plone/volto/registry"; - -const messages = defineMessages({ - PleaseChooseContent: { - id: "Please choose an existing content as source for this element", - defaultMessage: - "Please choose an existing content as source for this element", - }, -}); - -const DefaultImage = (props) => {props.alt; - -const TeaserBlockImageDefault = (props) => { - const { className, data, isEditMode } = props; - const locale = config.settings.dateLocale || "en"; - const intl = useIntl(); - const href = data.href?.[0]; - const image = data.preview_image?.[0]; - const align = data?.styles?.align; - const creationDate = data.href?.[0]?.CreationDate; - const formattedDate = formatDate({ - date: creationDate, - format: { - year: "numeric", - month: "short", - day: "2-digit", - }, - locale: locale, - }); - - const Image = config.getComponent("Image").component || DefaultImage; - const { openExternalLinkInNewTab } = config.settings; - - return ( -
- <> - {!href && isEditMode && ( - -
- -

{intl.formatMessage(messages.PleaseChooseContent)}

-
- - )} - {href && ( - -
- {(href.hasPreviewImage || href.image_field || image) && ( -
- -
- )} -
- {data?.head_title && ( -
{data.head_title}
- )} -

{data?.title}

- {data.creationDate &&

{formattedDate}

} - {!data.hide_description &&

{data?.description}

} -
-
- - )} - -
- ); -}; - -TeaserBlockImageDefault.propTypes = { - data: PropTypes.objectOf(PropTypes.any).isRequired, - isEditMode: PropTypes.bool, -}; - -export default TeaserBlockImageDefault; -``` - -TeaserBlockImageRight: - -```jsx -import React from "react"; -import PropTypes from "prop-types"; -import { Message } from "semantic-ui-react"; -import { defineMessages, useIntl } from "react-intl"; - -import imageBlockSVG from "@plone/volto/components/manage/Blocks/Image/block-image.svg"; - -import { - flattenToAppURL, - isInternalURL, - addAppURL, -} from "@plone/volto/helpers"; -import { MaybeWrap } from "@plone/volto/components"; -import { formatDate } from "@plone/volto/helpers/Utils/Date"; -import { UniversalLink } from "@plone/volto/components"; -import cx from "classnames"; -import config from "@plone/volto/registry"; - -const messages = defineMessages({ - PleaseChooseContent: { - id: "Please choose an existing content as source for this element", - defaultMessage: - "Please choose an existing content as source for this element", - }, -}); - -const DefaultImage = (props) => {props.alt; - -const TeaserBlockImageRight = (props) => { - const { className, data, isEditMode } = props; - const locale = config.settings.dateLocale || "en"; - const intl = useIntl(); - const href = data.href?.[0]; - const image = data.preview_image?.[0]; - const align = data?.styles?.align; - const creationDate = data.href?.[0]?.CreationDate; - const formattedDate = formatDate({ - date: creationDate, - format: { - year: "numeric", - month: "short", - day: "2-digit", - }, - locale: locale, - }); - - const Image = config.getComponent("Image").component || DefaultImage; - const { openExternalLinkInNewTab } = config.settings; - - return ( -
- <> - {!href && isEditMode && ( - -
- -

{intl.formatMessage(messages.PleaseChooseContent)}

-
- - )} - {href && ( - -
-
- {data?.head_title && ( -
{data.head_title}
- )} -

{data?.title}

- {data.creationDate &&

{formattedDate}

} - {!data.hide_description &&

{data?.description}

} -
- {(href.hasPreviewImage || href.image_field || image) && ( -
- -
- )} -
- - )} - -
- ); -}; - -TeaserBlockImageRight.propTypes = { - data: PropTypes.objectOf(PropTypes.any).isRequired, - isEditMode: PropTypes.bool, -}; - -export default TeaserBlockImageRight; -``` - -TeaserBlockImageOverlay: - -```jsx -import React from "react"; -import PropTypes from "prop-types"; -import { Message } from "semantic-ui-react"; -import { defineMessages, useIntl } from "react-intl"; -import cloneDeep from "lodash/cloneDeep"; -import imageBlockSVG from "@plone/volto/components/manage/Blocks/Image/block-image.svg"; -import { - flattenToAppURL, - isInternalURL, - addAppURL, -} from "@plone/volto/helpers"; -import { MaybeWrap } from "@plone/volto/components"; -import { formatDate } from "@plone/volto/helpers/Utils/Date"; -import { UniversalLink } from "@plone/volto/components"; -import cx from "classnames"; -import config from "@plone/volto/registry"; - -const messages = defineMessages({ - PleaseChooseContent: { - id: "Please choose an existing content as source for this element", - defaultMessage: - "Please choose an existing content as source for this element", - }, -}); - -const DefaultImage = (props) => {props.alt; - -const TeaserBlockImageOverlay = (props) => { - const { className, data, isEditMode, extension = "cardTemplates" } = props; - const locale = config.settings.dateLocale || "en"; - const intl = useIntl(); - const href = data.href?.[0]; - const image = data.preview_image?.[0]; - const align = data?.styles?.align; - const creationDate = data.href?.[0]?.CreationDate; - const formattedDate = formatDate({ - date: creationDate, - format: { - year: "numeric", - month: "short", - day: "2-digit", - }, - locale: locale, - }); - - const teaserExtenstions = - config.blocks.blocksConfig?.teaser?.extensions[extension].items; - let activeItem = teaserExtenstions.find( - (item) => item.id === data[extension] - ); - const extenionSchemaEnhancer = activeItem?.schemaEnhancer; - if (extenionSchemaEnhancer) - extenionSchemaEnhancer({ - schema: cloneDeep(config.blocks.blocksConfig?.teaser?.blockSchema), - data, - intl, - }); - - const Image = config.getComponent("Image").component || DefaultImage; - const { openExternalLinkInNewTab } = config.settings; - - return ( -
- <> - {!href && isEditMode && ( - -
- -

{intl.formatMessage(messages.PleaseChooseContent)}

-
- - )} - {href && ( - -
- {(href.hasPreviewImage || href.image_field || image) && ( -
- -
- )} - -
- {data?.head_title && ( -
{data.head_title}
- )} -
-

{data?.title}

- {!data.hide_description &&

{data?.description}

} - {data?.creationDate && ( -

{formattedDate}

- )} -
-
-
- - )} - -
- ); -}; - -TeaserBlockImageOverlay.propTypes = { - data: PropTypes.objectOf(PropTypes.any).isRequired, - isEditMode: PropTypes.bool, -}; - -export default TeaserBlockImageOverlay; -``` - -The styles have to be added as well: - -```{code-block} less -:force: true -.gradiant { - h2 { - color: white; - } - position: absolute; - bottom: 30px; - display: flex; - width: 100%; - height: 200px; - align-items: flex-end; - padding: 1.5rem; - background-image: linear-gradient( - 13.39deg, - rgba(46, 62, 76, 0.65) 38.6%, - rgba(46, 62, 76, 0.169) 59.52%, - rgba(69, 95, 106, 0) 79.64% - ); -} - -.teaser-item.overlay { - display: flex; - - .image-wrapper { - width: 100%; - } -} - -.has--objectFit--contain { - img { - object-fit: contain !important; - } -} - -.has--objectFit--cover { - img { - object-fit: cover !important; - } -} - -.has--objectFit--fill { - img { - object-fit: fill !important; - } -} - -.has--objectFit--scale-down { - img { - object-fit: scale-down !important; - } -} -``` - -Great. We now have extension per teaser in our block which controls each item individually. - -## Grid support to Teasers - -As mentioned before we will configure the grid-block to also use our extended teaser-block. -We need to override the grid-block configuration with our teaser block. - -In your volto-teaser-tutorial addon's `index.js`: - -```js -//This ensures that grid block uses our overridden teaser -config.blocks.blocksConfig.gridBlock.blocksConfig.teaser = - config.blocks.blocksConfig.teaser; -``` - -Woot. We will now have a grid block with our teaser variations so that each teaser can now have its own set of extensions. diff --git a/docs/volto_customization/index.md b/docs/volto_customization/index.md index e8c55a48d..b30c67b30 100644 --- a/docs/volto_customization/index.md +++ b/docs/volto_customization/index.md @@ -55,8 +55,6 @@ schema teaser_variations data_adapters styling -extending_teasers -listing_block ``` diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 9f1c64ded..7e6d13090 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -38,7 +38,7 @@ They assume you have a macOS/Linux machine. ### Python -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. +Installing Python is beyond the scope of this training. 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. Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. @@ -81,10 +81,10 @@ To bootstrap a new Plone project(with both backend and frontend), you can use [C You can use pipx to run cookieplone (see instructions for installation): ```shell -pipx run cookieplone tutorial-project +pipx run cookieplone project ``` -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. +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 the name of the project as `tutorial-project` and name of the addon as `volto-teaser-tutorial` when prompted for the addons. ```shell [11/17] Volto Addon Name (volto-project-title): volto-teaser-tutorial @@ -93,10 +93,6 @@ You will be presented with a series of prompts. You can also specify the addons 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. -```{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). -``` - ## Install the project To work on your project, you need to install both the frontend and backend. diff --git a/docs/volto_customization/listing_block.md b/docs/volto_customization/listing_block.md deleted file mode 100644 index 7ee3b2655..000000000 --- a/docs/volto_customization/listing_block.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -myst: - html_meta: - "description": "How to create a block variation" - "property=og:description": "How to create a block variation" - "property=og:title": "Create a simple listing block variation" - "keywords": "Volto, Training, Block variation" ---- - -# Create a simple listing block variation - -We will create a variation for listing block, the approach is the same we did for teasers. A new variation which will control the layout and extensions which will take care of individual items styling. - -First of all let's add a styling fieldset in the current schema of volto's default listing block . - -In your addon config: - -```js -import { addStylingFieldset } from "volto-teaser-tutorial/components/helpers"; - -if (config.blocks.blocksConfig.listing) { - config.blocks.blocksConfig.listing.title = "Listing (Tutorial)"; - config.blocks.blocksConfig.listing.schemaEnhancer = addStylingFieldset; -} -``` - -Create a file named `helpers.js` inside `components/` folder and add the relevant schema enhancer for it: - -```js -import { cloneDeep } from "lodash"; -import imageNarrowSVG from "@plone/volto/icons/image-narrow.svg"; -import imageFitSVG from "@plone/volto/icons/image-fit.svg"; -import imageWideSVG from "@plone/volto/icons/image-wide.svg"; -import imageFullSVG from "@plone/volto/icons/image-full.svg"; - -export const ALIGN_INFO_MAP = { - narrow_width: [imageNarrowSVG, "Narrow width"], - container_width: [imageFitSVG, "Container width"], - wide_width: [imageWideSVG, "Wide width"], - full: [imageFullSVG, "Full width"], -}; - -export const addStylingFieldset = ({ schema }) => { - const applied = schema?.properties?.styles; - - if (!applied) { - const resSchema = cloneDeep(schema); - - resSchema.fieldsets.push({ - id: "styling", - fields: ["styles"], - title: "Styling", - }); - resSchema.properties.styles = { - widget: "object", - title: "Styling", - schema: { - fieldsets: [ - { - id: "default", - title: "Default", - fields: ["size"], - }, - ], - properties: { - size: { - widget: "align", - title: "Section size", - actions: Object.keys(ALIGN_INFO_MAP), - actionsInfoMap: ALIGN_INFO_MAP, - }, - }, - required: [], - }, - }; - return resSchema; - } - - return schema; -}; -``` - -This function will inject styles field into the schema if isn't present already. We can add relevant styling here. Volto will build classNames based on the styles as mentioned in the earlier chapters. We will have to provide our own css for the generated classNames. - -```less -:force: true - -#main .has--size--narrow_width, -#main .narrow_width, -[class~="narrow_view"] [id="page-document"] > * { - max-width: var(--narrow-text-width, 500px) !important; -} - -#main .container_width, -#main .has--size--container_width, -.view-wrapper > *, -[class~="view-defaultview"] [id="page-document"] > *, -[class~="view-viewview"] [id="page-document"] > * { - max-width: var(--container-text-width, 1120px) !important; -} -``` - -In order to have a control over individual items in the listing let's create a sample variation of listing block. - -```js -import ListingVariation from "volto-teaser-tutorial/components/ListingBlockVariation"; - -config.blocks.blocksConfig.listing.variations = [ - ...(config.blocks.blocksConfig.listing.variations || []), - { - id: "tutorial", - isDefault: false, - title: "Sample Variation", - template: ListingVariation, - schemaEnhancer: ({ schema, FormData, intl }) => { - const extension = "cardTemplates"; - schema.fieldsets.push({ - id: "Cards", - title: "Cards", - fields: [], - }); - addExtensionFieldToSchema({ - schema, - name: extension, - items: config.blocks.blocksConfig.teaser.extensions[extension]?.items, - intl, - title: { id: "Card Type" }, - insertFieldToOrder: (schema, extension) => { - const cardFieldSet = schema.fieldsets.find( - (item) => item.id === "Cards" - ).fields; - if (cardFieldSet.indexOf(extension) === -1) - cardFieldSet.unshift(extension); - }, - }); - return schema; - }, - }, -]; -``` - -Notice that here we will keep the schemaEnhancer configuration of teaser extensions. For better readability we can also move these lines of code into a `baseSchemaEnhancer` which will serve for both listing and teaser block extensions. But we can leave it up to the user for now. - -Finally we write our own variation for ListingBlock: - -ListingBlockVariation.jsx - -```jsx -import React from "react"; -import PropTypes from "prop-types"; -import cloneDeep from "lodash/cloneDeep"; -import { useIntl } from "react-intl"; -import { ConditionalLink, UniversalLink } from "@plone/volto/components"; -import { flattenToAppURL } from "@plone/volto/helpers"; -import config from "@plone/volto/registry"; - -import { isInternalURL } from "@plone/volto/helpers/Url/Url"; - -const ListingVariation = (props) => { - const { - items, - linkTitle, - linkHref, - isEditMode, - data, - extension = "cardTemplates", - } = props; - let link = null; - let href = linkHref?.[0]?.["@id"] || ""; - - if (isInternalURL(href)) { - link = ( - - {linkTitle || href} - - ); - } else if (href) { - link = {linkTitle || href}; - } - - const intl = useIntl(); - - const teaserExtenstions = - config.blocks.blocksConfig?.teaser?.extensions[extension].items; - let activeItem = teaserExtenstions.find( - (item) => item.id === props?.[extension] - ); - const extenionSchemaEnhancer = activeItem?.schemaEnhancer; - if (extenionSchemaEnhancer) - extenionSchemaEnhancer({ - schema: cloneDeep(config.blocks.blocksConfig?.teaser?.blockSchema), - data: data || props, - intl, - }); - const ExtensionToRender = activeItem?.template; - - return ( - <> -
- {items.map((item) => ( -
- -
- ))} -
- - {link &&
{link}
} - - ); -}; - -ListingVariation.propTypes = { - items: PropTypes.arrayOf(PropTypes.any).isRequired, - linkMore: PropTypes.any, - isEditMode: PropTypes.bool, -}; -export default ListingVariation; -``` - -We will now have the per listing item styling support like we have for teaser blocks. We can also add more styling schema with the help of its individual schema extenders. diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index cc36b30c7..ca12b4337 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -137,7 +137,14 @@ const TeaserBlockImageDefault = (props) => { : null } > -
+
{(href.hasPreviewImage || href.image_field || image) && (
Body component in Teaser block also supports adding variations from component registry. You can read more about component registry in following chapters. diff --git a/docs/volto_customization/shadowing.md b/docs/volto_customization/shadowing.md index e43cbd4cf..f09503cb0 100644 --- a/docs/volto_customization/shadowing.md +++ b/docs/volto_customization/shadowing.md @@ -29,7 +29,7 @@ For example when we customize the News Item View instead of adding the override we add it as -`src/addon/volto-teaser-tutorial/src/customizations/volto/components/theme/View/NewsItemView.jsx`. +`packages/volto-teaser-tutorial/src/customizations/volto/components/theme/View/NewsItemView.jsx`. Both paths work fine though, we just want to go all-in with the addon-approach. diff --git a/docs/volto_customization/teaser_variations.md b/docs/volto_customization/teaser_variations.md index f22cf7390..1f4f1ae92 100644 --- a/docs/volto_customization/teaser_variations.md +++ b/docs/volto_customization/teaser_variations.md @@ -130,7 +130,14 @@ const TeaserBlockImageDefault = (props) => { : null } > -
+
{(href.hasPreviewImage || href.image_field || image) && (
config/index.js of Volto itself which is available in your projects in `frontend/omelette/src/config/index.js`. +You can find all existing options in the file config/index.js of Volto itself which is available in your projects in `frontend/core/packages/volto/src/config/index.js`. ```{seealso} Many options are explained in the {doc}`plone6docs:volto/configuration/settings-reference` From 9fb4a52b6750301758e82116c830bf7dab08db83 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sat, 2 Nov 2024 23:44:23 +0530 Subject: [PATCH 03/14] fix weather block --- docs/volto_customization/custom_block.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index bd484b699..5d978787a 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -69,8 +69,8 @@ const View = (props) => { const [weatherData, setWeatherData] = useState(null); useEffect(() => { - const latitude = data.latitude || "43.1849"; // Default Eibar latitude if no latitude is provided - const longitude = data.longitude || "-2.4716"; // Default to longitude if no longitude is provided + const latitude = data.latitude || "-15.7797"; // Default latitude if no latitude is provided + const longitude = data.longitude || "-47.9297"; // Default to longitude if no longitude is provided const abortController = new AbortController(); // creating an AbortController From 9adc25f79c9f6db7dc377f66f439cce578228b8d Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sun, 3 Nov 2024 00:14:58 +0530 Subject: [PATCH 04/14] simplified installation docs --- docs/volto_customization/installation.md | 78 +----------------------- 1 file changed, 2 insertions(+), 76 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 7e6d13090..21bd5f271 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -17,64 +17,15 @@ Getting started with Volto involves setting up a development environment, unders ## Prerequisites -Before you start working with Volto, ensure you have the following prerequisites: +Before you start working with this training, ensure you have the following prerequisites: -- Node.js LTS (<=20.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.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. - -### Python - -Installing Python is beyond the scope of this training. 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. - -Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. - -### pipx - -Install [pipx](https://pipx.pypa.io/stable/). - -```shell -pip install pipx - -``` - -### Node.js - -1. Install or update the supported LTS versions of Node.js, then activate the version supported in Volto. - - ```shell - nvm install --lts - nvm use --lts - ``` - -2. Verify that the supported version of Node.js is activated. - - ```shell - node -v - ``` - -### Make - -`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`. - -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). @@ -122,19 +73,6 @@ In the currently open session, issue the following command. make backend-start ``` -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 -``` - ### Start Plone frontend Create a second shell session in a new window. @@ -144,18 +82,6 @@ Start the Plone frontend with the following command. make frontend-start ``` -The Plone frontend server starts up and emits messages to the console, and should end with the following. - -```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 🚀 -``` - Open a browser at the following URL to visit your Plone site. http://localhost:3000 From 7811dfb04295f4ceeb822f4cbab8f8dc60a8cfbe Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sun, 3 Nov 2024 00:19:26 +0530 Subject: [PATCH 05/14] fix prerequisites --- docs/volto_customization/installation.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 21bd5f271..92d23c697 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -26,6 +26,16 @@ Before you start working with this training, ensure you have the following prere - 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.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 Plone stack To bootstrap a new Plone project(with both backend and frontend), you can use [Cookieplone](https://github.com/plone/cookieplone). From 4d8b8aabc1844bea9d760d4aafbccb08d8467cb1 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sun, 3 Nov 2024 00:23:06 +0530 Subject: [PATCH 06/14] fix blank line --- docs/volto_customization/installation.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 92d23c697..4c296eb23 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -190,7 +190,3 @@ 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. ``` - -``` - -``` From b82654d8b00188cb221c98736e5f911de27e2506 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Sun, 3 Nov 2024 13:11:35 +0530 Subject: [PATCH 07/14] fix code block --- docs/volto_customization/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 4c296eb23..8e0fefdb7 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -178,8 +178,8 @@ The basic ones are self explanatory. Note that we have path mapping inside `comp 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. +`@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 From cca0c31ed80c51193190f9c477eb7a9aeda8d1d9 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Mon, 4 Nov 2024 14:34:55 +0530 Subject: [PATCH 08/14] use correct command for pnpm workspaces --- docs/volto_customization/installation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 8e0fefdb7..a115bc755 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -137,8 +137,7 @@ 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 +pnpm --filter volto-teaser-tutorial add papaparse ``` ## Addons - first look From 482f91a1a6023674829fea485e81238db2443f01 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Mon, 4 Nov 2024 23:13:53 +0530 Subject: [PATCH 09/14] amend more worspace hints --- docs/volto_customization/installation.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index a115bc755..d1dd6ca13 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -110,7 +110,7 @@ You might have noticed that we have `volto.config.js` in the root of the project 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. -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. +We can define workspaces using the `pnpm-workspace.yaml` file in root of our project. This is taken care for us by Cookieplone. ```yaml packages: @@ -131,6 +131,11 @@ The dependencies section maps the package names to the workspace. The `workspace }, ``` +```{note} +We don't need to pin specific workspace before we publish/release our project. pnpm takes care of dynamically updating the versions of these packages when you do `pnpm pack` or `pnpm publish`. + +``` + ### Managing add-on dependencies To be able to add dependencies to the add-on, you need to add them via the From d91612d721ed191d3f0935f6a5758754357f06f7 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Tue, 5 Nov 2024 16:15:04 +0530 Subject: [PATCH 10/14] pin matching Plone and Volto versions correctly --- docs/volto_customization/installation.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index d1dd6ca13..45a6ca480 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -28,10 +28,11 @@ Before you start working with this training, ensure you have the following prere 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.12 | 17.0 or 18.0 | -| 5.2 | 2.7, 3.6-3.8 | 15.0 | +| Plone | Python | Volto | +| ----- | ------------ | -------------- | +| 6.1 | 3.10-3.12 | 18.0 | +| 6.0 | 3.8-3.12 | 16.0,17.0,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. From d9c8dcd11fd26f1a5c8f75b51a3593277cc7497b Mon Sep 17 00:00:00 2001 From: Nilesh Date: Thu, 7 Nov 2024 19:51:10 +0530 Subject: [PATCH 11/14] Apply suggestions from code review Co-authored-by: Steve Piercy --- docs/volto_customization/custom_block.md | 2 +- docs/volto_customization/installation.md | 19 ++++++++++--------- docs/volto_customization/schema.md | 2 +- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index 5d978787a..d01832709 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -9,7 +9,7 @@ myst: # Volto Weather Block (custom block) -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. +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 Brasilia. diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 45a6ca480..f4d763b62 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -25,14 +25,13 @@ Before you start working with this training, ensure you have the following prere - nvm - GNU make - Docker (if using the Plone docker images - see instructions for installation and usage) - +Follow the guide in Plone 6 Documentation, {ref}`create-project-cookieplone-prerequisites-for-installation-label`. The versions of Python that are supported in Volto depend on the version of Plone that you use. | Plone | Python | Volto | | ----- | ------------ | -------------- | | 6.1 | 3.10-3.12 | 18.0 | | 6.0 | 3.8-3.12 | 16.0,17.0,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. @@ -40,13 +39,15 @@ They assume you have a macOS/Linux machine. ## 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): +You can use pipx to run Cookieplone to generate a project. ```shell pipx run cookieplone project ``` -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 the name of the project as `tutorial-project` and name of the addon as `volto-teaser-tutorial` when prompted for the addons. +You will be presented with a series of prompts. +You can also specify the add-ons you want to install along with the project. +When prompted for {guilabel}`Volto Addon Name`, enter `volto-teaser-tutorial`. ```shell [11/17] Volto Addon Name (volto-project-title): volto-teaser-tutorial @@ -59,7 +60,7 @@ For the training, we will use the default values for the rest of the prompts. To work on your project, you need to install both the frontend and backend. -Change your current working directory to `tutorial-project`. +Change your current working directory to `project-title`. ```shell cd tutorial-project @@ -104,7 +105,7 @@ You can then login with admin/admin at { }; ``` -### typescript configuration +### TypeScript configuration 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. diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index ca12b4337..40d801a71 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -184,7 +184,7 @@ export default TeaserBlockImageDefault; ``` After this you will be able to choose variations for this block from the Blocks Settings sidebar. -Right now this variation only shows image top variation of Teaser block. +Right now this variation only shows the image top variation of the Teaser block. You could decide to modify the template here in any way though. ```{note} From 6e843e8662610c197ab51afbdecf96bda948efc8 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Thu, 7 Nov 2024 19:58:52 +0530 Subject: [PATCH 12/14] refactor: apply leftover suggestions --- docs/volto_customization/installation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index f4d763b62..e7149269b 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -25,13 +25,13 @@ Before you start working with this training, ensure you have the following prere - nvm - GNU make - Docker (if using the Plone docker images - see instructions for installation and usage) -Follow the guide in Plone 6 Documentation, {ref}`create-project-cookieplone-prerequisites-for-installation-label`. -The versions of Python that are supported in Volto depend on the version of Plone that you use. + Follow the guide in Plone 6 Documentation, {ref}`create-project-cookieplone-prerequisites-for-installation-label`. + The versions of Python that are supported in Volto depend on the version of Plone that you use. -| Plone | Python | Volto | -| ----- | ------------ | -------------- | -| 6.1 | 3.10-3.12 | 18.0 | -| 6.0 | 3.8-3.12 | 16.0,17.0,18.0 | +| Plone | Python | Volto | +| ----- | --------- | -------------- | +| 6.1 | 3.10-3.12 | 18.0 | +| 6.0 | 3.8-3.12 | 16.0,17.0,18.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. @@ -63,7 +63,7 @@ To work on your project, you need to install both the frontend and backend. Change your current working directory to `project-title`. ```shell -cd tutorial-project +cd project-title ``` To install both the Plone backend and frontend, use the following command. @@ -98,7 +98,7 @@ Open a browser at the following URL to visit your Plone site. http://localhost:3000 -You can then login with admin/admin at http://localhost:3000/login. +You can then login with admin/admin at http://localhost:3000/login ## Volto addon From a650478b5d4c53a64428848e2936994cc45866c4 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Fri, 8 Nov 2024 12:22:27 +0530 Subject: [PATCH 13/14] replace occurances of in links by md --- docs/volto_customization/custom_block.md | 2 +- docs/volto_customization/data_adapters.md | 2 +- docs/volto_customization/installation.md | 16 ++++++++-------- docs/volto_customization/intro.md | 18 +++++++++--------- docs/volto_customization/schema.md | 4 ++-- docs/volto_customization/styling.md | 4 ++-- docs/volto_customization/voltosettings.md | 6 +++--- 7 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index d01832709..b46352928 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -9,7 +9,7 @@ myst: # Volto Weather Block (custom block) -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. +Let's create a volto block that will display weather information for Brasilia. For this we can use [Open-Meteo API](https://open-meteo.com/). 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 Brasilia. diff --git a/docs/volto_customization/data_adapters.md b/docs/volto_customization/data_adapters.md index 444df07da..3e9ffd2d2 100644 --- a/docs/volto_customization/data_adapters.md +++ b/docs/volto_customization/data_adapters.md @@ -70,7 +70,7 @@ We can register our own dataAdapter in place of this by maintaining the same def In order for dataAdapters to work make sure the code of your block allows and consumes it in its implementation. ``` -The above Adapter gets consumed in Data component of teaser block. +The above Adapter gets consumed in [Data](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Data.jsx#L47) component of teaser block. Let's register a new `dataAdapter` our config: diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index e7149269b..8218c447a 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -19,12 +19,12 @@ Getting started with Volto involves setting up a development environment, unders Before you start working with this training, ensure you have the following prerequisites: -- 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) +- [Node.js LTS (>=20.x)](https://nodejs.org/en) [see instructions for installation](https://6.docs.plone.org/install/install-from-packages.html#nvm) +- [Python](https://www.python.org/) - See below for specific versions. +- [pipx](https://pipx.pypa.io/stable/) +- [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) +- [GNU make](https://www.gnu.org/software/make/) +- [Docker](https://www.docker.com/get-started)(if using the Plone docker images - [see instructions for installation and usage](https://6.docs.plone.org/install/containers/index.html)) Follow the guide in Plone 6 Documentation, {ref}`create-project-cookieplone-prerequisites-for-installation-label`. The versions of Python that are supported in Volto depend on the version of Plone that you use. @@ -189,9 +189,9 @@ This option allows you to set up module resolution paths. The mappings provided ## Documentation and Resources -Refer to the official Volto documentation for in-depth guides, tutorials, and examples. +Refer to the [official Volto documentation](https://6.docs.plone.org/volto/index.html) for in-depth guides, tutorials, and examples. -Join the Volto community, participate in discussions, and ask questions on the Volto GitHub repository or the Plone community chat on Discord. +Join the Volto community, participate in discussions, and ask questions on the Volto GitHub repository or the [Plone community chat on Discord](https://plone.org/news-and-events/news/2021/join-plone-chat-now-at-discord) ```{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 2a2808da0..d67505145 100644 --- a/docs/volto_customization/intro.md +++ b/docs/volto_customization/intro.md @@ -25,14 +25,14 @@ Additionally, if you have any specific questions, challenges, or expectations fo Some technologies and tools we use during the training: -- React https://react.dev/ -- Yarn https://yarnpkg.com +- React https://react.dev/ +- Yarn https://yarnpkg.com - JSX -- Volto https://github.com/plone/volto -- Cookieplone https://github.com/plone/cookieplone +- Volto https://github.com/plone/volto +- 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. +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](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTVkkJfSMHu-l-_AVW_uoRf) that can provide you with a solid foundation. These resources can serve as valuable supplements to what we'll cover here. We have designed this training to be beginner-friendly, but having some prior exposure to these technologies can be advantageous. It will help you grasp the concepts more quickly and make the learning experience even more enjoyable. @@ -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 >= 20 -- pnpm -- node version manager -- docker +- [node.js](https://nodejs.org/en/)>= 20 +- [pnpm](https://pnpm.io/installation) +- [node version manager](https://github.com/nvm-sh/nvm) +- [docker](https://www.docker.com/get-started/) diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index 40d801a71..35e6454f1 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -49,7 +49,7 @@ So in the default schema for teaser block we have: }, ``` -Notice the _variations_ key, in which we can have multiple view templates for a given block. Right now its going to use the default one which is the TeaserBlockDefaultBody. +Notice the _variations_ key, in which we can have multiple view templates for a given block. Right now its going to use the default one which is the [TeaserBlockDefaultBody](https://github.com/plone/volto/blob/985e419396b4d00567d12e7e309ea420012e9cc7/src/components/manage/Blocks/Teaser/DefaultBody.jsx#L1). We are going to create a new variation of this teaser block. This variation is essential because using it we will create block extensions per teaser. Later we can also enhance this variation with the new schema. @@ -188,5 +188,5 @@ Right now this variation only shows the image top variation of the Teaser block. You could decide to modify the template here in any way though. ```{note} -The Body component in Teaser block also supports adding variations from component registry. You can read more about component registry in following chapters. +The [Body](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Body.jsx#L13) component in Teaser block also supports adding variations from component registry. You can read more about component registry in following chapters. ``` diff --git a/docs/volto_customization/styling.md b/docs/volto_customization/styling.md index 3e78f4d6d..3730475f5 100644 --- a/docs/volto_customization/styling.md +++ b/docs/volto_customization/styling.md @@ -13,12 +13,12 @@ Its essential to also control the styling of Blocks and most importantly if the ## StyleWrapper(Styling Schemas) -In Volto we have a central wrapper named `StyleWrapper` which wraps around all the View template of Blocks. The job of stylewrapper is to build and inject style classNames into its children. +In Volto we have a central wrapper named [StyleWrapper](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Block/StyleWrapper.jsx#L1) which wraps around all the View template of Blocks. The job of stylewrapper is to build and inject style classNames into its children. In the schema at any point in time, we can call a volto helper which adds `styles` fields. Which then gets converted into classNames with the prefix `--has`. Its upto the theme owner in which way they want to add css for it. Simply, the job of StyleWrapper is to inject classNames(build from schema) into their children. -We see that in our Teaser config volto already calls the addStyling in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. +We see that in our Teaser config volto already calls the [addStyling](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/helpers/Extensions/withBlockSchemaEnhancer.js#L297) in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. ```jsx export const TeaserSchema = ({ intl }) => { diff --git a/docs/volto_customization/voltosettings.md b/docs/volto_customization/voltosettings.md index 38d8e4085..ddb593ebe 100644 --- a/docs/volto_customization/voltosettings.md +++ b/docs/volto_customization/voltosettings.md @@ -38,7 +38,7 @@ export default applyConfig; ``` ```{note} -The `...` is a use of the spread-syntax that "expands" the configuration into its elements and allows to change existing values and add new ones. +The `...` is a use of the [spread-syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) that "expands" the configuration into its elements and allows to change existing values and add new ones. ``` ```{note} @@ -70,7 +70,7 @@ export default applyConfig; Here are some more setting you might use in your projects: -- `contentIcons` - configure Content Types icons. See documentation. +- `contentIcons` - configure Content Types icons. See [documentation](https://6.docs.plone.org/volto/configuration/settings-reference.html#term-contentIcons). - `navDepth` - Navigation levels depth used in the navigation endpoint calls. Increasing this is useful for implementing fat navigation menus. - `workflowMapping` - Configure colors for workflow states/transitions - if you have a custom workflow or want to change the default colors. - `openExternalLinkInNewTab` - Kind of self-explaining, isn't it? @@ -78,7 +78,7 @@ Here are some more setting you might use in your projects: - `maxFileUploadSize` - Limit the size of uploads - `nonContentRoutes` - A list of path strings which are considered to be outside of plone-restapi's content serialization. For example: `/controlpanel, /login,/sitemap,/personal-information` are all nonContentRoutes. -You can find all existing options in the file config/index.js of Volto itself which is available in your projects in `frontend/core/packages/volto/src/config/index.js`. +You can find all existing options in the file [config/index.js](https://github.com/plone/volto/blob/main/packages/volto/src/config/index.js#L73) of Volto itself which is available in your projects in `frontend/core/packages/volto/src/config/index.js`. ```{seealso} Many options are explained in the {doc}`plone6docs:volto/configuration/settings-reference` From e050e9094009d4fbf316e60851bfa1f82ff75f41 Mon Sep 17 00:00:00 2001 From: nileshgulia1 Date: Thu, 14 Nov 2024 16:05:17 +0530 Subject: [PATCH 14/14] fix: apply suggestions from @stevepiercy --- docs/volto_customization/blocks.md | 14 +++++++------- docs/volto_customization/custom_block.md | 2 +- docs/volto_customization/data_adapters.md | 2 +- docs/volto_customization/installation.md | 8 ++++---- docs/volto_customization/schema.md | 4 ++-- docs/volto_customization/shadowing.md | 4 ++-- docs/volto_customization/styling.md | 6 +++--- docs/volto_customization/voltosettings.md | 8 ++++---- 8 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/volto_customization/blocks.md b/docs/volto_customization/blocks.md index 33c4b26d6..e070bacd8 100644 --- a/docs/volto_customization/blocks.md +++ b/docs/volto_customization/blocks.md @@ -7,10 +7,10 @@ myst: "keywords": "Volto, Training, Extend block" --- -# Extend volto blocks +# Extend Volto blocks There are various ways of extending Volto blocks. -Component shadowing (see last chapter) is a very basic to customize components in volto. +Component shadowing (see last chapter) is a very basic to customize components in Volto. But it comes with its own problems like keeping the shadowed component up to date with latest fixes and features of newer Volto versions. Instead of shadowing components we can: @@ -18,10 +18,10 @@ Instead of shadowing components we can: - Extend blocks by adding new block-variations - Write add schemaEnhancer to modify blocks schema -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. +Let us first change the View of the teaser block which we already have in Volto core by changing the block-configuration. +In our add-on `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 `/frontend/core/packages/volto/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: { @@ -48,7 +48,7 @@ The most simple customization is the View of the Teaser. The volto core teaser b ``` Every block in Volto has Edit and View components. -You can customize these individually by either shadowing or directly in the confuguration (`index.js` of your addon) like this: +You can customize these individually by either shadowing or directly in the confuguration (`index.js` of your add-on) like this: ```js import MyTeaserView from "volto-teaser-tutorial/components/Blocks/Teaser/View"; @@ -61,7 +61,7 @@ const applyConfig = (config) => { export default applyConfig; ``` -Of course we need to add our custom `MyTeaserView` component in our addon. +Of course we need to add our custom `MyTeaserView` component in our add-on. From the root of the project that is `packages/volto-teaser-tutorial/src/components/Blocks/Teaser/View.jsx`: ```jsx diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index b46352928..b3889b426 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -9,7 +9,7 @@ myst: # Volto Weather Block (custom block) -Let's create a volto block that will display weather information for Brasilia. For this we can use [Open-Meteo API](https://open-meteo.com/). 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](https://open-meteo.com/). 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 Brasilia. diff --git a/docs/volto_customization/data_adapters.md b/docs/volto_customization/data_adapters.md index 3e9ffd2d2..6358f8114 100644 --- a/docs/volto_customization/data_adapters.md +++ b/docs/volto_customization/data_adapters.md @@ -70,7 +70,7 @@ We can register our own dataAdapter in place of this by maintaining the same def In order for dataAdapters to work make sure the code of your block allows and consumes it in its implementation. ``` -The above Adapter gets consumed in [Data](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Data.jsx#L47) component of teaser block. +The above Adapter gets consumed in [`Data`](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Data.jsx#L47) component of teaser block. Let's register a new `dataAdapter` our config: diff --git a/docs/volto_customization/installation.md b/docs/volto_customization/installation.md index 8218c447a..92959f329 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -102,7 +102,7 @@ You can then login with admin/admin at http://localhost:3000/login ## 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. +Using Cookieplone we should already have a working Volto project with provided add-on. You can find the add-on in packages/volto-teaser-tutorial. ```{note} You might have noticed that we have {file}`volto.config.js` in the root of the project. This is the Volto configuration file allowing us to configure Volto and register add-ons. The add-ons list points to the add-on we just installed. Cookieplone takes care of registering the add-on for us. @@ -110,7 +110,7 @@ You might have noticed that we have {file}`volto.config.js` in the root of the p ## Workspaces -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. +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 add-ons along with other packages. We can define workspaces using the `pnpm-workspace.yaml` file in root of our project. This is taken care for us by Cookieplone. @@ -165,11 +165,11 @@ export default (config) => { ### TypeScript configuration -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. +Every add-on supports custom typescript configuration using `tsconfig.json` in the root of the add-on package. This file defines how the typeScript compiler should process the code in our add-on. You can inspect the tsconfig.json file in the volto-teaser-tutorial package. -The basic ones are self explanatory. Note that we have path mapping inside `compilerOptions` for all the packages that this addon depends on. +The basic ones are self explanatory. Note that we have path mapping inside `compilerOptions` for all the packages that this add-on depends on. ```js { diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index 35e6454f1..e10226d75 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -49,7 +49,7 @@ So in the default schema for teaser block we have: }, ``` -Notice the _variations_ key, in which we can have multiple view templates for a given block. Right now its going to use the default one which is the [TeaserBlockDefaultBody](https://github.com/plone/volto/blob/985e419396b4d00567d12e7e309ea420012e9cc7/src/components/manage/Blocks/Teaser/DefaultBody.jsx#L1). +Notice the _variations_ key, in which we can have multiple view templates for a given block. Right now its going to use the default one which is the [`TeaserBlockDefaultBody`](https://github.com/plone/volto/blob/985e419396b4d00567d12e7e309ea420012e9cc7/src/components/manage/Blocks/Teaser/DefaultBody.jsx#L1). We are going to create a new variation of this teaser block. This variation is essential because using it we will create block extensions per teaser. Later we can also enhance this variation with the new schema. @@ -188,5 +188,5 @@ Right now this variation only shows the image top variation of the Teaser block. You could decide to modify the template here in any way though. ```{note} -The [Body](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Body.jsx#L13) component in Teaser block also supports adding variations from component registry. You can read more about component registry in following chapters. +The [`Body`](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Teaser/Body.jsx#L13) component in Teaser block also supports adding variations from component registry. You can read more about component registry in following chapters. ``` diff --git a/docs/volto_customization/shadowing.md b/docs/volto_customization/shadowing.md index f09503cb0..99610509f 100644 --- a/docs/volto_customization/shadowing.md +++ b/docs/volto_customization/shadowing.md @@ -21,7 +21,7 @@ To avoid duplication we simply follow the chapter {ref}`volto-overrides-label` o In that chapter you learn how to override the logo, the footer, the news-item view and the default listing-block. -The only difference is whenever we add new files instead of adding them to the project we add the to our addon. +The only difference is whenever we add new files instead of adding them to the project we add the to our add-on. For example when we customize the News Item View instead of adding the override as: @@ -31,7 +31,7 @@ we add it as `packages/volto-teaser-tutorial/src/customizations/volto/components/theme/View/NewsItemView.jsx`. -Both paths work fine though, we just want to go all-in with the addon-approach. +Both paths work fine though, we just want to go all-in with the add-on approach. ```{seealso} - {ref}`voltohandson-header-component-label` (Volto Hands-On Training) diff --git a/docs/volto_customization/styling.md b/docs/volto_customization/styling.md index 3730475f5..4f333e3e6 100644 --- a/docs/volto_customization/styling.md +++ b/docs/volto_customization/styling.md @@ -13,12 +13,12 @@ Its essential to also control the styling of Blocks and most importantly if the ## StyleWrapper(Styling Schemas) -In Volto we have a central wrapper named [StyleWrapper](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Block/StyleWrapper.jsx#L1) which wraps around all the View template of Blocks. The job of stylewrapper is to build and inject style classNames into its children. +In Volto we have a central wrapper named [`StyleWrapper`](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/components/manage/Blocks/Block/StyleWrapper.jsx#L1) which wraps around all the View template of Blocks. The job of stylewrapper is to build and inject style classNames into its children. -In the schema at any point in time, we can call a volto helper which adds `styles` fields. Which then gets converted into classNames with the prefix `--has`. Its upto the theme owner in which way they want to add css for it. +In the schema at any point in time, we can call a Volto helper which adds `styles` fields. Which then gets converted into classNames with the prefix `--has`. Its upto the theme owner in which way they want to add css for it. Simply, the job of StyleWrapper is to inject classNames(build from schema) into their children. -We see that in our Teaser config volto already calls the [addStyling](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/helpers/Extensions/withBlockSchemaEnhancer.js#L297) in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. +We see that in our Teaser config Volto already calls the [`addStyling`](https://github.com/plone/volto/blob/9667cf735e5c3e848de852d615941d98193e0a5e/src/helpers/Extensions/withBlockSchemaEnhancer.js#L297) in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. ```jsx export const TeaserSchema = ({ intl }) => { diff --git a/docs/volto_customization/voltosettings.md b/docs/volto_customization/voltosettings.md index ddb593ebe..3dea54856 100644 --- a/docs/volto_customization/voltosettings.md +++ b/docs/volto_customization/voltosettings.md @@ -7,11 +7,11 @@ myst: "keywords": "Volto, configuration" --- -# Most useful volto settings +# Most useful Volto settings You can configure Volto by modifying settings in a js-file. -In our addon we can modify the `index.js` +In our add-on we can modify the `index.js` ```js const applyConfig = (config) => { @@ -42,7 +42,7 @@ The `...` is a use of the [spread-syntax](https://developer.mozilla.org/en-US/do ``` ```{note} -If you instead make your changes in the project (i.e. not using a addon) you make the same changes in the file `config.js` of the project. +If you instead make your changes in the project (i.e. not using a add-on) you make the same changes in the file `config.js` of the project. ``` Some of the settings are duplicates of settings that exist in the Plone backend. @@ -78,7 +78,7 @@ Here are some more setting you might use in your projects: - `maxFileUploadSize` - Limit the size of uploads - `nonContentRoutes` - A list of path strings which are considered to be outside of plone-restapi's content serialization. For example: `/controlpanel, /login,/sitemap,/personal-information` are all nonContentRoutes. -You can find all existing options in the file [config/index.js](https://github.com/plone/volto/blob/main/packages/volto/src/config/index.js#L73) of Volto itself which is available in your projects in `frontend/core/packages/volto/src/config/index.js`. +You can find all existing options in the file [`config/index.js`](https://github.com/plone/volto/blob/main/packages/volto/src/config/index.js#L73) of Volto itself which is available in your projects in `frontend/core/packages/volto/src/config/index.js`. ```{seealso} Many options are explained in the {doc}`plone6docs:volto/configuration/settings-reference`