From e54f5ab71b4f3d3bd57a0458d566bf3981135505 Mon Sep 17 00:00:00 2001 From: Claudia Ifrim Date: Tue, 10 Oct 2023 12:25:31 +0300 Subject: [PATCH 01/42] fix links to documentation/resources --- docs/volto_customization/data_adapters.md | 2 +- docs/volto_customization/extending_teasers.md | 32 +++++++++++-------- docs/volto_customization/index.md | 2 +- docs/volto_customization/installation.md | 18 +++++------ docs/volto_customization/intro.md | 14 ++++---- docs/volto_customization/schema.md | 14 ++++---- docs/volto_customization/styling.md | 4 +-- docs/volto_customization/voltosettings.md | 6 ++-- 8 files changed, 47 insertions(+), 45 deletions(-) diff --git a/docs/volto_customization/data_adapters.md b/docs/volto_customization/data_adapters.md index 47205af09..64b5cb1e5 100644 --- a/docs/volto_customization/data_adapters.md +++ b/docs/volto_customization/data_adapters.md @@ -72,7 +72,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 component of teaser block. Let's register a new `dataAdapter` our config: diff --git a/docs/volto_customization/extending_teasers.md b/docs/volto_customization/extending_teasers.md index 8acedf669..5aaf6a8e4 100644 --- a/docs/volto_customization/extending_teasers.md +++ b/docs/volto_customization/extending_teasers.md @@ -273,8 +273,7 @@ export default TeaserBlockImageDefault; TeaserBlockImageRight: -```{code-block} jsx - +```jsx import React from "react"; import PropTypes from "prop-types"; import { Message } from "semantic-ui-react"; @@ -282,7 +281,11 @@ 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 { + 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"; @@ -354,10 +357,10 @@ const TeaserBlockImageRight = (props) => { {(href.hasPreviewImage || href.image_field || image) && (
- {
{(href.hasPreviewImage || href.image_field || image) && (
- Node.js LTS (16.x) - (see instructions for installation) +- Node.js LTS (16.x) - (see instructions for installation) - Python - See below for specific versions. -- Docker (if using the Plone docker images - see instructions for installation and how to run a Plone docker container) +- 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 | -| ----- | ------------ | ----- | -| 5.2 | 2.7, 3.6-3.8 | 15.0 | -| 6.0 | 3.8-3.10 | 16.0 | +| Plone | Python | Volto | +| ----- | ------------ | ------------ | +| 6.0 | 3.8-3.11 | 16.0 or 17.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. @@ -36,7 +36,7 @@ They assume you have a macOS/Linux machine. ## Bootstrap a new Volto project 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): +First, install it as a global tool (see instructions for installation): ```{code-block} shell npm install -g yo @@ -253,5 +253,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. ``` - - diff --git a/docs/volto_customization/intro.md b/docs/volto_customization/intro.md index 65db343bf..ebed63877 100644 --- a/docs/volto_customization/intro.md +++ b/docs/volto_customization/intro.md @@ -25,10 +25,10 @@ Additionally, if you have any specific questions, challenges, or expectations fo Some technologies and tools we use during the training: -- React -- Yarn +- React https://react.dev/ +- Yarn https://yarnpkg.com - JSX -- Volto +- Volto https://github.com/plone/volto - Volto Generator - Plone 6! @@ -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](https://nodejs.org/en/) >= 16 -- [yarn](https://yarnpkg.com/getting-started/install) -- [node version manager](https://github.com/nvm-sh/nvm) -- [docker](https://www.docker.com/get-started/) +- node.js >= 16 +- yarn +- node version manager +- docker diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index 09f681d8b..53751cac8 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -49,27 +49,27 @@ 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. 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. Go ahead and extend the in the variations key of the teaser-block in `index.js` like this: ```js -import TeaserBlockImageVariation from 'volto-teaser-tutorial/components/TeaserBlockImageVariation'; +import TeaserBlockImageVariation from "volto-teaser-tutorial/components/TeaserBlockImageVariation"; const applyConfig = (config) => { // ... config.blocks.blocksConfig.teaser.variations = [ ...config.blocks.blocksConfig.teaser.variations, { - id: 'image-top-variation', - title: 'Image(Top) variation', + id: "image-top-variation", + title: "Image(Top) variation", template: TeaserBlockImageVariation, }, - ] + ]; return config; -} +}; export default applyConfig; ``` @@ -183,5 +183,5 @@ You could decide to modify the template here already though. In the coming chapter we are gonna enhance this variation with extension per teaser. ```{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 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 e7cdc0ded..72b15235e 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` 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](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 in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. ```{code-block} jsx diff --git a/docs/volto_customization/voltosettings.md b/docs/volto_customization/voltosettings.md index ba4a006e5..7fbdde4ef 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](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. +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. ``` ```{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 https://6.docs.plone.org/volto/configuration/settings-reference.html#term-contentIcons +- `contentIcons` - configure Content Types icons. See documentation. - `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](https://github.com/plone/volto/blob/master/src/config/index.js#L73) 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/omelette/src/config/index.js`. ```{seealso} Many options are explained in the {doc}`plone6docs:volto/configuration/settings-reference` From decc7a34420143473cffe943ee5b57ceb4a33fa5 Mon Sep 17 00:00:00 2001 From: Claudia Ifrim Date: Tue, 10 Oct 2023 14:16:36 +0300 Subject: [PATCH 02/42] reformat code blocks and fix warnings --- docs/volto_customization/blocks.md | 22 +++-- docs/volto_customization/custom_block.md | 74 ++++++++--------- docs/volto_customization/data_adapters.md | 16 ++-- docs/volto_customization/extending_teasers.md | 8 +- docs/volto_customization/installation.md | 43 +++++----- docs/volto_customization/listing_block.md | 81 +++++++++---------- docs/volto_customization/schema.md | 7 +- docs/volto_customization/styling.md | 42 +++++----- docs/volto_customization/teaser_variations.md | 64 +++++++-------- docs/volto_customization/voltosettings.md | 10 +-- 10 files changed, 175 insertions(+), 192 deletions(-) diff --git a/docs/volto_customization/blocks.md b/docs/volto_customization/blocks.md index 9144866b0..e8f3f698c 100644 --- a/docs/volto_customization/blocks.md +++ b/docs/volto_customization/blocks.md @@ -23,8 +23,7 @@ In our addon `volto-teaser-tutorial` we will step by step extend each component The most simple customization is the View of the Teaser. The volto core teaser block configration (in `omelette/src/config/Blocks.jsx`) looks like: -```{code-block} js - +```js teaser: { id: 'teaser', title: 'Teaser', @@ -51,13 +50,13 @@ 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: -```{code-block} js -import MyTeaserView from 'volto-teaser-tutorial/components/Blocks/Teaser/View' +```js +import MyTeaserView from "volto-teaser-tutorial/components/Blocks/Teaser/View"; const applyConfig = (config) => { - config.blocks.blocksConfig.teaser.view = MyTeaserView + config.blocks.blocksConfig.teaser.view = MyTeaserView; return config; -} +}; export default applyConfig; ``` @@ -65,17 +64,16 @@ 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`: -```{code-block} jsx -import React from 'react'; -import TeaserBody from '@plone/volto/components/manage/Blocks/Teaser/Body'; -import { withBlockExtensions } from '@plone/volto/helpers'; +```jsx +import React from "react"; +import TeaserBody from "@plone/volto/components/manage/Blocks/Teaser/Body"; +import { withBlockExtensions } from "@plone/volto/helpers"; const TeaserView = (props) => { - return ; + return ; }; export default withBlockExtensions(TeaserView); - ``` Here, the View component renders a TeaserBody which will be a result of an active variation, we will come to that in later chapters. diff --git a/docs/volto_customization/custom_block.md b/docs/volto_customization/custom_block.md index 8af404a49..bb8537822 100644 --- a/docs/volto_customization/custom_block.md +++ b/docs/volto_customization/custom_block.md @@ -13,81 +13,78 @@ Let's create a volto block that will display weather information for Eibar. For 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. -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#bootstrap-a-new-volto-project) section. +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. 2. **Create a New Block:** In your Volto project directory, navigate to the "src/components" folder and locate/create the "Blocks" directory. Create a new folder for your custom block; let's name it "Weather". 3. **Define the Block Schema:** Inside the "Weather" folder, create a "schema.js" file to define your block's schema. Here's a basic schema for our block needs: -```{code-block} js +```js export const weatherBlockSchema = (props) => { return { - title: 'Weather Block', - description: 'Display weather information for location.', + title: "Weather Block", + description: "Display weather information for location.", fieldsets: [ { - id: 'default', - title: 'Default', - fields: ['latitude', 'longitude', 'location'], + id: "default", + title: "Default", + fields: ["latitude", "longitude", "location"], }, ], properties: { latitude: { - title: 'Latitude', + title: "Latitude", description: - 'Enter the latitude of the location for which you want to display the weather (e.g., 43.1849).', - widget: 'text', + "Enter the latitude of the location for which you want to display the weather (e.g., 43.1849).", + widget: "text", }, longitude: { - title: 'Longitude', + title: "Longitude", description: - 'Enter the longitude of the location for which you want to display the weather (e.g., -2.4716).', - widget: 'text', + "Enter the longitude of the location for which you want to display the weather (e.g., -2.4716).", + widget: "text", }, location: { - title: 'Location', + title: "Location", description: - 'Enter the name of the location for which you want to display the weather (e.g., Eibar, Basque Country).', - widget: 'text', + "Enter the name of the location for which you want to display the weather (e.g., Eibar, Basque Country).", + widget: "text", }, }, - required: ['latitude', 'longitude', 'location'], + required: ["latitude", "longitude", "location"], }; }; export default weatherBlockSchema; - ``` 4. **Create the Block Component:** Inside the "Weather" folder, create a "View.jsx" file to define your block's React component. This component will make an API request to fetch the weather data and display it: -```{code-block} jsx - -import React, { useEffect, useState } from 'react'; +```jsx +import React, { useEffect, useState } from "react"; const View = (props) => { const { data = {} } = props; - const location = data.location || 'Eibar, Basque Country'; + const location = data.location || "Eibar, Basque Country"; 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 || "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 abortController = new AbortController(); // creating an AbortController fetch( `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}¤t_weather=true&timezone=auto`, - { signal: abortController.signal }, // passing the signal to the query + { signal: abortController.signal } // passing the signal to the query ) .then((response) => response.json()) .then((data) => { setWeatherData(data); }) .catch((error) => { - if (error.name === 'AbortError') return; - console.error('Error fetching weather data:', error); + if (error.name === "AbortError") return; + console.error("Error fetching weather data:", error); throw error; }); @@ -101,7 +98,7 @@ const View = (props) => { {weatherData ? (

Weather in {location}

-

Temperature: {weatherData.current_weather.temperature} °C

+

Temperature: {weatherData.current_weather.temperature} °C

) : (

Loading weather data...

@@ -109,19 +106,17 @@ const View = (props) => { ); }; - export default View; ``` You should also create a "Edit.jsx" file. The BlockDataForm component will transform the schema.js data into a usable sidebar. -```{code-block} jsx - -import React, { useMemo } from 'react'; -import { SidebarPortal } from '@plone/volto/components'; -import BlockDataForm from '@plone/volto/components/manage/Form/BlockDataForm'; -import weatherBlockSchema from './schema'; -import View from './View'; +```jsx +import React, { useMemo } from "react"; +import { SidebarPortal } from "@plone/volto/components"; +import BlockDataForm from "@plone/volto/components/manage/Form/BlockDataForm"; +import weatherBlockSchema from "./schema"; +import View from "./View"; const Edit = (props) => { const schema = useMemo(() => weatherBlockSchema(props), [props]); @@ -150,12 +145,11 @@ const Edit = (props) => { }; export default Edit; - ``` 5. **Register the Block:** In your Volto project, locate the "components/index.js" file and add an the entries for your "Weather Block" -```{code-block} js +```js ... import WeatherEdit from './components/Blocks/Weather/Edit'; import WeatherView from './components/Blocks/Weather/View'; @@ -167,7 +161,7 @@ export { WeatherView, WeatherEdit }; We need to configure the project to make it aware of a new block by adding it to the object configuration that is located in "src/config.js". For that we need the 2 blocks components we created and a svg icon that will be displayed in the blocks chooser. -```{code-block} js +```js import WeatherEdit from './components/Blocks/Weather/Edit'; import WeatherView from './components/Blocks/Weather/View'; import worldSVG from '@plone/volto/icons/world.svg'; diff --git a/docs/volto_customization/data_adapters.md b/docs/volto_customization/data_adapters.md index 64b5cb1e5..444df07da 100644 --- a/docs/volto_customization/data_adapters.md +++ b/docs/volto_customization/data_adapters.md @@ -11,8 +11,7 @@ myst: The Teaser block has an ability to let user mutate or intercept block settings data from their customization. The `dataAdapter` field gets registered in Teaser configuration in order to achieve this. -```{code-block} js - +```js teaser: { id: 'teaser', title: 'Teaser', @@ -39,8 +38,7 @@ teaser: { The signature of `dataAdapter` is like this: -```{code-block} js - +```js export const TeaserBlockDataAdapter = ({ block, data, @@ -76,23 +74,23 @@ The above Adapter gets consumed in { let dataSaved = { ...data, [id]: value, }; - if (id === 'title' && !isEmpty(value)) { + if (id === "title" && !isEmpty(value)) { dataSaved = { ...dataSaved, title: value[0].toUpperCase() + value.slice(1), diff --git a/docs/volto_customization/extending_teasers.md b/docs/volto_customization/extending_teasers.md index 5aaf6a8e4..c2339cb1c 100644 --- a/docs/volto_customization/extending_teasers.md +++ b/docs/volto_customization/extending_teasers.md @@ -585,10 +585,10 @@ We need to override the grid-block configuration with our teaser block. In your volto-teaser-tutorial addon's `index.js`: -```{code-block} js - //This ensures that grid block uses our overridden teaser - config.blocks.blocksConfig.gridBlock.blocksConfig.teaser = - config.blocks.blocksConfig.teaser; +```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/installation.md b/docs/volto_customization/installation.md index 23518a709..128ebd9d5 100644 --- a/docs/volto_customization/installation.md +++ b/docs/volto_customization/installation.md @@ -38,14 +38,14 @@ They assume you have a macOS/Linux machine. 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): -```{code-block} shell +```shell npm install -g yo npm install -g @plone/generator-volto ``` Then you can bootstrap the project with: -```{code-block} shell +```shell yo @plone/volto volto-tutorial-project ``` @@ -55,12 +55,12 @@ to add add-ons, choose `false`. Now you can start your newly created Volto project: -```{code-block} shell +```shell cd volto-tutorial-project yarn start ``` -You can then login with admin/admin at http://localhost:3000/login. +You can then login with admin/admin at http://localhost:3000/login. ## Bootstrap an add-on @@ -68,7 +68,7 @@ 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): -```{code-block} shell +```shell yo @plone/volto:addon ``` @@ -81,7 +81,7 @@ scaffolding of the add-on completes, you can check the created files in Back to the project, you can edit `jsconfig.json` and add your add-on: -```{code-block} json +```json { "compilerOptions": { "baseUrl": "src", @@ -103,13 +103,13 @@ JavaScript packages that are shipped transpiled. 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. -```{code-block} shell +```shell npx -p @plone/scripts addon clone [options] [destination] ``` 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. -```{code-block} shell +```shell npx -p @plone/scripts addon clone https://github.com/kitconcept/volto-teaser-tutorial.git --branch main ``` @@ -120,14 +120,14 @@ to manage the package and `jsconfig.json` changes. Install mrs-developer as a development dependency by running: -```{code-block} shell +```shell yarn add -W -D mrs-developer ``` Create a `mrs.developer.json` in your project with the following content (adjust it according to your names and repository location): -```{code-block} json +```json { "volto-teaser-tutorial": { "url": "https://github.com//volto-teaser-tutorial.git", @@ -149,7 +149,7 @@ You could treat workspaces as major "working environment" for your project. So a Change the Volto project's `package.json` to include something like: -```{code-block} json +```json { "private": "true", "workspaces": [ @@ -168,19 +168,19 @@ It's only needed to make sure you can't accidentally publish the package to NPM. 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): -```{code-block} shell +```shell yarn workspaces info yarn workspace volto-teaser-tutorial add papaparse ``` ````{note} There are several other add-on templates, such as -[voltocli](https://github.com/nzambello/voltocli) or -[eea/volto-addon-template](https://github.com/eea/volto-addon-template). +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: -```{code-block} shell +```shell mkdir -p src/addons/volto-teaser-tutorial cd src/addons/volto-teaser-tutorial npm init @@ -189,6 +189,7 @@ npm init 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`. + ```` ### Load the add-on in Volto @@ -196,7 +197,7 @@ a configuration loader. Just make sure to point the `main` in To tell Volto about our new add-on, add it to the `addons` key of the Volto project `package.json`: -```{code-block} js +```js // ... "addons": ["volto-teaser-tutorial"] // ... @@ -212,7 +213,7 @@ Their `main` entry in `package.json` should point to `src/index.js`, which should be an ES6 module with a default export. Here is the default add-on configuration loader: -```{code-block} js +```js export default (config) => { return config; }; @@ -224,7 +225,7 @@ export default (config) => { 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. ``` -```{code-block} js +```js export function simpleLink(config) { return installSimpleLink(config); } @@ -234,11 +235,11 @@ export function tableButton(config) { } ``` -``` +```js ... "addons": [ -"volto-slate:tableButton,simpleLink", -"@eeacms/volto-tabs-block", + "volto-slate:tableButton,simpleLink", + "@eeacms/volto-tabs-block", ] ... diff --git a/docs/volto_customization/listing_block.md b/docs/volto_customization/listing_block.md index f95c4c9f5..7ee3b2655 100644 --- a/docs/volto_customization/listing_block.md +++ b/docs/volto_customization/listing_block.md @@ -15,8 +15,8 @@ First of all let's add a styling fieldset in the current schema of volto's defau In your addon config: -```{code-block} js -import { addStylingFieldset } from 'volto-teaser-tutorial/components/helpers'; +```js +import { addStylingFieldset } from "volto-teaser-tutorial/components/helpers"; if (config.blocks.blocksConfig.listing) { config.blocks.blocksConfig.listing.title = "Listing (Tutorial)"; @@ -26,7 +26,7 @@ if (config.blocks.blocksConfig.listing) { Create a file named `helpers.js` inside `components/` folder and add the relevant schema enhancer for it: -```{code-block} js +```js import { cloneDeep } from "lodash"; import imageNarrowSVG from "@plone/volto/icons/image-narrow.svg"; import imageFitSVG from "@plone/volto/icons/image-fit.svg"; @@ -82,7 +82,7 @@ export const addStylingFieldset = ({ 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. -```{code-block} less +```less :force: true #main .has--size--narrow_width, @@ -102,44 +102,41 @@ This function will inject styles field into the schema if isn't present already. In order to have a control over individual items in the listing let's create a sample variation of listing block. -```{code-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; - }, +```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. @@ -148,7 +145,7 @@ Finally we write our own variation for ListingBlock: ListingBlockVariation.jsx -```{code-block} jsx +```jsx import React from "react"; import PropTypes from "prop-types"; import cloneDeep from "lodash/cloneDeep"; diff --git a/docs/volto_customization/schema.md b/docs/volto_customization/schema.md index 53751cac8..8050b9ca0 100644 --- a/docs/volto_customization/schema.md +++ b/docs/volto_customization/schema.md @@ -78,8 +78,7 @@ We should create this view template in our `components/TeaserBlockImageVariation TeaserBlockImageVariation.jsx: -```{code-block} jsx - +```jsx import React from "react"; import PropTypes from "prop-types"; import { Message } from "semantic-ui-react"; @@ -142,9 +141,9 @@ const TeaserBlockImageDefault = (props) => { {(href.hasPreviewImage || href.image_field || image) && (
addStyling in the schema. The job of this function is to add styles field in the styling fieldset in schema provided. -```{code-block} jsx - +```jsx export const TeaserSchema = ({ intl }) => { const schema = { title: intl.formatMessage(messages.teaser), @@ -93,8 +92,7 @@ and then we can manipulate those fields by adding whatever styles we want. Let's In your variation schemaEnhancer: -```{code-block} js - +```js config.blocks.blocksConfig.teaser.variations = [ ...config.blocks.blocksConfig.teaser.variations, { @@ -131,22 +129,25 @@ config.blocks.blocksConfig.teaser.variations = [ As StyleWrapper wraps around our view component in `RenderBlocks`. The styleNames should be available in our component's rendered html. -```{code-block} html - +```html
- -
-
- Alt image text -
-
-
-

teaser View

-

-
+ +
+
+ Alt image text +
+
+
+

teaser View

+

- +
+
``` @@ -186,10 +187,9 @@ StyleMenu is not the part of Blocks engine instead its a volto-slate plugin and In your policy package, you can add styleMenu configuration like: -```{code-block} jsx - -import paintSVG from '@plone/volto/icons/paint.svg'; -import { Icon } from '@plone/volto/components'; +```jsx +import paintSVG from "@plone/volto/icons/paint.svg"; +import { Icon } from "@plone/volto/components"; config.settings.slate.styleMenu = { ...(config.settings.slate.styleMenu || {}), diff --git a/docs/volto_customization/teaser_variations.md b/docs/volto_customization/teaser_variations.md index 2e928b9d9..f22cf7390 100644 --- a/docs/volto_customization/teaser_variations.md +++ b/docs/volto_customization/teaser_variations.md @@ -15,8 +15,7 @@ schemaEnhancers works on the concept of composition. They are just functions whi In our variation, let's add a schemaEnhancer to modify existing schema and add a `CreationDate` from catalog metadata brain. -```{code-block} js - +```js config.blocks.blocksConfig.teaser.variations = [ ...config.blocks.blocksConfig.teaser.variations, { @@ -39,8 +38,7 @@ config.blocks.blocksConfig.teaser.variations = [ And then in your code of that variation, you should consume that field accordingly. -```{code-block} js - +```js const creationDate = data.href?.[0]?.CreationDate; const formattedDate = formatDate({ date: creationDate, @@ -57,7 +55,7 @@ const formattedDate = formatDate({ Finally render it conditionally on the basis of `data.creationDate` -```{code-block} jsx +```jsx { data?.creationDate &&

{formattedDate}

; } @@ -65,32 +63,32 @@ Finally render it conditionally on the basis of `data.creationDate` The whole component looks like: -```{code-block} 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 } 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'; +```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 } 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', + id: "Please choose an existing content as source for this element", defaultMessage: - 'Please choose an existing content as source for this element', + "Please choose an existing content as source for this element", }, }); -const DefaultImage = (props) => {props.alt; +const DefaultImage = (props) => {props.alt; const TeaserBlockImageDefault = (props) => { const { className, data, isEditMode } = props; - const locale = config.settings.dateLocale || 'en'; + const locale = config.settings.dateLocale || "en"; const intl = useIntl(); const href = data.href?.[0]; const image = data.preview_image?.[0]; @@ -99,19 +97,18 @@ const TeaserBlockImageDefault = (props) => { const formattedDate = formatDate({ date: creationDate, format: { - year: 'numeric', - month: 'short', - day: '2-digit', + year: "numeric", + month: "short", + day: "2-digit", }, locale: locale, }); - const Image = config.getComponent('Image').component || DefaultImage; + const Image = config.getComponent("Image").component || DefaultImage; const { openExternalLinkInNewTab } = config.settings; - return ( -
+
<> {!href && isEditMode && ( @@ -125,21 +122,21 @@ const TeaserBlockImageDefault = (props) => {
{(href.hasPreviewImage || href.image_field || image) && (
- { return config; }; @@ -23,7 +23,7 @@ export default applyConfig; Here three settings are changed: -```{code-block} js +```js const applyConfig = (config) => { config.settings = { ...config.settings, @@ -32,7 +32,7 @@ const applyConfig = (config) => { hasWorkingCopySupport: true, }; return config; -} +}; export default applyConfig; ``` @@ -50,7 +50,7 @@ For example the setting `supportedLanguages` must match the one set in the Plone To configure Volto as a multilingual project you do this: -```{code-block} js +```js const applyConfig = (config) => { config.settings = { ...config.settings, @@ -59,7 +59,7 @@ const applyConfig = (config) => { supportedLanguages: ["en", "de", "fr"], }; return config; -} +}; export default applyConfig; ``` From cb3a57743b5f62ac230309734cfe3b88a60a50a0 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 12:03:55 +0200 Subject: [PATCH 03/42] Changed Assistant Typos in starttheming.md --- docs/voltohandson/starttheming.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/voltohandson/starttheming.md b/docs/voltohandson/starttheming.md index af3339a4b..58ce17047 100644 --- a/docs/voltohandson/starttheming.md +++ b/docs/voltohandson/starttheming.md @@ -25,7 +25,7 @@ Finally edit your `theme.config` and change the `@siteFolder` variable to contai ## Basic font family -[plone.org](plone.org) uses the "Assisstant" font instead of the Volto default "Poppins". You can use Semantic UI variables for customizing the font, as it's a valuable feature. +[plone.org](plone.org) uses the "Assistant" font instead of the Volto default "Poppins". You can use Semantic UI variables for customizing the font, as it's a valuable feature. Create a file called `site.variables`in the following path `src/addons//theme/globals/`. @@ -38,25 +38,25 @@ Everytime you add a new file to your project you will have to restart your devel Edit the new file and add this: ```less -@fontName: "Asisstant"; +@fontName: "Assistant"; ``` You can set it to any Google font available, and the online version of the font will be used. You can also set other variables concerning the font used, such as the sizes available. In case you want to use more than one font or a font that is self-hosted, -you should define it as usual in CSS and set the variable `importGoogleFonts` appropriately. As `Assisstant` is Google Font we will set: +you should define it as usual in CSS and set the variable `importGoogleFonts` appropriately. As `Assistant` is Google Font we will set: ```less @importGoogleFonts: true; ``` -Two more important variables that are changed in plone.org are: +Two more important Variables that are changed in plone.org are: ```less @largeMonitorBreakpoint: 1330px; @emSize: 16px; ``` -This changes the width of the default container. Add them as well. +These Two Variables change the Width of the Default Container. Add them as well. ```{tip} From a2ec14f5d9253162abb4305eb731f2da7b223e0c Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 12:05:35 +0200 Subject: [PATCH 04/42] Update breadcrumbs.md Typo Fixes --- docs/voltohandson/breadcrumbs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/breadcrumbs.md b/docs/voltohandson/breadcrumbs.md index 976ebd400..d9dcc7f1a 100644 --- a/docs/voltohandson/breadcrumbs.md +++ b/docs/voltohandson/breadcrumbs.md @@ -15,7 +15,7 @@ myst: We want to hide breadcrumbs from the homepage and change the styling a bit. -We can do it by using bare styling, since Volto injects CSS classes in the body that help us to style depending on the object, the content type and the path. +We can do it by using bare styling, since Volto injects CSS classes in the body that help us to style depending on the object, the Content Type and the path. Volto does it very much like Plone does. ```less From af7b9d83f0751a761c6a89f3c6fb29558e2741d8 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 12:11:12 +0200 Subject: [PATCH 05/42] Update footer.md Changed Broken Links --- docs/voltohandson/footer.md | 44 ++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/voltohandson/footer.md b/docs/voltohandson/footer.md index d30648a43..e6e6d9eff 100644 --- a/docs/voltohandson/footer.md +++ b/docs/voltohandson/footer.md @@ -34,14 +34,14 @@ Then, we replace the `Footer` component content to match the one from plone.org. - About Plone + About Plone - Try Plone + Try Plone - Download Plone + Download Plone Documentation @@ -50,10 +50,10 @@ Then, we replace the `Footer` component content to match the one from plone.org. Training - Security + Security - Roadmap + Roadmap Github @@ -64,23 +64,23 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Community + Community Forum - Chat + Chat - Contribute code + Contribute code - Report an issue + Report an issue - News and events + News and events Conference @@ -91,30 +91,30 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Foundation + Foundation - + Join the foundation - + - Board + Board Donate - Sponsors + Sponsors - + Code of conduct - + - Foundation members + Foundation members Shop @@ -125,9 +125,9 @@ Then, we replace the `Footer` component content to match the one from plone.org. - + Follow us - + @@ -177,7 +177,7 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Privacy Policy + Privacy Policy @@ -210,7 +210,7 @@ Then, we replace the `Footer` component content to match the one from plone.org.
``` -and add this styling to the `custom.overrides` file: +And we Add this styling to the `custom.overrides` file: ```less //Footer From 432afad04ceafe88c135766a6e3acfee735a1a4f Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 12:15:25 +0200 Subject: [PATCH 06/42] Update introtoblocks.md Changed the import Path to a static path --- docs/voltohandson/introtoblocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/introtoblocks.md b/docs/voltohandson/introtoblocks.md index 93c58d628..b1fae6dc9 100644 --- a/docs/voltohandson/introtoblocks.md +++ b/docs/voltohandson/introtoblocks.md @@ -116,7 +116,7 @@ export { SliderBlockEdit, SliderBlockView }; We need to configure the project to make it aware of a new block by adding it to the object configuration for that we need the 2 blocks components we created and a svg icon that will be displayed in the blocks chooser. This will again be done in the projects config file: ```js -import { SliderBlockView, SliderBlockEdit } from "@package/components"; +import { SliderBlockView, SliderBlockEdit } from "./customizations/components/index.js"; import heroSVG from "@plone/volto/icons/hero.svg"; ``` From 5ac5f77b9da1b369a40ccaa344a1d8bc63376dd6 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 13:03:44 +0200 Subject: [PATCH 07/42] Update docs/voltohandson/breadcrumbs.md Co-authored-by: Steve Piercy --- docs/voltohandson/breadcrumbs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/breadcrumbs.md b/docs/voltohandson/breadcrumbs.md index d9dcc7f1a..b4f844c1f 100644 --- a/docs/voltohandson/breadcrumbs.md +++ b/docs/voltohandson/breadcrumbs.md @@ -15,7 +15,7 @@ myst: We want to hide breadcrumbs from the homepage and change the styling a bit. -We can do it by using bare styling, since Volto injects CSS classes in the body that help us to style depending on the object, the Content Type and the path. +We can do it by using bare styling, since Volto injects CSS classes in the body that help us to style, depending on the object, the content type, and the path. Volto does it very much like Plone does. ```less From 390a56c35c673072120b267de6f0ae0ddce77b77 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 13:04:06 +0200 Subject: [PATCH 08/42] Update docs/voltohandson/starttheming.md Co-authored-by: Steve Piercy --- docs/voltohandson/starttheming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/starttheming.md b/docs/voltohandson/starttheming.md index 58ce17047..40594302c 100644 --- a/docs/voltohandson/starttheming.md +++ b/docs/voltohandson/starttheming.md @@ -50,7 +50,7 @@ you should define it as usual in CSS and set the variable `importGoogleFonts` ap @importGoogleFonts: true; ``` -Two more important Variables that are changed in plone.org are: +Two more important variables that are changed in plone.org are: ```less @largeMonitorBreakpoint: 1330px; From 2ded91e89503d487e39a92cc3dc5c712378e0e32 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 13:04:30 +0200 Subject: [PATCH 09/42] Update docs/voltohandson/starttheming.md Co-authored-by: Steve Piercy --- docs/voltohandson/starttheming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/starttheming.md b/docs/voltohandson/starttheming.md index 40594302c..697f43c72 100644 --- a/docs/voltohandson/starttheming.md +++ b/docs/voltohandson/starttheming.md @@ -44,7 +44,7 @@ Edit the new file and add this: You can set it to any Google font available, and the online version of the font will be used. You can also set other variables concerning the font used, such as the sizes available. In case you want to use more than one font or a font that is self-hosted, -you should define it as usual in CSS and set the variable `importGoogleFonts` appropriately. As `Assistant` is Google Font we will set: +you should define it as usual in CSS and set the variable `importGoogleFonts` appropriately. As `Assistant` is a Google Font we will set: ```less @importGoogleFonts: true; From 52bdf21e7e75908611bb696f028d4036f8b48933 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Sat, 14 Oct 2023 13:05:22 +0200 Subject: [PATCH 10/42] Update docs/voltohandson/starttheming.md Co-authored-by: Steve Piercy --- docs/voltohandson/starttheming.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/voltohandson/starttheming.md b/docs/voltohandson/starttheming.md index 697f43c72..c261a9102 100644 --- a/docs/voltohandson/starttheming.md +++ b/docs/voltohandson/starttheming.md @@ -56,7 +56,8 @@ Two more important variables that are changed in plone.org are: @largeMonitorBreakpoint: 1330px; @emSize: 16px; ``` -These Two Variables change the Width of the Default Container. Add them as well. +These two variables change the width of the default container. +Add them as well. ```{tip} From a081de07fb8a58920aef5af67052a463140601a6 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Mon, 16 Oct 2023 14:00:01 +0200 Subject: [PATCH 11/42] Update footer.md Added the Fixes Requested by @jackkahl --- docs/voltohandson/footer.md | 92 +++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/docs/voltohandson/footer.md b/docs/voltohandson/footer.md index e6e6d9eff..6d274b946 100644 --- a/docs/voltohandson/footer.md +++ b/docs/voltohandson/footer.md @@ -34,29 +34,31 @@ Then, we replace the `Footer` component content to match the one from plone.org. - About Plone + About Plone - Try Plone + Try Plone - Download Plone + + Download Plone + - Documentation + Documentation - Training + Training - Security + Security - Roadmap + Roadmap - Github + Github @@ -64,26 +66,30 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Community + Community - Forum + Forum - Chat + Chat - Contribute code + + Contribute code + - Report an issue + Report an issue - News and events + + News and events + - Conference + Conference @@ -91,33 +97,39 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Foundation + Foundation - + Join the foundation - + - Board + + Board + - Donate + Donate - Sponsors + + Sponsors + - + Code of conduct - + - Foundation members + + Foundation members + - Shop + Shop @@ -125,9 +137,9 @@ Then, we replace the `Footer` component content to match the one from plone.org. - + Follow us - + @@ -135,17 +147,17 @@ Then, we replace the `Footer` component content to match the one from plone.org. - + Mastodon - + - Twitter + Twitter - + Instagram - + @@ -154,19 +166,19 @@ Then, we replace the `Footer` component content to match the one from plone.org. - + YouTube - + - + Linkedin - + - + Facebook - + @@ -177,7 +189,9 @@ Then, we replace the `Footer` component content to match the one from plone.org. - Privacy Policy + + Privacy Policy + From a04924cdc50215056d61f1d167c1788b1c93d3e3 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Mon, 16 Oct 2023 14:33:07 +0200 Subject: [PATCH 12/42] Update introtoblocks.md Fixed the Import Path --- docs/voltohandson/introtoblocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/introtoblocks.md b/docs/voltohandson/introtoblocks.md index b1fae6dc9..7743c550b 100644 --- a/docs/voltohandson/introtoblocks.md +++ b/docs/voltohandson/introtoblocks.md @@ -116,7 +116,7 @@ export { SliderBlockEdit, SliderBlockView }; We need to configure the project to make it aware of a new block by adding it to the object configuration for that we need the 2 blocks components we created and a svg icon that will be displayed in the blocks chooser. This will again be done in the projects config file: ```js -import { SliderBlockView, SliderBlockEdit } from "./customizations/components/index.js"; +import { SliderBlockView, SliderBlockEdit } from "./components/"; import heroSVG from "@plone/volto/icons/hero.svg"; ``` From 774456992b9e98e4a7dba7eff235aea4edba9ee5 Mon Sep 17 00:00:00 2001 From: Molochem <140883099+Molochem@users.noreply.github.com> Date: Mon, 16 Oct 2023 14:44:35 +0200 Subject: [PATCH 13/42] Update footer.md Grammar changes at the Request of @jackkahl --- docs/voltohandson/footer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/footer.md b/docs/voltohandson/footer.md index 6d274b946..f5c682d88 100644 --- a/docs/voltohandson/footer.md +++ b/docs/voltohandson/footer.md @@ -224,7 +224,7 @@ Then, we replace the `Footer` component content to match the one from plone.org.
``` -And we Add this styling to the `custom.overrides` file: +And add this styling to the `custom.overrides` file: ```less //Footer From a9e97272f3672021548bd6f50bad99404435e13b Mon Sep 17 00:00:00 2001 From: Gil Forcada Codinachs Date: Thu, 19 Oct 2023 15:17:30 +0200 Subject: [PATCH 14/42] Fix mentioned filename extension --- docs/theming/theme_diazo.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/theming/theme_diazo.md b/docs/theming/theme_diazo.md index cd6a016aa..139199ee3 100644 --- a/docs/theming/theme_diazo.md +++ b/docs/theming/theme_diazo.md @@ -707,9 +707,9 @@ For example if you install a JQuery library you will find all JavaScript and CSS ## Adjust the layout and manifest files -We need to adjust a bit the `manifest.ini`, to reflect the layout structure of the Bootstrap theme we got. +We need to adjust a bit the `manifest.cfg`, to reflect the layout structure of the Bootstrap theme we got. -By default the `manifest.ini` will look like this: +By default the `manifest.cfg` will look like this: ```ini [theme] From c7b047f9e8c609bb1d1a14f86647d387e08f2076 Mon Sep 17 00:00:00 2001 From: Andreas Jung Date: Tue, 24 Oct 2023 10:44:58 +0200 Subject: [PATCH 15/42] documentation bug for #818 regarding basePath --- docs/mastering-plone/relations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/mastering-plone/relations.md b/docs/mastering-plone/relations.md index 1cae93711..5bc9e8b61 100644 --- a/docs/mastering-plone/relations.md +++ b/docs/mastering-plone/relations.md @@ -129,7 +129,9 @@ relationlist_field = RelationList( directives.widget( "relationlist_field", RelatedItemsFieldWidget, - pattern_options=make_relation_root_path, + pattern_options={ + "basePath": make_relation_root_path, + } ) ``` From 747795d14f336de3e9b2a8544035bb1038b68dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Tue, 24 Oct 2023 19:33:31 +0200 Subject: [PATCH 16/42] Remove TODO StaticCatalogVocabulary in Volto --- docs/mastering-plone/relations.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/mastering-plone/relations.md b/docs/mastering-plone/relations.md index 5bc9e8b61..91b3b9a4c 100644 --- a/docs/mastering-plone/relations.md +++ b/docs/mastering-plone/relations.md @@ -111,7 +111,7 @@ directives.widget( ) ``` -`basePath` can also be a method. In this exmaple we use the helper-method `plone.app.multilingual.browser.interfaces.make_relation_root_path`. +`basePath` can also be a method. In this example we use the helper-method `plone.app.multilingual.browser.interfaces.make_relation_root_path`. ```{code-block} python :emphasize-lines: 13 @@ -138,7 +138,7 @@ directives.widget( ### Using the search mode of the Related Items Widget ```{note} -These settings only have a effect in Plone 6 Classic. +These settings only have an effect in Plone 6 Classic. ``` So far we only used the vocabulary `plone.app.vocabularies.Catalog` that returns the full content tree. @@ -303,10 +303,6 @@ RelationList: ## Using different widgets for relations -```{todo} -Support for `StaticCatalogVocabulary` in Volto is currently still missing. -``` - Often the standard widget for relations is not what you want since it can be hard to navigate to the content you want to relate to. If you want to use checkboxes, radiobuttons or a selection-dropdown you need to use `StaticCatalogVocabulary` instead of `CatalogSource` to specify your options. From 617457eeb69da5c6a224ce31f87cf0f02b6d8b76 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 29 Oct 2023 21:55:07 -0700 Subject: [PATCH 17/42] Remove regex from sphinx-copybutton config, now that linenos are excluded by default See https://sphinx-copybutton.readthedocs.io/en/latest/use.html#automatic-exclusion-of-prompts-from-the-copies See also https://github.com/plone/documentation/pull/1563 --- docs/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 28822bd76..1bd5ac58d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -220,10 +220,6 @@ '', ] -# -- sphinx_copybutton ----------------------- -copybutton_prompt_text = r"^ {0,2}\d{1,3}" -copybutton_prompt_is_regexp = True - # -- sphinx.ext.todo ----------------------- todo_include_todos = True # Uncomment to show todos. From f621f29c6df0bee73995a178a495a5c73daf54c0 Mon Sep 17 00:00:00 2001 From: Gil Forcada Codinachs Date: Tue, 14 Nov 2023 16:34:25 +0100 Subject: [PATCH 18/42] Minor typos --- docs/theming/theme_scratch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/theming/theme_scratch.md b/docs/theming/theme_scratch.md index 0fd10ff23..910e794de 100644 --- a/docs/theming/theme_scratch.md +++ b/docs/theming/theme_scratch.md @@ -132,7 +132,7 @@ If everything works as expected next step is to start up your instance for the f ## Startup -We recommend to swith to your SDK here. If you're using Visual Studio Code you can open a terminal `Terminal > New Terminal` and run the following commands inside your editor. This helps you to keep track of windows and processes. +We recommend to switch to your IDE here. If you're using Visual Studio Code you can open a terminal `Terminal > New Terminal` and run the following commands inside your editor. This helps you to keep track of windows and processes. Start your instance for the very first time: From 5fca1bf2574e34ce176941ae9ff13deecfc90cf1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 19 Nov 2023 08:48:02 -0800 Subject: [PATCH 19/42] JSX is now an official lexer in Pygments --- requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 3b5e757cb..d92b4a0a8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,6 @@ -c constraints.txt Sphinx -jsx-lexer lesscpy linkify-it-py myst-parser From a5091eb20056476e2b42bfbc0402e5b00a6d1b3c Mon Sep 17 00:00:00 2001 From: Ujjwal Sinha Date: Thu, 14 Dec 2023 01:45:11 +0530 Subject: [PATCH 20/42] Corrected 4 Typos --- docs/mastering-plone-5/behaviors_1.md | 2 +- docs/mastering-plone-5/dexterity_reference.md | 2 +- docs/mastering-plone/about_mastering.md | 2 +- docs/mastering-plone/features.md | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/mastering-plone-5/behaviors_1.md b/docs/mastering-plone-5/behaviors_1.md index 369499c1f..629a51088 100644 --- a/docs/mastering-plone-5/behaviors_1.md +++ b/docs/mastering-plone-5/behaviors_1.md @@ -198,6 +198,6 @@ We must add the behavior to {file}`profiles/default/types/talk.xml`: ``` -[plone5_fieldset]: https://5.docs.plone.org/develop/addons/schema-driven-forms/customising-form-behaviour/fieldsets.html?highlight=fieldset +[plone5_fieldset]: https://5.docs.plone.org/develop/addons/schema-driven-forms/customizing-form-behaviour/fieldsets.html?highlight=fieldset [plone5_iformfieldprovider]: https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/custom-add-and-edit-forms.html?highlight=iformfieldprovider#edit-forms [plone5_plone.supermodel]: https://5.docs.plone.org/external/plone.app.dexterity/docs/schema-driven-types.html#schema-interfaces-vs-other-interfaces diff --git a/docs/mastering-plone-5/dexterity_reference.md b/docs/mastering-plone-5/dexterity_reference.md index 27dfcf007..f2adc7d36 100644 --- a/docs/mastering-plone-5/dexterity_reference.md +++ b/docs/mastering-plone-5/dexterity_reference.md @@ -711,7 +711,7 @@ class IMyEvent(model.Schema): To learn more about directives, validators and default values, refer to the following: - [Form schema hints and directives](https://5.docs.plone.org/external/plone.app.dexterity/docs/reference/form-schema-hints.html) -- [Validation](https://5.docs.plone.org/develop/addons/schema-driven-forms/customising-form-behaviour/validation.html) (this documentation unfortunately still uses the obsolete grok technology) +- [Validation](https://5.docs.plone.org/develop/addons/schema-driven-forms/customizing-form-behaviour/validation.html) (this documentation unfortunately still uses the obsolete grok technology) - [z3c.form documentation](https://z3cform.readthedocs.io/en/latest/advanced/validator.html) - [Default values for fields on add forms](https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/defaults.html) ``` diff --git a/docs/mastering-plone/about_mastering.md b/docs/mastering-plone/about_mastering.md index e4d24c40e..b0b803631 100644 --- a/docs/mastering-plone/about_mastering.md +++ b/docs/mastering-plone/about_mastering.md @@ -31,7 +31,7 @@ Thank you for reading and your charity with non-native English speakers / writer ## Upcoming Trainings -Next Plone Conference, usually in october. +Next Plone Conference, usually in October. Announced on [plone.org](https://plone.org) If you want to have an on-site training or want to attend a public training, please ask for trainings on [community.plone.org](https://community.plone.org) or one of the {ref}`trainers`. diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index a0ae4773c..b503f494e 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -14,7 +14,7 @@ myst: % TODO Short appetizer on all the fancy features. Now we create a Plone instance and take a look at all the features you can use as an integrator. -Developers get a glimps on the features that can be modified easily. +Developers get a glimpse on the features that can be modified easily. (features-start-stop-label)= @@ -44,7 +44,7 @@ Zope instance is up and running, ready to create a Plone instance. We now have a running Zope with a database, but no content. -Push the botton {guilabel}`Create a new Plone site`. +Push the button {guilabel}`Create a new Plone site`. Log in with `admin` and password `secret`. The initial login is defined in file `instance.yaml`. You should change your password in production sites via `http://localhost:8080/acl_users/users/manage_users`. @@ -213,7 +213,7 @@ Edit the front page: - Change the title to `Plone Conference 2050, Solis Lacus, Mars`. - Remove the text blocks below the title by selecting all and deleting them. - Add some dummy text. -- Click somewhere in the text, press return and see the block beeing splitted. +- Click somewhere in the text, press return and see the block being splitted. - Save the page. If you have already content in your instance, you may want to delete it. @@ -554,7 +554,7 @@ You can even make a page, with or without sub pages, editable only by a group of Plone has an integrated mechanism to remember urls that where modified. A moved page is still available via the former url. -Additional to this behavior, a page can be explicitly made available under further urls. +Additional to this behaviour, a page can be explicitly made available under further urls. You can find the UI for adding alternative urls following the context menu {guilabel}`...`. From 32df15b54cf1b437b9ee964eaa0a18e10e5d96c0 Mon Sep 17 00:00:00 2001 From: Ujjwal Sinha Date: Thu, 14 Dec 2023 01:50:42 +0530 Subject: [PATCH 21/42] PR for #825 --- docs/mastering-plone-5/dexterity_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone-5/dexterity_reference.md b/docs/mastering-plone-5/dexterity_reference.md index f2adc7d36..f782b2b4f 100644 --- a/docs/mastering-plone-5/dexterity_reference.md +++ b/docs/mastering-plone-5/dexterity_reference.md @@ -701,7 +701,7 @@ class IMyEvent(model.Schema): required=False) @invariant - def validate_start_end(data): + def validate_start_end(data): if data.start is not None and data.end is not None: if data.start > data.end: raise Invalid(_('Start must be before the end.')) From 8afed5a856774664bf160f1f32eb85be81a47c0e Mon Sep 17 00:00:00 2001 From: Ujjwal Sinha <138270264+ujjwaleee26@users.noreply.github.com> Date: Thu, 14 Dec 2023 15:18:14 +0530 Subject: [PATCH 22/42] Update docs/mastering-plone-5/behaviors_1.md Co-authored-by: Steve Piercy --- docs/mastering-plone-5/behaviors_1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone-5/behaviors_1.md b/docs/mastering-plone-5/behaviors_1.md index 629a51088..d658131c9 100644 --- a/docs/mastering-plone-5/behaviors_1.md +++ b/docs/mastering-plone-5/behaviors_1.md @@ -198,6 +198,6 @@ We must add the behavior to {file}`profiles/default/types/talk.xml`: ``` -[plone5_fieldset]: https://5.docs.plone.org/develop/addons/schema-driven-forms/customizing-form-behaviour/fieldsets.html?highlight=fieldset +[plone5_fieldset]: https://5.docs.plone.org/develop/addons/schema-driven-forms/customising-form-behaviour/fieldsets.html [plone5_iformfieldprovider]: https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/custom-add-and-edit-forms.html?highlight=iformfieldprovider#edit-forms [plone5_plone.supermodel]: https://5.docs.plone.org/external/plone.app.dexterity/docs/schema-driven-types.html#schema-interfaces-vs-other-interfaces From 8a5ae575d78e592f0128eb30de67497d2243d7b1 Mon Sep 17 00:00:00 2001 From: Ujjwal Sinha Date: Thu, 14 Dec 2023 15:24:10 +0530 Subject: [PATCH 23/42] fix-#825 --- docs/mastering-plone-5/dexterity_reference.md | 4 ++-- docs/mastering-plone/features.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/mastering-plone-5/dexterity_reference.md b/docs/mastering-plone-5/dexterity_reference.md index f782b2b4f..27dfcf007 100644 --- a/docs/mastering-plone-5/dexterity_reference.md +++ b/docs/mastering-plone-5/dexterity_reference.md @@ -701,7 +701,7 @@ class IMyEvent(model.Schema): required=False) @invariant - def validate_start_end(data): + def validate_start_end(data): if data.start is not None and data.end is not None: if data.start > data.end: raise Invalid(_('Start must be before the end.')) @@ -711,7 +711,7 @@ class IMyEvent(model.Schema): To learn more about directives, validators and default values, refer to the following: - [Form schema hints and directives](https://5.docs.plone.org/external/plone.app.dexterity/docs/reference/form-schema-hints.html) -- [Validation](https://5.docs.plone.org/develop/addons/schema-driven-forms/customizing-form-behaviour/validation.html) (this documentation unfortunately still uses the obsolete grok technology) +- [Validation](https://5.docs.plone.org/develop/addons/schema-driven-forms/customising-form-behaviour/validation.html) (this documentation unfortunately still uses the obsolete grok technology) - [z3c.form documentation](https://z3cform.readthedocs.io/en/latest/advanced/validator.html) - [Default values for fields on add forms](https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/defaults.html) ``` diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index b503f494e..f9b9c1232 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -554,7 +554,7 @@ You can even make a page, with or without sub pages, editable only by a group of Plone has an integrated mechanism to remember urls that where modified. A moved page is still available via the former url. -Additional to this behaviour, a page can be explicitly made available under further urls. +Additional to this behavior, a page can be explicitly made available under further urls. You can find the UI for adding alternative urls following the context menu {guilabel}`...`. From 8e69e6525c61e00e17500f9a24e10f14f7d52f22 Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Tue, 19 Dec 2023 13:26:23 +0530 Subject: [PATCH 24/42] Update glossary.md - smoother language, - clearer explanations, - improved grammar. --- docs/glossary.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index aab0baac7..94a22a74d 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -28,7 +28,7 @@ ZODB [A native object database for Python](https://zodb.org/en/latest/). Barceloneta - The default theme for Plone 5. + The Default Theme for Plone 5. CMS Content Management System @@ -59,7 +59,7 @@ NFS [Network File System](https://en.wikipedia.org/wiki/Network_File_System). Amazon Opsworks - [AWS OpsWorks](https://aws.amazon.com/opsworks/) is a configuration management service that uses Chef, an automation platform that treats server configurations as code. + [AWS OpsWorks](https://aws.amazon.com/opsworks/) is a configuration management service which uses Chef, an automation platform that treats server configurations as code. Ansible [Ansible](https://www.ansible.com/) is an open source automation platform. @@ -69,10 +69,10 @@ Archetypes The deprecated framework for building content types in Plone. Chef - [A configuration management tool written in Ruby and Erlang](https://www.chef.io/products/chef-infra/). + [A configuration management tool in Ruby and Erlang](https://www.chef.io/products/chef-infra/). CloudFormation - [AWS CloudFormation](https://aws.amazon.com/cloudformation/) gives developers and systems administrators an way to create and manage a collection of related AWS resources, provisioning and updating them in an orderly and predictable fashion. + [AWS CloudFormation](https://aws.amazon.com/cloudformation/) gives developers and systems administrators a powerful way to create and manage a collection of related AWS resources, provisioning and updating them in an orderly and predictable fashion. Travis CI Travis CI is a hosted, distributed continuous integration service used to build and test software projects hosted at GitHub. @@ -92,7 +92,7 @@ Dexterity [Dexterity](https://github.com/plone/plone.dexterity), the base framework for building content types, both through-the-web and as filesystem code for Zope. Dublin Core - The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, etc.), as well as physical resources such as books or CDs, and objects like artworks. + The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, etc.). It can also be used to describe physical resources such as books or CDs, and objects like artworks. ZMI The Zope Management Interface. @@ -118,7 +118,7 @@ Rapido application It is a folder containing templates, Python code, and YAML files. block - Blocks display a chunk of HTML which can be inserted in your Plone pages. + Blocks display chunks of HTML that can be inserted into your Plone pages. element Elements are the dynamic components of your blocks. @@ -155,14 +155,14 @@ Webpack Webpack entrypoint The main files generated by webpack as a result. They typically contain the application source code based on modules bundled together, but it can also include other resources, such as static resources. - It can contain code to automatically trigger the load of other JavaScript code files called "chunks". + They can contain code to automatically trigger the load of other JavaScript code files called "chunks". Babel - A JavaScript compiler that "transpiles" newer standards JavaScript to something that any browser can load. + A JavaScript compiler that "translates" newer standards JavaScript to something that any browser can load. Express - A JavaScript HTTP server with a simple API to build custom applications. - Volto uses it as its server. + A JavaScript HTTP server with a simple API, to build custom applications. + Volto uses it as its web server. Server-Side Rendering (SSR) When first loading any Plone page, users will get HTML markup that closely matches the final DOM structure of the React components used to render that page. @@ -184,7 +184,7 @@ Transpilation The transformation of JavaScript code that uses advanced language features, unavailable for some browsers, to code rewritten to support them. ES6 - ECMAScript 6, a newer version of the JavaScript language. + ECMAScript 6 (ES6), a newer version of the JavaScript language that introduces features like arrow functions and classes. mrs-developer Also called "missdev", a tool similar to buildout's `mr.developer`. @@ -276,10 +276,10 @@ plonecli GenericSetup [GenericSetup](https://5.docs.plone.org/develop/addons/components/genericsetup.html) is a framework to modify the Plone site during add-on package installation and uninstallation. - It provides XML-based rules to change the site settings. + It provides XML-based rules to change the configuration settings. cookiecutter-plone-starter - [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter` template, created by the Plone community, to bootstrap + [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter`-template, created by the Plone community, to bootstrap a new Plone 6 project using Volto and a relational database. Traefik @@ -294,4 +294,4 @@ Nginx Varnish [Varnish](https://varnish-cache.org/intro/) is a high-performance HTTP accelerator and reverse proxy caching server designed to speed up web applications by caching content in memory. - It serves stored content to users quickly, reducing the load on web servers and enhancing the overall user experience by delivering web pages at high speed. \ No newline at end of file + It serves stored content to users quickly, reducing the load on web servers and enhancing the overall user experience by delivering web pages at high speed. From 8cf011fdd5b88eebd9c8911e84052d17e4471d17 Mon Sep 17 00:00:00 2001 From: vivek kumar Date: Wed, 20 Dec 2023 10:25:00 +0530 Subject: [PATCH 25/42] Address reviewer feedback --- docs/glossary.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 94a22a74d..f87c5ae65 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -28,7 +28,7 @@ ZODB [A native object database for Python](https://zodb.org/en/latest/). Barceloneta - The Default Theme for Plone 5. + The default theme for Plone 5. CMS Content Management System @@ -59,7 +59,7 @@ NFS [Network File System](https://en.wikipedia.org/wiki/Network_File_System). Amazon Opsworks - [AWS OpsWorks](https://aws.amazon.com/opsworks/) is a configuration management service which uses Chef, an automation platform that treats server configurations as code. + [AWS OpsWorks](https://aws.amazon.com/opsworks/) is a configuration management service that uses Chef, an automation platform that treats server configurations as code. Ansible [Ansible](https://www.ansible.com/) is an open source automation platform. @@ -69,10 +69,10 @@ Archetypes The deprecated framework for building content types in Plone. Chef - [A configuration management tool in Ruby and Erlang](https://www.chef.io/products/chef-infra/). + [A configuration management tool written in Ruby and Erlang](https://www.chef.io/products/chef-infra/). CloudFormation - [AWS CloudFormation](https://aws.amazon.com/cloudformation/) gives developers and systems administrators a powerful way to create and manage a collection of related AWS resources, provisioning and updating them in an orderly and predictable fashion. + [AWS CloudFormation](https://aws.amazon.com/cloudformation/) gives developers and systems administrators a way to create and manage a collection of related AWS resources, provisioning and updating them in an orderly and predictable fashion. Travis CI Travis CI is a hosted, distributed continuous integration service used to build and test software projects hosted at GitHub. @@ -92,7 +92,8 @@ Dexterity [Dexterity](https://github.com/plone/plone.dexterity), the base framework for building content types, both through-the-web and as filesystem code for Zope. Dublin Core - The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, etc.). It can also be used to describe physical resources such as books or CDs, and objects like artworks. + The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, and other online content). + It can also be used to describe physical resources such as books or CDs, and objects like artworks. ZMI The Zope Management Interface. @@ -158,11 +159,11 @@ Webpack entrypoint They can contain code to automatically trigger the load of other JavaScript code files called "chunks". Babel - A JavaScript compiler that "translates" newer standards JavaScript to something that any browser can load. + A JavaScript compiler that "transpiles" newer standards JavaScript to something that any browser can load. Express - A JavaScript HTTP server with a simple API, to build custom applications. - Volto uses it as its web server. + [Express](https://expressjs.com/) is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. + Volto uses Express. Server-Side Rendering (SSR) When first loading any Plone page, users will get HTML markup that closely matches the final DOM structure of the React components used to render that page. @@ -184,7 +185,9 @@ Transpilation The transformation of JavaScript code that uses advanced language features, unavailable for some browsers, to code rewritten to support them. ES6 - ECMAScript 6 (ES6), a newer version of the JavaScript language that introduces features like arrow functions and classes. +ECMAScript 6 + [ECMAScript 6 (ES6)](https://262.ecma-international.org/6.0/) is a scripting language specification on which [JavaScript](https://developer.mozilla.org/en-US/docs/Glossary/JavaScript) is based. + [Ecma International](https://www.ecma-international.org/) is in charge of standardizing ECMAScript. mrs-developer Also called "missdev", a tool similar to buildout's `mr.developer`. @@ -279,7 +282,7 @@ GenericSetup It provides XML-based rules to change the configuration settings. cookiecutter-plone-starter - [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter`-template, created by the Plone community, to bootstrap + [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter` template, created by the Plone community, to bootstrap a new Plone 6 project using Volto and a relational database. Traefik From ad3bf953ffdc9e80893216d27857b0180cf86542 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Sat, 30 Dec 2023 16:10:05 +0100 Subject: [PATCH 26/42] Fix link to installation instructions (missing Sphinx label) --- docs/mastering-plone/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone/installation.md b/docs/mastering-plone/installation.md index 43946263f..b88342d40 100644 --- a/docs/mastering-plone/installation.md +++ b/docs/mastering-plone/installation.md @@ -146,7 +146,7 @@ You have two options: ### Option 1: Frontend from scratch with Volto generator -{ref}`plone6docs:frontend-getting-started-installing-volto-label` +Follow the instructions of `docs.plone.org`: {doc}`plone6docs:volto/recipes/creating-project`. ### Option 2. Start with prepared training project `volto-ploneconf` with all code for the training From 846f882dd7df0d8f1d13290552a5e2705bbe934b Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Sun, 14 Jan 2024 19:57:50 +0530 Subject: [PATCH 27/42] Update features.md I, Vivek Kumar , agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation. description : Revamped documentation language for enhanced readability --- docs/mastering-plone/features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index f9b9c1232..8123979ed 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -216,8 +216,8 @@ Edit the front page: - Click somewhere in the text, press return and see the block being splitted. - Save the page. -If you have already content in your instance, you may want to delete it. -Go to `/contents` by clicking the folder icon in the toolbar. +If there is existing content in your instance, you might consider removing it. +Navigate to `/contents` by clicking the folder icon in the toolbar. Select all objects and delete them. Create a site structure: From 60da1080beac4d14c1d6df7c2a73bb6b81ae379d Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Mon, 22 Jan 2024 00:07:22 +0530 Subject: [PATCH 28/42] Spelling Error inside the training docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit description : spelling error ✅type ❌typ I, Vivek Kumar , agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation. --- docs/mastering-plone/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index 8123979ed..1f2ce70b6 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -289,7 +289,7 @@ Event Image : Like file but png, jpeg or other image types. - The Image content typ has an image field. + The Image content type has an image field. Values of the image field are saved in multiple scales to be accessible easily when rendering. ```{figure} _static/features_add_a_image.png From 98e63b0b8b948bd9d5b2a968355d4201f555c259 Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Wed, 24 Jan 2024 08:00:24 +0530 Subject: [PATCH 29/42] Correct spelling errors and include omitted words in the documentation. I'm reading the Volto Hands-On documentation, and I've encountered some mistakes. I've raised a pull request to correct the errors. I, Vivek Kumar, agree to have this contribution published under the Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation. --- docs/voltohandson/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/voltohandson/quickstart.md b/docs/voltohandson/quickstart.md index 4b3cb7c06..c256b9e00 100644 --- a/docs/voltohandson/quickstart.md +++ b/docs/voltohandson/quickstart.md @@ -18,7 +18,7 @@ To create our first volto project we will install the volto generator tool (http ```shell yo @plone/volto ``` -The dialogue in the console will ask you first to prompt a name for your project. When choosing an apropriate name, please note that due to a current bug your name should not begin with a number. After you have given a name to your project, you will be a wether you want to install any addons. You can skip by pressing the `enter` button, as we dont want to use any 3rd party addons for the training. +The dialogue in the console will ask you first to prompt a name for your project. When choosing an appropriate name, please note that due to a current bug your name should not begin with a number. After you have given a name to your project, you will be asked weather you want to install any addons. You can skip by pressing the `enter` button, as we don't want to use any third-party addons for the training. ```{hint} In case you want to install any addons you can find a curated list of addons of all different sorts here: https://github.com/collective/awesome-volto From 8ba46dfe206c741b4075266654f71d290a9ad946 Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Thu, 25 Jan 2024 18:17:05 +0530 Subject: [PATCH 30/42] Update docs/voltohandson/quickstart.md Co-authored-by: Steve Piercy --- docs/voltohandson/quickstart.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/voltohandson/quickstart.md b/docs/voltohandson/quickstart.md index c256b9e00..1065cebc6 100644 --- a/docs/voltohandson/quickstart.md +++ b/docs/voltohandson/quickstart.md @@ -18,7 +18,10 @@ To create our first volto project we will install the volto generator tool (http ```shell yo @plone/volto ``` -The dialogue in the console will ask you first to prompt a name for your project. When choosing an appropriate name, please note that due to a current bug your name should not begin with a number. After you have given a name to your project, you will be asked weather you want to install any addons. You can skip by pressing the `enter` button, as we don't want to use any third-party addons for the training. +The dialogue in the console will first prompt you for a name for your project. +When choosing an appropriate name, please note that due to a current bug, your name should not begin with a number. +After you have given a name to your project, you will be asked whether you want to install any add-ons. +You can skip ahead by pressing the {kbd}`enter` button, as we don't want to use any third-party add-ons for the training. ```{hint} In case you want to install any addons you can find a curated list of addons of all different sorts here: https://github.com/collective/awesome-volto From 73aff0bd5290eed490788f1d6126002477b5b9f2 Mon Sep 17 00:00:00 2001 From: Vivek Kumar <91373023+Vivek-04022001@users.noreply.github.com> Date: Fri, 26 Jan 2024 18:55:41 +0530 Subject: [PATCH 31/42] Enhance Path Handling in Makefile --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index ff0c42d6f..1a1724f23 100644 --- a/Makefile +++ b/Makefile @@ -3,8 +3,8 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = $(realpath bin/sphinx-build) -SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild) +SPHINXBUILD = "$(realpath bin/sphinx-build)" +SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)" PAPER = DOCS_DIR = ./docs/ BUILDDIR = ../_build From f9bc774226ea74ab7862d2039a9ae89c3350c046 Mon Sep 17 00:00:00 2001 From: Mudit Choudhary <74391865+muditchoudhary@users.noreply.github.com> Date: Wed, 21 Feb 2024 09:13:18 +0530 Subject: [PATCH 32/42] fix: Fix a typo --- docs/mastering-plone/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index 1f2ce70b6..fafdbf9fd 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -274,7 +274,7 @@ Page News Item -: Basically a page with an image and an image caption to be used for press releases an such. +: Basically a page with an image and an image caption to be used for press releases as such. ```{figure} _static/features_add_a_news_item.png ``` From 0cf5a2ab88e6c263a3ff185a4ddbdbe9e084800e Mon Sep 17 00:00:00 2001 From: Mudit Choudhary <74391865+muditchoudhary@users.noreply.github.com> Date: Wed, 21 Feb 2024 14:24:39 +0530 Subject: [PATCH 33/42] fix: typos --- docs/mastering-plone/features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mastering-plone/features.md b/docs/mastering-plone/features.md index fafdbf9fd..15ff92b4a 100644 --- a/docs/mastering-plone/features.md +++ b/docs/mastering-plone/features.md @@ -238,7 +238,7 @@ The view of the newly created site structure ``` Additional to these conference pages we also want some news and events. -We want a registration page and an a protected section for the conference team. +We want a registration page and a protected section for the conference team. - Add a page "News" - In `/news`: Add a News Item "Conference Website online!" with some image @@ -274,7 +274,7 @@ Page News Item -: Basically a page with an image and an image caption to be used for press releases as such. +: Basically a page with an image and an image caption to be used for press releases and such. ```{figure} _static/features_add_a_news_item.png ``` From abf77dc134f9df06c11c1d3b19eb44461e8af78c Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Wed, 13 Mar 2024 11:21:56 -0400 Subject: [PATCH 34/42] Update project.md Dead links for Plone Documentation --- docs/effective-volto/getting-started/project.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/effective-volto/getting-started/project.md b/docs/effective-volto/getting-started/project.md index 435dad01b..600b11a75 100644 --- a/docs/effective-volto/getting-started/project.md +++ b/docs/effective-volto/getting-started/project.md @@ -29,11 +29,11 @@ pip install cookiecutter ### nvm, Node.JS, Yeoman, and Yarn -First install `nvm` and latest Node.JS according to the [Plone documentation](https://6.docs.plone.org/volto/getting-started/install.html#install-nvm-nodejs-version-manager). +First install `nvm` and latest Node.JS according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). -After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/volto/getting-started/install.html#yeoman). +After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). -Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/volto/getting-started/install.html#yarn-nodejs-package-manager). +Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). ### Docker (optional, but recommended) From c63f4b7c610c5082b04f47e36798cbd8cb38b914 Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Wed, 13 Mar 2024 14:55:10 -0400 Subject: [PATCH 35/42] Update docs/effective-volto/getting-started/project.md Co-authored-by: Steve Piercy --- docs/effective-volto/getting-started/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/effective-volto/getting-started/project.md b/docs/effective-volto/getting-started/project.md index 600b11a75..5fa2b92eb 100644 --- a/docs/effective-volto/getting-started/project.md +++ b/docs/effective-volto/getting-started/project.md @@ -31,7 +31,7 @@ pip install cookiecutter First install `nvm` and latest Node.JS according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). -After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). +After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#yeoman-and-the-volto-boilerplate-generator). Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). From 8b03d660ba7e3d452de1e064c4c79b036e297ba5 Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Wed, 13 Mar 2024 14:55:19 -0400 Subject: [PATCH 36/42] Update docs/effective-volto/getting-started/project.md Co-authored-by: Steve Piercy --- docs/effective-volto/getting-started/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/effective-volto/getting-started/project.md b/docs/effective-volto/getting-started/project.md index 5fa2b92eb..40bb00fe7 100644 --- a/docs/effective-volto/getting-started/project.md +++ b/docs/effective-volto/getting-started/project.md @@ -29,7 +29,7 @@ pip install cookiecutter ### nvm, Node.JS, Yeoman, and Yarn -First install `nvm` and latest Node.JS according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). +First install `nvm` and latest Node.JS according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#nvm). After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#yeoman-and-the-volto-boilerplate-generator). From 209e5620bd8334f4440d61f316f41b04d0396ff8 Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Wed, 13 Mar 2024 15:01:45 -0400 Subject: [PATCH 37/42] Update docs/effective-volto/getting-started/project.md Co-authored-by: Steve Piercy --- docs/effective-volto/getting-started/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/effective-volto/getting-started/project.md b/docs/effective-volto/getting-started/project.md index 40bb00fe7..454af4f6c 100644 --- a/docs/effective-volto/getting-started/project.md +++ b/docs/effective-volto/getting-started/project.md @@ -33,7 +33,7 @@ First install `nvm` and latest Node.JS according to the [Plone documentation](ht After that, install Yeoman according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#yeoman-and-the-volto-boilerplate-generator). -Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#pre-requisites-for-installation). +Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/install/create-project.html#yarn). ### Docker (optional, but recommended) From 1ba3a2c4233bac895e32fd671cf1dcbbe1a0ae3b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 13 Mar 2024 21:39:50 -0700 Subject: [PATCH 38/42] Bump versions --- .github/workflows/build_deploy.yml | 4 ++-- .github/workflows/test.yml | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml index e36259a19..a7eb4251f 100644 --- a/.github/workflows/build_deploy.yml +++ b/.github/workflows/build_deploy.yml @@ -16,9 +16,9 @@ jobs: - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: - python-version: "3.10" + python-version: "3.12" cache: 'pip' - name: Install dependencies diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c2a005df1..3f0f98f25 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -7,12 +7,12 @@ jobs: if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: - python-version: "3.10" + python-version: "3.12" - name: Install dependencies run: | From 0ece78921553d9f5ec593e1b4fbb31bcf5317907 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 13 Mar 2024 21:40:06 -0700 Subject: [PATCH 39/42] Remove tasks that are already performed in test.yml --- .github/workflows/build_deploy.yml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml index a7eb4251f..ae8930209 100644 --- a/.github/workflows/build_deploy.yml +++ b/.github/workflows/build_deploy.yml @@ -26,18 +26,6 @@ jobs: python -m pip install --upgrade pip pip install -q -r requirements.txt -c constraints.txt pip freeze - sudo snap install --edge vale - - - name: Run Vale - run: | - git clone https://github.com/errata-ai/Microsoft.git - cp -r ./Microsoft/Microsoft ./styles - VALEFILES=$(find ./docs/ -type f -name "*.md" -print) - vale --no-exit $VALEFILES - - # TODO Raise linkcheck barrier again. - # - name: Run linkcheck - # run: make linkcheck - name: Prepare deploy run: make deploy From 7c3d4b51d32c1c37fb7cb731a7b9f3a20a12846e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 13 Mar 2024 22:08:47 -0700 Subject: [PATCH 40/42] Include vale and pin to a supported version --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index d92b4a0a8..0430482f4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,3 +12,4 @@ sphinx-sitemap sphinx-togglebutton sphinxcontrib-spelling sphinxext-opengraph +vale==2.30.0 From 3e194d6616584099dd1257a6189519f3a1a404ce Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Thu, 21 Mar 2024 09:19:37 -0400 Subject: [PATCH 41/42] Update volto_frontpage.md --- docs/mastering-plone/volto_frontpage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mastering-plone/volto_frontpage.md b/docs/mastering-plone/volto_frontpage.md index 6e9c46c4e..514683bf5 100644 --- a/docs/mastering-plone/volto_frontpage.md +++ b/docs/mastering-plone/volto_frontpage.md @@ -57,14 +57,14 @@ To understand why we need a collection criterion for a dynamic frontpage in Volt :align: left ``` -In the sidebar we see the `criteria` selection and if we click there, it'll show some of the selectable criterions ordered in categories like the following: +In the sidebar we see the `criteria` selection and if we click there, it'll show some of the selectable criteria ordered in categories like the following: - `Metadata` contains indexes that are counting as metadata like Type (means Portal Types) and Review State - `Text` contains indexes that are counting as text-data like Description and Searchable Text - `Dates` contains indexes which are working with date-data like Effective Date and Creation Date To get all talks we marked as `featured` we have to get the listing block to recognize our newly created index. -This means we have to add our index to the collection criterions, so we can select it. +This means we have to add our index to the collection criteria, so we can select it. To add our new index as a criterion to be appliable in a listing block or a collection, we have to switch to our `backend`. There we have to create a plone.app.registry record for our index. This can be achieved by adding a new file {file}`profiles/default/registry/querystring.xml`: From ebf4667e72658fdac089ff25a16e448c67a79211 Mon Sep 17 00:00:00 2001 From: Koran Agan Date: Fri, 22 Mar 2024 08:44:59 -0400 Subject: [PATCH 42/42] Update docs/mastering-plone/volto_frontpage.md Co-authored-by: Steve Piercy --- docs/mastering-plone/volto_frontpage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone/volto_frontpage.md b/docs/mastering-plone/volto_frontpage.md index 514683bf5..1c1ac42b7 100644 --- a/docs/mastering-plone/volto_frontpage.md +++ b/docs/mastering-plone/volto_frontpage.md @@ -57,7 +57,7 @@ To understand why we need a collection criterion for a dynamic frontpage in Volt :align: left ``` -In the sidebar we see the `criteria` selection and if we click there, it'll show some of the selectable criteria ordered in categories like the following: +In the sidebar, we see the {guilabel}`Criteria` select menu, and if we click there, it'll show some of the selectable criteria ordered in categories like the following: - `Metadata` contains indexes that are counting as metadata like Type (means Portal Types) and Review State - `Text` contains indexes that are counting as text-data like Description and Searchable Text