diff --git a/docs/source/addons/best-practices.md b/docs/source/addons/best-practices.md index e58eb3c8e2..1b9ae38cc5 100644 --- a/docs/source/addons/best-practices.md +++ b/docs/source/addons/best-practices.md @@ -73,15 +73,15 @@ hold the Cypress integration tests and trigger the CI tests. If you're releasing your add-on to `npmjs.com`, please consider adding the following tags, next to your add-on-specific tags: -- volto-addon -- volto -- plone -- react +- `volto-addon` +- `volto` +- `plone` +- `react` -## Include in collective/awesome-volto +## Include in `collective/awesome-volto` Even if you think your add-on is not generic or it's tricky to integrate, please consider including your add-on in the -[collective/awesome-volto](https://github.com/collective/awesome-volto) add-ons +[`collective/awesome-volto`](https://github.com/collective/awesome-volto) add-ons list. This provides visibility to your add-on but also further solidifies Volto's possition in our Plone community. diff --git a/docs/source/addons/index.md b/docs/source/addons/index.md index b692529aa5..6eb16aa905 100644 --- a/docs/source/addons/index.md +++ b/docs/source/addons/index.md @@ -32,7 +32,7 @@ by Babel), whole-process customization via razzle.extend.js and integration with Volto's {term}`configuration registry`. ``` -The add-on can be published to an NPM registry or directly installed from github +The add-on can be published to an npm registry or directly installed from github by Yarn. By using [mrs-develop](https://github.com/collective/mrs-developer), it's possible to have a workflow similar to zc.buildout's mr.developer, where you can "checkout" an add-on for development. @@ -56,7 +56,7 @@ You can install a Volto add-on just like any other JS package: yarn add name-of-add-on ``` -If the add-on is not published on NPM, you can retrieve it directly from Github: +If the add-on is not published on npm, you can retrieve it directly from Github: ```shell yarn add collective/volto-dropdownmenu @@ -74,7 +74,7 @@ configurations methods, making it possible to selectively choose which specific add-on functionality you want to load. In your Volto project's ``package.json`` you can allow the add-on to alter the -global configuration by adding, in the `addons` key, a list of volto add-on +global configuration by adding, in the `addons` key, a list of Volto add-on package names, like: ```js @@ -439,9 +439,9 @@ in your add-on's `addons` key, just like you do in your project. By doing so, that other add-on's configuration loader is executed first, so you can depend on the configuration being already applied. Another benefit is that you'll have to declare only the "top level" add-on in your project, the dependencies will be -discovered and automatically treated as Volto add-ons. For example, volto-slate -depends on volto-object-widget's configuration being already applied, so -volto-slate can declare in its `package.json`: +discovered and automatically treated as Volto add-ons. For example, `volto-slate` +depends on `volto-object-widget`'s configuration being already applied, so +`volto-slate` can declare in its `package.json`: ```json { diff --git a/docs/source/backend/index.md b/docs/source/backend/index.md index 4b5c35a609..8fa6ff980b 100644 --- a/docs/source/backend/index.md +++ b/docs/source/backend/index.md @@ -40,11 +40,11 @@ Search and indexing integration Access to images and files are a special use case in Volto. Usually in plain HTML, `src` and `href` attributes resource calls cannot be wrapped in a JavaScript backend call. This is problematic when dealing with protected resources that need the user to be authenticated to access them. -For this reason, these resources are rerouted through an internal route in Node Express server and wrapped with the proper authentication headers. +For this reason, these resources are rerouted through an internal route in the Node.js Express server and wrapped with the proper authentication headers. These proxied backend routes are in place for accessing URLs containing `@@downloads` `@@display-file`, and `@@images` backend views. These are the backend `BrowserView`s routes that retrieve images and file resources. -Thus the Node Express server takes care of proxying and enhancing them at the same time as the authentication headers. +Thus the Node.js Express server takes care of proxying and enhancing them at the same time as the authentication headers. ```{todo} This section contains pointers for backend integration with Plone. diff --git a/docs/source/blocks/editcomponent.md b/docs/source/blocks/editcomponent.md index daae5580b7..50c5bc189a 100644 --- a/docs/source/blocks/editcomponent.md +++ b/docs/source/blocks/editcomponent.md @@ -21,7 +21,7 @@ The sidebar and the object browser are the main ones. ## Sidebar -We can use the new sidebar when building our blocks' edit components. +We can use the new sidebar when building our block's edit components. The sidebar is a new UI asset that is available in Volto 4. You need to instantiate it this way: @@ -195,19 +195,19 @@ this.props.openObjectBrowser({ This widget shows an objectBrowser to find content/contents on site. -It is the default widget for vocabulary fields that uses plone.app.vocabularies.Catalog. +It is the default widget for vocabulary fields that uses `plone.app.vocabularies.Catalog`. It works in 3 different mode: -- **image**: The field value is an object. - The path of selected item is saved in 'url' property of value object. (fieldName: {url:''}) -- **link**: The field value is an object. - The path of selected item is saved in 'href' property of value object. (fieldName: {href:''}) -- **multiple**: The field value is an array of objects. +- `image`: The field value is an object. + The path of selected item is saved in `url` property of value object. (`fieldName: {url:''}`) +- `link`: The field value is an object. + The path of selected item is saved in `href` property of value object. (`fieldName: {href:''}`) +- `multiple`: The field value is an array of objects. #### `return` prop -The object widget returns always an array, even if it's meant to have only one object in return. In order to fix that situation and do not issue a breaking change, a `return` prop is being introduced, so if it's value is `single`, then it returns a single value: +The object widget returns always an array, even if it's meant to have only one object in return. In order to fix that situation and do not issue a breaking change, a `return` prop is being introduced, so if its value is `single`, then it returns a single value: ```js export const Image = () => ; @@ -219,8 +219,8 @@ This situation will be fixed in subsequent Volto releases. #### PropDataName vs dataName -- **dataName** is the prop inside _data_ object, used for _link_ and _image_ mode. -- **PropDataName** is the name of field wich value is _data_. It's used for _multiple_ mode. +- `dataName` is the prop inside `data` object, used for `link` and `image` mode. +- `PropDataName` is the name of field wich value is `data`. It's used for `multiple` mode. For example: @@ -230,9 +230,9 @@ content:{ '@id': 'page-1', related_pages:[], image:{url:""}, link:{href:""} } if we use object browser widget for fields: -- **related_pages**: propDataName is _related_pages_ and dataName is null, -- **image**: dataName is _url_ and propDataName is null -- **link**: dataName is _href_ and propDataName is null +- `related_pages`: propDataName is `related_pages` and `dataName` is `null`. +- `image`: dataName is `url` and `propDataName` is `null`. +- `link`: dataName is `href` and `propDataName` is `null`. #### Usage in blocks schema @@ -273,7 +273,7 @@ tokenized value, as if it was selected via the Object Browser widget. #### ObjectBrowserWidgetMode() -Returns the component widget with _mode_ passed as argument. +Returns the component widget with `mode` passed as argument. The default mode for ObjectBrowserWidget is multiple. If you would like to use this widget with link or image mode as widget field for a specific field id (for example), you could specify in in config.js as: @@ -299,7 +299,7 @@ If `selectableTypes` is set in `widgetOptions.pattern_options`, then only items ``` -You can also set the _selectableTypes_ from plone when declaring a field for contenttype: +You can also set the `selectableTypes` from `plone` when declaring a field for `contenttype`: ```jsx form.widget( @@ -313,15 +313,15 @@ form.widget( ); ``` -#### MaximumSelectionSize +#### `maximumSelectionSize` -If **maximumSelectionSize** is set in _widgetOptions.pattern_options_, widget allows to select at most the **maximumSelectionSize** number of items defined in _widgetOptions.pattern_options.maximumSelectionSize_. +If `maximumSelectionSize` is set in `widgetOptions.pattern_options`, the widget allows to select at most the `maximumSelectionSize` number of items defined in `widgetOptions.pattern_options.maximumSelectionSize`. ```jsx ``` -You can also set the _maximumSelectionSize_ from plone when declaring a field for contenttype: +You can also set the `maximumSelectionSize` from `plone` when declaring a field for `contenttype`: ```jsx form.widget( @@ -429,15 +429,15 @@ class Example extends Component { The current block engine is available as the separate `BlocksForm` component, used to be a part of the `Form.jsx` component. It has been previously exposed -as the [@eeacms/volto-blocks-form](https://github.com/eea/volto-blocks-form) +as the [`@eeacms/volto-blocks-form`](https://github.com/eea/volto-blocks-form) addon and reused in several other addons, so you can find integration examples in addons such as -[volto-columns-block](https://github.com/eea/volto-columns-block), -[volto-accordion-block](https://github.com/rohberg/volto-accordion-block), -[@eeacms/volto-accordion-block](https://github.com/eea/volto-accordion-block), -[@eeacms/volto-grid-block](https://github.com/eea/volto-accordion-block), but +[`volto-columns-block`](https://github.com/eea/volto-columns-block), +[`volto-accordion-block`](https://github.com/rohberg/volto-accordion-block), +[`@eeacms/volto-accordion-block`](https://github.com/eea/volto-accordion-block), +[`@eeacms/volto-grid-block`](https://github.com/eea/volto-accordion-block), but probably the simplest implementation to follow is in the -[@eeacms/volto-group-block](https://github.com/eea/volto-group-block) +[`@eeacms/volto-group-block`](https://github.com/eea/volto-group-block) Notice that the `BlocksForm` component allows overriding the edit block wrapper and allows passing a custom `blocksConfig` configuration object, for @@ -507,6 +507,6 @@ You can also reuse the DragDropList component as a separate component: ``` -Check the source code of volto-columns-block and -[volto-taxonomy](https://github.com/eea/volto-taxonomy/) for details on +Check the source code of `volto-columns-block` and +[`volto-taxonomy`](https://github.com/eea/volto-taxonomy/) for details on how to reuse this component. diff --git a/docs/source/configuration/backend.md b/docs/source/configuration/backend.md index 4e11fcf0bb..b695c7419f 100644 --- a/docs/source/configuration/backend.md +++ b/docs/source/configuration/backend.md @@ -9,7 +9,7 @@ myst: # Backend configuration -## plone.volto +## `plone.volto` In order to fully support all Volto features, the Plone backend content API needs to be prepared for Volto. The add-on `plone.volto` does all the heavy lifting for you and is ready to use in your own projects. We used it in our Getting Started section. This package is slightly opinionated but provides the correct default settings for when diff --git a/docs/source/configuration/environmentvariables.md b/docs/source/configuration/environmentvariables.md index 4cb8f8b028..6c8e5f6a69 100644 --- a/docs/source/configuration/environmentvariables.md +++ b/docs/source/configuration/environmentvariables.md @@ -188,7 +188,7 @@ As a result, your app will load the add-ons in the following order: - `volto-slate` ```{important} -The `ADDONS` key is a Volto specific configuration. Simply setting `ADDONS` doesn't download the javascript package. This has to be covered by another way, either installing the addon package (with yarn add) or loading it as a development package with mrs-developer. +The `ADDONS` key is a Volto specific configuration. Simply setting `ADDONS` doesn't download the JavaScript package. This has to be covered by another way, either installing the addon package (with yarn add) or loading it as a development package with mrs-developer. ``` ## BUILD_DIR diff --git a/docs/source/configuration/expanders.md b/docs/source/configuration/expanders.md index 8e553eda89..de1bc7a008 100644 --- a/docs/source/configuration/expanders.md +++ b/docs/source/configuration/expanders.md @@ -4,7 +4,7 @@ myst: "description": "Configure the API expanders in Volto using the `settings.apiExpanders`" "property=og:description": "Configure the API expanders in Volto using the `settings.apiExpanders`" "property=og:title": "API expanders" - "keywords": "Volto, Plone, frontend, React, api expanders" + "keywords": "Volto, Plone, frontend, React, API expanders" --- # API expanders diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md index 93f4c0c9af..86bf599143 100644 --- a/docs/source/configuration/internalproxy.md +++ b/docs/source/configuration/internalproxy.md @@ -18,9 +18,9 @@ develop/test drive/demo Volto. To understand the need for the internal proxy, there are three processes running in a Volto website: -1. A frontend web application running in your browser (Javascript) -2. A Node.js server process that delivers the javascript to the client and does - {term}`server-side rendering` (SSR) of your pages on first request (Javascript, the +1. A frontend web application running in your browser (JavaScript) +2. A Node.js server process that delivers the JavaScript to the client and does + {term}`server-side rendering` (SSR) of your pages on first request (JavaScript, the Razzle package is used for SSR) 3. A Plone server process that stores and delivers all content through a REST API (Python) @@ -30,16 +30,16 @@ The default values from Volto configuration expect a Plone content backend locat What happens in the default development configuration/setup: -* The client side Volto javascript files precooked HTML (SSR) is served from http://localhost:3000/ by the NodeJS server process -* The client javascript does API requests for content and other data on the same url at http://localhost:3000/++api++/ -* The NodeJS service its internal proxy requests the data from the Plone content backend api and delivers +* The client side Volto JavaScript files precooked HTML (SSR) is served from http://localhost:3000/ by the Node.js server process +* The client JavaScript does API requests for content and other data on the same url at http://localhost:3000/++api++/ +* The Node.js service its internal proxy requests the data from the Plone content backend API and delivers back json to the frontend. * The web browser application is happy, because all connections go through the same URL and no CORS related security issues will be triggered. ```{tip} You could also use the internal proxy for production setups. For convenience and for testing/demoing using the stock build, it is also enabled in production mode since -Volto 14. But it is bad for performance because the server side running Node process +Volto 14. But it is bad for performance because the server side running Node.js process is also responsable for generating the SSR HTML. With nginx, Apache or another 'reverse proxy' you can also create an internal API mount which is more suited for that. For more deployment information see {doc}`../deploying/seamless-mode`. @@ -59,12 +59,13 @@ export const settings = { ``` or use the environment variable: + ```bash RAZZLE_DEV_PROXY_API_PATH=http://localhost:8081/mysite yarn start ``` -This redefines the request path from the internal proxy of the server side Node proces to the Plone content backend API, but leaves the frontend Volto process making all content requests to http://localhost:3000/++api++/ +This redefines the request path from the internal proxy of the server side Node.js process to the Plone content backend API, but leaves the frontend Volto process making all content requests to `http://localhost:3000/++api++/`. ### Advanced usage -See [](../recipes/environment-variables.md) for recipes on internal proxy usage. +See {doc}`../recipes/environment-variables` for recipes for internal proxy usage. diff --git a/docs/source/configuration/multilingual.md b/docs/source/configuration/multilingual.md index b8dad7d155..f9b7888f61 100644 --- a/docs/source/configuration/multilingual.md +++ b/docs/source/configuration/multilingual.md @@ -10,7 +10,7 @@ myst: # Multilingual Volto provide support for Plone's Multilingual feature. You need to install Multiligual -support in Plone (plone.app.multilingual add-on), that comes available by default since +support in Plone (`plone.app.multilingual` add-on), that comes available by default since Plone 5 and can be installed in Plone's control panel. ## Volto configuration diff --git a/docs/source/configuration/volto-slate/api.md b/docs/source/configuration/volto-slate/api.md index 9095aa3b11..aa0a867757 100644 --- a/docs/source/configuration/volto-slate/api.md +++ b/docs/source/configuration/volto-slate/api.md @@ -90,7 +90,7 @@ The {term}`elementEditor` is a top-level wrapper of all plugins used in `volto-s It consists of various modules: `makeInlineElementPlugin` -: Used to build and install a custom schema based plugin from volto-slate API. +: Used to build and install a custom schema based plugin from `volto-slate` API. It expects a set of options passed as a property to your plugin. `PluginEditor` diff --git a/docs/source/configuration/zero-config-builds.md b/docs/source/configuration/zero-config-builds.md index d6e02a8e27..6b78d82458 100644 --- a/docs/source/configuration/zero-config-builds.md +++ b/docs/source/configuration/zero-config-builds.md @@ -14,12 +14,14 @@ This feature is available since Volto 13. ``` In the past (before Volto 13), Volto was configured in build time using several -environment vars, commonly supplied via the command line, like: +environment variables, commonly supplied via the command line, such as the following: -`PORT=11001 RAZZLE_API_PATH=https://plone.org/api yarn build` +```shell +PORT=11001 RAZZLE_API_PATH=https://plone.org/api yarn build` +``` -and since RAZZLE is a isomorphic app, some of these values passed on build time, were -hardcoded in the code because the code in client and server need to know them upfront to +and since Razzle is an isomorphic application, some of these values passed on build time, were +hardcoded in the code because the code in client and server need to know them up front to in order to work. Volto 13 has several new features that allows zero configuration on build time, using diff --git a/docs/source/contributing/language-features.md b/docs/source/contributing/language-features.md index eb385c8d6d..6186b3d543 100644 --- a/docs/source/contributing/language-features.md +++ b/docs/source/contributing/language-features.md @@ -1,8 +1,8 @@ --- myst: html_meta: - "description": "Volto is developed using Babel to transpile modern Javascript to Javascript that browsers are able to understand and execute." - "property=og:description": "Volto is developed using Babel to transpile modern Javascript to Javascript that browsers are able to understand and execute." + "description": "Volto is developed using Babel to transpile modern JavaScript to JavaScript that browsers are able to understand and execute." + "property=og:description": "Volto is developed using Babel to transpile modern JavaScript to JavaScript that browsers are able to understand and execute." "property=og:title": "Language features and conventions" "keywords": "Volto, Plone, frontend, React, Babel, translations, language, internationalization, i18n, localization, transpilation" --- @@ -11,7 +11,7 @@ myst: ## Babel -Volto is developed using Babel to transpile modern Javascript to Javascript that +Volto is developed using Babel to transpile modern JavaScript to JavaScript that browsers are able to understand and execute. Ecma International's TC39 (https://tc39.es/) is a group of JavaScript developers, @@ -19,7 +19,7 @@ implementers, academics, and more, collaborating with the community to maintain evolve the definition of JavaScript. They stablished a process (https://tc39.es/process-document/) where the proposals are discussed, developed, and eventually approved (or dropped). The process has five stages (0 to 4) where reaching -the stage 4 means the proposal is accepted and it becomes part of the Javascript +the stage 4 means the proposal is accepted and it becomes part of the JavaScript specification. Babel enables a series of features and syntax that the developer can use in code to diff --git a/docs/source/contributing/linting.md b/docs/source/contributing/linting.md index b4c131312d..0bb1ac4350 100644 --- a/docs/source/contributing/linting.md +++ b/docs/source/contributing/linting.md @@ -15,9 +15,9 @@ gaps! ``` Volto developers can enjoy a lot of freedom in their choice of text editors and -IDEs, thanks to the strong tooling provided by the Javascript ecosystem. +IDEs, thanks to the strong tooling provided by the JavaScript ecosystem. -At the core of these capabilities is ESLint, the advanced javascript linting +At the core of these capabilities is ESLint, the advanced JavaScript linting and formatting tool. Also included with Volto is integration with Stylelint and Prettier. diff --git a/docs/source/contributing/redux.md b/docs/source/contributing/redux.md index 2e8a6d1e3f..290a8c55da 100644 --- a/docs/source/contributing/redux.md +++ b/docs/source/contributing/redux.md @@ -111,7 +111,7 @@ Creating a "request action" potentially triggers some additional access. For example, even if we only declare the `GET_CONTENT` type of action, we can see that `GET_CONTENT_SUCCESS`, `GET_CONTENT_PENDING` and `GET_CONTENT_FAIL` are also used in the `content` reducer. They are automatically created by the -special Api middleware, available in `src/middleware/api.js`. +special API middleware, available in `src/middleware/api.js`. ## Customizing the Redux middleware diff --git a/docs/source/contributing/volto-core-addons.md b/docs/source/contributing/volto-core-addons.md index d408a082f2..1c4d485961 100644 --- a/docs/source/contributing/volto-core-addons.md +++ b/docs/source/contributing/volto-core-addons.md @@ -1,4 +1,4 @@ -# Volto Core add-ons +# Volto core add-ons Volto has the concept of "core add-ons". They are add-ons that are always installed in Volto. diff --git a/docs/source/deploying/apache.md b/docs/source/deploying/apache.md index e25ea09ca7..3fdfed51b3 100644 --- a/docs/source/deploying/apache.md +++ b/docs/source/deploying/apache.md @@ -9,7 +9,8 @@ myst: # Apache -Apache configuration for a Plone backend deployed under /api and a Volto frontend deployed under the root "/". This configuration also redirects http -> https: +Apache configuration for a Plone backend deployed under `/api` and a Volto frontend deployed under the root `/`. +This configuration also redirects `http` -> `https`. ```apache diff --git a/docs/source/deploying/pm2.md b/docs/source/deploying/pm2.md index 608de9af46..b223f21d8b 100644 --- a/docs/source/deploying/pm2.md +++ b/docs/source/deploying/pm2.md @@ -3,19 +3,19 @@ myst: html_meta: "description": "Using PM2 as a process manager for deployment of Volto." "property=og:description": "Using PM2 as a process manager for deployment of Volto." - "property=og:title": "Deployment using a node process manager (PM2)" + "property=og:title": "Deployment using a Node.js process manager (PM2)" "keywords": "Volto, Plone, frontend, React, deployment, PM2" --- -# Deployment using a node process manager (PM2) +# Deployment using a Node.js process manager (PM2) -PM2 is a popular and maintained process manager based in node (https://pm2.keymetrics.io/). +PM2 is a popular and maintained process manager based in Node.js (https://pm2.keymetrics.io/). ```{note} -You can use the good old known supervisord as well. However, the supervisord project is stalled and in low maintenance mode for many years. PM2 is a good alternative, and as you'll see you can manage all kind of processes, not only node ones, including the Plone processes. +You can use the good old known supervisord as well. However, the supervisord project is stalled and in low maintenance mode for many years. PM2 is a good alternative, and as you'll see you can manage all kind of processes, not only Node.js ones, including the Plone processes. ``` -Create a file `mywebsite.com.pm2.config.js` in your repo or on your server. +Create a file `mywebsite.com.pm2.config.js` in your repository or on your server. ```{important} Make sure your PM2 config file sufix ends in `config.js`, otherwise PM2 will ignore it. @@ -54,8 +54,8 @@ module.exports = { }; ``` -- `mywebsite.com-volto` starts the Node process that is responsible for Volto {term}`server-side rendering`. -- `mywebsite.com-api-zeo` starts the ZEO server. +- `mywebsite.com-volto` starts the Node.js process that's responsible for Volto {term}`server-side rendering`. +- `mywebsite.com-api-zeo` starts the {term}`ZEO` server. - `mywebsite.com-api-instance1` starts the first Zope instance. - `mywebsite.com-api-instance2` starts the second Zope instance. diff --git a/docs/source/deploying/seamless-mode.md b/docs/source/deploying/seamless-mode.md index 5c6f0caf1a..13d5652a0a 100644 --- a/docs/source/deploying/seamless-mode.md +++ b/docs/source/deploying/seamless-mode.md @@ -87,7 +87,7 @@ problematic from the SEO point of view), so indexers cannot reach it. Repeatable docker builds (since the config will be based on runtime). -Ready to use production builds (e.g. vanila Volto built, ready for testing), configured in runtime. +Ready to use production builds (e.g. vanilla Volto built, ready for testing), configured in runtime. ![How Plone 6 works](HowPlone6Works001.png) diff --git a/docs/source/deploying/simple.md b/docs/source/deploying/simple.md index bfbe194fac..1215cb3cd5 100644 --- a/docs/source/deploying/simple.md +++ b/docs/source/deploying/simple.md @@ -9,7 +9,7 @@ myst: # Simple deployment -Volto is a Node application that runs on your machine/server and listens to a port. Once you are ready to deploy it, you should build it running: +Volto is a Node.js application that runs on your machine/server and listens to a port. Once you are ready to deploy it, you should build it running: ```bash $ yarn build @@ -35,7 +35,7 @@ $ NODE_ENV=production node build/server.js This will start Volto in the PORT specified in the build command, and will issue internal API queries to the RAZZLE_API_PATH specified as well. -The simplest deployment is to start this node process in your server by any mean of your choice (systemd, process manager, etc) and manage its lifecycle. +The simplest deployment is to start this Node.js process in your server by any mean of your choice (systemd, process manager, etc) and manage its lifecycle. ## Reverse proxies @@ -72,4 +72,4 @@ location ~ / { ### Understanding CORS errors -If you're getting [CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue) you need to understand the nature of these errors: the backend server (usually Plone) needs to be configured to "know" the final domain where the content is fetched. This is done for security purposes, to protect the information in the backend server from being loaded by client browsers on unknown domains. So make sure that the backend server is properly configured for your purposes. When using Plone with Docker, check the [CORS](https://github.com/plone/plone.docker#for-basic-usage) documentation section, otherwise the [CORS section of plone.rest](https://github.com/plone/plone.rest#cors). +If you're getting [CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue) you need to understand the nature of these errors: the backend server (usually Plone) needs to be configured to "know" the final domain where the content is fetched. This is done for security purposes, to protect the information in the backend server from being loaded by client browsers on unknown domains. So make sure that the backend server is properly configured for your purposes. When using Plone with Docker, check the [CORS](https://github.com/plone/plone.docker#for-basic-usage) documentation section, otherwise the [CORS section of `plone.rest`](https://github.com/plone/plone.rest#cors). diff --git a/docs/source/getting-started/install.md b/docs/source/getting-started/install.md index cb405dac88..cee9d43440 100644 --- a/docs/source/getting-started/install.md +++ b/docs/source/getting-started/install.md @@ -4,7 +4,7 @@ myst: "description": "Installing Volto" "property=og:description": "Installing Volto" "property=og:title": "Getting Started" - "keywords": "Volto, Plone, frontend, React, install, nvm, NodeJS, JavaScript" + "keywords": "Volto, Plone, frontend, React, install, nvm, Node.js , JavaScript" --- (frontend-getting-started-label)= @@ -45,25 +45,25 @@ They assume you have a macOS/Linux machine. There are three processes continuously running when you have a working Volto website: 1. A frontend web application running in your browser (JavaScript) -2. A Node.js server process that delivers the JavaScript to the client and does +2. A {term}`Node.js` server process that delivers the JavaScript to the client and does {term}`server-side rendering` (SSR) of your pages on first request (JavaScript, the Razzle package is used for SSR) 3. A Plone server process that stores and delivers all content through a REST API (Python) When you start with Volto most of the first customisations you will want to make (or maybe ever need to make) are in the JavaScript code used in the browser and Razzle process. Therefore -this getting started chapter will focus on installing a NodeJS/JavaScript environment locally +this getting started chapter will focus on installing a Node.js/JavaScript environment locally and suggest you start the API backend using a container. (frontend-getting-started-install-nvm-label)= -## Install nvm (NodeJS version manager) +## Install nvm (Node.js version manager) -If you have a working Node JavaScript development already set up on your machine or you prefer -another management tool to install/maintain node this step is not needed. If you have less +If you have a working Node.js JavaScript development already set up on your machine or you prefer +another management tool to install/maintain Node.js this step is not needed. If you have less experience with setting up JavaScript, it's a good idea to integrate nvm for development, as -it provides easy access to any NodeJS released version. +it provides easy access to any Node.js released version. 1. Open a terminal console and type: @@ -86,14 +86,14 @@ it provides easy access to any NodeJS released version. nvm version ``` -4. Install any active LTS version of NodeJS (https://github.com/nodejs/release#release-schedule): +4. Install any active LTS version of Node.js (https://github.com/nodejs/release#release-schedule): ```bash nvm install 18 nvm use 18 ``` -5. Test NodeJS: +5. Test Node.js : ```bash node -v @@ -104,8 +104,8 @@ it provides easy access to any NodeJS released version. ``` ```{note} - Volto supports currently active NodeJS LTS versions based on [NodeJS - Releases page](https://github.com/nodejs/release#release-schedule), starting with Node 16 LTS. + Volto supports currently active Node.js LTS versions based on [Node.js + Releases page](https://github.com/nodejs/release#release-schedule), starting with Node.js 16 LTS. ``` @@ -122,9 +122,9 @@ npm install -g yo (frontend-getting-started-yarn-label)= -## Yarn (NodeJS package manager) +## Yarn (Node.js package manager) -Install the Yarn Classic version (not the 2.x one!), of the popular node package manager. +Install the Yarn Classic version (not the 2.x one!), of the popular Node.js package manager. 1. Open a terminal and type: @@ -206,7 +206,7 @@ execute `docker run` will be use to persist the backend server data. If you are somewhat familiar with Python development, you can also install Plone locally without using Docker. Check the [backend configuration](../configuration/backend.md) section. -It also has more information on plone.volto. +It also has more information on `plone.volto`. (frontend-getting-started-install-volto-label)= @@ -266,7 +266,7 @@ You may choose to install the canary version, which is the latest alpha release, ## Build the production bundle In production environments, you should build an static version of your (Volto) app. The -app should be run in a node process (because of the {term}`server-side rendering` +app should be run in a Node.js process (because of the {term}`server-side rendering` part), but it also have a client part that is provided and deployed by the server side rendering process. @@ -277,12 +277,12 @@ side rendering process. ``` The resultant build is available in the `build` folder. -2. Run the Volto Nodejs process +2. Run the Volto Node.js process ```bash yarn start:prod ``` - to run the node process with the production build. You can also run it manually: + to run the Node.js process with the production build. You can also run it manually: ```bash NODE_ENV=production node build/server.js diff --git a/docs/source/getting-started/roadmap.md b/docs/source/getting-started/roadmap.md index 3af14a07b0..cba274e63b 100644 --- a/docs/source/getting-started/roadmap.md +++ b/docs/source/getting-started/roadmap.md @@ -23,16 +23,16 @@ complete and accurate picture of the Volto framework. ## The foundation -As is the case with similar modern Javascript-based applications, you should know: +As is the case with similar modern JavaScript-based applications, you should know: -- Modern Javascript development. Volto uses next-generation Javascript. Follow +- Modern JavaScript development. Volto uses next-generation JavaScript. Follow the [ES6 guide](https://flaviocopes.com/es6/) to get up to speed. - React knowledge - [basic level is fine](https://react.dev/learn/tutorial-tic-tac-toe) for the beginning, you'll progress along the way. React itself is a simple and well documented framework. -- A basic understanding of Javascript +- A basic understanding of JavaScript [CommonJS](https://flaviocopes.com/commonjs/), - [NPM packages](https://flaviocopes.com/npm/), + [npm packages](https://flaviocopes.com/npm/), [Yarn](https://flaviocopes.com/yarn/), [Babel](https://flaviocopes.com/babel/) and [Webpack](https://flaviocopes.com/webpack/). @@ -42,7 +42,7 @@ As is the case with similar modern Javascript-based applications, you should kno Once you've bootstrapped your Volto project you can already start hacking. Some of the things you can do at this stage: -- Configure your text editor for Javascript and Volto development +- Configure your text editor for JavaScript and Volto development - Volto project-based development - Understand and debug React errors - Understand React component lifecycle @@ -63,7 +63,7 @@ can be really productive. - Write new Redux actions and reducers - Create new views for Plone content. -- Install and integrate new Javascript libraries or third-party React +- Install and integrate new JavaScript libraries or third-party React components - Create a new Volto addon - Integrate addon LESS with Volto's theme variables @@ -81,9 +81,9 @@ can be really productive. Not really advanced but perhaps less common, here's some stuff you can do: -- Provide backend-based integration to your Volto code, write plone.restapi +- Provide backend-based integration to your Volto code, write `plone.restapi` endpoints, adapters and other extensions -- Custom integration for blocks to the backend using the block transfomers +- Custom integration for blocks to the backend using the block transformers concept - Write Express middleware for Volto's server - Customize Volto's Webpack configuration or project loader using Razzle diff --git a/docs/source/index.md b/docs/source/index.md index ee7723015f..d0bf5427c0 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -31,7 +31,7 @@ the Volto blocks can provide a fast development experience that reduces developer frustration and improves end-user experience. To start developing a new Volto project you should have minimal React and -modern Javascript knowledge. Follow the +modern JavaScript knowledge. Follow the {doc}`getting-started/install` guide to bootstrap a new Volto project and start hacking! diff --git a/docs/source/recipes/contextnavigation.md b/docs/source/recipes/contextnavigation.md index 6f3f658db0..d88826729c 100644 --- a/docs/source/recipes/contextnavigation.md +++ b/docs/source/recipes/contextnavigation.md @@ -35,7 +35,7 @@ you can compute and pass a custom path like: As parameters you can use: - `name`: The title of the navigation tree. -- `root_path`: Root node path, can be "frontend path", derived from router +- `root_path`: Root Node.js path, can be "frontend path", derived from router - `includeTop`: Bool, Include top nodeschema - `currentFolderOnly`: Bool, Only show the contents of the current folder. - `topLevel`: Int, Start level @@ -44,5 +44,4 @@ As parameters you can use: - `thumb_scale`: String, Override thumb scale - `no_thumbs`: Bool, Suppress thumbs -Notice the similarity to the classic Plone navigation portlet, as the -plone.restapi implementation is based on that original code. +Notice the similarity to the classic Plone navigation portlet, as the `plone.restapi` implementation is based on that original code. diff --git a/docs/source/recipes/ie11compat.md b/docs/source/recipes/ie11compat.md index 6001158ae9..0f74529689 100644 --- a/docs/source/recipes/ie11compat.md +++ b/docs/source/recipes/ie11compat.md @@ -19,7 +19,7 @@ This documentation is orientative. Volto does NOT support legacy or vendor depre These package versions should be pinned to this especific versions, unless their code or dependencies have some es6 only compatible, because their -maintainers mainly target the node world. +maintainers mainly target the Node.js world. * "query-string": "4.1.0" * "superagent": "3.8.2" diff --git a/docs/source/releases.md b/docs/source/releases.md index af6c27d753..7ea2a95d5f 100644 --- a/docs/source/releases.md +++ b/docs/source/releases.md @@ -17,7 +17,7 @@ myst: What you can expect from Volto releases and the Volto release management. Volto uses Semantic Versioning to communicate bugfixes, new features, and breaking changes. It -supports Plone 5.2.x on Python 3, Plone 6, and LTS versions of NodeJS. +supports Plone 5.2.x on Python 3, Plone 6, and LTS versions of Node.js. ## Semantic Versioning @@ -65,6 +65,6 @@ Volto relies on Plone (core) and [Plone REST API](https://pypi.org/project/plone Volto should work on old Plone versions as well since Plone REST API supports Plone back to version 4.3 (including Archetypes). Though, we do not actively support versions or test Plone versions that have been released long before Volto existed. -## NodeJS +## Node.js -Volto always supports only LTS versions of [NodeJS](https://github.com/nodejs/release#release-schedule). +Volto always supports only LTS versions of [Node.js ](https://github.com/nodejs/release#release-schedule). diff --git a/docs/source/theming/using-third-party-themes.md b/docs/source/theming/using-third-party-themes.md index bc545302ca..21f6f5f720 100644 --- a/docs/source/theming/using-third-party-themes.md +++ b/docs/source/theming/using-third-party-themes.md @@ -11,12 +11,12 @@ myst: # Using third party libraries and themes other than `semantic-ui` -You can use Volto with third party libraries or themes written in SASS and avoid applying `semantic-ui` on public facing views. +You can use Volto with third party libraries or themes written in Sass and avoid applying `semantic-ui` on public facing views. This is made possible by code splitting, where interfaces have a marker CSS class to encapsulate styles and avoid conflicts between `semantic-ui` and the custom theme you would use. ## The problem -The main purpose could be to use a sass based theme like Bootstrap. +The main purpose could be to use a Sass based theme like Bootstrap. If you want to load a different styling library using the base Volto configuration, you will load a huge bundle with both having weight and performance issues thus this would likely imply conflicts on base elements as containers. ## The solution @@ -53,9 +53,9 @@ Then, in your `theme.config` change the following and the needed variables: + @container : 'pastanaga-cms-ui'; ``` -### Use sass loader +### Use Sass loader -If you have to load sass, you will need `razzle-plugin-scss` and you will have to customize `razzle.config.js` integrating that plugin into razzle configuration. +If you have to load Sass, you will need `razzle-plugin-scss` and you will have to customize `razzle.config.js` integrating that plugin into Razzle configuration. Example: @@ -91,7 +91,7 @@ module.exports = Object.assign({}, volto_config, { Complete example in an active project: https://github.com/RedTurtle/design-volto-theme/blob/master/razzle.config.js -In that project, there is the sass loader and the svg loader, too. +In that project, there is the Sass loader and the SVG loader, too. ### Including custom styles diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index f32f862e6e..9215c64866 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -28,16 +28,16 @@ Thus it is safe to run it on top of your project and answer the prompts. ## Upgrading to Volto 17.x.x -### Ending support for NodeJS 14 +### Ending support for Node.js 14 -Long Term Support for NodeJS 14 by the NodeJS community ends in April 2023. -Volto 17 no longer supports NodeJS 14. -Please update your projects to a NodeJS LTS version, where either 16 or 18 is supported at the moment of this writing. +Long Term Support for {term}`Node.js` 14 by the Node.js community ends in April 2023. +Volto 17 no longer supports Node.js 14. +Please update your projects to a Node.js LTS version, where either 16 or 18 is supported at the moment of this writing. Version 18 is recommended. #### localhost now resolves to an IPv6 address -NodeJS 18 prefers to resolve `localhost` to an IPv6 address instead of IPv4. +Node.js 18 prefers to resolve `localhost` to an IPv6 address instead of IPv4. If you are setting `RAZZLE_API_PATH` to a URL that includes `localhost`, change the hostname to `127.0.0.1` instead. @@ -217,11 +217,11 @@ It is recommended to go the extra mile and migrate the `text` blocks to `slate` Use the `blocks-conversion-tool`. See https://github.com/plone/blocks-conversion-tool for more information. -### Deprecating NodeJS 12 +### Deprecating Node.js 12 -Since April 30, 2022, NodeJS 12 is out of Long Term Support by the NodeJS community. -NodeJS 12 is deprecated in Volto 13. -Please update your projects to a NodeJS LTS version, where either 14 or 16 is supported at the moment of this writing. +Since April 30, 2022, Node.js 12 is out of Long Term Support by the Node.js community. +Node.js 12 is deprecated in Volto 13. +Please update your projects to a Node.js LTS version, where either 14 or 16 is supported at the moment of this writing. Version 16 is recommended. ### Upgraded to Razzle 4 @@ -337,7 +337,7 @@ We updated Volto to be able to use it, however some changes have to be made in y nodeLinker: node-modules ``` - Then, if you are using Node >=16.10 run: + Then, if you are using Node.js >=16.10 run: ```shell corepack enable @@ -352,7 +352,7 @@ We updated Volto to be able to use it, however some changes have to be made in y ``` ```{important} - It is highly recommended that you use the latest Node 16. + It is highly recommended that you use the latest Node.js 16. ``` 2. Change your root project `Makefile` to include these commands: @@ -848,7 +848,7 @@ Apply the following diff to your add-on's `babel.config.js`: ``` ```{note} -For convenience the `i18n` script is now an executable in the node environment. +For convenience the `i18n` script is now an executable in the Node.js environment. ``` ### Removal of the old configuration system based on imports @@ -865,8 +865,8 @@ Not really a breaking change, but it's worth noting it. By default, Volto 14 com {doc}`../configuration/locking` enabled, if the backend supports it. Thus: - Upgrade Plone RestAPI - - **plone.restapi**>=`8.9.0` (Plone 5+) - - **plone.restapi**>=`7.4.0` (Plone 4) + - `plone.restapi`>=`8.9.0` (Plone 5+) + - `plone.restapi`>=`7.4.0` (Plone 4) - Update `plone:CORSPolicy` to include `Lock-Token` within `allow_headers`: ```xml @@ -928,10 +928,10 @@ The `getVocabulary` action has changed API. Before, it used separate positional ## Upgrading to Volto 13.x.x -### Deprecating NodeJS 10 +### Deprecating Node.js 10 -Since April 30th, 2021 NodeJS 10 is out of Long Term Support by the NodeJS community, so -we are deprecating it in Volto 13. Please update your projects to a NodeJS LTS version +Since April 30th, 2021 Node.js 10 is out of Long Term Support by the Node.js community, so +we are deprecating it in Volto 13. Please update your projects to a Node.js LTS version (12 or 14 at the moment of this writing). ### Seamless mode is the default in development mode @@ -1099,7 +1099,7 @@ messages for the used translations is advisable, but not required. (frontend-upgrade-guide-volto-configuration-registry-label)= -### Volto Configuration Registry +### Volto configuration registry The configuration object in Volto is located in the `~/config` module and uses it as container of Volto's config taking advantage of the ES6 module system. So we "import" @@ -1109,8 +1109,8 @@ the config every time we need it, then the exported config data in that module It's been a while since we were experiencing undesired side effects from "circular import dependency" problems in Volto, due to the very nature of the solution (importing the `~/config`). Although they aren't very noticeable, they are there, waiting to bite -us. In fact, circular dependencies are common in NodeJS world, and the very nature of -how it works make them "workable" thanks to the NodeJS own import resolution algorithm. +us. In fact, circular dependencies are common in Node.js world, and the very nature of +how it works make them "workable" thanks to the Node.js own import resolution algorithm. So the "build" always works, although we have the circular dependencies, but that leads to weird problems like (just to mention one of them) the {term}`hot module replacement` (HMR) not working properly. @@ -1679,11 +1679,11 @@ First, update the `package.json` of your Volto project to Volto 6.x.x. This release includes a number of changes to the internal dependencies. If you have problems building your project, you might need to remove your `node_modules` and, ultimately, also remove your `yarn.lock` file. Then run again `yarn` for rebuilding the dependencies. ``` -### Upgrade to Node 12 +### Upgrade to Node.js 12 -We have now dependencies that requires `node >=10.19.0`. Although Node 10 has still LTS +We have now dependencies that requires `node >=10.19.0`. Although Node.js 10 has still LTS "maintenance" treatment (see https://github.com/nodejs/release#release-schedule) the recommended path -is that you use from now on node 12 which is LTS since last October. +is that you use from now on Node.js 12 which is LTS since last October. ### New Razzle version and related development dependencies @@ -1957,7 +1957,7 @@ const initialBlocks = {}; For better resource grouping, the `ImageSidebar` component has been moved to the `Image` block component directory: `components/manage/Blocks/Image` -### Copy `yarn.lock` from volto-starter-kit in Alpha 17 +### Copy `yarn.lock` from `volto-starter-kit` in Alpha 17 Due to changes in the dependency tree, it's required to use a specific `yarn.lock` file by deleting it and copy the one here: https://github.com/plone/volto-starter-kit/blob/master/yarn.lock before upgrading to Volto alpha 17. @@ -2090,7 +2090,7 @@ Plone RESTAPI was updated for that purpose too, and running an upgrade step (do This is the version compatibility table across all the packages involved: -Volto 4 - plone.restapi >= 5.0.0 - kitconcept.voltodemo >= 2.0 +Volto 4 - `plone.restapi` >= 5.0.0 - `kitconcept.voltodemo` >= 2.0 ```{note} The renaming happened in Volto 4 alpha.10 and plone.restapi 5.0.0. Volto 4 alpha versions under that release use older versions of `plone.restapi` and `kitconcept.voltodemo`, however if you are using alpha releases it's recommended to upgrade to the latest alpha or the final release of Volto 4. @@ -2274,7 +2274,7 @@ Then update your `package.json` to Volto 3.x. ``` Volto 3.x is compatible with the new changes introduced in the vocabularies -endpoint in plone.restapi 4.0.0. If you custom-build a widget based in the +endpoint in `plone.restapi` 4.0.0. If you custom-build a widget based in the Volto ones, you should update them as well. Volto updated its own widget set to support them: diff --git a/news/1190.internal b/news/1190.internal new file mode 100644 index 0000000000..e8c73c5d56 --- /dev/null +++ b/news/1190.internal @@ -0,0 +1 @@ +Improved spellcheck to keep spellings consistent. @chirayu-humar \ No newline at end of file diff --git a/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index 0ff684308f..793df78cd1 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -1,10 +1,15 @@ `plone.restapi` `plone.volto` +[Aa]sync +[Bb]ackend +JavaScript npm +nvm +Pastanaga Plone Razzle RichText +Sass Volto +Vue Zope -JavaScript -NodeJS diff --git a/styles/Vocab/Plone/reject.txt b/styles/Vocab/Plone/reject.txt index 1deaa26744..1cefa812f0 100644 --- a/styles/Vocab/Plone/reject.txt +++ b/styles/Vocab/Plone/reject.txt @@ -1,5 +1,2 @@ -node -nodejs -javascript -js -Javascript \ No newline at end of file +[^.]js +NodeJS