Hello world
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [ + { + text: 'Hello world', + }, + ], + }, + ]); + }); + + it('two root tags', () => { + const html = 'Hello world
something
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [ + { + text: 'Hello world', + }, + ], + }, + { + type: 'p', + children: [ + { + text: 'something', + }, + ], + }, + ]); + }); + + it('takes inline elements', () => { + const html = 'hello'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'strong', + children: [ + { + text: 'hello', + }, + ], + }, + ]); + }); + + it('strips unknown elements', () => { + const html = 'Hello \n\t\t\t\t World!\t
'; + + expect(htmlUtils.removeSpaceBeforeAfterEndLine(html)).toBe( + 'Hello\n World!\t
', + ); + }); + + it('#2: convert all tabs to spaces', () => { + const html = 'Hello\n World!\t
'; + + expect(htmlUtils.convertTabsToSpaces(html)).toBe( + 'Hello\n World!
', + ); + }); + + it('#3: convert line breaks spaces', () => { + const html = 'Hello\n World!
'; + + expect(htmlUtils.convertLineBreaksToSpaces(html)).toBe( + 'Hello World!
', + ); + }); + + it('#4: remove space follows space in sibling text node', () => { + const html = 'Hello World!
'; + + const dom = new JSDOM(html); + const body = dom.window.document.body; + const span = body.querySelector('span'); + + expect(htmlUtils.removeSpaceFollowSpace(' World!', span)).toBe('World!'); + }); + + it('#4: remove space follows space in sibling inline node', () => { + const html = 'Hello World!
'; + + const dom = new JSDOM(html); + const body = dom.window.document.body; + const span = body.querySelector('span'); + const b = body.querySelector('b'); + + expect(htmlUtils.removeSpaceFollowSpace('Hello ', b)).toBe('Hello '); + expect(htmlUtils.removeSpaceFollowSpace(' World!', span)).toBe('World!'); + }); + + it('#4: remove space in text node follows space in sibling inline node', () => { + const html = 'Hello World!
'; + + const dom = new JSDOM(html); + const body = dom.window.document.body; + const b = body.querySelector('b'); + + const textNode = b.nextSibling; + expect(textNode.textContent).toBe(' World! '); + + expect(htmlUtils.removeSpaceFollowSpace(' World! ', textNode)).toBe( + 'World! ', + ); + }); + + it('#5. Remove space at beginning of element', () => { + const html = 'Hello World!
'; + + const dom = new JSDOM(html); + const body = dom.window.document.body; + const h1 = body.querySelector('h1'); + + const textNode = h1.firstChild; + expect(textNode.textContent).toBe(' Hello '); + + expect(htmlUtils.removeElementEdges(' Hello ', textNode)).toBe('Hello '); + }); + + it('#5. Remove space at end of element', () => { + const html = 'Hello World!
'; + + const dom = new JSDOM(html); + const body = dom.window.document.body; + const h1 = body.querySelector('h1'); + + const textNode = h1.lastChild; + expect(textNode.textContent).toBe(' '); + + expect(htmlUtils.removeElementEdges(' ', textNode)).toBe(''); + }); + + it('collapses multiple consecutive spaces', () => { + const html = 'hello world'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'strong', + children: [{ text: 'hello world' }], + }, + ]); + }); + + it('preserves spaces between two inline nodes', () => { + const html = 'hello world'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'i', + children: [{ text: 'hello' }], + }, + { text: ' ' }, + { + type: 'i', + children: [{ text: 'world' }], + }, + ]); + }); + + it('preserves spaces between one block and one inline node', () => { + const html = 'hello
world'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [{ text: 'hello' }], + }, + { text: ' ' }, + { + type: 'i', + children: [{ text: 'world' }], + }, + ]); + }); + + it('preserves spaces between one inline node and one block node', () => { + const html = 'helloworld
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'i', + children: [{ text: 'hello' }], + }, + { text: ' ' }, + { + type: 'p', + children: [{ text: 'world' }], + }, + ]); + }); + + it('replaces a single newline inside text with a space', () => { + const html = 'hello\nworld'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'i', + children: [{ text: 'hello world' }], + }, + ]); + }); + + it('replaces multiple newlines inside text with a space', () => { + const html = 'hello\n\n\nworld'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'i', + children: [{ text: 'hello world' }], + }, + ]); + }); + + it('removes whitespace between block elements', () => { + const html = 'hello
\n \nworld
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [{ text: 'hello' }], + }, + { + type: 'p', + children: [{ text: 'world' }], + }, + ]); + }); + + it('transforms newlines at beginning of tags to space', () => { + const html = 'hello\nworld'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'b', + children: [{ text: 'hello' }], + }, + { + type: 'i', + children: [{ text: ' world' }], + }, + ]); + }); + + it('transforms newlines after a space', () => { + const html = 'Lorem Ipsum\nis simply dummy text\n
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [ + { + type: 'strong', + children: [{ text: 'Lorem Ipsum' }], + }, + { text: ' is simply dummy text' }, + ], + }, + ]); + }); + + it('transforms newlines to space after an inline tag', () => { + const html = 'Lorem Ipsum\nis simply dummy text
'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'p', + children: [ + { + type: 'strong', + children: [{ text: 'Lorem Ipsum' }], + }, + { text: ' is simply dummy text' }, + ], + }, + ]); + }); + + it('it removes new lines at beginning of text of block nodes', () => { + const html = 'hello\n world\n
dot'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'b', + children: [{ text: 'hello' }], + }, + { + type: 'p', + children: [{ text: 'world' }], + }, + { + type: 'i', + children: [{ text: 'dot' }], + }, + ]); + }); + + it('it removes consecutive space in inline nodes', () => { + const html = `hello world`; + // console.log(JSON.stringify(tojson(html), null, 2)); + + expect(tojson(html)).toStrictEqual([ + { + type: 'b', + children: [{ text: 'hello ' }], + }, + { + type: 'i', + children: [{ text: 'world' }], + }, + ]); + }); + + it('it handles text fragments', () => { + const html = + 'Lorem Ipsum\nis simply dummy text of the printing and typesetting industry.'; + + expect(tojson(html)).toStrictEqual([ + { + type: 'strong', + children: [{ text: 'Lorem Ipsum' }], + }, + { + text: ' is simply dummy text of the printing and typesetting industry.', + }, + ]); + }); + + it('handles chrome + firefox style copy', () => { + const html = `Hello world`; + + expect(tojson(html)).toStrictEqual([ + { + type: 'strong', + children: [{ text: 'Hello' }], + }, + { + text: ' ', + }, + { + text: 'world', + }, + ]); + }); +}); diff --git a/__tests__/webpack-relative-resolver.test.js b/__tests__/webpack-relative-resolver.test.js index 41519c4c53..960d81a28a 100644 --- a/__tests__/webpack-relative-resolver.test.js +++ b/__tests__/webpack-relative-resolver.test.js @@ -120,10 +120,16 @@ describe('functions as a Webpack resolver plugin', () => { const resolved = []; const resolver = { - plugin(typ, resolveCallback) { - resolveCallback(req, () => flag.push(true)); + ensureHook(typ) { + return this; }, - doResolve(type, req, _, callback) { + getHook(typ) { + return this; + }, + tapAsync: (name, callback) => { + callback(req, {}); + }, + doResolve(type, req, _, resolveContext, callback) { flag.push(true); resolved.push(req.request); }, @@ -143,10 +149,16 @@ describe('functions as a Webpack resolver plugin', () => { const resolved = []; const resolver = { - plugin(typ, resolveCallback) { - resolveCallback(req, () => flag.push(true)); + ensureHook(typ) { + return this; + }, + getHook(typ) { + return this; + }, + tapAsync: (name, callback) => { + callback(req, {}, () => flag.push(true)); }, - doResolve(type, req, _, callback) { + doResolve(type, req, _, resolveContext, callback) { flag.push(true); resolved.push(req.request); }, diff --git a/addon-registry.js b/addon-registry.js index 3dfea21f45..666c0bcd04 100644 --- a/addon-registry.js +++ b/addon-registry.js @@ -148,7 +148,7 @@ class AddonConfigurationRegistry { }, ); - this.initRazzleExtenders(); + this.initAddonExtenders(); } /** @@ -310,18 +310,26 @@ class AddonConfigurationRegistry { } /** - * Allow addons to provide razzle.config extenders. These extenders - * modules (named razzle.extend.js) need to provide two functions: + * Allow addons to provide various extenders. + * + * The razzle.extend.js modules (named razzle.extend.js) needs to provide + * two functions: * `plugins(defaultPlugins) => plugins` and * `modify(...) => config` + * + * The eslint.extend.js */ - initRazzleExtenders() { + initAddonExtenders() { this.getAddons().forEach((addon) => { const base = path.dirname(addon.packageJson); const razzlePath = path.resolve(`${base}/razzle.extend.js`); if (fs.existsSync(razzlePath)) { addon.razzleExtender = razzlePath; } + const eslintPath = path.resolve(`${base}/eslint.extend.js`); + if (fs.existsSync(eslintPath)) { + addon.eslintExtender = eslintPath; + } }); } @@ -340,6 +348,12 @@ class AddonConfigurationRegistry { .filter((e) => e); } + getEslintExtenders() { + return this.getAddons() + .map((o) => o.eslintExtender) + .filter((e) => e); + } + /** * Returns a mapping name:diskpath to be uses in webpack's resolve aliases */ diff --git a/api/Makefile b/api/Makefile index fbe15f133d..3820acf081 100644 --- a/api/Makefile +++ b/api/Makefile @@ -4,7 +4,7 @@ # https://tech.davis-hansson.com/p/make/ SHELL:=bash .ONESHELL: -.SHELLFLAGS:=-xeu -o pipefail -O inherit_errexit -c +.SHELLFLAGS:=-eu -o pipefail -c .SILENT: .DELETE_ON_ERROR: MAKEFLAGS+=--warn-undefined-variables diff --git a/api/README.rst b/api/README.rst index c249527cbc..3203aea283 100644 --- a/api/README.rst +++ b/api/README.rst @@ -45,7 +45,7 @@ are required for cryptography, image handling/scaling support and compression. You can find more up to date details on installing these necessary libraries for linux systems in the 'Mastering Plone' training at --> https://training.plone.org/5/mastering-plone/installation.html#installing-plone-backend +-> https://training.plone.org/mastering-plone/installation.html#installing-plone-backend For Windows you could try WSL (Windows subsystem for Linux) and for Mac OS X for example Homebrew to install these necessary support libraries. diff --git a/api/buildout.cfg b/api/buildout.cfg index fba6d75667..feb689d278 100644 --- a/api/buildout.cfg +++ b/api/buildout.cfg @@ -1,7 +1,7 @@ [buildout] index = https://pypi.org/simple/ extends = - http://dist.plone.org/release/6.0.0b3/versions.cfg + http://dist.plone.org/release/6.0.2/versions.cfg version-constraints.cfg versions.cfg parts = instance plonesite site-packages test robot-server diff --git a/api/versions.cfg b/api/versions.cfg index 2541a60e2c..d404ee2ec3 100644 --- a/api/versions.cfg +++ b/api/versions.cfg @@ -5,8 +5,8 @@ async-generator = 1.10 collective.folderishtypes = 3.0.0 collective.recipe.plonesite = 1.12.0 h11 = 0.12.0 -plone.restapi = 8.32.0 -plone.volto = 4.0.0a13 +plone.restapi = 8.35.1 +plone.volto = 4.0.7 prompt-toolkit = 2.0.10 pyOpenSSL = 21.0.0 robotframework-debuglibrary = 2.2.2 diff --git a/cypress.config.js b/cypress.config.js index 8e6be41a2b..4f2286287f 100644 --- a/cypress.config.js +++ b/cypress.config.js @@ -5,7 +5,7 @@ module.exports = defineConfig({ chromeWebSecurity: false, projectId: 'hvviu4', e2e: { - baseUrl: 'http://localhost:3000', + baseUrl: 'http://127.0.0.1:3000', excludeSpecPattern: ['*~'], specPattern: 'cypress/tests/**/*.{js,jsx,ts,tsx}', }, diff --git a/cypress/fixtures/halfdome2022.jpg b/cypress/fixtures/halfdome2022.jpg new file mode 100644 index 0000000000..58c9411ca2 Binary files /dev/null and b/cypress/fixtures/halfdome2022.jpg differ diff --git a/cypress/support/commands.js b/cypress/support/commands.js index 5739a60e38..cd2e6f23d4 100644 --- a/cypress/support/commands.js +++ b/cypress/support/commands.js @@ -2,7 +2,7 @@ import '@testing-library/cypress/add-commands'; import { getIfExists } from '../helpers'; import { ploneAuth } from './constants'; -const HOSTNAME = Cypress.env('BACKEND_HOST') || 'localhost'; +const HOSTNAME = Cypress.env('BACKEND_HOST') || '127.0.0.1'; const GUILLOTINA_API_URL = `http://${HOSTNAME}:8081/db/web`; const PLONE_SITE_ID = Cypress.env('SITE_ID') || 'plone'; const PLONE_API_URL = @@ -11,6 +11,11 @@ const PLONE_API_URL = const SLATE_SELECTOR = '.content-area .slate-editor [contenteditable=true]'; const SLATE_TITLE_SELECTOR = '.block.inner.title [contenteditable="true"]'; +const TABLE_SLATE_SELECTOR = + '.celled.fixed.table tbody tr:nth-child(1) td:first-child() [contenteditable="true"]'; +const TABLE_HEAD_SLATE_SELECTOR = + '.celled.fixed.table thead tr th:first-child() [contenteditable="true"]'; + const ploneAuthObj = { user: ploneAuth[0], pass: ploneAuth[1], @@ -46,9 +51,12 @@ Cypress.Commands.add( contentType, contentId, contentTitle, + contentDescription, path = '', allow_discussion = false, transition = '', + bodyModifier = (body) => body, + image = false, }) => { let api_url, auth; if (Cypress.env('API') === 'guillotina') { @@ -61,40 +69,44 @@ Cypress.Commands.add( api_url = PLONE_API_URL; auth = ploneAuthObj; } + + const defaultParams = { + method: 'POST', + url: `${api_url}/${path}`, + headers: { + Accept: 'application/json', + }, + auth: auth, + body: { + '@type': contentType, + id: contentId, + title: contentTitle, + description: contentDescription, + allow_discussion: allow_discussion, + }, + }; + if (contentType === 'File') { - return cy.request({ - method: 'POST', - url: `${api_url}/${path}`, - headers: { - Accept: 'application/json', - }, - auth: auth, - body: { - '@type': contentType, - id: contentId, - title: contentTitle, + const params = { + ...defaultParams, + body: bodyModifier({ + ...defaultParams.body, file: { data: 'dGVzdGZpbGUK', encoding: 'base64', filename: 'lorem.txt', 'content-type': 'text/plain', }, - allow_discussion: allow_discussion, - }, - }); + }), + }; + + return cy.request(params); } if (contentType === 'Image') { - return cy.request({ - method: 'POST', - url: `${api_url}/${path}`, - headers: { - Accept: 'application/json', - }, - auth: auth, - body: { - '@type': contentType, - id: contentId, - title: contentTitle, + const params = { + ...defaultParams, + body: bodyModifier({ + ...defaultParams.body, image: { data: 'iVBORw0KGgoAAAANSUhEUgAAANcAAAA4CAMAAABZsZ3QAAAAM1BMVEX29fK42OU+oMvn7u9drtIPisHI4OhstdWZyt4fkcXX5+sAg74umMhNp86p0eJ7vNiKw9v/UV4wAAAAAXRSTlMAQObYZgAABBxJREFUeF7tmuty4yAMhZG4X2zn/Z92J5tsBJwWXG/i3XR6frW2Y/SBLIRAfaQUDNt8E5tLUt9BycfcKfq3R6Mlfyimtx4rzp+K3dtibXkor99zsEqLYZltblTecciogoh+TXfY1Ve4dn07rCDGG9dHSEEOg/GmXl0U1XDxTKxNK5De7BxsyyBr6gGm2/vPxKJ8F6f7BXKfRMp1xIWK9A+5ks25alSb353dWnDJN1k35EL5f8dVGifTf/4tjUuuFq7u4srmXC60yAmldLXIWbg65RKU87lcGxJCFqUPv0IacW0PmSivOZFLE908inPToMmii/roG+MRV/O8FU88i8tFsxV3a06MFUw0Qu7RmAtdV5/HVVaOVMTWNOWSwMljLhzhcB6XIS7OK5V6AvRDNN7t5VJWQs1J40UmalbK56usBG/CuCHSYuc+rkUGeMCViNRARPrzW52N3oQLe6WifNliSuuGaH3czbVNudI9s7ZLUCLHVwWlyES522o1t14uvmbblmVTKqFjaZYJFSTPP4dLL1kU1z7p0lzdbRulmEWLxoQX+z9ce7A8GqEEucllLxePuZwdJl1Lezu0hoswvTPt61DrFcRuujV/2cmlxaGBC7Aw6cpovGANwRiSdOAWJ5AGy4gLL64dl0QhUEAuEUNws+XxV+OKGPdw/hESGYF9XEGaFC7sNLMSXWJjHsnanYi87VK428N2uxpOjOFANcagLM5l+7mSycM8KknZpKLcGi6jmzWGr/vLurZ/0g4u9AZuAoeb5r1ceQhyiTPY1E4wUR6u/F3H2ojSpXMMriBPT9cezTto8Cx+MsglHL4fv1Rxrb1LVw9yvyQpJ3AhFnLZfuRLH2QsOG3FGGD20X/th/u5bFAt16Bt308KjF+MNOXgl/SquIEySX3GhaZvc67KZbDxcCDORz2N8yCWPaY5lyQZO7lQ29fnZbt3Xu6qoge4+DjXl/MocySPOp9rlvdyznahRyHEYd77v3LhugOXDv4J65QXfl803BDAdaWBEDhfVx7nKofjoVCgxnUAqw/UAUDPn788BDvQuG4TDtdtUPvzjSlXAB8DvaDOhhrmhwbywylXAm8CvaouikJTL93gs3y7Yy4VYbIxOHrcMizPqWOjqO9l3Uz52kibQy4xxOgqhJvD+w5rvokOcAlGvNCfeqCv1ste1stzLm0f71Iq3ZfTrPfuE5nhPtF+LvQE2lffQC7pYtQy3tdzdrKvd5TLVVzDetScS3nEKmmwDyt1Cev1kX3YfbvzNK4fzrlw+cB6vm+uiUgf2zdXI62241LawCb7Pi5FXFPF8KpzDoF/Sw2lg+GrHNbno1mhPu+VCF/vfMnw06PnUl6j48dVHD3jHNHPua+fc3o/5yp/zsGi0vYtzi3Pz5mHd4T6BWMIlewacd63AAAAAElFTkSuQmCC', @@ -102,38 +114,75 @@ Cypress.Commands.add( filename: 'image.png', 'content-type': 'image/png', }, - }, - }); + }), + }; + + return cy.request(params); } if ( ['Document', 'News Item', 'Folder', 'CMSFolder'].includes(contentType) ) { - return cy - .request({ - method: 'POST', - url: `${api_url}/${path}`, - headers: { - Accept: 'application/json', + const params = { + ...defaultParams, + body: { + ...defaultParams.body, + blocks: { + 'd3f1c443-583f-4e8e-a682-3bf25752a300': { '@type': 'title' }, + '7624cf59-05d0-4055-8f55-5fd6597d84b0': { '@type': 'slate' }, }, - auth: auth, - body: { - '@type': contentType, - id: contentId, - title: contentTitle, - blocks: { - 'd3f1c443-583f-4e8e-a682-3bf25752a300': { '@type': 'title' }, - '7624cf59-05d0-4055-8f55-5fd6597d84b0': { '@type': 'slate' }, - }, - blocks_layout: { - items: [ - 'd3f1c443-583f-4e8e-a682-3bf25752a300', - '7624cf59-05d0-4055-8f55-5fd6597d84b0', - ], - }, - allow_discussion: allow_discussion, + blocks_layout: { + items: [ + 'd3f1c443-583f-4e8e-a682-3bf25752a300', + '7624cf59-05d0-4055-8f55-5fd6597d84b0', + ], }, - }) - .then(() => { + }, + }; + + if (image) { + let sourceFilename = 'cypress/fixtures/halfdome2022.jpg'; + let imageObject = { + encoding: 'base64', + filename: 'image.jpg', + 'content-type': 'image/jpg', + }; + if (typeof image === 'object') { + sourceFilename = image.sourceFilename; + imageObject = { + ...imageObject, + ...image, + }; + } + cy.readFile(sourceFilename, 'base64').then((encodedImage) => { + const withImageParams = { + ...params, + body: bodyModifier({ + ...params.body, + preview_image: { + ...imageObject, + data: encodedImage, + }, + }), + }; + + return cy.request(withImageParams).then(() => { + if (transition) { + cy.setWorkflow({ + path: path || contentId, + review_state: transition, + }); + } + console.log(`${contentType} created`); + }); + }); + } else { + const documentParams = { + ...params, + body: bodyModifier({ + ...params.body, + }), + }; + return cy.request(documentParams).then(() => { if (transition) { cy.setWorkflow({ path: path || contentId, @@ -142,6 +191,7 @@ Cypress.Commands.add( } console.log(`${contentType} created`); }); + } } else { return cy .request({ @@ -151,12 +201,12 @@ Cypress.Commands.add( Accept: 'application/json', }, auth: auth, - body: { + body: bodyModifier({ '@type': contentType, id: contentId, title: contentTitle, allow_discussion: allow_discussion, - }, + }), }) .then(() => { if (transition) { @@ -195,10 +245,34 @@ Cypress.Commands.add('removeContent', ({ path = '' }) => { }); }); +// Get content +Cypress.Commands.add('getContent', ({ path = '' }) => { + let api_url, auth; + if (Cypress.env('API') === 'guillotina') { + api_url = GUILLOTINA_API_URL; + auth = { + user: 'root', + pass: 'root', + }; + } else { + api_url = PLONE_API_URL; + auth = ploneAuthObj; + } + + return cy.request({ + method: 'get', + url: `${api_url}/${path}`, + headers: { + Accept: 'application/json', + }, + auth: auth, + }); +}); + // --- Add DX Content-Type ---------------------------------------------------------- Cypress.Commands.add('addContentType', (name) => { let api_url, auth; - api_url = Cypress.env('API_PATH') || 'http://localhost:8080/Plone'; + api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:8080/Plone'; auth = ploneAuthObj; return cy @@ -219,7 +293,7 @@ Cypress.Commands.add('addContentType', (name) => { // --- Remove DX behavior ---------------------------------------------------------- Cypress.Commands.add('removeContentType', (name) => { let api_url, auth; - api_url = Cypress.env('API_PATH') || 'http://localhost:8080/Plone'; + api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:8080/Plone'; auth = ploneAuthObj; return cy @@ -238,7 +312,7 @@ Cypress.Commands.add('removeContentType', (name) => { // --- Add DX field ---------------------------------------------------------- Cypress.Commands.add('addSlateJSONField', (type, name) => { let api_url, auth; - api_url = Cypress.env('API_PATH') || 'http://localhost:8080/Plone'; + api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:8080/Plone'; auth = ploneAuthObj; return cy @@ -263,7 +337,7 @@ Cypress.Commands.add('addSlateJSONField', (type, name) => { // --- Remove DX field ---------------------------------------------------------- Cypress.Commands.add('removeSlateJSONField', (type, name) => { let api_url, auth; - api_url = Cypress.env('API_PATH') || 'http://localhost:8080/Plone'; + api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:8080/Plone'; auth = ploneAuthObj; return cy @@ -291,7 +365,7 @@ Cypress.Commands.add( password = 'password', roles = ['Member', 'Reader', 'Editor'], groups = { - '@id': 'http://localhost:3000/@users', + '@id': 'http://127.0.0.1:3000/@users', items: [ { id: 'AuthenticatedUsers', @@ -375,7 +449,7 @@ Cypress.Commands.add( password = ploneAuth[1], roles = ['Member', 'Reader'], users = { - '@id': 'http://localhost:3000/@groups', + '@id': 'http://127.0.0.1:3000/@groups', items: [], items_total: 0, }, @@ -589,7 +663,7 @@ Cypress.Commands.add( (query, htmlContent) => { return cy .wrap(query) - .type(' ') + .type(' {backspace}') .trigger('paste', createHtmlPasteEvent(htmlContent)); }, ); @@ -737,6 +811,12 @@ function createHtmlPasteEvent(htmlContent) { ); } +Cypress.Commands.add('addNewBlock', (blockName, createNewSlate = false) => { + let block; + block = cy.getSlate(createNewSlate).type(`/${blockName}{enter}`); + return block; +}); + Cypress.Commands.add('navigate', (route = '') => { return cy.window().its('appHistory').invoke('push', route); }); @@ -749,3 +829,23 @@ Cypress.Commands.add('settings', (key, value) => { return cy.window().its('settings'); }); Cypress.Commands.add('getIfExists', getIfExists); + +Cypress.Commands.add('getTableSlate', (header = false) => { + let slate; + + cy.addNewBlock('table'); + cy.wait(2000); + + const selector = header ? TABLE_HEAD_SLATE_SELECTOR : TABLE_SLATE_SELECTOR; + + cy.getIfExists( + selector, + () => { + slate = cy.get(selector).last(); + }, + () => { + slate = cy.get(selector, { timeout: 10000 }).last(); + }, + ); + return slate; +}); diff --git a/cypress/support/guillotina.js b/cypress/support/guillotina.js index 5300ff21cd..f8f9275e3f 100644 --- a/cypress/support/guillotina.js +++ b/cypress/support/guillotina.js @@ -3,7 +3,7 @@ export function setupGuillotina() { Authorization: 'Basic cm9vdDpyb290', 'Content-Type': 'application/json', }; - const api_url = 'http://localhost:8081/db'; + const api_url = 'http://127.0.0.1:8081/db'; cy.request({ method: 'POST', @@ -62,7 +62,7 @@ export function tearDownGuillotina({ allowFail = false } = {}) { Authorization: 'Basic cm9vdDpyb290', 'Content-Type': 'application/json', }; - const api_url = 'http://localhost:8081/db'; + const api_url = 'http://127.0.0.1:8081/db'; cy.request({ method: 'DELETE', diff --git a/cypress/support/reset-fixture.js b/cypress/support/reset-fixture.js index a9a5fad79c..ebe6fffaf6 100644 --- a/cypress/support/reset-fixture.js +++ b/cypress/support/reset-fixture.js @@ -1,5 +1,5 @@ function setup() { - const api_url = Cypress.env('API_PATH') || 'http://localhost:55001/plone'; + const api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:55001/plone'; cy.request({ method: 'POST', url: `${api_url}/RobotRemote`, @@ -10,7 +10,7 @@ function setup() { } function teardown() { - const api_url = Cypress.env('API_PATH') || 'http://localhost:55001/plone'; + const api_url = Cypress.env('API_PATH') || 'http://127.0.0.1:55001/plone'; cy.request({ method: 'POST', url: `${api_url}/RobotRemote`, diff --git a/cypress/support/upgradetests.js b/cypress/support/upgradetests.js index 8d8d976636..03205a9c70 100644 --- a/cypress/support/upgradetests.js +++ b/cypress/support/upgradetests.js @@ -6,7 +6,7 @@ export const getsystemNeedsUpgrade = { plone_gs_metadata_version_file_system: '6008', plone_gs_metadata_version_installed: '6006', plone_restapi_version: '8.32.0', - plone_version: '6.0.0b3', + plone_version: '6.0.0', python_version: '3.9.14 (main, Sep 13 2022, 03:20:56) \n[GCC 10.2.1 20210110]', upgrade: true, diff --git a/cypress/tests/core/basic/autologin.js b/cypress/tests/core/basic/autologin.js index 214d03e478..2e3a5627ee 100644 --- a/cypress/tests/core/basic/autologin.js +++ b/cypress/tests/core/basic/autologin.js @@ -2,7 +2,7 @@ import { ploneAuth } from '../../../support/constants'; describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:55001/plone'; + const api_url = 'http://127.0.0.1:55001/plone'; const user = ploneAuth[0]; const password = ploneAuth[1]; diff --git a/cypress/tests/core/basic/language-controlpanel.js b/cypress/tests/core/basic/language-controlpanel.js new file mode 100644 index 0000000000..fb734abde2 --- /dev/null +++ b/cypress/tests/core/basic/language-controlpanel.js @@ -0,0 +1,26 @@ +describe('Language control-panel', () => { + beforeEach(() => { + cy.visit('/'); + cy.autologin(); + cy.waitForResourceToLoad('@navigation'); + cy.waitForResourceToLoad('@breadcrumbs'); + cy.waitForResourceToLoad('@actions'); + }); + + it('Displays all valid fields in language control-panel', () => { + cy.visit('/controlpanel/language'); + cy.get('main').within(() => { + cy.get('.field-wrapper-default_language').should('be.visible'); + cy.get('.field-wrapper-available_languages').should('be.visible'); + cy.get('.field-wrapper-use_combined_language_codes').should('be.visible'); + }); + }); + + it('Does not display unwanted fields in language control-panel', () => { + cy.visit('/controlpanel/language'); + cy.get('main').within(() => { + cy.get('.field-wrapper-always_show_selector').should('not.exist'); + cy.get('.field-wrapper-display_flags').should('not.exist'); + }); + }); +}); diff --git a/cypress/tests/core/basic/sharing.js b/cypress/tests/core/basic/sharing.js index de532dacf2..423f1e5beb 100644 --- a/cypress/tests/core/basic/sharing.js +++ b/cypress/tests/core/basic/sharing.js @@ -67,7 +67,7 @@ describe('Sharing Tests', () => { cy.visit('/logout'); cy.wait('@logout'); - cy.autologin('test-user'); + cy.autologin('test-user', 'correct horse battery staple'); cy.visit('/my-page'); cy.findByRole('heading', { name: /my page/i }).should('exist'); }); diff --git a/cypress/tests/core/blocks/blocks-autofocus.js b/cypress/tests/core/blocks/blocks-autofocus.js index 225942ae5f..9e9c27be21 100644 --- a/cypress/tests/core/blocks/blocks-autofocus.js +++ b/cypress/tests/core/blocks/blocks-autofocus.js @@ -17,15 +17,10 @@ describe('New Block Auto Focus Tests', () => { cy.navigate('/my-page/edit'); cy.intercept('GET', '/**/my-page').as('content'); cy.intercept('PATCH', '*').as('save'); - // when I add a text block - //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); }); it('Press Enter on a description block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Text').click(); - cy.get('.blocks-chooser .text').contains('Description').click(); + cy.addNewBlock('description'); cy.get('.documentDescription').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -35,8 +30,10 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a text block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Text').click(); - cy.get('.blocks-chooser .text').contains('Text').click(); + cy.getSlate().click(); + cy.get('button.block-add-button').click(); + cy.get('.blocks-chooser .title').contains('Text').click({ force: true }); + cy.get('.blocks-chooser .text').contains('Text').click({ force: true }); cy.get('.text-slate-editor-inner').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -46,8 +43,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a image block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Media').click(); - cy.get('.blocks-chooser .media').contains('Image').click(); + cy.addNewBlock('image'); cy.get('.block-editor-image').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -57,8 +53,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a video block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Media').click(); - cy.get('.blocks-chooser .media').contains('Video').click(); + cy.addNewBlock('video'); cy.get('.block-editor-video').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -68,8 +63,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a listing block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); cy.get('.block-editor-listing').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -79,8 +73,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a table of contents block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Table of Contents').click(); + cy.addNewBlock('contents'); cy.get('.block-editor-toc').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -90,8 +83,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a maps block adds new autofocused default block', () => { - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); cy.get('.block-editor-maps').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -101,9 +93,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a html block adds new autofocused default block', () => { - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('HTML').click(); + cy.addNewBlock('html'); cy.get('.block-editor-html').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) @@ -113,9 +103,7 @@ describe('New Block Auto Focus Tests', () => { }); it('Press Enter on a search block adds new autofocused default block', () => { - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Search').click(); + cy.addNewBlock('search'); cy.get('.block-editor-search').first().click().type('{enter}'); cy.get('*[class^="block-editor"]') .eq(2) diff --git a/cypress/tests/core/blocks/blocks-chooser.js b/cypress/tests/core/blocks/blocks-chooser.js new file mode 100644 index 0000000000..f5816a8db7 --- /dev/null +++ b/cypress/tests/core/blocks/blocks-chooser.js @@ -0,0 +1,62 @@ +describe('Blocks Tests', () => { + beforeEach(() => { + cy.intercept('POST', '*').as('saveImage'); + cy.intercept('GET', '/**/image.png/@@images/image').as('getImage'); + // given a logged in editor and a page in edit mode + cy.visit('/'); + cy.autologin(); + cy.createContent({ + contentType: 'Document', + contentId: 'my-page', + contentTitle: 'My Page', + }); + cy.visit('/my-page'); + cy.waitForResourceToLoad('@navigation'); + cy.waitForResourceToLoad('@breadcrumbs'); + cy.waitForResourceToLoad('@actions'); + cy.waitForResourceToLoad('@types'); + cy.waitForResourceToLoad('my-page'); + cy.navigate('/my-page/edit'); + }); + + it('Add image block', () => { + // when I add an image block + cy.getSlate().click(); + cy.get('.ui.basic.icon.button.block-add-button').click(); + cy.get('.ui.basic.icon.button.image').contains('Image').click(); + cy.get('.block.image .ui.input input[type="text"]').type( + `https://github.com/plone/volto/raw/master/logos/volto-colorful.png{enter}`, + ); + cy.get('#toolbar-save').click(); + cy.url().should('eq', Cypress.config().baseUrl + '/my-page'); + + // then the page view should contain the image block + cy.get('#page-document img').should( + 'have.attr', + 'src', + 'https://github.com/plone/volto/raw/master/logos/volto-colorful.png', + ); + + cy.get('#page-document img') + .should('be.visible') + .and(($img) => { + // "naturalWidth" and "naturalHeight" are set when the image loads + expect($img[0].naturalWidth).to.be.greaterThan(0); + }); + }); + + it('Press Enter on a listing block adds new autofocused default block', () => { + cy.getSlate().click(); + cy.get('button.block-add-button').click(); + cy.get('.blocks-chooser .title').contains('Common').click(); + cy.get('.blocks-chooser .common') + .contains('Listing') + .click({ force: true }); + cy.get('.block-editor-listing').first().click().type('{enter}'); + cy.get('*[class^="block-editor"]') + .eq(2) + .within(() => { + return cy.get('.selected'); + }); + }); +}); diff --git a/cypress/tests/core/blocks/blocks-copypaste.js b/cypress/tests/core/blocks/blocks-copypaste.js index 6cfa17154f..8b1f0d7091 100644 --- a/cypress/tests/core/blocks/blocks-copypaste.js +++ b/cypress/tests/core/blocks/blocks-copypaste.js @@ -20,10 +20,7 @@ describe('Blocks copy/paste', () => { cy.intercept('PATCH', '/**/my-page').as('save'); cy.intercept('GET', '/**/my-page').as('content'); // GIVEN: A page with multiple blocks - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); cy.get(`.block.maps .toolbar-inner .ui.input input`) .type( '', @@ -62,10 +59,7 @@ describe('Blocks copy/paste', () => { // GIVEN: A page with multiple blocks cy.intercept('PATCH', '/**/my-page').as('save'); cy.intercept('GET', '/**/my-page').as('content'); - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); cy.get(`.block.maps .toolbar-inner .ui.input input`) .type( '', @@ -105,10 +99,7 @@ describe('Blocks copy/paste', () => { cy.intercept('PATCH', '/**/my-page').as('save'); cy.intercept('GET', '/**/my-page').as('content'); // GIVEN: A page with multiple blocks - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); cy.get(`.block.maps .toolbar-inner .ui.input input`) .type( '', diff --git a/cypress/tests/core/blocks/blocks-listing.js b/cypress/tests/core/blocks/blocks-listing.js index c6de188ce0..bea65dac47 100644 --- a/cypress/tests/core/blocks/blocks-listing.js +++ b/cypress/tests/core/blocks/blocks-listing.js @@ -55,10 +55,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('My title'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //verify before save cy.get(`.block.listing .listing-body:first-of-type`).contains( @@ -115,10 +112,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('My title'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //verify before save cy.get(`.block.listing .listing-body:first-of-type`).contains( @@ -137,7 +131,7 @@ describe('Listing Block Tests', () => { ); }); - it.only('Add Listing block - results preview', () => { + it('Add Listing block - results preview', () => { cy.intercept('PATCH', '/**/my-page').as('save'); cy.intercept('GET', '/**/my-page').as('content'); cy.intercept('GET', '/**/@types/Document').as('schema'); @@ -171,10 +165,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('My title'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); cy.get('.sidebar-container .tabs-wrapper .menu .item') .contains('Block') @@ -250,10 +241,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('My title'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //verify before save cy.get(`.block.listing .listing-body:first-of-type`).contains( @@ -308,10 +296,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('My title'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //******** add Type criteria filter cy.get('.querystring-widget .fields').contains('Add criteria').click(); @@ -372,10 +357,7 @@ describe('Listing Block Tests', () => { //add listing block cy.scrollTo('bottom'); - cy.getSlate(true).click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing', true); //******** add Type criteria filter cy.get('.sidebar-container .tabs-wrapper .menu .item') @@ -451,10 +433,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('Listing block - Test Criteria: short-name'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //******** add short-name criteria filter cy.get('.sidebar-container .tabs-wrapper .menu .item') @@ -544,10 +523,7 @@ describe('Listing Block Tests', () => { ); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //******** add location criteria filter cy.get('.sidebar-container .tabs-wrapper .menu .item') @@ -636,10 +612,7 @@ describe('Listing Block Tests', () => { ); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //******** add location criteria filter cy.get('.sidebar-container .tabs-wrapper .menu .item') @@ -730,10 +703,7 @@ describe('Listing Block Tests', () => { cy.wait('@schema'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //******** add location criteria filter cy.get('.sidebar-container .tabs-wrapper .menu .item') @@ -816,10 +786,7 @@ describe('Listing Block Tests', () => { cy.clearSlateTitle().type('Listing block - respect batching and limits'); //add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); //verify before save cy.get(`.block.listing .listing-body:first-of-type`).contains('My Folder'); diff --git a/cypress/tests/core/blocks/blocks-map.js b/cypress/tests/core/blocks/blocks-map.js index c4872e9671..9644513af9 100644 --- a/cypress/tests/core/blocks/blocks-map.js +++ b/cypress/tests/core/blocks/blocks-map.js @@ -18,10 +18,8 @@ describe('Map Block Tests', () => { it('Add maps block - Google Maps', () => { // when I add a maps block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); + cy.get(`.block.maps .toolbar-inner .ui.input input`) .type( '', @@ -43,10 +41,8 @@ describe('Map Block Tests', () => { it('Add maps block - OpenStreet Maps', () => { // when I add a maps block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Maps').click(); + cy.addNewBlock('maps'); + cy.get(`.block.maps .toolbar-inner .ui.input input`) .type( 'View Larger Map', diff --git a/cypress/tests/core/blocks/blocks-search.js b/cypress/tests/core/blocks/blocks-search.js index 9fe55fe871..d4ca23f8a9 100644 --- a/cypress/tests/core/blocks/blocks-search.js +++ b/cypress/tests/core/blocks/blocks-search.js @@ -43,10 +43,7 @@ describe('Search Block Tests', () => { cy.getSlateTitle().focus().click().type('My Search Page'); // Add Search listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Search').click(); + cy.addNewBlock('search'); // Add search query criteria cy.get('#blockform-fieldset-searchquery').click(); diff --git a/cypress/tests/core/blocks/blocks.js b/cypress/tests/core/blocks/blocks.js index 7e0912118d..e206dbc965 100644 --- a/cypress/tests/core/blocks/blocks.js +++ b/cypress/tests/core/blocks/blocks.js @@ -67,10 +67,7 @@ describe('Blocks Tests', () => { it('Add HTML block', () => { // when I add a maps block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('HTML').click(); + cy.addNewBlock('html'); cy.get(`.block.html .npm__react-simple-code-editor__textarea`).type( `
This is HTML`, ); @@ -92,10 +89,7 @@ describe('Blocks Tests', () => { cy.intercept('PATCH', '*').as('save'); cy.intercept('GET', '/**/my-page').as('content'); // Edit - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.ui.buttons .button.slateTable').click(); + cy.addNewBlock('table'); cy.wait(2000); cy.get( '.celled.fixed.table thead tr th:first-child() [contenteditable="true"]', @@ -235,4 +229,19 @@ describe('Blocks Tests', () => { // 'header-two', // ); // }); + + it('Handles unknown blocks', () => { + cy.createContent({ + contentType: 'Document', + contentId: 'test-doc', + contentTitle: 'my test document', + bodyModifier(body) { + body.blocks['abc'] = { '@type': 'missing' }; + body.blocks_layout.items.push('abc'); + return body; + }, + }); + cy.visit('/test-doc'); + cy.get('#page-document div').should('have.text', 'Unknown Block missing'); + }); }); diff --git a/cypress/tests/core/blocks/hero.js b/cypress/tests/core/blocks/hero.js index d93012c22b..445dbc13f3 100644 --- a/cypress/tests/core/blocks/hero.js +++ b/cypress/tests/core/blocks/hero.js @@ -29,10 +29,7 @@ describe('Blocks Tests', () => { cy.navigate('/my-page/edit'); cy.wait('@schema'); - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .hero').contains('Hero').click(); + cy.addNewBlock('hero'); // cy.fixture(expectedFile).then(fileContent => { // cy.get(`.block.${block} [data-cy="dropzone]`).upload( diff --git a/cypress/tests/core/blocks/teaser.js b/cypress/tests/core/blocks/teaser.js new file mode 100644 index 0000000000..60a4c13a4c --- /dev/null +++ b/cypress/tests/core/blocks/teaser.js @@ -0,0 +1,49 @@ +context('Blocks Acceptance Tests', () => { + beforeEach(() => { + cy.visit('/'); + cy.viewport('macbook-16'); + cy.createContent({ + contentType: 'Document', + contentId: 'document', + contentTitle: 'Document', + }); + cy.autologin(); + }); + + it('As editor I can add a (standalone) Teaser block', () => { + // GIVEN a Document with the title document and a Document to reference with the title Blue Orchidees + cy.createContent({ + contentType: 'Document', + contentId: 'blue-orchidees', + contentTitle: 'Blue Orchidees', + contentDescription: 'are growing on the mountain tops', + image: true, + path: '/document', + }); + cy.visit('/document/edit'); + // WHEN I create a Teaser block + cy.get('.block .slate-editor [contenteditable=true]').click(); + cy.get('.button .block-add-button').click({ force: true }); + cy.get('.blocks-chooser .mostUsed .button.teaser') + .contains('Teaser') + .click({ force: true }); + cy.get( + '.objectbrowser-field[aria-labelledby="fieldset-default-field-label-href"] button[aria-label="Open object browser"]', + ).click(); + cy.get('[aria-label="Select Blue Orchidees"]').dblclick(); + cy.wait(500); + cy.get('.align-buttons .ui.buttons button[aria-label="Center"]').click(); + cy.get('#toolbar-save').click(); + + // THEN I can see the Teaser block + cy.visit('/document'); + cy.get('.block.teaser').should('have.class', 'has--align--center'); + cy.get('.block.teaser .image-wrapper img') + .should('have.attr', 'src') + .and('include', '/document/blue-orchidees/@@images/preview_image-'); + cy.get('.block.teaser .content h2').contains('Blue Orchidees'); + cy.get('.block.teaser .content p').contains( + 'are growing on the mountain tops', + ); + }); +}); diff --git a/cypress/tests/core/guillotina/autologin.js b/cypress/tests/core/guillotina/autologin.js index 67eb37e9be..fce720381b 100644 --- a/cypress/tests/core/guillotina/autologin.js +++ b/cypress/tests/core/guillotina/autologin.js @@ -1,6 +1,6 @@ describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:8081/db/web'; + const api_url = 'http://127.0.0.1:8081/db/web'; const user = 'admin'; const password = 'admin'; diff --git a/cypress/tests/core/volto-slate/09-block-slate-slashmenu.js b/cypress/tests/core/volto-slate/09-block-slate-slashmenu.js new file mode 100644 index 0000000000..8cce4cb989 --- /dev/null +++ b/cypress/tests/core/volto-slate/09-block-slate-slashmenu.js @@ -0,0 +1,14 @@ +import { slateBeforeEach } from '../../../support/e2e'; + +describe('SlashMenu Test: Shortcuts', () => { + beforeEach(slateBeforeEach); + + it('As editor I can create a Table block using the SlashMenu shortcut', function () { + // Use SlashMenu shortcut to create a table block + cy.getSlateEditorAndType('/t').type('{enter}'); + cy.toolbarSave(); + + // then the page view should contain a table + cy.get('#page-document table').should('be.visible'); + }); +}); diff --git a/cypress/tests/core/volto-slate/24-block-slate-format-boldlists.js b/cypress/tests/core/volto-slate/24-block-slate-format-boldlists.js index 1ebb4fb339..1971244b8f 100644 --- a/cypress/tests/core/volto-slate/24-block-slate-format-boldlists.js +++ b/cypress/tests/core/volto-slate/24-block-slate-format-boldlists.js @@ -40,31 +40,31 @@ describe('Block Tests: Bold Bulleted lists', () => { 'sleep furiously.', ); }); + it('As editor I can paste internal(slate formatted) formatted bulleted lists', function () { // Complete chained commands - cy.getSlateEditorAndType('This is slate"s own bold content'); - cy.setSlateSelection('This is slate"s own'); + cy.getSlateEditorAndType("This is slate's own bold content"); + cy.setSlateSelection("This is slate's own"); //create a bold bullted list cy.clickSlateButton('Bulleted list'); cy.clickSlateButton('Bold'); //copy content "This is slate"s own" - cy.setSlateCursor('content') - .type('{enter}') - .pasteClipboard( - 'This is slate"s own', - ); + cy.setSlateCursor('content').type('{enter}'); + cy.getSlate().pasteClipboard( + "This is slate's own", + ); // Save cy.toolbarSave(); cy.get('[id="page-document"] ul li:nth-child(1) strong').contains( - 'This is slate"s own', + "This is slate's own", ); //pasted content cy.get('[id="page-document"] ul li:nth-child(2) strong').contains( - 'This is slate"s own', + "This is slate's own", ); }); @@ -83,6 +83,7 @@ describe('Block Tests: Bold Bulleted lists', () => { // Save cy.toolbarSave(); + // cy.pause(); cy.get('[id="page-document"] ul li:nth-child(1) strong').contains( 'This is slate"s own bold content', diff --git a/cypress/tests/core/volto-slate/27-block-slate-paste-html.js b/cypress/tests/core/volto-slate/27-block-slate-paste-html.js new file mode 100644 index 0000000000..74a815f29c --- /dev/null +++ b/cypress/tests/core/volto-slate/27-block-slate-paste-html.js @@ -0,0 +1,47 @@ +import { slateBeforeEach } from '../../../support/e2e'; + +describe('Block Tests: external text containing html contents/tags ', () => { + beforeEach(slateBeforeEach); + + it('should paste external text containing html', function () { + // cy.getSlateEditorAndType('Let"s paste external html texts'); + // cy.setSlateCursor('texts').type('{enter}'); + cy.getSlate().pasteClipboard( + '
For simplicity, emissions arising (CRF 3B) were presented for all livestock type h CH4 and N2O), e CO2e value.single CO2e figure.
', + ); + + // Save + cy.toolbarSave(); + + cy.get('[id="page-document"] p').should('have.length', 1); + }); + + it('should paste external formatted text and does not split the blocks', function () { + // The idea is pasteClipboard should only apply on its attached slate block + // by not splitting them into blocks. + cy.getSlate().pasteClipboard( + `Lorem Ipsum +is simply dummy text of the printing and typesetting industry. +
`, + ); + + // Save + cy.toolbarSave(); + cy.get('[id="page-document"] > p:nth-of-type(1)').should( + 'have.html', + `Lorem Ipsum is simply dummy text of the printing and typesetting industry.`, + ); + }); + + it('should paste external text containing empty anchor links', function () { + cy.getSlate().pasteClipboard( + ` + `, + ); + + // Save + cy.toolbarSave(); + + cy.get('[id="page-document"] p a').should('have.length', 1); + }); +}); diff --git a/cypress/tests/core/volto-slate/28-table-block-slate-paste.js b/cypress/tests/core/volto-slate/28-table-block-slate-paste.js new file mode 100644 index 0000000000..50b3b64627 --- /dev/null +++ b/cypress/tests/core/volto-slate/28-table-block-slate-paste.js @@ -0,0 +1,55 @@ +import { slateBeforeEach } from '../../../support/volto-slate'; + +describe('Block Tests: pasting content in table block', () => { + beforeEach(slateBeforeEach); + + it('should paste text', function () { + cy.intercept('PATCH', '/**/my-page').as('save'); + + // Paste + cy.getTableSlate(true) + .focus() + .click() + .pasteClipboard('Some Text from Clipboard'); + + cy.getTableSlate() + .focus() + .click() + .pasteClipboard('Some Text from Clipboard'); + + // Save + cy.toolbarSave(); + cy.wait('@save'); + + // View + cy.get('.celled.fixed.table thead tr th:first').contains( + 'Some Text from Clipboard', + ); + cy.get( + '.celled.fixed.table tbody tr:nth-child(1) td:first-child()', + ).contains('Some Text from Clipboard'); + }); + + it('should paste external text containing html', function () { + // Paste + cy.getTableSlate(true) + .focus() + .click() + .pasteClipboard( + 'For simplicity, emissions arising (CRF 3B) were presented for all livestock type h CH4 and N2O), e CO2e value.single CO2e figure.
', + ); + + cy.getTableSlate() + .focus() + .click() + .pasteClipboard( + 'For simplicity, emissions arising (CRF 3B) were presented for all livestock type h CH4 and N2O), e CO2e value.single CO2e figure.
', + ); + + // Save + cy.toolbarSave(); + + // View + cy.get('[id="page-document"] p').should('have.length', 2); + }); +}); diff --git a/cypress/tests/coresandbox/autologin.js b/cypress/tests/coresandbox/autologin.js index 45c13788ca..bc4d02606d 100644 --- a/cypress/tests/coresandbox/autologin.js +++ b/cypress/tests/coresandbox/autologin.js @@ -2,7 +2,7 @@ import { ploneAuth } from '../../support/constants'; describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:55001/plone'; + const api_url = 'http://127.0.0.1:55001/plone'; const user = ploneAuth[0]; const password = ploneAuth[1]; diff --git a/cypress/tests/coresandbox/defaultview.js b/cypress/tests/coresandbox/defaultview.js new file mode 100644 index 0000000000..e3955c0dce --- /dev/null +++ b/cypress/tests/coresandbox/defaultview.js @@ -0,0 +1,39 @@ +context('Block Default View / Edit Acceptance Tests', () => { + describe('Block Default View / Edit', () => { + beforeEach(() => { + // given a logged in editor and a page in edit mode + cy.visit('/'); + cy.autologin(); + cy.createContent({ + contentType: 'Document', + contentId: 'document', + contentTitle: 'Test document', + }); + cy.visit('/document'); + cy.waitForResourceToLoad('@navigation'); + cy.waitForResourceToLoad('@breadcrumbs'); + cy.waitForResourceToLoad('@actions'); + cy.waitForResourceToLoad('@types'); + cy.waitForResourceToLoad('document'); + cy.navigate('/document/edit'); + cy.getSlateTitle(); + }); + + it('I can add a block with Default View / Edit based on schema and interact with it', function () { + cy.getSlate().click(); + cy.get('.button .block-add-button').click({ force: true }); + cy.get('.blocks-chooser .mostUsed .button.testBlockDefaultView').click(); + + cy.get('#field-fieldAfterObjectList') + .click() + .type('Colorless green ideas sleep furiously.'); + + cy.get('.page-block').contains('Colorless green ideas sleep furiously.'); + + cy.get('#toolbar-save').click(); + cy.get('[id="page-document"]').contains( + 'Colorless green ideas sleep furiously.', + ); + }); + }); +}); diff --git a/cypress/tests/coresandbox/fields.js b/cypress/tests/coresandbox/fields.js index 7770b54596..ddf4230bd2 100644 --- a/cypress/tests/coresandbox/fields.js +++ b/cypress/tests/coresandbox/fields.js @@ -1,4 +1,106 @@ context('Special fields Acceptance Tests', () => { + describe('Form with default values', () => { + beforeEach(() => { + // given a logged in editor and a page in edit mode + cy.visit('/'); + cy.autologin(); + cy.createContent({ + contentType: 'Document', + contentId: 'document', + contentTitle: 'Test document', + }); + cy.visit('/document'); + cy.waitForResourceToLoad('@navigation'); + cy.waitForResourceToLoad('@breadcrumbs'); + cy.waitForResourceToLoad('@actions'); + cy.waitForResourceToLoad('@types'); + cy.waitForResourceToLoad('document'); + cy.navigate('/document/edit'); + cy.getSlateTitle(); + }); + + it('As an editor I can add a block that has default values', () => { + cy.intercept('PATCH', '/**/document').as('save'); + cy.intercept('GET', '/**/@types/Document').as('schema'); + cy.getSlate().click(); + cy.get('.button .block-add-button').click({ force: true }); + cy.wait(100); + cy.get('.blocks-chooser .mostUsed .button.testBlock').click(); + + cy.findByLabelText('Field with default').click(); + cy.get('#field-firstWithDefault').should( + 'have.value', + 'Some default value', + ); + + cy.findByLabelText('Add item').click(); + cy.findAllByText('Item #1').should('have.length', 1); + + cy.findByLabelText('Extra').should('have.value', 'Extra default'); + cy.get('#toolbar-save').click(); + cy.wait('@save'); + + cy.navigate('/document/edit'); + cy.wait('@schema'); + + cy.findAllByText('Test Block Edit').click(); + + cy.get('#field-firstWithDefault').should( + 'have.value', + 'Some default value', + ); + cy.findByLabelText('Extra').should('have.value', 'Extra default'); + + cy.getContent({ path: '/document' }).should((response) => { + const { body } = response; + const [, testBlock] = Object.entries(body.blocks).find( + ([, block]) => block['@type'] === 'testBlock', + ); + expect(testBlock.style).to.deep.equal({ color: 'red' }); + expect(testBlock.slides[0].extraDefault).to.deep.equal('Extra default'); + }); + }); + }); + + describe('HTML Richtext Widget', () => { + beforeEach(() => { + // given a logged in editor and a page in edit mode + cy.visit('/'); + cy.autologin(); + cy.createContent({ + contentType: 'Document', + contentId: 'document', + contentTitle: 'Test document', + }); + cy.visit('/document'); + cy.waitForResourceToLoad('@navigation'); + cy.waitForResourceToLoad('@breadcrumbs'); + cy.waitForResourceToLoad('@actions'); + cy.waitForResourceToLoad('@types'); + cy.waitForResourceToLoad('document'); + cy.navigate('/document/edit'); + cy.getSlateTitle(); + }); + + it('Handles whitespaces properly', () => { + cy.intercept('PATCH', '/**/document').as('save'); + cy.getSlate().click(); + cy.get('.button .block-add-button').click({ force: true }); + cy.get('.blocks-chooser .mostUsed .button.testBlock').click(); + cy.get('#fieldset-default-field-label-html').click(); + cy.get('.slate_wysiwyg_box [contenteditable=true]').type( + ' hello world ', + ); + cy.get('#toolbar-save').click(); + cy.wait('@save'); + + cy.get('.test-block').should( + 'contain.text', + 'hello world
', + ); + }); + }); + describe('ObjectListWidget', () => { beforeEach(() => { // given a logged in editor and a page in edit mode @@ -53,6 +155,7 @@ context('Special fields Acceptance Tests', () => { cy.findAllByText('Item #3').should('have.length', 0); }); }); + describe('Variation field', () => { beforeEach(() => { // given a logged in editor and a page in edit mode @@ -83,6 +186,7 @@ context('Special fields Acceptance Tests', () => { cy.findByText('Custom'); }); }); + describe('ObjectBrowserWidget', () => { beforeEach(() => { // given a logged in editor and a page in edit mode @@ -108,6 +212,7 @@ context('Special fields Acceptance Tests', () => { cy.navigate('/document/edit'); cy.getSlateTitle(); }); + it('As editor I can add a block with an objetBrowserWidget and the context path is preserved', function () { cy.getSlate().click(); cy.get('.button .block-add-button').click({ force: true }); diff --git a/cypress/tests/coresandbox/listingblock.js b/cypress/tests/coresandbox/listingblock.js index a49dc6ad3e..82fe619aec 100644 --- a/cypress/tests/coresandbox/listingblock.js +++ b/cypress/tests/coresandbox/listingblock.js @@ -40,10 +40,7 @@ context('Listing block tests', () => { cy.navigate('/document/edit'); // Add listing block - cy.getSlate().click(); - cy.get('button.block-add-button').click(); - cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.addNewBlock('listing'); // select variation cy.get('#field-variation') @@ -88,10 +85,13 @@ context('Listing block tests', () => { cy.navigate('/document/edit'); // Add listing block + cy.addNewBlock('listing'); cy.getSlate().click(); cy.get('button.block-add-button').click(); cy.get('.blocks-chooser .title').contains('Common').click(); - cy.get('.blocks-chooser .common').contains('Listing').click(); + cy.get('.blocks-chooser .common') + .contains('Listing') + .click({ force: true }); // select variation cy.get('#field-variation') diff --git a/cypress/tests/guillotina/autologin.js b/cypress/tests/guillotina/autologin.js index 67eb37e9be..fce720381b 100644 --- a/cypress/tests/guillotina/autologin.js +++ b/cypress/tests/guillotina/autologin.js @@ -1,6 +1,6 @@ describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:8081/db/web'; + const api_url = 'http://127.0.0.1:8081/db/web'; const user = 'admin'; const password = 'admin'; diff --git a/cypress/tests/multilingual/autologin.js b/cypress/tests/multilingual/autologin.js index 45c13788ca..bc4d02606d 100644 --- a/cypress/tests/multilingual/autologin.js +++ b/cypress/tests/multilingual/autologin.js @@ -2,7 +2,7 @@ import { ploneAuth } from '../../support/constants'; describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:55001/plone'; + const api_url = 'http://127.0.0.1:55001/plone'; const user = ploneAuth[0]; const password = ploneAuth[1]; diff --git a/cypress/tests/workingCopy/autologin.js b/cypress/tests/workingCopy/autologin.js index 45c13788ca..bc4d02606d 100644 --- a/cypress/tests/workingCopy/autologin.js +++ b/cypress/tests/workingCopy/autologin.js @@ -2,7 +2,7 @@ import { ploneAuth } from '../../support/constants'; describe('Autologin Tests', () => { it('Autologin as an standalone test', function () { - const api_url = 'http://localhost:55001/plone'; + const api_url = 'http://127.0.0.1:55001/plone'; const user = ploneAuth[0]; const password = ploneAuth[1]; diff --git a/docker-compose.yml b/docker-compose.yml index 7bd820f2bd..82a49830b7 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,14 +2,13 @@ version: '3.3' services: backend: - image: plone/plone-backend:6.0.0b2 + image: plone/plone-backend:6.0.1 # Plone 5.2 series can be used too - # image: plone/plone-backend:5.2.9 + # image: plone/plone-backend:5.2.10 ports: - '8080:8080' environment: - SITE=Plone - - 'ADDONS=plone.restapi==8.29.0 plone.volto==4.0.0a13 plone.rest==2.0.0a5' - 'PROFILES=plone.volto:default-homepage' labels: - traefik.enable=true @@ -47,7 +46,7 @@ services: reverse-proxy: # The official v2 Traefik docker image - image: traefik:v2.8 + image: traefik:v2.9 # Enables the web UI and tells Traefik to listen to docker command: --api.insecure=true --providers.docker ports: @@ -57,7 +56,7 @@ services: - "8888:8080" volumes: # So that Traefik can listen to the Docker events - - /var/run/docker.sock:/var/run/docker.sock + - /var/run/docker.sock:/var/run/docker.sock:ro labels: - traefik.http.middlewares.gzip.compress=true - traefik.http.middlewares.gzip.compress.excludedcontenttypes=image/png, image/jpeg, font/woff2 diff --git a/docs/source/_static/copy.svg b/docs/source/_static/copy.svg new file mode 100644 index 0000000000..3e9fd912ba --- /dev/null +++ b/docs/source/_static/copy.svg @@ -0,0 +1,6 @@ + \ No newline at end of file diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 0f540ff020..d792d49f36 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -35,6 +35,12 @@ figure img, width: 200px; margin-bottom: 1rem; } + +img.inline { + margin: 0; + height: 1em; +} + span.linenos { padding-right: 1em; } @@ -234,3 +240,7 @@ span.guilabel, span.menuselection { font-style: italic; white-space: nowrap; } + +video { + width: 100%; +} diff --git a/docs/source/_static/cut.svg b/docs/source/_static/cut.svg new file mode 100644 index 0000000000..6a3b112b14 --- /dev/null +++ b/docs/source/_static/cut.svg @@ -0,0 +1,3 @@ + \ No newline at end of file diff --git a/docs/source/_static/paste.svg b/docs/source/_static/paste.svg new file mode 100644 index 0000000000..91e9435607 --- /dev/null +++ b/docs/source/_static/paste.svg @@ -0,0 +1,6 @@ + \ No newline at end of file diff --git a/docs/source/_static/user-manual/blocks/add-new-block.gif b/docs/source/_static/user-manual/blocks/add-new-block.gif new file mode 100644 index 0000000000..29425365e9 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/add-new-block.gif differ diff --git a/docs/source/_static/user-manual/blocks/block-copy-cut.mp4 b/docs/source/_static/user-manual/blocks/block-copy-cut.mp4 new file mode 100644 index 0000000000..2a6a0658eb Binary files /dev/null and b/docs/source/_static/user-manual/blocks/block-copy-cut.mp4 differ diff --git a/docs/source/_static/user-manual/blocks/block-left-add-icon.png b/docs/source/_static/user-manual/blocks/block-left-add-icon.png new file mode 100644 index 0000000000..bcb7c63d93 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/block-left-add-icon.png differ diff --git a/docs/source/_static/user-manual/blocks/block-paste.mp4 b/docs/source/_static/user-manual/blocks/block-paste.mp4 new file mode 100644 index 0000000000..05ffbc66e6 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/block-paste.mp4 differ diff --git a/docs/source/_static/user-manual/blocks/block-types-menu.png b/docs/source/_static/user-manual/blocks/block-types-menu.png new file mode 100644 index 0000000000..7bd3a57916 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/block-types-menu.png differ diff --git a/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png b/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png new file mode 100644 index 0000000000..46554cffd1 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png differ diff --git a/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png b/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png new file mode 100644 index 0000000000..9d3e887867 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png differ diff --git a/docs/source/_static/user-manual/blocks/hero-block.png b/docs/source/_static/user-manual/blocks/hero-block.png new file mode 100644 index 0000000000..6b284bac90 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/hero-block.png differ diff --git a/docs/source/_static/user-manual/blocks/html-block.png b/docs/source/_static/user-manual/blocks/html-block.png new file mode 100644 index 0000000000..64481f922f Binary files /dev/null and b/docs/source/_static/user-manual/blocks/html-block.png differ diff --git a/docs/source/_static/user-manual/blocks/image-block-configuration-options.png b/docs/source/_static/user-manual/blocks/image-block-configuration-options.png new file mode 100644 index 0000000000..555308d43d Binary files /dev/null and b/docs/source/_static/user-manual/blocks/image-block-configuration-options.png differ diff --git a/docs/source/_static/user-manual/blocks/image-block.png b/docs/source/_static/user-manual/blocks/image-block.png new file mode 100644 index 0000000000..2cdba7290b Binary files /dev/null and b/docs/source/_static/user-manual/blocks/image-block.png differ diff --git a/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png b/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png new file mode 100644 index 0000000000..efa356c7cd Binary files /dev/null and b/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png differ diff --git a/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png b/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png new file mode 100644 index 0000000000..9d3e887867 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png differ diff --git a/docs/source/_static/user-manual/blocks/listing-block-configuration.png b/docs/source/_static/user-manual/blocks/listing-block-configuration.png new file mode 100644 index 0000000000..4ef4628d93 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/listing-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/listing-block.png b/docs/source/_static/user-manual/blocks/listing-block.png new file mode 100644 index 0000000000..8073df0fbd Binary files /dev/null and b/docs/source/_static/user-manual/blocks/listing-block.png differ diff --git a/docs/source/_static/user-manual/blocks/map-blocks-configuration.png b/docs/source/_static/user-manual/blocks/map-blocks-configuration.png new file mode 100644 index 0000000000..c6213fe009 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/map-blocks-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/maps-block.png b/docs/source/_static/user-manual/blocks/maps-block.png new file mode 100644 index 0000000000..fd08e0b62e Binary files /dev/null and b/docs/source/_static/user-manual/blocks/maps-block.png differ diff --git a/docs/source/_static/user-manual/blocks/search-block-configuration.png b/docs/source/_static/user-manual/blocks/search-block-configuration.png new file mode 100644 index 0000000000..43f174a8df Binary files /dev/null and b/docs/source/_static/user-manual/blocks/search-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/search-block.png b/docs/source/_static/user-manual/blocks/search-block.png new file mode 100644 index 0000000000..70c6e72ea7 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/search-block.png differ diff --git a/docs/source/_static/user-manual/blocks/table-block-configuration.png b/docs/source/_static/user-manual/blocks/table-block-configuration.png new file mode 100644 index 0000000000..236762bf2c Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/table-block.png b/docs/source/_static/user-manual/blocks/table-block.png new file mode 100644 index 0000000000..ca73e45924 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-block.png differ diff --git a/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png b/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png new file mode 100644 index 0000000000..6da6c6ad64 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/table-of-contents-block.png b/docs/source/_static/user-manual/blocks/table-of-contents-block.png new file mode 100644 index 0000000000..73faaba5da Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-of-contents-block.png differ diff --git a/docs/source/_static/user-manual/blocks/teaser-block-configuration.png b/docs/source/_static/user-manual/blocks/teaser-block-configuration.png new file mode 100644 index 0000000000..55c21c78cd Binary files /dev/null and b/docs/source/_static/user-manual/blocks/teaser-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/teaser-block.png b/docs/source/_static/user-manual/blocks/teaser-block.png new file mode 100644 index 0000000000..b8a500982b Binary files /dev/null and b/docs/source/_static/user-manual/blocks/teaser-block.png differ diff --git a/docs/source/_static/user-manual/blocks/video-block-configuration.png b/docs/source/_static/user-manual/blocks/video-block-configuration.png new file mode 100644 index 0000000000..b6c5283ca3 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/video-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/video-block.png b/docs/source/_static/user-manual/blocks/video-block.png new file mode 100644 index 0000000000..870ac385bc Binary files /dev/null and b/docs/source/_static/user-manual/blocks/video-block.png differ diff --git a/docs/source/addons/best-practices.md b/docs/source/addons/best-practices.md index ae5bcbe773..e58eb3c8e2 100644 --- a/docs/source/addons/best-practices.md +++ b/docs/source/addons/best-practices.md @@ -24,7 +24,7 @@ register the most basic configuration of that widget with a name that can be used. On more complicated cases, see if you can structure your code to use the -`settings` configuration registry, or stash your configuration in your block +`settings` {term}`configuration registry`, or stash your configuration in your block registration, for example. As an example: let's say we're building a Color Picker widget and we want to @@ -36,7 +36,7 @@ multiple instances of that color widget with custom color palettes. ### Provide additional configuration -An add-on can ship with multiple Volto configuration loaders. This makes it +An add-on can ship with multiple {term}`Volto configuration loader`s. This makes it possible to provide configuration methods for demo purposes, for example, or to ship with a default "shallow" integration, then provide another separate configuration loader for a deeper integration. diff --git a/docs/source/addons/index.md b/docs/source/addons/index.md index de1b615520..cf456c215b 100644 --- a/docs/source/addons/index.md +++ b/docs/source/addons/index.md @@ -19,86 +19,86 @@ best-practices There are several advanced scenarios where we might want to have more control and flexibility beyond using the plain Volto project to build a site. -We can build Volto add-on products and make them available as generic -Javascript packages that can be included in any Volto project. By doing so we +We can build Volto {term}`add-on` products and make them available as generic +JavaScript packages that can be included in any Volto project. By doing so we can provide code and component reutilization across projects and, of course, benefit from open source collaboration. ```{note} -By declaring a Javascript package as a "Volto addon", Volto provides +By declaring a JavaScript package as a Volto add-on, Volto provides several integration features: language features (so they can be transpiled by Babel), whole-process customization via razzle.extend.js and -integration with Volto's configuration registry. +integration with Volto's {term}`configuration registry`. ``` -The addon 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 addon for development. +you can "checkout" an add-on for development. -An addon can be almost anything that a Volto project can be. They can: +An add-on can be almost anything that a Volto project can be. They can: - provide additional views and blocks - override or extend Volto's builtin views, blocks, settings -- shadow (customize) Volto's (or another addon's) modules +- shadow (customize) Volto's (or another add-on's) modules - register custom routes -- provide custom Redux actions and reducers +- provide custom {term}`Redux` actions and reducers - register custom Express middleware for Volto's server process - tweak Volto's Webpack configuration, load custom Razzle and Webpack plugins - even provide a custom theme, just like a regular Volto project does. -## Configuring a Volto project to use an addon +## Configuring a Volto project to use an add-on -You can install a Volto addon just like any other JS package: +You can install a Volto add-on just like any other JS package: ```shell -yarn add name-of-addon +yarn add name-of-add-on ``` -If the addon 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 ``` -Next, you'll need to add the addon (identified by its JS package name) to the +Next, you'll need to add the add-on (identified by its JS package name) to the `addons` key of your Volto project's `package.json`. More details in the next section. -### Loading addon configuration +### Loading add-on configuration -As a convenience, an addon can export configuration functions that can mutate, -in-place, the overall Volto configuration registry. An addon can export multiple +As a convenience, an add-on can export configuration functions that can mutate, +in-place, the overall Volto {term}`configuration registry`. An add-on can export multiple configurations methods, making it possible to selectively choose which specific -addon functionality you want to load. +add-on functionality you want to load. -In your Volto project's ``package.json`` you can allow the addon to alter the -global configuration by adding, in the ``addons`` key, a list of volto addon +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 package names, like: ```js { "name": "my-nice-volto-project", - ... + "addons": [ - "acme-volto-foo-addon", - "@plone/some-addon", - "collective-another-volto-addon" + "acme-volto-foo-add-on", + "@plone/some-add-on", + "collective-another-volto-add-on" ], - ... + } ``` ```{warning} -Adding the addon package to the `addons` key is obligatory! It allows Volto +Adding the add-on package to the `addons` key is mandatory! It allows Volto to treat that package properly and provide it with BabelJS language features. In Plone terminology, it is like including a Python egg to the `zcml` section of zc.buildout. ``` -Some addons might choose to allow the Volto project to selectively load some of +Some add-ons might choose to allow the Volto project to selectively load some of their configuration, so they may offer additional configuration functions, -which you can load by overloading the addon name in the ``addons`` package.json +which you can load by overloading the add-on name in the `addons` package.json key, like so: ```{code-block} json @@ -107,23 +107,23 @@ key, like so: { "name": "my-nice-volto-project", "addons": [ - "acme-volto-foo-addon:loadOptionalBlocks,overrideSomeDefaultBlock", + "acme-volto-foo-add-on:loadOptionalBlocks,overrideSomeDefaultBlock", "volto-ga" ], } ``` ```{note} -The additional comma-separated names should be exported from the addon +The additional comma-separated names should be exported from the add-on package's ``index.js``. The main configuration function should be exported as -the default. An addon's default configuration method will always be loaded. +the default. An add-on's default configuration method will always be loaded. ``` -If for some reason, you want to manually load the addon, you could always do, +If for some reason, you want to manually load the add-on, you could always do, in your project's ``config.js`` module: ```js -import loadExampleAddon, { enableOptionalBlocks } from 'volto-example-addon'; +import loadExampleAddon, { enableOptionalBlocks } from 'volto-example-add-on'; import * as voltoConfig from '@plone/volto/config'; const config = enableOptionalBlocks(loadExampleAddon(voltoConfig)); @@ -131,7 +131,6 @@ const config = enableOptionalBlocks(loadExampleAddon(voltoConfig)); export blocks = { ...config.blocks, } -... ``` As this is a common operation, Volto provides a helper method for this: @@ -151,26 +150,27 @@ export blocks = { ``` The `applyConfig` helper ensures that each configuration methods returns the -config object, avoiding odd and hard to track errors when developing addons. +config object, avoiding odd and hard to track errors when developing add-ons. -## Creating addons +## Creating add-ons -Volto addon packages are just CommonJS packages. The only requirement is that +Volto add-on packages are just CommonJS packages. The only requirement is that they point the `main` key of their `package.json` to a module that exports, as -a default function that acts as a Volto configuration loader. +a default function that acts as a {term}`Volto configuration loader`. -Although you could simply use `npm init` to generate an addon initial code, +Although you could simply use `npm init` to generate an add-on initial code, we now have a nice [Yeoman-based generator](https://github.com/plone/generator-volto) that you can use: -``` +```shell npm install -g @plone/generator-volto yo @plone/volto:addon [
```
-
Then it's at your discretion how you define the CSS class names in your theme.
+If you need other style of classnames generated, you can use the classname
+converters defined in `config.settings.styleClassNameConverters`, by
+registering fieldnames suffixed with the converter name. For example, a style
+data like:
+
+```
+{
+ "styles": {
+ "theme:noprefix": "primary",
+ "inverted:bool": true,
+ }
+}
+```
+
+will generate classnames `primary inverted`
+
## Align class injection
There is an automatic class name injection happening at the same time the style wrapper class names injection.
diff --git a/docs/source/blocks/core/index.md b/docs/source/blocks/core/index.md
new file mode 100644
index 0000000000..03c2b19613
--- /dev/null
+++ b/docs/source/blocks/core/index.md
@@ -0,0 +1,19 @@
+---
+myst:
+ html_meta:
+ "description": "Core blocks provided in Volto by default"
+ "property=og:description": "Core blocks provided in Volto by default"
+ "property=og:title": "Core blocks provided in Volto by default"
+ "keywords": "Volto, Plone, frontend, React, blocks, default, core"
+---
+
+# Core Blocks developer notes
+
+This part of the documentation describes how to develop the core blocks in Volto.
+
+```{toctree}
+:maxdepth: 1
+
+listing
+teaser
+```
diff --git a/docs/source/blocks/core/listing.md b/docs/source/blocks/core/listing.md
new file mode 100644
index 0000000000..5472fd9fd2
--- /dev/null
+++ b/docs/source/blocks/core/listing.md
@@ -0,0 +1,65 @@
+---
+myst:
+ html_meta:
+ "description": "The listing block provides an additional extension letting the developer modify the default 'No results found' message using the configuration of the block"
+ "property=og:description": "The listing block provides an additional extension letting the developer modify the default 'No results found' message using the configuration of the block"
+ "property=og:title": "Listing block extensions mechanism"
+ "keywords": "Volto, Plone, frontend, React, Upgrade, Guide, Block extensions, variations, schema enhancers, listing block"
+---
+
+(listing-block)=
+
+# Listing block
+
+The listing block is a special block that can be configured to run a catalog query in the backend and show the results of that search.
+
+Apart from the {ref}`standard variation ` and {ref}`schema enchancing extensions `, the listing block provides a configurable way to handle the "No results" message.
+
+When the listing block configured search returns no results, Volto presents a default "No results found" message.
+But sometimes you want to change such a message to offer more meaningful messages, or do some other fancy stuff in that case.
+For instance, you may want to show a "There are no future events" or "There are no images in the gallery" message for a given listing block.
+
+To achieve that, you can configure a new `noResultsComponent` when configuring the listing block, and provide a custom component to render such a message.
+To do that, you need to reconfigure that option in the configuration of your project:
+
+```jsx
+import { FormattedMessage } from 'react-intl';
+
+const MyNoResultsComponent = (props) => {
+ return (
+ ![]()
` tag with the following signature.
+
+```jsx
+
- ;
```
diff --git a/docs/source/blocks/index.md b/docs/source/blocks/index.md
index be691f9b1c..2a8e485349 100644
--- a/docs/source/blocks/index.md
+++ b/docs/source/blocks/index.md
@@ -19,4 +19,5 @@ editcomponent
block-style-wrapper
extensions
ssr
+core/index
```
diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md
index e9d81009c5..e92e736042 100644
--- a/docs/source/blocks/settings.md
+++ b/docs/source/blocks/settings.md
@@ -26,7 +26,6 @@ import CardTeaserView from '@package/components/Blocks/CardTeaserView';
import DefaultColumnRenderer from '@package/components/Blocks/DefaultColumnRenderer';
import NumberColumnRenderer from '@package/components/Blocks/NumberColumnRenderer';
import ColoredColumnRenderer from '@package/components/Blocks/ColoredColumnRenderer';
-import CardTeaserView from '@package/components/Blocks/CardTeaserView';
import CustomSchemaEnhancer from '@package/components/Blocks/CustomSchemaEnhancer';
diff --git a/docs/source/blocks/ssr.md b/docs/source/blocks/ssr.md
index 8cc44a84d7..933dccb1c6 100644
--- a/docs/source/blocks/ssr.md
+++ b/docs/source/blocks/ssr.md
@@ -10,7 +10,7 @@ myst:
# Server-side rendering for async blocks
By default blocks that depend on async-fetched data won't be rendered fully in
-the server-side rendering phase. For the main "content", Volto provides
+the {term}`server-side rendering` phase. For the main "content", Volto provides
a mechanism for async rendering in the form of `asyncConnect` and
`asyncPropExtenders`.
@@ -31,5 +31,5 @@ export default ({ dispatch, data, path }) => {
```
All promises returned will be awaited before the rendering of that block, so
-the strategy is to dispatch the data-fetching actions so that the Redux store
+the strategy is to dispatch the data-fetching actions so that the {term}`Redux` store
gets populated.
diff --git a/docs/source/cheatsheet.md b/docs/source/cheatsheet.md
index f2708476b6..f7b8601d7d 100644
--- a/docs/source/cheatsheet.md
+++ b/docs/source/cheatsheet.md
@@ -14,7 +14,7 @@ myst:
# Cheatsheet
```{seealso}
-{doc}`plone:contributing/writing-docs-guide`
+{doc}`plone:contributing/documentation/myst-reference`
```
@@ -102,25 +102,10 @@ Click the reference {ref}`volto-demo-label` to jump to the target.
);
}
);
-
```
```python
- def asdas:
- """ """
-```
-
-## Toggle paragraph (Exercises / FAQ)
-
-````{admonition} This is a title
-:class: toggle
-
-```{code-block} python
-:linenos:
-:emphasize-lines: 1, 3
-
-a = 2
-print("my 1st line")
-print(f"my {a}nd line")
+def somefunction:
+"""mydocstring"""
+ pass
```
-````
diff --git a/docs/source/conf.py b/docs/source/conf.py
index d5a274aaca..679833e9a9 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -56,11 +56,12 @@
extensions = [
"myst_parser",
"sphinx.ext.autodoc",
+ "sphinx.ext.ifconfig",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx_copybutton",
- "sphinxcontrib.spelling",
"sphinxext.opengraph",
+ "sphinxcontrib.video",
]
@@ -86,6 +87,7 @@
r"https://github.com/plone/documentation/issues/new/choose", # requires auth
# Ignore specific anchors
r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
+ r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0",
r"https://github.com/browserslist/browserslist#queries",
r"https://github.com/nodejs/release#release-schedule",
r"https://github.com/plone/plone.docker#for-basic-usage",
@@ -117,6 +119,7 @@
"spelling_wordlist.txt",
"**/CHANGES.rst",
"**/LICENSE.rst",
+ "contributing/branch-policy.md",
]
html_extra_path = [
@@ -137,6 +140,7 @@
"linkify", # Identify “bare” web URLs and add hyperlinks.
"colon_fence", # You can also use ::: delimiters to denote code fences,\
# instead of ```.
+ "html_image",
]
@@ -153,9 +157,9 @@
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
#
intersphinx_mapping = {
- "plone": ("https://6.dev-docs.plone.org/", None),
+ "plone": ("https://6.docs.plone.org/", None),
"python": ("https://docs.python.org/3/", None),
- "training": ("https://training.plone.org/5/", None),
+ "training": ("https://training.plone.org/", None),
}
@@ -166,9 +170,9 @@
# -- OpenGraph configuration ----------------------------------
-ogp_site_url = "https://6.dev-docs.plone.org/"
+ogp_site_url = "https://6.docs.plone.org/"
ogp_description_length = 200
-ogp_image = "https://docs.plone.org/_static/Plone_logo_square.png"
+ogp_image = "https://6.docs.plone.org/_static/Plone_logo_square.png"
ogp_site_name = "Plone Documentation"
ogp_type = "website"
ogp_custom_meta_tags = [
@@ -199,7 +203,7 @@
# Announce that we have an opensearch plugin
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch
-html_use_opensearch = "https://docs.plone.org"
+html_use_opensearch = "https://6.docs.plone.org"
html_theme_options = {
# TODO: Either get a separate GA ID or enable this one once it is in production.
@@ -246,3 +250,6 @@
# The name of an image file (relative to this directory) to place at the top of
# the title page.
latex_logo = "_static/logo_2x.png"
+
+def setup(app):
+ app.add_config_value("context", "volto", "env")
diff --git a/docs/source/configuration/component-registry.md b/docs/source/configuration/component-registry.md
index 25d39e7abb..1043115cdc 100644
--- a/docs/source/configuration/component-registry.md
+++ b/docs/source/configuration/component-registry.md
@@ -1,11 +1,22 @@
-# Component Registry
+---
+myst:
+ html_meta:
+ "description": "Volto provides an integrated component registry that stores named references to components, allowing them to be queried programmatically."
+ "property=og:description": "Volto provides an integrated component registry that stores named references to components, allowing them to be queried programmatically."
+ "property=og:title": "Component registry in Volto"
+ "keywords": "Volto, Plone, frontend, React, registry, component"
+---
-The configuration registry has a component registry integrated on itself.
+(component-registry)=
+
+# Component registry
+
+The {term}`configuration registry` has a component registry integrated on itself.
These registry stores by a given name the components.
Later you can retrieve them by this name, and use them in your code.
The idea behind is to provide an alternative and more convenient way to customize components.
-You can override programatically such registrations from your add-on or projects because it's stored in the configuration registry.
-You can customize a component without using shadowing at all, if the code that calls the component retrieves the information of the component to use from the component registry.
+You can override programmatically such registrations from your add-on or projects because it's stored in the configuration registry.
+You can customize a component without using {term}`shadowing` at all, if the code that calls the component retrieves the information of the component to use from the component registry.
You can even have modifiers to the component registrations: dependencies. So you can "adapt" the call given an array of such dependencies.
## Registering components by name using `config.registerComponent`
diff --git a/docs/source/configuration/environmentvariables.md b/docs/source/configuration/environmentvariables.md
index ec1c82bd06..4cb8f8b028 100644
--- a/docs/source/configuration/environmentvariables.md
+++ b/docs/source/configuration/environmentvariables.md
@@ -101,7 +101,7 @@ Set `DEBUG_ADDONS_LOADER=true` to have Volto generate a file, `addon-dependency-
dot addon-dependency-graph.dot -Tsvg -o out.svg
```
-#### Component Shadowing errors (shadowing)
+#### Component shadowing errors (shadowing)
It displays the errors of the non-compliant customizations (in server console) if you are experiencing problems with a customization not working.
diff --git a/docs/source/configuration/experimental.md b/docs/source/configuration/experimental.md
new file mode 100644
index 0000000000..103e8a1be9
--- /dev/null
+++ b/docs/source/configuration/experimental.md
@@ -0,0 +1,36 @@
+---
+myst:
+ html_meta:
+ "description": "Enable experimental features in Volto's configuration object"
+ "property=og:description": "Enable experimental features in Volto's configuration object"
+ "property=og:title": "Experimental features"
+ "keywords": "Volto, Plone, frontend, experimental, features"
+---
+
+# Experimental features
+
+Experimental features are planned for inclusion in a future release of Volto,
+but are not yet considered mature by the community.
+An experimental feature gives users an easy way to install it and see if anything breaks before we make a new stable release that includes it.
+
+## Volto configuration
+
+You can enable an experimental feature—also called a "feature flag"—in Volto's configuration object as shown below.
+
+```js
+import config from '@plone/volto/registry'
+
+config.experimental.addBlockButton.enabled = true;
+```
+
+Currently the following experimental features are available:
+
+```{glossary}
+:sorted:
+
+addBlockButton
+ Enables a new UI for adding blocks.
+ The button to add a block is now shown below any selected block.
+ A text block can also be added by clicking in the empty area at the bottom of the content area.
+
+```
diff --git a/docs/source/configuration/how-to.md b/docs/source/configuration/how-to.md
index ead54e6081..12d3bfae16 100644
--- a/docs/source/configuration/how-to.md
+++ b/docs/source/configuration/how-to.md
@@ -9,7 +9,7 @@ myst:
# The configuration registry
-Volto has a centralized configuration registry used to parameterize Volto. It has the
+Volto has a centralized {term}`configuration registry` used to parameterize Volto. It has the
form of a singleton that can be called and queried from anywhere in your code like this:
```js
diff --git a/docs/source/configuration/index.md b/docs/source/configuration/index.md
index 421c36f0d3..fde6916ff3 100644
--- a/docs/source/configuration/index.md
+++ b/docs/source/configuration/index.md
@@ -14,6 +14,7 @@ myst:
how-to
settings-reference
+experimental
zero-config-builds
component-registry
internalproxy
diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md
index a5f4820236..93f4c0c9af 100644
--- a/docs/source/configuration/internalproxy.md
+++ b/docs/source/configuration/internalproxy.md
@@ -9,7 +9,7 @@ myst:
# Internal proxy to content backend API
-The server side Volto SSR process (based on Razzle) has an internal proxy to the backend API
+The server side Volto {term}`SSR` process (based on Razzle) has an internal proxy to the backend API
enabled by default.
It provides a better developer experience out of the box, so the developer doesn't has to
@@ -20,7 +20,7 @@ To understand the need for the internal proxy, there are three processes running
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
- Server Side Rendering (SSR) of your pages on first request (Javascript, the
+ {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)
diff --git a/docs/source/configuration/settings-reference.md b/docs/source/configuration/settings-reference.md
index cc43b0a37e..d5d989f356 100644
--- a/docs/source/configuration/settings-reference.md
+++ b/docs/source/configuration/settings-reference.md
@@ -28,39 +28,12 @@ navDepth
defaultBlockType
The default block type in Volto is "text", which uses the current DraftJS-based implementation for the rich text editor. Future alternative rich text editors will need to use this setting and replace it with their block type. The block definition should also include the `blockHasValue` function, which is needed to activate the Block Chooser functionality. See this function signature in [Blocks > Settings](../blocks/settings.md).
+
sentryOptions
- Sentry configuration:
+ In Volto 16.0.0.alpha.45, Sentry integration was moved from core to the add-on [`@plone-collective/volto-sentry`](https://www.npmjs.com/package/@plone-collective/volto-sentry).
- ```js
- import {
- settings as defaultSettings,
- } from '@plone/volto/config';
-
- const settings = {
- ...defaultSettings,
- sentryOptions: {
- ...defaultSettings.sentryOptions,
- dsn: 'https://key@sentry.io/1',
- environment: 'production',
- release: '1.2.3',
- serverName: 'volto',
- tags: {
- site: 'foo.bar',
- app: 'test_app',
- logger: 'volto',
- },
- extras: {
- key: 'value',
- },
- integrations: [
- ...defaultSettings.sentryOptions.integrations,
- // new MyAwesomeIntegration()
- ]
- }
- };
- ```
```{seealso}
- See more about [Sentry integration](../deploying/sentry.md).
+ See {doc}`../deploying/sentry`.
```
contentIcons
@@ -105,7 +78,7 @@ persistentReducers
maxResponseSize
The library that we use to get files and images from the backend (superagent)
has a response size limit of 200 mb, so if you want to get a file bigger than 200 mb
- from Plone, the SSR will throw an error.
+ from Plone, the {term}`SSR` will throw an error.
You can edit this limit in the `settings` object setting a new value in bytes
(for example, to set 500 mb you need to write 5000000000).
@@ -145,7 +118,7 @@ storeExtenders
asyncPropsExtenders
Per-route customizable `asyncConnect` action dispatcher. These enable
- proper server-side rendering of content that depends on additional async
+ proper {term}`server-side rendering` of content that depends on additional async
props coming from backend calls. It is a list of route-like configuration
objects (they are matched using
[matchRoutes](https://github.com/remix-run/react-router/blob/ea44618e68f6a112e48404b2ea0da3e207daf4f0/packages/react-router-config/modules/matchRoutes.js).
@@ -227,6 +200,13 @@ controlpanels
The group can be one of the default groups 'General', 'Content', 'Security', 'Add-on Configuration', 'Users and Groups' or a custom group.
+filterControlPanelsSchema
+ A schema factory for a control panel. It is used internally, to tweak the schemas provided by the controlpanel endpoint, to make them fit for Volto.
+
+errorHandlers
+ A list of error handlers that will be called when there is an unhandled exception. Each error handler is a function that
+ receives a single argument, the `error` object.
+
workflowMapping
It's an object that defines the mapping between workflow states/transitions and the color that should show in the change Workflow dropdown. This is the default:
@@ -246,11 +226,157 @@ workflowMapping
It's meant to be extended with your own workflows/transitions.
It is recommended to assign the same color to the transition as the destination state, so the user can have the visual hint to which state are they transitioning to.
-errorHandlers
- A list of error handlers that will be called when there is an unhandled exception. Each error handler is a function that
- receives a single argument, the `error` object.
+
+styleClassNameConverters
+ An object with functions used by the style wrapper helpers to convert style
+ data to actual class names. You can customize the generated classname by
+ registering fieldnames with names such as `:`,
+ where the converter is registered here.
+
+styleClassNameExtenders
+ An array containing functions that extends how the StyleWrapper builds a list of styles. These functions have the signature `({ block, content, data, classNames }) => classNames`. Here are some examples of useful ones, for simplicity, they are compacted in one extender:
+
+ ```js
+ import { getPreviousNextBlock } from '@plone/volto/helpers';
+
+ config.settings.styleClassNameExtenders = [
+ ({ block, content, data, classNames }) => {
+ let styles = [];
+ const [previousBlock, nextBlock] = getPreviousNextBlock({
+ content,
+ block,
+ });
+
+ // Inject a class depending of which type is the next block
+ if (nextBlock?.['@type']) {
+ styles.push(`next--is--${nextBlock['@type']}`);
+ }
+
+ // Inject a class depending if previous is the same type of block
+ if (data?.['@type'] === previousBlock?.['@type']) {
+ styles.push('previous--is--same--block-type');
+ }
+
+ // Inject a class depending if next is the same type of block
+ if (data?.['@type'] === nextBlock?.['@type']) {
+ styles.push('next--is--same--block-type');
+ }
+
+ // Inject a class depending if it's the first of block type
+ if (data?.['@type'] !== previousBlock?.['@type']) {
+ styles.push('is--first--of--block-type');
+ }
+
+ // Inject a class depending if it's the last of block type
+ if (data?.['@type'] !== nextBlock?.['@type']) {
+ styles.push('is--last--of--block-type');
+ }
+
+ // Given a StyleWrapper defined `backgroundColor` style
+ const previousColor =
+ previousBlock?.styles?.backgroundColor ?? 'transparent';
+ const currentColor = data?.styles?.backgroundColor ?? 'transparent';
+ const nextColor = nextBlock?.styles?.backgroundColor ?? 'transparent';
+
+ // Inject a class depending if the previous block has the same `backgroundColor`
+ if (currentColor === previousColor) {
+ styles.push('previous--has--same--backgroundColor');
+ } else if (currentColor !== previousColor) {
+ styles.push('previous--has--different--backgroundColor');
+ }
+
+ // Inject a class depending if the next block has the same `backgroundColor`
+ if (currentColor === nextColor) {
+ styles.push('next--has--same--backgroundColor');
+ } else if (currentColor !== nextColor) {
+ styles.push('next--has--different--backgroundColor');
+ }
+
+ return [...classNames, ...styles];
+ },
+ ];
+ ```
+
+apiExpanders
+ You can configure the API expanders in Volto using `settings.apiExpanders`, as in the following example.
+
+ ```jsx
+ import { GET_CONTENT } from '@plone/volto/constants/ActionTypes';
+
+ export default function applyConfig (config) {
+ config.settings.apiExpanders = [
+ ...config.settings.apiExpanders,
+ {
+ match: '',
+ GET_CONTENT: ['mycustomexpander'],
+ },
+ {
+ match: '/de',
+ GET_CONTENT: ['myothercustomexpander'],
+ },
+ {
+ match: '/de',
+ GET_CONTENT: ['navigation'],
+ querystring: {
+ 'expand.navigation.depth': 3,
+ },
+ }
+ ];
+
+ return config;
+ }
+ ```
+
+ If you want Volto to make only a single request, combining all the expanders in it, then configure `apiExpanders` as shown.
+
+ ```jsx
+ config.settings.apiExpanders = [
+ {
+ match: '',
+ GET_CONTENT: ['breadcrumbs', 'navigation', 'actions', 'types'],
+ },
+ ],
+ ```
+ The configuration accepts a list of matchers, with the ability to filter by the request path and action type for maximum flexibility.
+ It also accepts a `querystring` object that allows configuring the expanders via query string parameters, such as the navigation expander.
+
+additionalToolbarComponents
+ For additional toolbar menus, the menu body component needs to be added to the on-demand loaded components.
+
+ ```jsx
+ config.settings.additionalToolbarComponents = {
+ bookmarksMenu: {
+ component: BookmarksEditorComponent,
+ wrapper: null,
+ },
+ };
+ ```
+
+ The plug:
+ ```jsx
+
+ {({ onClickHandler }) => {
+ return (
+
+ );
+ }}
+
+ ```
```
+
## Views settings
They are exposed in `config.views`:
@@ -299,7 +425,7 @@ layoutViewsNamesMapping
## Server-specific serverConfig
-Settings that are relevant to the Express-powered Volto SSR server are stored
+Settings that are relevant to the Express-powered Volto {term}`SSR` server are stored
in the `config.settings.serverConfig` object.
```{glossary}
@@ -321,5 +447,4 @@ extractScripts
For the moment it admits only one property: `errorPages` whose value is a Boolean.
If `extractScripts.errorPages` is `true`, the JS will be inserted into the error page.
-
```
diff --git a/docs/source/configuration/volto-config-js.md b/docs/source/configuration/volto-config-js.md
index bddbca06f1..56bbcf417d 100644
--- a/docs/source/configuration/volto-config-js.md
+++ b/docs/source/configuration/volto-config-js.md
@@ -1,6 +1,6 @@
# Dynamic Volto Addons Configuration
-There are some cases where defining the Volto addons your project is going to use is not enough, and you need more control over it. For example, when you have several builds under the umbrella of the same project that share the core of the code, but each build have special requirements, like other CSS, customizations, shadowing or the features of other addons available.
+There are some cases where defining the Volto addons your project is going to use is not enough, and you need more control over it. For example, when you have several builds under the umbrella of the same project that share the core of the code, but each build have special requirements, like other CSS, customizations, {term}`shadowing` or the features of other addons available.
There is a scapehatch `volto.config.js`. This module exports an object and can have arbitrary code depending on your needs:
diff --git a/docs/source/configuration/volto-slate/configuration-settings.md b/docs/source/configuration/volto-slate/configuration-settings.md
index bd08d57a52..a6da06c3b2 100644
--- a/docs/source/configuration/volto-slate/configuration-settings.md
+++ b/docs/source/configuration/volto-slate/configuration-settings.md
@@ -237,4 +237,23 @@ They are not persisted in the final value, so they are useful, for example, to h
```js
slate.runtimeDecorators = [([node, path], ranges) => ranges];
-```
\ No newline at end of file
+```
+
+
+(editor-configuration-blocks-initialBlocksFocus-label)=
+
+## `blocks.initialBlocksFocus`
+
+Determine which type of block should be selected on edit.
+
+```js
+blocks.initialBlocksFocus === {
+ :
+};
+```
+
+Disable selection of any block and prevent scrolling to a block:
+
+```js
+blocks.initialBlocksFocus === null;
+```
diff --git a/docs/source/configuration/volto-slate/index.md b/docs/source/configuration/volto-slate/index.md
index d728a0018a..98272cf87b 100644
--- a/docs/source/configuration/volto-slate/index.md
+++ b/docs/source/configuration/volto-slate/index.md
@@ -39,7 +39,7 @@ Some of the main reasons that drove us to create `volto-slate`, instead of enhan
We can override core functionality, something that is built in as pluggable, directly in Slate.
- Volto's Draft.js-based implementation depends on Redraft for its final output, which comes with its own bugs and issues.
While it is nice to have view-mode components, this is something that `volto-slate` implements just as well.
-- Because Slate's internal storage uses a tree modeled on the DOM pattern, its final rendered output is very clean.
+- Because Slate's internal storage uses a tree modeled on the {term}`DOM` pattern, its final rendered output is very clean.
Note: the Slate editor value is a JSON object, similar to the Draft.js-based implementation.
diff --git a/docs/source/configuration/volto-slate/writing-plugins.md b/docs/source/configuration/volto-slate/writing-plugins.md
index 066276c943..ddae66601f 100644
--- a/docs/source/configuration/volto-slate/writing-plugins.md
+++ b/docs/source/configuration/volto-slate/writing-plugins.md
@@ -152,7 +152,7 @@ export const TOOLTIP = 'tooltip';
## Volto configuration registry
-Finally register the plugin and the toolbar button in Volto's configuration.
+Finally register the plugin and the toolbar button in Volto's {term}`configuration registry`.
```js
diff --git a/docs/source/developer-guidelines/Quanta.pdf b/docs/source/contributing/Quanta.pdf
similarity index 100%
rename from docs/source/developer-guidelines/Quanta.pdf
rename to docs/source/contributing/Quanta.pdf
diff --git a/docs/source/developer-guidelines/acceptance-tests.md b/docs/source/contributing/acceptance-tests.md
similarity index 92%
rename from docs/source/developer-guidelines/acceptance-tests.md
rename to docs/source/contributing/acceptance-tests.md
index 3757adaf2b..de27105552 100644
--- a/docs/source/developer-guidelines/acceptance-tests.md
+++ b/docs/source/contributing/acceptance-tests.md
@@ -68,7 +68,7 @@ There are some artifacts available for the acceptance tests made accessible to C
### Access History, Redux Store and Settings
-We expose the History, Redux Store and Settings from the app (only for Cypress environments) so we can easily access them and execute actions (like navigate using the router), dispatch Redux actions or change app settings "on the fly".
+We expose the History, {term}`Redux` Store and Settings from the app (only for Cypress environments) so we can easily access them and execute actions (like navigate using the router), dispatch Redux actions or change app settings "on the fly".
#### Navigate using React Router
diff --git a/docs/source/developer-guidelines/accessibility-guidelines.md b/docs/source/contributing/accessibility-guidelines.md
similarity index 100%
rename from docs/source/developer-guidelines/accessibility-guidelines.md
rename to docs/source/contributing/accessibility-guidelines.md
diff --git a/docs/source/contributing/branch-policy.md b/docs/source/contributing/branch-policy.md
new file mode 100644
index 0000000000..d274e78e38
--- /dev/null
+++ b/docs/source/contributing/branch-policy.md
@@ -0,0 +1,49 @@
+The Volto team enforces the following branch policy when developers contribute to its core.
+
+Releases of general packages (`@plone/generator-volto`, `@plone/scripts`, and so on) are cut from the `master` branch.
+
+stable and latest
+: The terms _stable_ and _latest_ mean the same thing in this policy.
+ They refer to the stable and latest released version of Volto.
+ They have no branch names in git.
+
+canary
+: The term _canary_ refers to the metaphorical canary in a coalmine; if an issue is detected following its release, the damage is limited to only those users who have installed it.
+ It usually includes experimental and breaking features for testing.
+ During the development process, a canary release will be cut from the `master` branch.
+ When it becomes worthy of a beta or release candidate version, a new numbered branch should be cut, and non-breaking changes must be merged into it.
+
+legacy
+: A version that it is unsupported and receives no bug fixes.
+ It has no branch name in git.
+
+`master`
+: This is the bleeding edge branch in git.
+ It is the branch upon which future development occurs, and from which future releases shall be cut.
+
+ When we cut a release candidate, we:
+
+ 1. create a new numbered git branch from master, and
+ 2. cut a release candidate version whose name aligns with the new numbered git branch.
+
+ For example, when we cut the release candidate version 16.0.0-rc.1, we created a git branch `16.x.x`.
+ We also freeze the release candidate, and stop adding features to it.
+ This allows us to continue development on `master`, which may include both breaking changes that must not be backported, and bug fixes and feature additions that may be backported but only after the release candidate becomes final.
+
+ When opening a pull request, the contributor must open it against `master`.
+ If the pull request is a feature or a bugfix, and if the release manager deems it useful to the latest version's branch, they may ask the contributor to backport it to that branch.
+
+`16.x.x`
+: This is the current actively developed branch in git, meaning that it may receive new features and bug fixes.
+ Its version is currently at 16.0.0-rc.1 as a release candidate.
+ It will become the stable version upon the final release of version 16.0.0.
+
+`15.x.x`
+: At the moment of this writing, `15.x.x` is the current stable branch in git.
+ Upon the final release of version 16.0.0, the `15.x.x` branch line will become legacy.
+
+## Translation contributing policy
+
+Due to the nature of `master` and `16.x.x` branches, some developments that may land in `master` may not be backported to `16.x.x`. This means that many translations that may come with those developments will be useless in the `16.x.x` branch and thus porting them to `16.x.x` makes no sense.
+
+So when contributing translations, please create PRs directly from branches created from `16.x.x` and point your PRs to that exact branch instead of `master`.
diff --git a/docs/source/developer-guidelines/design-principles.md b/docs/source/contributing/design-principles.md
similarity index 97%
rename from docs/source/developer-guidelines/design-principles.md
rename to docs/source/contributing/design-principles.md
index 3d8110b3e6..4252c1ca85 100644
--- a/docs/source/developer-guidelines/design-principles.md
+++ b/docs/source/contributing/design-principles.md
@@ -64,8 +64,7 @@ In Volto we have a blank page in front of us. Let's work to keep it clean and sh
## Customization and extensibility
-Volto should ensure customization every core component via "component shadowing",
-whenever it is possible.
+Volto should ensure customization of every core component via {term}`component shadowing`, whenever it is possible.
Extensibility should also be a requirement on Volto core and in every new added feature,
whenever it applies. Volto have to ensure that it can be "pluggable" and provide enough
diff --git a/docs/source/developer-guidelines/icons.md b/docs/source/contributing/icons.md
similarity index 100%
rename from docs/source/developer-guidelines/icons.md
rename to docs/source/contributing/icons.md
diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md
new file mode 100644
index 0000000000..adc5e4d2aa
--- /dev/null
+++ b/docs/source/contributing/index.md
@@ -0,0 +1,129 @@
+---
+myst:
+ html_meta:
+ "description": "How to contribute to Volto, the frontend for Plone."
+ "property=og:description": "How to contribute to Volto, the frontend for Plone."
+ "property=og:title": "How to contribute to Volto, the frontend for Plone."
+ "keywords": "Plone, Volto, contributing, developer, guidelines"
+---
+
+(contributing-to-volto-label)=
+
+# Contributing to Volto
+
+First read {doc}`plone:contributing/index`.
+Volto follows those guidelines with a few specific variations, as described in this chapter.
+
+
+(contributing-reporting-an-issue-or-making-a-feature-request-label)=
+
+## Reporting an issue or making a feature request
+
+If you know the issue or feature request is for Volto, first search for an existing item in the [Volto issue tracker](https://github.com/plone/volto/issues).
+
+If an issue does not already exist for your item, then you can [create a new issue or feature request in Volto](https://github.com/plone/volto/issues/new/choose).
+When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues).
+
+In your report, please specify a few things:
+
+- What are the steps to reproduce the problem?
+- What do you expect when you follow those steps?
+- What do you observe?
+- Which Plone version are you using?
+- Include relevant screenshots, error messages, and stack traces.
+
+
+(contributing-volto-sign-and-return-the-plone-contributor-agreement-label)=
+
+## Sign and return the Plone Contributor Agreement
+
+The Volto Team reviews pull requests only from people with a GitHub account who have signed and returned the {ref}`Plone Contributor Agreement `, and subsequently been assigned to a Plone Team in GitHub.
+
+
+(contributing-branch-policy-label)=
+
+## Branch policy
+
+```{include} ./branch-policy.md
+```
+
+
+(contributing-translations-label)=
+
+## Translations
+
+All text that can be shown in a browser must be translatable.
+Please mark all such strings as translatable as defined in the [i18n guide](../recipes/i18n.md).
+
+
+(contributing-change-log-entry-label)=
+
+## Change log entry
+
+Volto requires that you include a change log entry or news item with your contribution.
+Your attribution must be in the format of `@github_username`.
+
+```{seealso}
+For details see {ref}`contributing-change-log-label`.
+```
+
+
+(contributing-documenting-your-changes-label)=
+
+## Documenting your changes
+
+If the feature includes a breaking change, you must include instructions for how to upgrade in the [upgrade guide](../upgrade-guide/index.md).
+
+
+(contributing-code-quality-label)=
+
+## Code quality
+
+All pull requests must pass tests, documentation builds, and other code quality checks.
+These checks are enforced automatically on every pull request, so you might as well save time and frustration by doing these checks locally first.
+
+Specifically:
+
+- {doc}`./linting`
+- {doc}`./testing`
+- {doc}`./acceptance-tests`
+
+
+(contributing-developer-guidelines-label)=
+
+## Developer guidelines
+
+Development and configuration of Volto is managed through your {ref}`choice of Plone installation method `.
+You may choose to install Plone via {ref}`containers ` or from its {ref}`packages `.
+
+```{todo}
+When referring to installation and configuration of Plone's backend, this part of the Volto documentation may have obsolete content.
+The most current information for installing and configuring Plone is in {ref}`install-index-label`.
+Please report any issues in the [Volto issue tracker](https://github.com/plone/volto/issues/).
+```
+
+```{toctree}
+:maxdepth: 1
+
+design-principles
+style-guide
+language-features
+linting
+react
+redux
+routing
+icons
+testing
+acceptance-tests
+accessibility-guidelines
+typescript
+volto-core-addons
+```
+
+
+(contributing-final-advice-label)=
+
+## Final advice
+
+If you become hesitant after reading the foregoing, don't worry.
+You can always create a pull request, mark it as "Draft", and improve these points later while requesting help from the community.
diff --git a/docs/source/developer-guidelines/language-features.md b/docs/source/contributing/language-features.md
similarity index 97%
rename from docs/source/developer-guidelines/language-features.md
rename to docs/source/contributing/language-features.md
index 1feac77cad..eb385c8d6d 100644
--- a/docs/source/developer-guidelines/language-features.md
+++ b/docs/source/contributing/language-features.md
@@ -39,7 +39,7 @@ currently targeting.
By doing this, enables the bundles to be smaller, as the resultant code does not need to
support old browsers (thus, transform your code to ES5 compatible code) as Babel will
apply only the required transforms that your target enviroments need. For more
-information: https://babeljs.io/docs/en/babel-preset-env#browserslist-integration
+information: https://babeljs.io/docs/babel-preset-env#browserslist-integration
Volto project generators use this browserlist by default (you can find it in your local `package.json`):
diff --git a/docs/source/developer-guidelines/linting.md b/docs/source/contributing/linting.md
similarity index 100%
rename from docs/source/developer-guidelines/linting.md
rename to docs/source/contributing/linting.md
diff --git a/docs/source/developer-guidelines/react.md b/docs/source/contributing/react.md
similarity index 100%
rename from docs/source/developer-guidelines/react.md
rename to docs/source/contributing/react.md
diff --git a/docs/source/developer-guidelines/redux.md b/docs/source/contributing/redux.md
similarity index 94%
rename from docs/source/developer-guidelines/redux.md
rename to docs/source/contributing/redux.md
index 2b97a99672..2e8a6d1e3f 100644
--- a/docs/source/developer-guidelines/redux.md
+++ b/docs/source/contributing/redux.md
@@ -16,7 +16,7 @@ gaps!
As with any other complex React project, the way global state is handled
across all components has a big impact on the overall architecture. Basic
-knowledge of Redux is needed to understand this part, but Volto's use of Redux
+knowledge of {term}`Redux` is needed to understand this part, but Volto's use of Redux
is "typical" and you can find plenty examples in Volto's code base.
To access the global state, a component needs to be connected with `connect`.
@@ -42,7 +42,7 @@ export default compose(
If multiple Higher Order Components need to be used, like in the above example,
the `compose` can be used to combine all of them in a final component.
-If you're writing Function Components, you can use the `useSelector` hook. See
+If you're writing Function Components, you can use the `useSelector` {term}`hook`. See
`src/components/theme/OutdatedBrowser/OutdatedBrowser.jsx` for an example.
When using the `connect` function, you can `select` parts from the global store
@@ -54,7 +54,7 @@ developer extension](https://chrome.google.com/webstore/detail/redux-devtools/lm
The code that is used to populate this store is in the `src/reducers` folder.
In some parts of Volto you'll see `asyncConnect` being used, which is needed to
-enable proper server-side rendering of components. Using it makes sure that the
+enable proper {term}`server-side rendering` of components. Using it makes sure that the
component will be constructed with the proper data already fetched from the
backend and available as props.
@@ -77,7 +77,7 @@ Components you can use the `useDispatch` hook.
Global state update fetches are typically triggered by components in the mount
lifecycle stage. See for example `src/components/theme/Search/Search.jsx` for
a component that needs to interact with the backend to show its content. In the
-redux flow of information, actions trigger the asynchronous processes and when
+Redux flow of information, actions trigger the asynchronous processes and when
that content arrives to the global app, it is pushed as props through the
`connect` mechanism. So components only deal indirectly with async information:
they trigger getting that information and it will arrive as a property once it
@@ -115,7 +115,7 @@ special Api middleware, available in `src/middleware/api.js`.
## Customizing the Redux middleware
-It is possible to tweak Volto's Redux middleware, for example to add new
+It is possible to tweak Volto's {term}`Redux middleware`, for example to add new
middleware by using the `config.settings.storeExtender` configuration option.
If you have Redux middleware that you want to insert as the first middleware to
be used, for example, you could configure your project with:
diff --git a/docs/source/developer-guidelines/routing.md b/docs/source/contributing/routing.md
similarity index 100%
rename from docs/source/developer-guidelines/routing.md
rename to docs/source/contributing/routing.md
diff --git a/docs/source/developer-guidelines/style-guide.md b/docs/source/contributing/style-guide.md
similarity index 100%
rename from docs/source/developer-guidelines/style-guide.md
rename to docs/source/contributing/style-guide.md
diff --git a/docs/source/developer-guidelines/testing.md b/docs/source/contributing/testing.md
similarity index 100%
rename from docs/source/developer-guidelines/testing.md
rename to docs/source/contributing/testing.md
diff --git a/docs/source/developer-guidelines/typescript.md b/docs/source/contributing/typescript.md
similarity index 100%
rename from docs/source/developer-guidelines/typescript.md
rename to docs/source/contributing/typescript.md
diff --git a/docs/source/developer-guidelines/volto-core-addons.md b/docs/source/contributing/volto-core-addons.md
similarity index 100%
rename from docs/source/developer-guidelines/volto-core-addons.md
rename to docs/source/contributing/volto-core-addons.md
diff --git a/docs/source/deploying/pm2.md b/docs/source/deploying/pm2.md
index caa2df43d6..608de9af46 100644
--- a/docs/source/deploying/pm2.md
+++ b/docs/source/deploying/pm2.md
@@ -54,7 +54,7 @@ module.exports = {
};
```
-- `mywebsite.com-volto` starts the Node process that is responsible for Volto server-side rendering.
+- `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-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 cf0479cc9c..5c6f0caf1a 100644
--- a/docs/source/deploying/seamless-mode.md
+++ b/docs/source/deploying/seamless-mode.md
@@ -13,7 +13,7 @@ myst:
This was added in Volto 13 as an experimental feature. During the experimental phase, we realized of several issues hard to solve, which made us rethink the feature into its second incarnation, available since Volto 14.
-The first implementation wanted to unify both backend and frontend under the same sun, using the `Accept` header to route the requests to the API and the Volto SSR server. As a reference and for the record, these were the major issues we encountered (https://github.com/plone/volto/issues/2706):
+The first implementation wanted to unify both backend and frontend under the same sun, using the `Accept` header to route the requests to the API and the Volto {term}`SSR` server. As a reference and for the record, these were the major issues we encountered (https://github.com/plone/volto/issues/2706):
- Browsers are unable to differentiate cached responses using the `Accept` header, so the last one (usually the JSON one) was cached, then shown in some situations (like browser restart and open tabs). The back button also showed the JSON responses under some circumstances.
- The use of cache servers and services is hard since they do not accept the `Vary` header (Cloudflare) and in Varnish the handling is also difficult to differentiate both requests and cache (and then invalidate) them properly.
diff --git a/docs/source/deploying/sentry_backend_message.png b/docs/source/deploying/sentry-backend-message.png
similarity index 100%
rename from docs/source/deploying/sentry_backend_message.png
rename to docs/source/deploying/sentry-backend-message.png
diff --git a/docs/source/deploying/sentry_frontend_message.png b/docs/source/deploying/sentry-frontend-message.png
similarity index 100%
rename from docs/source/deploying/sentry_frontend_message.png
rename to docs/source/deploying/sentry-frontend-message.png
diff --git a/docs/source/deploying/sentry_messages.png b/docs/source/deploying/sentry-messages.png
similarity index 100%
rename from docs/source/deploying/sentry_messages.png
rename to docs/source/deploying/sentry-messages.png
diff --git a/docs/source/deploying/sentry.md b/docs/source/deploying/sentry.md
index ea2da02699..c2edd27011 100644
--- a/docs/source/deploying/sentry.md
+++ b/docs/source/deploying/sentry.md
@@ -4,50 +4,92 @@ myst:
"description": "Volto Integration with Sentry"
"property=og:description": "Volto Integration with Sentry"
"property=og:title": "Integration with Sentry"
- "keywords": "Volto, Plone, frontend, React, Integration, Sentry"
+ "keywords": "Volto, Plone, frontend, React, Integration, Sentry, volto-sentry, add-on"
---
# Integration with Sentry
+Volto can be configured to work with [Sentry.io](https://sentry.io/welcome/).
+Sentry is a monitoring platform that can help identify the cause of errors in your project.
+
+
## Prerequisities
-1. In Sentry create a new organization, and add a project to it
-2. On the projects settings page, from Client Keys (DSN), take the SENTRY_DSN
-3. Create an API Token: on the top left corner, click on your name -> API keys and create a new token, "project:write" scope should be selected.
-**Note:** Instructions tested with Sentry 9.1.2
+1. Install the add-on [`@plone-collective/volto-sentry`](https://www.npmjs.com/package/@plone-collective/volto-sentry).
+2. In Sentry, create a new organization, and add a project to it.
+3. On the projects settings page, from {guilabel}`Client Keys (DSN)`, take the `SENTRY_DSN`.
+4. Create an API Token: in the top-left corner, click on {guilabel}`your name -> API keys`, and create a new token.
+ {guilabel}`project:write` scope should be selected.
+
+```{note}
+Instructions tested with Sentry 9.1.2.
+```
+
+```{versionchanged} 16.0.0.alpha.45
+Sentry was moved from Volto core and into a separate add-on [`volto-sentry`](https://github.com/collective/volto-sentry).
+```
+
## Setup
-Volto creates bundles of the source codes, if an error is sent to sentry, it will only show the traceback in the bundles. To have nice traceback, we have to upload the source code and source map in sentry.
-This doesn't have to be done manually, we can configure our volto application to do all the steps automatically.
-There are 2 ways to configure the application:
+Volto creates bundles of the source codes.
+If an error is sent to Sentry, it will only show the traceback in the bundles.
+To have a nice traceback, we have to upload the source code and source map to Sentry.
+This can be configured in our Volto application to do all the steps automatically.
+
+There are 2 ways to configure the application.
+
+
+### 1. Build time
+
+This method can be used when the application is deployed directly on a host machine and built locally.
-### 1. Buildtime
-This can be used when the application is deployed directly on a host machine, and built locally.
+The configuration is done using environment variables.
-The configuration is done using environment variables:
- - SENTRY_DSN - required to enable the feature
- - SENTRY_URL - the url of sentry
- - SENTRY_AUTH_TOKEN - the authentication token for sentry
- - SENTRY_ORG - the name of the organization in sentry
- - SENTRY_PROJECT -the name of the project in sentry
- - SENTRY_RELEASE - release number
- - SENTRY_FRONTEND_CONFIG - optional, here we can specify TAGS
- and ADDITIONAL DATA for the messages from the browser we send to sentry
- - SENTRY_BACKEND_CONFIG - same as SENTRY_FRONTEND_CONFIG, but we configure the messages from the backend
+`SENTRY_DSN`
+: Required to enable the feature.
-If these env variables are configured, when the app is built, a new release will be created in sentry, and the source code and source maps will be uploaded it.
-After starting the application if an error will occure, the errors will be sent to sentry, and will be linked to the specified release.
+`SENTRY_URL`
+: The URL of Sentry.
-Example of usage:
+`SENTRY_AUTH_TOKEN`
+: The authentication token for Sentry.
-```bash
-SENTRY_URL=https://mysentry.com SENTRY_AUTH_TOKEN=foo SENTRY_ORG=my_organization SENTRY_PROJECT=new_project SENTRY_RELEASE=2.0.0 SENTRY_DSN=https://boo@sentry.com/1 yarn build
+`SENTRY_ORG`
+: The name of the organization in Sentry.
+
+`SENTRY_PROJECT`
+: The name of the project in Sentry.
+
+`SENTRY_RELEASE`
+: The release number.
+
+`SENTRY_FRONTEND_CONFIG`
+: Optional, here we can specify `TAGS` and `ADDITIONAL DATA` for the messages we send to Sentry from the browser.
+
+`SENTRY_BACKEND_CONFIG`
+: Same as `SENTRY_FRONTEND_CONFIG`, but we configure the messages from the backend.
+
+If these environment variables are configured when the app is built, a new release will be created in Sentry, and the source code and source maps will be uploaded to it.
+After starting the application, if an error occurs, the errors will be sent to Sentry, and will be linked to the specified release.
+
+Example usage:
+
+```shell
+SENTRY_URL=https://mysentry.com \
+SENTRY_AUTH_TOKEN=foo \
+SENTRY_ORG=my_organization \
+SENTRY_PROJECT=new_project \
+SENTRY_RELEASE=2.0.0 \
+SENTRY_DSN=https://boo@sentry.com/1 yarn build
node build/server.js
```
+
+
### 2. Runtime
-Within your Volto project or a dedicated Volto add-on you can configure Sentry via `settings.sentryOptions` configuration key:
+
+Within your Volto project or a dedicated Volto add-on, you can configure Sentry via the `settings.sentryOptions` configuration key:
```js
import {
@@ -76,31 +118,51 @@ const settings = {
]
}
};
-See more about [Sentry Custom Integrations](https://docs.sentry.io/platforms/javascript/configuration/integrations)
-
-In case you plan to use the application using docker, you will not want to have the sentry setup in the docker image.
-The configuration for setting up sentry on runtime is very similar as how we set it up for buildtime, but with some small differences:
-
- - SENTRY_URL - the url of sentry
- - SENTRY_AUTH_TOKEN - the authentication token for sentry
- - SENTRY_ORG - the name of the organization in sentry
- - SENTRY_PROJECT -the name of the project in sentry
- - SENTRY_RELEASE - release number
- - RAZZLE_SENTRY_DSN - required to enable the feature
- - RAZZLE_SENTRY_FRONTEND_CONFIG - optional, here we can specify TAGS
- and ADDITIONAL DATA for the messages from the browser we send to sentry
- - RAZZLE_SENTRY_BACKEND_CONFIG - same as RAZZLE_SENTRY_FRONTEND_CONFIG, but we configure the messages from the backend
- - RAZZLE_SENTRY_RELEASE - release number, should be the same as SENTRY_RELEASE
-
-In the entrypoint of our docker image we have to add the ./create-sentry-release.sh script. When the container is started, this script will check in sentry if the specified release already exists, if not, it will create it and upload the source code and the source maps.
-The script can be executed also manually and if we want to overwrite the existing files in sentry, we can use the --force flag:
-
-```bash
+```
+
+See more about [Sentry Custom Integrations](https://docs.sentry.io/platforms/javascript/configuration/integrations/custom/).
+
+In case you plan to use the application using Docker, you will not want to have the Sentry setup in the Docker image.
+The configuration for setting up Sentry on runtime is very similar to how we set it up for build time, but with some small differences.
+
+`SENTRY_URL`
+: The URL of Sentry.
+
+`SENTRY_AUTH_TOKEN`
+: The authentication token for Sentry.
+
+`SENTRY_ORG`
+: The name of the organization in Sentry.
+
+`SENTRY_PROJECT`
+: The name of the project in Sentry.
+
+`SENTRY_RELEASE`
+: The release number.
+
+`RAZZLE_SENTRY_DSN`
+: Required to enable the feature.
+
+`RAZZLE_SENTRY_FRONTEND_CONFIG`
+: Optional, here we can specify `TAGS` and `ADDITIONAL DATA` for the messages we send to Sentry from the browser.
+
+`RAZZLE_SENTRY_BACKEND_CONFIG`
+: Same as `RAZZLE_SENTRY_FRONTEND_CONFIG`, but we configure the messages from the backend.
+
+`RAZZLE_SENTRY_RELEASE`
+ The release number, which should be the same as `SENTRY_RELEASE`.
+
+In the entrypoint of our Docker image, we have to add the script `./create-sentry-release.sh`.
+When the container is started, this script will check in Sentry if the specified release already exists, and if not, it will create it and upload the source code and the source maps.
+The script can also be executed manually, and if we want to overwrite the existing files in Sentry, we can use the `--force` flag.
+
+```shell
./create-sentry-release.sh --force
```
-Example of entrypoint:
-```bash
+Example of entrypoint.
+
+```shell
#!/usr/bin/env bash
set -Ex
@@ -129,7 +191,7 @@ echo "Starting Volto"
exec "$@"
```
-Starting with docker:
+Starting the container with Docker.
```shell
docker run -p 3000:3000 -p 3001:3001 \
@@ -162,16 +224,19 @@ services:
- RAZZLE_SENTRY_RELEASE=2.0.0
```
+
## Configuration options
-This applies to both SENTRY_FRONTEND_CONFIG and SENTRY_BACKEND_CONFIG
+This applies to both `SENTRY_FRONTEND_CONFIG` and `SENTRY_BACKEND_CONFIG`.
+
+If you are using _build time_ configuration, you have to use `SENTRY_FRONTEND_CONFIG` and `SENTRY_BACKEND_CONFIG`.
-**Note:** In case you are using buildtime configuration you have to use SENTRY_FRONTEND_CONFIG and SENTRY_BACKEND_CONFIG.
+If you are using _runtime_ configuration, use `RAZZLE_SENTRY_FRONTEND_CONFIG` and `RAZZLE_SENTRY_BACKEND_CONFIG`.
-But if you are using runtime configuration, use RAZZLE_SENTRY_FRONTEND_CONFIG and RAZZLE_SENTRY_BACKEND_CONFIG
+We have the possibility to add `TAGS` and `ADDITIONAL DATA` for our messages for categorization in Sentry.
+We can configure these two variables separately, as we might want to separate the messages from frontend and backend.
-We have the possibility to add TAGS and ADDITIONAL DATA for our messages for categorization in SENTRY. We can configure these 2 variables separately, as we might want to separate the messages from frontend and backend.
-Example of configurations:
+Example of configuration.
```json
{
@@ -190,7 +255,7 @@ Example of configurations:
}
```
-Example of usage with buildtime setup:
+Example of usage with build time setup.
```console
SENTRY_URL=https://mysentry.com
@@ -204,7 +269,7 @@ SENTRY_BACKEND_CONFIG='{"tags":{"site":"www.test.com","app":"test_app"} yarn bui
node build/server.js
```
-Example with Docker Compose:
+Example with Docker Compose.
```yaml
version: '3'
@@ -226,11 +291,11 @@ services:
- RAZZLE_SENTRY_BACKEND_CONFIG={"tags":{"site":"www.test.com","app":"test_app"},"extras":{"logger":"javascript-backend", "server":"server#1"}}
```
-## Example of messages in SENTRY
+## Example messages in Sentry
-1. List of messages
-
-2. Messages from the frontend, with its own TAGS and ADDITIONAL DATA
-
-3. Messages from the backend, with its own TAGS and ADDITIONAL DATA
-
+1. List of messages
+ 
+2. Messages from the frontend, with its own `TAGS` and `ADDITIONAL DATA`
+ 
+3. Messages from the backend, with its own `TAGS` and `ADDITIONAL DATA`
+ 
diff --git a/docs/source/developer-guidelines/contributing.md b/docs/source/developer-guidelines/contributing.md
deleted file mode 100644
index 5234987ffd..0000000000
--- a/docs/source/developer-guidelines/contributing.md
+++ /dev/null
@@ -1,61 +0,0 @@
----
-myst:
- html_meta:
- "description": "A guide on how to contribute to Volto, the frontend for Plone."
- "property=og:description": "A guide on how to contribute to Volto, the frontend for Plone."
- "property=og:title": "Contributing to Volto"
- "keywords": "Volto, Plone, frontend, React, guidelines"
----
-
-# Contributing to Volto
-
-You may have an issue to report, make a feature request, report a security vulnerability, or you want to create a pull request.
-You have come to the right place to learn how to do so.
-
-
-## Reporting an issue or making a feature request
-
-If you know the issue or feature request is for Volto, first search for an existing item in the [Volto issue tracker](https://github.com/plone/volto/issues).
-
-If an issue does not already exist for your item, then you can [create a new issue or feature request in Volto](https://github.com/plone/volto/issues/new/choose).
-When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues).
-
-In your report, please specify a few things:
-
-- What are the steps to reproduce the problem?
-- What do you expect when you follow those steps?
-- What do you observe?
-- Which Plone version are you using?
-- Include relevant screenshots, error messages, and stack traces.
-
-## Create a pull request
-
-You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement) to contribute code and documentation to any Plone project.
-This means that we can NOT accept pull requests from you until you do this.
-
-All pull requests must include a note under the `(unreleased)` version under the appropriate subheading of [CHANGELOG.md](https://github.com/plone/volto/blob/master/CHANGELOG.md).
-Do not edit already released versions.
-
-If the feature includes a breaking change, you must include instructions for how to upgrade in the [upgrade guide](../upgrade-guide/index.md).
-
-All text that can be shown in a browser must be translatable. Please mark all such
-strings as translatable as defined in the [i18n guide](../recipes/i18n.md).
-
-
-## Code Quality
-
-All pull requests must pass tests, documentation builds, and other code quality checks.
-Contributors are strongly encouraged to run these checks locally before creating a pull request.
-These checks are enforced automatically on every pull request, so you might as well save time and frustration by doing these checks locally first.
-
-Specifically:
-
-- {doc}`./linting`
-- {doc}`./testing`
-- {doc}`./acceptance-tests`
-
-
-If after reading this you become hesitant, don't worry.
-You can always create a pull request, mark it as "Draft", and improve the above points later, requesting help from the community.
-
-Welcome to the Plone community, and thank you for contributing!
diff --git a/docs/source/developer-guidelines/index.md b/docs/source/developer-guidelines/index.md
deleted file mode 100644
index e81f734f17..0000000000
--- a/docs/source/developer-guidelines/index.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-myst:
- html_meta:
- "description": "Developer Guidelines"
- "property=og:description": "Developer Guidelines"
- "property=og:title": "Developer Guidelines"
- "keywords": "Developer, Guidelines"
----
-
-# Developer Guidelines
-
-```{toctree}
-:maxdepth: 1
-
-contributing
-design-principles
-style-guide
-language-features
-linting
-react
-redux
-routing
-icons
-testing
-acceptance-tests
-accessibility-guidelines
-typescript
-volto-core-addons
-```
diff --git a/docs/source/getting-started/install.md b/docs/source/getting-started/install.md
index 97bc9c0ca2..7dd17ff64b 100644
--- a/docs/source/getting-started/install.md
+++ b/docs/source/getting-started/install.md
@@ -11,6 +11,11 @@ myst:
# Getting Started
+```{warning}
+This chapter of the documentation has been superseded by the official Plone 6 Documentation chapter {ref}`install-index-label`.
+This chapter contains some legacy information that may be useful to Plone 5.2 development.
+```
+
(frontend-getting-started-installing-volto-label)=
@@ -18,22 +23,16 @@ myst:
Volto can be installed in any operating system assuming that the following pre-requisites are met:
-- [Node.js LTS (16.x)](https://nodejs.org/en/)
-- [Python](https://python.org/) - See below for specific versions.
+- [Node.js LTS (18.x)](https://nodejs.org/en)
+- [Python](https://www.python.org/) - See below for specific versions.
- [Docker](https://www.docker.com/get-started) (if using the Plone docker images)
-```{note}
-*UPDATE 2022-10-25*: Since 2022-10-25, NodeJS 18 is in LTS state (https://github.com/nodejs/release#release-schedule). However, due to changes in internal SSL libraries, some Volto dependencies have been deprecated and need to be updated in order to continue working in NodeJS 18, mainly Webpack 4 (see: https://github.com/webpack/webpack/issues/14532#issuecomment-947525539 for further information). You can still use it, but NodeJS should be run under a special flag: `NODE_OPTIONS=--openssl-legacy-provider`. See also Volto's PR: https://github.com/plone/volto/pull/3699 for more information.
-```
-
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 (beta) | 3.8-3.10 | 16.0 (alpha) |
-
-At the time of this writing, Volto 16 is still in alpha status, and Plone 6 is in beta status.
+| 6.0 | 3.8-3.10 | 16.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.
@@ -47,7 +46,7 @@ There are three processes continuously running when you have a working Volto web
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
- Server Side Rendering (SSR) of your pages on first request (JavaScript, the
+ {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)
@@ -90,8 +89,8 @@ it provides easy access to any NodeJS released version.
4. Install any active LTS version of NodeJS (https://github.com/nodejs/release#release-schedule):
```bash
- nvm install 16
- nvm use 16
+ nvm install 18
+ nvm use 18
```
5. Test NodeJS:
@@ -106,7 +105,7 @@ 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 12 LTS.
+ Releases page](https://github.com/nodejs/release#release-schedule), starting with Node 16 LTS.
```
@@ -221,23 +220,13 @@ You may choose to install the canary version, which is the latest alpha release,
```bash
npm install -g yo @plone/generator-volto
- # install latest stable release
yo @plone/volto
- # or install latest alpha release
- yo @plone/volto --canary
```
-2. Answer to the prompted questions and provide the name of the new app (folder) to be created. For the sake of this documentation, provide `myvoltoproject` as project name then.
-
- ````{note}
- You can run the generator with parameters to tailor your requirements.
-
- ```bash
- yo @plone/volto --help
- ```
+See the [Creating a project](../recipes/creating-project) page for more
+advanced options that can be passed to the generator.
- or take a look at the [README](https://github.com/plone/volto/blob/master/packages/generator-volto/README.md) for more information.
- ````
+2. Answer the questions when prompted, and provide the name of the new app (folder) to be created. For the sake of this documentation, provide `myvoltoproject` as the project name.
3. Change directory to the newly created folder `myvoltoapp` (or the one you've chosen):
```bash
@@ -263,7 +252,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 server side rendering
+app should be run in a node 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.
diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md
index 6e5ca53005..3b5fcf48ea 100644
--- a/docs/source/getting-started/others.md
+++ b/docs/source/getting-started/others.md
@@ -15,14 +15,14 @@ On the [Plone Trainings Website](https://training.plone.org) you'll find
Volto-dedicated open training materials plus React and other
Javascript-centered trainings.
-- [Mastering Plone 6 Development](https://training.plone.org/5/mastering-plone/)
+- [Mastering Plone 6 Development](https://training.plone.org/mastering-plone/)
The comprehensive training on Plone 6 with best practice tips for developers and integrators.
- [Volto](https://training.plone.org/5/volto/index.html)
A detailed training on how to create your own website using Volto frontend.
-- [Volto Hands-On](https://training.plone.org/5/voltohandson/index.html)
-- [Volto Add-ons Development](https://training.plone.org/5/voltoaddons/index.html)
+- [Volto Hands-On](https://training.plone.org/voltohandson/index.html)
+- [Volto Add-ons Development](https://training.plone.org/voltoaddons/index.html)
- [Plone Deployment](https://training.plone.org/5/plone-deployment/index.html)
-- [React](https://training.plone.org/5/react/index.html)
+- [React](https://training.plone.org/react/index.html)
- [JavaScript For Plone Developers](https://training.plone.org/5/javascript/index.html)
## How does it work under the hood
@@ -31,29 +31,38 @@ You can watch the talk during the World Plone Day 2021:
-## Presentations at the last two PloneConf's
+## Presentations at Plone Conferences (PloneConf) and other events
-In recent years the new Volto frontend for Plone has been presented in more and more talks from
+In recent years the react based Volto frontend for Plone has been presented in more and more talks at
our yearly Conferences:
-- [PloneConf 2021 Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi)
+### PloneConf 2022
-- [PloneConf 2020 Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3)
+[PloneConf 2022 full Playlist on Youtube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
+Plone 6 site presentations:
-## PloneConf 2019
+- [Rai Way: Plone6 supporting the world of italian information, sports and entertainment](https://www.youtube.com/watch?v=hHHGlSjf5O4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
+- [How Plone Powers Hundreds of Websites at one of the Largest Research Institutions in Europe](https://www.youtube.com/watch?v=bxWt-GEmPcc&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
-PloneConf 2019 and other events have several Volto-relevant presentations, but not stored in a
-single playlist:
-### Howtos
+Developer/intergrator talks:
-- [Rob Gietema - How to create your own Volto site!](https://www.youtube.com/watch?v=3QLN8tsjjf4)
-- [Rodrigo Ferreira de Souza - Data migration to Plone 5.2 and Volto](https://www.youtube.com/watch?v=kb9SEsnllqE)
+- [Anatomy of a Volto project](https://www.youtube.com/watch?v=JtNufyFlgc8&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
+- [Creating a Volto Theme](https://www.youtube.com/watch?v=AMHN74Jr27Y&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
+- [A Deep Dive Into Internals Of Volto](https://www.youtube.com/watch?v=sMeTDRgp3uI&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
+- [DevOps Bird's Eye View on the Plone 6 Backend](https://www.youtube.com/watch?v=L5PvGwWC9P4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z)
-### Panels and discussions
+## Previous PloneConfs
-- [Timo Stollenwerk - Breaking New Grounds](https://www.youtube.com/watch?v=9nRxgeCuIDs)
-- [Panel - Ask me anything on Volto](https://www.youtube.com/watch?v=jwbpXJlDVOs)
-- [Luca Pisani - Plone and React.js: An interview to Volto](https://www.youtube.com/watch?v=JZFUOG843no)
-- [Victor Fernandez de Alba - Plone Beyond 2020: Jump into Volto today!](https://www.youtube.com/watch?v=8QrGOgXo1Js)
-- [Nicola Zambello - A Volto story: building a website by prototyping](https://www.youtube.com/watch?v=xtxJURICkWc)
+- [PloneConf 2021 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi)
+- [PloneConf 2020 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3)
+
+
+## World Plone Day 2022
+
+World Plone Day is a 24-hour streaming event, with the goal was to promote and educate the public about the benefits of using Plone and of being part of the Plone community. [Full World Plone Day 2022 playlist on Youtube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL)
+
+- [Plone 6 Volto's Seamless Mode](https://www.youtube.com/watch?v=Mj8pHRBls-w&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL)
+- [Volto add ons separator and carousel](https://www.youtube.com/watch?v=eyTMI5TYcVg&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL)
+- [Weekly Volto Live – Retrospective](https://www.youtube.com/watch?v=WT6OjkSrB20&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL)
+- [Migrating from Classic to Volto](https://www.youtube.com/watch?v=09fg456T90s&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL)
diff --git a/docs/source/getting-started/roadmap.md b/docs/source/getting-started/roadmap.md
index 0803e0df02..3af14a07b0 100644
--- a/docs/source/getting-started/roadmap.md
+++ b/docs/source/getting-started/roadmap.md
@@ -14,7 +14,7 @@ and adjust to the new frontend-centered development.
But if you already have some frontend development experience any JS frameworks
such as AngularJS, Vue or React, you'll find that Volto is a relatively shallow
-framework, structured as a typical Redux-centered React application. Although
+framework, structured as a typical {term}`Redux`-centered React application. Although
there will be Volto-specific knowledge to be gained along the way, you can be
productive in a short time.
@@ -28,7 +28,7 @@ As is the case with similar modern Javascript-based applications, you should kno
- 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://reactjs.org/tutorial/tutorial.html) for the beginning, you'll progress
+ 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
[CommonJS](https://flaviocopes.com/commonjs/),
diff --git a/docs/source/index.md b/docs/source/index.md
index ca9c536ecd..ee7723015f 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -47,5 +47,7 @@ addons/index
backend/index
deploying/index
upgrade-guide/index
-developer-guidelines/index
+user-manual/index
+contributing/index
+release-notes/index
```
diff --git a/docs/source/recipes/appextras.md b/docs/source/recipes/appextras.md
index 3d6b1238c9..7455c4bbaf 100644
--- a/docs/source/recipes/appextras.md
+++ b/docs/source/recipes/appextras.md
@@ -16,7 +16,7 @@ component.
## How to use it
-You can either use it by overriding it via Component Shadowing by placing
+You can either use it by overriding it via {term}`component shadowing` by placing
a custom `src/customizations/components/theme/AppExtras/AppExtras.jsx`...
Or you can use the new key of `config.settings`, the `appExtras`. This is
diff --git a/docs/source/recipes/creating-project.md b/docs/source/recipes/creating-project.md
index 80ea0876f1..c577cedd35 100644
--- a/docs/source/recipes/creating-project.md
+++ b/docs/source/recipes/creating-project.md
@@ -9,16 +9,27 @@ myst:
# Creating a new Volto project
-For using Volto for a project (i.e. use Volto as a library), You should use Volto's project generator `@plone/generator-volto`. It's a boilerplate generator based in Yeoman that will provide you with the basic files and folder structure to bootstrap a Volto site. In addition to bootstrapping standalone Volto projects, it can also bootstrap Volto addons.
+For using Volto for a project—in other words, use Volto as a library—you should use Volto's project generator `@plone/generator-volto`.
+It's a boilerplate generator based in Yeoman that will provide you with the basic files and folder structure to bootstrap a Volto site.
+In addition to bootstrapping stand-alone Volto projects, it can also bootstrap Volto add-ons.
1. Open a terminal and execute:
- ```shell
+ ```bash
npm install -g yo @plone/generator-volto
+ # Install the latest and stable release of Volto with the following command
yo @plone/volto
+ # or you can install the "canary" release, including any alpha release
+ yo @plone/volto --canary
+ # or you can install any specific released version
+ yo @plone/volto --volto=15.0.0
+ # you can even pass a GitHub repo and specific branch
+ yo @plone/volto --volto=plone/volto#16.0.0
+ # you can bootstrap with add-ons
+ yo @plone/volto --addon=volto-form-block
```
-2. Answer to the prompted questions and provide the name of the new app (folder) to be created. For the sake of this documentation, provide `myvoltoproject` as project name then.
+2. Answer the questions when prompted, and provide the name of the new app (folder) to be created. For the sake of this documentation, provide `myvoltoproject` as the project name then.
````{note}
You can run the generator with parameters to tailor your requirements.
diff --git a/docs/source/recipes/customizing-components.md b/docs/source/recipes/customizing-components.md
index 6731711675..12864ecb1a 100644
--- a/docs/source/recipes/customizing-components.md
+++ b/docs/source/recipes/customizing-components.md
@@ -10,7 +10,7 @@ myst:
# Customizing Components
You are able to customize the existing Volto components using a pattern called
-`component shadowing` using the `customizations` folder. You have to identify and locate
+{term}`component shadowing` using the `customizations` folder. You have to identify and locate
the component that you want to customize, let's say the Logo component in [Volto source
code](https://github.com/plone/volto/tree/master/src).
diff --git a/docs/source/recipes/express.md b/docs/source/recipes/express.md
index 02e2340905..9c15e107f8 100644
--- a/docs/source/recipes/express.md
+++ b/docs/source/recipes/express.md
@@ -10,7 +10,7 @@ myst:
# Custom Express middleware
Volto uses the popular [Express](https://expressjs.com/) server for its
-Server-Side Rendering implementation and static resource serving. In some
+{term}`server-side rendering` implementation and static resource serving. In some
cases it is useful to extend this server with new functionality. For example,
Volto includes a middleware that proxies the backend and that can be used
during development. Other use cases might include a CORS proxy server, a proxy
diff --git a/docs/source/recipes/folder-structure.md b/docs/source/recipes/folder-structure.md
index aea1dc0e2b..25249e3674 100644
--- a/docs/source/recipes/folder-structure.md
+++ b/docs/source/recipes/folder-structure.md
@@ -9,13 +9,13 @@ myst:
# Folder structure
-Volto is based on React, Redux, and React-Router. All of the
+Volto is based on React, {term}`Redux`, and React-Router. All of the
code is located in the `src` folder. The following convention for locating
resources is used.
## Actions
-`actions` contains all the redux actions for fetching all backend data like
+`actions` contains all the Redux actions for fetching all backend data like
content, users and external resources that are pulled into our app in general.
## Components
diff --git a/docs/source/recipes/ie11compat.md b/docs/source/recipes/ie11compat.md
index 4ff8bcd7b3..6001158ae9 100644
--- a/docs/source/recipes/ie11compat.md
+++ b/docs/source/recipes/ie11compat.md
@@ -39,7 +39,7 @@ import '@babel/polyfill';
```
```{seealso}
-See https://babeljs.io/docs/en/babel-polyfill for more updated information
+See https://babeljs.io/docs/babel-polyfill for more updated information
```
## babel-env
diff --git a/docs/source/recipes/lazyload.md b/docs/source/recipes/lazyload.md
index ba895c12ec..a0195f9a17 100644
--- a/docs/source/recipes/lazyload.md
+++ b/docs/source/recipes/lazyload.md
@@ -14,7 +14,7 @@ using `@loadable/component` library. You can also benefit from it in your own pr
using it.
```{note}
-Webpack 4 is already lazy load enabled, using `import()` but @loadable/component makes the process safe since Volto is using Server Side Rendering. The React community is working actively in the React async mode popularly known as Suspense. Suspense will be SSR safe but in the meanwhile it's not ready, `@loadable/component` is the community accepted replacement.
+Webpack 4 is already lazy load enabled, using `import()` but @loadable/component makes the process safe since Volto is using {term}`server-side rendering`. The React community is working actively in the React async mode popularly known as Suspense. Suspense will be {term}`SSR` safe but in the meanwhile it's not ready, `@loadable/component` is the community accepted replacement.
```
## Lazy load a component
@@ -84,16 +84,22 @@ located**.
### The useLazyLibs hook
-In functional components you can use the `useLazyLibs` hook, which allows
+In functional components you can use the `useLazyLibs` {term}`hook`, which allows
greater flexibility (the `injectLazyLibs` hook uses `useLazyLibs` internally).
You can call the hook like:
```jsx
import { useLazyLibs } from '@plone/volto/helpers/Loadable/Loadable';
-useLazyLibs(['toastify', 'reactDnd'])
+const loaded = useLazyLibs(['toastify', 'reactDnd'])
// or:
-useLazyLibs(['toastify', 'reactDnd'], {shouldRerender: false})
+const loaded = useLazyLibs(['toastify', 'reactDnd'], {shouldRerender: false})
+
+const reactDnd = loaded?.reactDnd;
+
+if (reactDnd) {
+ // The library is now loaded and can be used.
+}
```
Passing the `shouldRerender` as false as options will cause the component to
diff --git a/docs/source/recipes/widget.md b/docs/source/recipes/widget.md
index 842196a6d8..ebb232d0d5 100644
--- a/docs/source/recipes/widget.md
+++ b/docs/source/recipes/widget.md
@@ -150,6 +150,10 @@ Based on this setup, Volto will render this field with the `TokenWidget`.
See [storybook](https://6.dev-docs.plone.org/storybook) with available widgets.
```
+## Widget `isDisabled` Props
+
+We can disable the input of a widget by passing props `isDisabled: true`.
+
## Write a new widget
```{note}
diff --git a/docs/source/release-notes/index.md b/docs/source/release-notes/index.md
new file mode 100644
index 0000000000..7b40c7d23f
--- /dev/null
+++ b/docs/source/release-notes/index.md
@@ -0,0 +1,13 @@
+---
+myst:
+ html_meta:
+ "description": "Volto Release Notes for the Plone content management system"
+ "property=og:description": "Volto Release Notes for the Plone content management system"
+ "property=og:title": "Volto Release Notes"
+ "keywords": "Volto, Plone, frontend, Release Notes, change log, changelog, change history"
+---
+
+````{ifconfig} context in ("documentation")
+```{include} ../../../submodules/volto/CHANGELOG.md
+```
+````
diff --git a/docs/source/theming/custom-styling.md b/docs/source/theming/custom-styling.md
index 00c90b6481..bd5fd44044 100644
--- a/docs/source/theming/custom-styling.md
+++ b/docs/source/theming/custom-styling.md
@@ -55,8 +55,8 @@ both) files (including the matching folder structure) in your theme folder.
## Pastanaga UI Theme
Volto implements Pastanaga UI theme, a new theme for Content Management Systems
-created and designed by [Albert Casado](https://twitter.com/albertcasado). For
-more info:
+created and designed by [Albert Casado](https://twitter.com/albertcasado).
+For more info:
* https://pastanaga.io
* https://github.com/plone/pastanaga
@@ -75,28 +75,67 @@ https://github.com/plone/volto/tree/master/theme/themes/pastanaga
Pastanaga Theme is an example on how to customize the default Semantic UI look
and feel.
+
## Examples: Changing Base Font
-We start by creating the file `theme/globals/site.variables`. In this file we
-can override any value. We do not need to copy the whole file. We can add
-variables we would like to change. When we want to change the base font, we add
-the following:
+We start by creating the file `theme/globals/site.variables`.
+In this file we can override any value.
+We do not need to copy the whole file from Volto core.
+We can add variables we would like to change.
+When we want to change the base font, we add the following:
```less
@fontName : 'Comic Sans MS';
```
-> Make sure you have the 'Comic Sans MS' font installed. This is the
-> 'ttf-mscorefonts-installer' package for the Debian linux distribution.
+The font 'Comic Sans MS' needs to be either installed on you machine or provided with your app.
+
+To provide the font with your app, the following steps are necessary:
+
+1. Get your font and copy the files to `/theme/assets/fonts/`.
+
+1. Usually the font provider gives you ready made font-face instructions.
+ Copy these font-face code lines to `/theme/typography.css`.
+ There are a lot of font providers.
+ If you choose Google fonts, check [google-webfonts-helper](https://gwfh.mranftl.com/fonts) to generate `font-face` CSS code and download font files to include in your project.
+
+1. Add to the end of `/theme/theme.config` a function to load your font-faces:
+
+ ```less
+ .loadThemeFonts() {
+ @import "./typography.css";
+ }
+ ```
-> If you create a new file, the watcher won't be aware of it, you must restart
-> the `yarn start` Volto process again.
+1. Call this load function in `/theme/globals/site.overrides`:
-You can also point it to any Google Web Font name like:
+ ```less
+ .loadThemeFonts();
+ ```
+
+1. In `/theme/globals/site.variables` you can now override both, the font for headings (h1, h2, h3, …) and the font for the rest.
+
+ ```less
+ // Do not override @fontName!
+ // @fontName: 'Raleway', 'Helvetica Neue', Arial, Helvetica, sans-serif;
+
+ @pageFont: 'Raleway', 'Helvetica Neue', Arial, Helvetica, sans-serif;
+ @headerFont: 'Rubic Microbe', 'Helvetica Neue', Arial, Helvetica, sans-serif;
+ ```
+
+Voilà.
+Start your Volto app if you created new files.
+
+````{tip}
+For testing purpose you can refrain from installing the font and from providing the font with your app if the font is a Google font.
+With the following two lines you tell Volto to load the font "Montserrat" from `fonts.google.com`.
```less
@fontName : 'Montserrat';
+@importGoogleFonts : true;
```
+````
+
## Changing The Breadcrumbs
diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md
index 99be41d2cf..31bd17f7f9 100644
--- a/docs/source/upgrade-guide/index.md
+++ b/docs/source/upgrade-guide/index.md
@@ -11,27 +11,75 @@ myst:
# Upgrade Guide
-This upgrade guide lists all breaking changes in Volto and explains the
- steps that are necessary to upgrade to the latest version.
+This upgrade guide lists all breaking changes in Volto and explains the steps that are necessary to upgrade to the latest version.
Volto uses Semantic Versioning.
For more information see {ref}`volto-versioning-policy`.
```{note}
-There are times when updating the Volto boilerplate (the one generated by
-`@plone/generator-volto`) is enough to fulfill all the changes. If you haven't
-heavily modified it, moving things around and copying over your dependencies might
-do when dealing with upgrades. We keep the generator up to date and in sync with
-current Volto release. Please notice that the generator is able to tell you when it
-runs if it's outdated. The generator is also able to "update" your project with
-the latest changes, and propose to you to merge the changes, so you can run it on top of your project by answering the prompt.
+There are times when updating the Volto boilerplate (the one generated by `@plone/generator-volto`) is enough to fulfill all the changes.
+If you have not heavily modified it, moving things around and copying over your dependencies might do when dealing with upgrades.
+We keep the generator up to date and in sync with the current Volto release.
+When it runs, the generator will tell you whether it is outdated.
+The generator will also "update" your project with the latest changes, and propose to merge the changes.
+Thus it is safe to run it on top of your project and answer the prompts.
```
+(volto-upgrade-guide-17.x.x)=
+
+## Upgrading to Volto 17.x.x
+
+### Ending support for NodeJS 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.
+Version 18 is recommended.
+
+#### localhost now resolves to an IPv6 address
+
+NodeJS 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.
+
+### Webpack 5
+
+Volto 17 now uses Webpack 5.
+If you customized `razzle.config.js` for your project to change Webpack configuration
+or use Webpack plugins, you might need to make adjustments.
+
+### Razzle upgraded to version `4.2.18`
+
+Razzle has been upgraded to version `4.2.18`.
+It is recommended that you update your project's dependency on Razzle to this version in order to avoid duplication.
+
+### `BlockChooser` component now uses `popperjs` internally
+
+Technically not a breaking, the API nor the component contract has changed, but it's worth noting this change in here.
+
+```{versionadded} 17.0.0-alpha.1
+The `BlockChooser` component now uses `popperjs` library to position itself in the screen.
+It spawns at the end of the body instead of inner the block that called it.
+This is better from the UI point of view, since any other element can take precedence in the CSS element flow, preventing the block chooser to get overlapped by anything else.
+```
+
+If you have customized the `BlockChooser` in any way could be that this now could interact with your customizations.
+
+### Removed `hamburgers` library
+
+The `hamburgers` library was removed from core Volto, replaced by a much more lightweight approach.
+If your theme or add-ons relied on it, add it again as a dependency in them, or adopt the CSS part that you are using in them.
+
+### Fixed i18n script by taking into account the real add-on order
+
+By fixing this, we may break how the locales were applied, since the order will now be correct.
+Please check the translations of your project and add-ons, and verify that the translations are still correct.
+This could be especially true if you did translation overrides, two add-ons were using different translations for the same `msgid`, or there were conflicting `msgid`s in different add-ons.
(volto-upgrade-guide-16.x.x)=
## Upgrading to Volto 16.x.x
-### `volto-slate` is now core
+### `volto-slate` is now in core
From Volto 16.0.0-alpha.15 onwards, `volto-slate` is integrated into Volto core and enabled as the default text block.
The previous text block `text` based on `draftJS` is now deprecated and is restricted (hidden) in Volto bootstrap.
@@ -102,9 +150,12 @@ For projects already using `volto-slate`, take the following steps in your proje
You will have to configure your project to continue using `draftJS`, for example, in your `config.js` or in your add-on:
```js
+import { WysiwygWidget } from '@plone/volto/components';
+
config.settings.defaultBlockType = 'text'
config.blocks.blocksConfig.table.restricted = false;
config.blocks.blocksConfig.slateTable.restricted = true;
+config.widgets.widget.richtext = WysiwygWidget;
```
#### Existing projects using core `draftJS`, opting to start using `slate` without migrating (possible, but not recommended)
@@ -129,55 +180,62 @@ Version 16 is recommended.
### Upgraded to Razzle 4
```{versionadded} 16.0.0-alpha.38
-Volto has upgraded from Razzle 3 to Razzle 4. You should perform these steps in case you are upgrading to this version or above.
+Volto has upgraded from Razzle 3 to Razzle 4.
+You should perform these steps in case you are upgrading to this version or above.
```
#### Steps after upgrade
A few updates may be needed in existing projects:
-1. Add the `cache` directory to `.gitignore`.
-2. If `package.json` includes scripts that run `razzle test` with the `--env=jest-environment-jsdom-sixteen` option, update them to use `--env=jsdom` instead.
-3. Update the `jest` configuration in `package.json` to replace the `jest-css-modules` transform:
+1. Add the `cache` directory to `.gitignore`.
+2. If `package.json` includes scripts that run `razzle test` with the `--env=jest-environment-jsdom-sixteen` option, update them to use `--env=jsdom` instead.
+3. Update the `jest` configuration in `package.json` to replace the `jest-css-modules` transform:
-```diff
-"jest": {
- "transform": {
-- "^.+\\.css$": "jest-css-modules",
-- "^.+\\.scss$": "jest-css-modules"
- },
- "moduleNameMapper": {
-+ "\\.(css|less|scss|sass)$": "identity-obj-proxy"
- }
-}
-```
+ ```diff
+ "jest": {
+ "transform": {
+ - "^.+\\.css$": "jest-css-modules",
+ - "^.+\\.scss$": "jest-css-modules"
+ },
+ "moduleNameMapper": {
+ + "\\.(css|less|scss|sass)$": "identity-obj-proxy"
+ }
+ }
+ ```
-4. Add `--noninteractive` option to the build script
+4. Add the option `--noninteractive` to the build script.
-```diff
-- "build": "razzle build",
-+ "build": "razzle build --noninteractive",
-```
+ ```diff
+ - "build": "razzle build",
+ + "build": "razzle build --noninteractive",
+ ```
-5. If you use custom Razzle plugins, update them to use the new format with multiple functions: https://razzlejs.org/docs/upgrade-guide#plugins (the old format still works, but is deprecated).
-6. If you have customized webpack loader configuration related to CSS, make sure it is updated to be compatible with PostCSS 8.
-7. It's recommended that you remove your existing `node_modules` and start clean.
-8. If the add-ons you are using are not yet updated to latest `@plone/scripts`, it's also recommended that you force the version in your build, setting this in `package.json`:
+5. If you use custom Razzle plugins, update them to use the new format with multiple functions.
+ The old format still works, but is deprecated.
-```json
- "resolutions": {
- "**/@plone/scripts": "^2.0.0"
- }
-```
+ ```{seealso}
+ See https://razzlejs.org/docs/upgrade-guide#plugins
+ ```
+
+6. If you have customized webpack loader configuration related to CSS, make sure it is updated to be compatible with PostCSS 8.
+7. It's recommended that you remove your existing `node_modules` and start clean.
+8. If the add-ons you are using are not yet updated to the latest `@plone/scripts`, it's also recommended that you force the version in your build, setting this in `package.json`:
+
+ ```json
+ "resolutions": {
+ "**/@plone/scripts": "^2.0.0"
+ }
+ ```
#### Upgrade and update add-ons dependency on `@plone/scripts`
-```{warning}
+```{note}
This applies only to Volto add-ons.
```
Most probably you are using `@plone/scripts` in your add-on, since it's used in i18n messageid generation and has other add-on utilities.
-When upgrading to Volto 16.0.0-alpha.38 or above, you should upgrade `@plone/scripts` to a version 2.0.0 or above.
+When upgrading to Volto 16.0.0-alpha.38 or above, you should upgrade `@plone/scripts` to version 2.0.0 or above.
It's also recommended you move it from `dependencies` to `devDependencies`.
```diff
@@ -216,77 +274,111 @@ index 2f4e1e8..51bd52b 100644
### Jest is downgraded from version 27 to 26
-Razzle 4 internal API is only compatible with up to Jest 26.
+Razzle 4 internal API is only compatible with Jest up to version 26.
### Upgrade to use yarn 3
Volto was using the old, classic yarn (v1).
-It has become quite obsolete and yarn has evolved a lot during the last years.
-We are updating Volto to be able to use it, however some changes have to be made in your projects configuration:
-
-1. Enable yarn 3 in your projects, adding `yarnrc.yml`:
-
-```yml
-defaultSemverRangePrefix: ""
-
-nodeLinker: node-modules
-```
-
-Then, if you are using Node >=16.10 run:
-
-```shell
-corepack enable
-yarn set version 3.2.3
-```
-
-Corepack isn't included with Node.js in versions before 16.10.
-To address that, run:
-
-```shell
-npm i -g corepack
-```
-
-```{note}
-It is highly recommended that you use latest Node 16.
-```
-
-2. Change your root project `Makefile` to include these commands:
-
-```diff
-+.PHONY: preinstall
-+preinstall:
-+ if [ -f $$(pwd)/mrs.developer.json ]; then if [ -f $$(pwd)/node_modules/.bin/missdev ]; then yarn develop; else yarn develop:npx; fi; fi
-+
-+.PHONY: omelette
-+omelette:
-+ if [ ! -d omelette ]; then ln -sf node_modules/@plone/volto omelette; fi
-```
-
-3. Change your `package.json` scripts section:
-
-```diff
- "version": "1.0.0",
- "scripts": {
- "start": "razzle start",
-- "preinstall": "if [ -f $(pwd)/mrs.developer.json ]; then if [ -f $(pwd)/node_modules/.bin/missdev ]; then yarn develop; else yarn develop:npx; fi; fi",
-+ "preinstall": "make preinstall",
- "postinstall": "yarn omelette && yarn patches",
-- "omelette": "if [ ! -d omelette ]; then ln -sf node_modules/@plone/volto omelette; fi",
-+ "omelette": "make omelette",
- "patches": "/bin/bash patches/patchit.sh > /dev/null 2>&1 ||true",
-```
-
-Yarn 3 no longer support inline bash scripts in the `scripts` section.
-We need to move them to the `Makefile` and update the calls.
-
-4. It doesn't allow to use commands not declared as direct dependencies, so in your projects you should add `razzle` as a dependency:
-
-```diff
-devDependencies: {
-+ "razzle": "4.2.17",
-```
-
-5. Replace your project `yarn.lock` for the Volto's one, then run `yarn` again.
+It has become quite obsolete and yarn has evolved a lot in recent years.
+We updated Volto to be able to use it, however some changes have to be made in your project's configuration:
+
+1. Enable yarn 3 in your project, adding `.yarnrc.yml`:
+
+ ```yaml
+ defaultSemverRangePrefix: ""
+
+ nodeLinker: node-modules
+ ```
+
+ Then, if you are using Node >=16.10 run:
+
+ ```shell
+ corepack enable
+ yarn set version 3.2.3
+ ```
+
+ Corepack isn't included with Node.js in versions before 16.10.
+ To address that, run:
+
+ ```shell
+ npm i -g corepack
+ ```
+
+ ```{important}
+ It is highly recommended that you use the latest Node 16.
+ ```
+
+2. Change your root project `Makefile` to include these commands:
+
+ ```diff
+ +.PHONY: install
+ +install: ## Install the frontend
+ + @echo "Install frontend"
+ + $(MAKE) omelette
+ + $(MAKE) preinstall
+ + yarn install
+ +
+ +.PHONY: preinstall
+ +preinstall: ## Preinstall task, checks if missdev (mrs-developer) is present and runs it
+ + if [ -f $$(pwd)/mrs.developer.json ]; then make develop; fi
+
+ +
+ +.PHONY: develop
+ +develop: ## Runs missdev in the local project (mrs.developer.json should be present)
+ + npx -p mrs-developer missdev --config=jsconfig.json --output=addons --fetch-https
+ +
+ +.PHONY: omelette
+ +omelette: ## Creates the omelette folder that contains a link to the installed version of Volto (a softlink pointing to node_modules/@plone/volto)
+ + if [ ! -d omelette ]; then ln -sf node_modules/@plone/volto omelette; fi
+ +
+ +.PHONY: patches
+ +patches:
+ + /bin/bash patches/patchit.sh > /dev/null 2>&1 ||true
+ ```
+
+ You can copy the file over to your project if you have not made any amendment to it.
+
+3. Change your `package.json` scripts section:
+
+ ```diff
+ "version": "1.0.0",
+ "scripts": {
+ "start": "razzle start",
+ - "preinstall": "if [ -f $(pwd)/mrs.developer.json ]; then if [ -f $(pwd)/node_modules/.bin/missdev ]; then yarn develop; else yarn develop:npx; fi; fi",
+ - "omelette": "if [ ! -d omelette ]; then ln -sf node_modules/@plone/volto omelette; fi",
+ - "patches": "/bin/bash patches/patchit.sh > /dev/null 2>&1 ||true",
+ - "postinstall": "yarn omelette && yarn patches",
+ + "postinstall": "make omelette && make patches",
+ - "patches": "/bin/bash patches/patchit.sh > /dev/null 2>&1 ||true",
+ ```
+
+ Yarn 3 no longer supports inline bash scripts in the `scripts` section.
+ It does not support the `preinstall` lifecycle state, so we cannot trigger things while we run `yarn install` or just `yarn`.
+ As a result, we moved all the commands related to the `preinstall` actions into `Makefile`, then updated the calls in both files as shown above.
+
+ ````{important}
+ After making the changes in this step, we will have to modify our development workflow, especially if we use actions that happened during the `preinstall` state.
+ The most relevant one is updating the code that is managed by `mrs-developer`.
+ If you follow the code above, you'll need to call these `Makefile` commands before each `yarn install`.
+ It's recommended to use the `make install` command instead of just `yarn` or `yarn install`.
+
+ ```shell
+ make install
+ ```
+
+ Remember to update your CI scripts accordingly.
+ ````
+
+4. Yarn 3 does not allow the use of commands not declared as direct dependencies.
+ In your project, you should add `razzle` and `@plone/scripts` as development dependencies:
+
+ ```diff
+ devDependencies: {
+ + "@plone/scripts": "^2.1.2",
+ + "razzle": "4.2.17",
+ ```
+
+5. Replace your project `yarn.lock` with Volto's, then run `yarn` again.
### Removed `date-fns` from build
@@ -295,56 +387,67 @@ It was in the build because `Cypress` depended on it.
After `Cypress` was upgraded, it no longer depends on `date-fns`.
If your project still depends on `date-fns`, add it as a dependency of your project.
-```{warning}
+````{warning}
The `date-fns` version present in the build was quite old (1.x.x series).
Beware when using an updated version (2.x.x), as it may contain some breaking changes.
-Also take a look at: https://dockyard.com/blog/2020/02/14/you-probably-don-t-need-moment-js-anymore
+
+
+```{seealso}
+https://dockyard.com/blog/2020/02/14/you-probably-don-t-need-moment-js-anymore
+```
If you need to format dates in Volto, it's recommended to use the `FormattedDate` component in Volto core.
It uses modern recommendations for date formatting on the web.
-```
+````
-### Upgraded core to use Cypress 10
+### Upgraded core to use Cypress 11
-Cypress has overhauled the testing app and included native support of Apple Silicon Computers from 10.2.0 onwards.
-This improves dramatically the launch and test times in these machines.
+Cypress has overhauled their testing application, beginning with Cypress 10.
+It now includes native support of Apple silicon chip computers.
+This dramatically improved the launch and test times on those machines.
It also includes the new "component" testing feature that might be appealing in the near future.
-The only drawback is that they also overhauled the configuration forcing to migrate from old config based on JSON files to a better JS-based one. They also changed and renamed some of the options.
-Luckily, they provide a good reporting when old configuration is in place and an interactive migration wizard.
-Core configuration has been updated, but you will require to update your Cypress configuration if you want to use core's Cypress 10.
-Could be that forcing your project to use older versions might still work with old configurations.
+The only drawback is that they also overhauled the configuration, forcing migration from old configuration based on JSON files to a better JavaScript-based one.
+They also changed and renamed some options.
+Luckily, Cypress provides both good reporting when an old configuration is in place, and an interactive migration wizard.
+
+Core configuration has been updated to use Cypress 11.
+You will need to update your Cypress configuration from versions older than Cypress 10 if you want to use core's Cypress 11.
+If you have already updated your configuration to use Cypress 10 or later in a previous upgrade, your configuration might already work with Cypress 11.
+It is possible that forcing your project to use older versions might still work with old configurations.
+```{seealso}
See https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0 for more information.
+```
### The complete configuration registry is passed to the add-ons and the project configuration pipeline
-The core in versions prior Volto 16.0.0-alpha.22 was passing a simplified version of the configuration registry (in fact, a plain object primitive) to the add-on list and project configuration pipeline.
+The core in versions prior to Volto 16.0.0-alpha.22 passed a simplified version of the configuration registry—in fact, a plain object primitive—to the add-on list and project configuration pipeline.
From Volto 16.0.0-alpha.22 onwards, the full configuration registry is passed through the pipeline.
-This allows to have access to the advanced registry features, like the new component registry.
-You may want to update your configuration in case that you were updating the primitive using basic object operators (spread, etc) in the config object itself.
-For example, this won't work anymore:
+This allows you to have access to the advanced registry features, like the new component registry.
+You may want to update your configuration in case you updated the primitive using basic object operators (spread, and others) in the configuration object itself.
+For example, this will not work anymore:
```js
- return {
- ...config,
- blocks: {
- ...config.blocks,
- blocksConfig: {
- ...config.blocks.blocksConfig,
- ...addonBlocks,
- listing: listing(config),
- },
+return {
+ ...config,
+ blocks: {
+ ...config.blocks,
+ blocksConfig: {
+ ...config.blocks.blocksConfig,
+ ...addonBlocks,
+ listing: listing(config),
},
- views: {
- ...config.views,
- contentTypesViews: {
- ...config.views.contentTypesViews,
- Folder: NewsAndEvents,
- },
+ },
+ views: {
+ ...config.views,
+ contentTypesViews: {
+ ...config.views.contentTypesViews,
+ Folder: NewsAndEvents,
},
- };
+ },
+};
```
Using the spread operator while you mutate the configuration object is not required.
@@ -364,7 +467,7 @@ The other rules apply, so make sure you return the `config` object after mutatin
### Refactor the component registry API in the configuration registry
-After a period of testing, this experimental feature has been refactored to adequate better to existing requirements.
+After a period of testing, this experimental feature has been refactored to adequate existing requirements.
#### Renamed `registry.resolve` to `registry.getComponent`
@@ -375,7 +478,7 @@ After a period of testing, this experimental feature has been refactored to adeq
#### `registry.getComponent` signature changes
-It maintains signature compatibility with `registry.resolve` but introduces new arguments for bigger flexibility.
+It maintains signature compatibility with `registry.resolve`, but introduces new arguments for greater flexibility.
See documentation for more information.
@@ -391,22 +494,22 @@ config.registerComponent({
```
````
-### Main workflow change menu changed from Pastanaga UI simplification to classic Plone implementation
+### Main workflow change menu changed from Pastanaga UI simplification to Classic UI Plone implementation
Pastanaga UI envisioned a simplification of the classic Plone workflow change dropdown.
-The idea is that for users, the transition names were too cryptic and it was difficult to infer the destination state from them.
-So the simplification was meant to show the destination state as a transition name, simplifying the user experience.
+The transition names were too cryptic, and it was difficult to infer the destination state from them.
+This simplification was meant to show the destination state as a transition name, simplifying the user experience.
-This vision was partially implemented in Volto, bypassing the information coming from Plone, waiting for the next step: introduce this vision in Plone core (thus, change the workflow definitions) including this simplified mode, but maintaining the complete mode, with the full transition names.
+This vision was partially implemented in Volto, bypassing the information coming from Plone, waiting for the next step: introduce this vision in Plone core (thus, change the workflow definitions) including this simplified mode, but maintaining the complete mode with the full transition names.
-Since this never happened, we are going back to the classic mode, so the dropdown will show the transition names.
+Since this never happened, we are going back to the Classic UI mode, so the dropdown will show the transition names.
When the simplified vision is implemented, we will revisit it.
#### Move Layout constants to `config.views.layoutViewsNamesMapping`.
-The `constants` layout module was removed in favor of an object in the Configuration Registry: `config.views.layoutViewsNamesMapping`.
+The `constants` layout module was removed in favor of an object in the configuration registry, `config.views.layoutViewsNamesMapping`.
-If you have added or modified the Plone layout views literal mapping, you should now use this setting, and you can remove the module shadowing customization.
+If you added or modified the Plone layout views literal mapping, you should now use this setting, and you can remove the module shadowing customization.
You can now add an i18n `id` for any layout that you create as well, since the `Display` component is now i18n aware.
@@ -446,11 +549,11 @@ defineMessages({
})
```
-### `react-window` no longer a Volto dependency
+### `react-window` is no longer a Volto dependency
Volto used this library to generate dynamic "windowed/virtualized" select widget options.
-It moved to use `react-virtualized` instead of `react-window` because it provides a more broad set of features that Volto required.
-If you were using it in your project, you'll have to include it as a direct dependency of it from now on.
+It moved to use `react-virtualized` instead of `react-window` because it provides a broader feature set that Volto requires.
+If you were using it in your project, you will need to include it as a direct dependency from now on.
### Change the way the style wrapper is enabled and how to add the `styles` field
@@ -459,23 +562,30 @@ We decided it is best to deal with it as any other schema field and enhance it v
This improves the developer experience, especially when dealing with variations that can provide their own styles and other schema fields.
```{deprecated} 16.0.0-alpha.46
-The options `enableStyling` and `stylesSchema` no longer work. You need to provide them using your own block schema. If you are extending an existing one, you should add it as a normal `schemaEnhancer` modification.
+The options `enableStyling` and `stylesSchema` no longer work.
+You need to provide them using your own block schema.
+If you are extending an existing one, you should add it as a normal `schemaEnhancer` modification.
```
+```{seealso}
See https://6.dev-docs.plone.org/volto/blocks/block-style-wrapper.html for more documentation.
+```
-### Remove Sentry integration from core
+### Sentry integration moved from Volto core to add-on
The Sentry integration was implemented in Volto core at a time when Volto did not provide a good add-on story.
Since then, the add-on story has improved.
It now makes sense to extract this feature into its own add-on.
-You can find it in [`@collective/volto-sentry`](https://github.com/collective/volto-sentry).
+Integrate Sentry in your app with [`@plone-collective/volto-sentry`](https://www.npmjs.com/package/@plone-collective/volto-sentry).
+
+```{versionchanged} 16.0.0.alpha.45
+```
### Upgrade `husky` to latest version
-In the case that you are using husky in your projects (like Volto does), you will have to adapt to the new way that `husky` has for defining hooks.
+In case you use `husky` in your projects (like Volto does), you must adapt to the new way that `husky` defines {term}`hooks`.
-You'll have to add a script in your `package.json` file called `prepare`:
+You will have to add a script in your `package.json` file called `prepare`:
```diff
"build": "razzle build --noninteractive",
@@ -483,7 +593,38 @@ You'll have to add a script in your `package.json` file called `prepare`:
"test": "razzle test --maxWorkers=50%",
```
-After execute it, `husky` will install itself in the `.husky` folder of your project. Then you need to create the default hook scripts in `.husky` that you want to execute. You can copy over the Volto ones (take a look in Volto's `.husky` folder).
+After executing it, `husky` will install itself in the `.husky` folder of your project.
+Then you need to create the default hook scripts in `.husky` that you want to execute.
+You can copy over the Volto ones (take a look in Volto's `.husky` folder).
+
+### Better defaults handling
+
+````{versionadded} 16.0.0-alpha.51
+Prior to this version, we handled default values in schemas for blocks settings in a faulty and buggy manner.
+The state inferred was not deterministic and depended on the fields with defaults present.
+
+To correct this and allow Volto to handle defaults in a correct way, we have to pass down an additional prop to the `BlockDataForm` whenever we use it in our custom or add-on code, as in the following example.
+
+```{code-block} jsx
+:linenos:
+:emphasize-lines: 10
+
+ {
+ this.props.onChangeBlock(this.props.block, {
+ ...this.props.data,
+ [id]: value,
+ });
+ }}
+ onChangeBlock={onChangeBlock}
+ formData={this.props.data}
+ block={block}
+ />
+```
+````
+
(volto-upgrade-guide-15.x.x)=
@@ -492,8 +633,8 @@ After execute it, `husky` will install itself in the `.husky` folder of your pro
### Updated react-cookie library
This fixes a use case where cookies could potentially be messed up if your site is under heavy load.
-The old `react-cookie` library was not able to handle correctly the SSR part, specially the one that
-is shared in "Nobody's land" (not SSR, not under the React tree, actions, Redux middleware).
+The old `react-cookie` library was not able to handle correctly the {term}`SSR` part, specially the one that
+is shared in "Nobody's land" (not SSR, not under the React tree, actions, {term}`Redux middleware`).
Upgrading to the latest version of the `react-cookie` suite (`react-cookie`, `universal-cookie-express` and `universal-cookie`) will fix it.
You have to take action only in case you did some development involving cookies. The `react-cookie`
@@ -513,41 +654,42 @@ DraftJS libraries are now lazy-loaded, and some changes have been introduced in
The old way:
```js
- export default function applyConfig(config) {
- config.settings = {
- ...config.settings,
- listBlockTypes = [
- ...config.settings.listBlockTypes,
- 'my-list-item',
- ]
- }
- return config;
+export default function applyConfig(config) {
+ config.settings = {
+ ...config.settings,
+ listBlockTypes = [
+ ...config.settings.listBlockTypes,
+ 'my-list-item',
+ ]
}
+ return config;
+}
```
The new way:
```js
- export default function applyConfig(config) {
- const { richtextEditorSettings } = config.settings;
- config.settings.richtextEditorSettings = (props) => {
- const result = richtextEditorSettings(props);
- result.listBlockTypes = [...result.listBlockTypes, 'my-list-item']
- return result;
- }
- return config;
+export default function applyConfig(config) {
+ const { richtextEditorSettings } = config.settings;
+ config.settings.richtextEditorSettings = (props) => {
+ const result = richtextEditorSettings(props);
+ result.listBlockTypes = [...result.listBlockTypes, 'my-list-item']
+ return result;
}
+ return config;
+}
```
### Language Switcher no longer takes care of the sync of the language
-This responsibility has been transferred in full to the API Redux middleware, if you have shadowed either `LanguageSwitcher` or `MultilingualRedirector` (during the alpha phase) components, please update them.
+This responsibility has been transferred in full to the API {term}`Redux middleware`, if you have shadowed either `LanguageSwitcher` or `MultilingualRedirector` (during the alpha phase) components, please update them.
Not doing so won't break your project, but they won't get the latest features and bug fixes, and probably will update the language cookie twice.
### LinkView component markup change
-The `LinkView` component has the literal `The link address is: ` is now wrapped in a `
` block instead of a `` block. Please check if you have a CSS bound to that node and adjust accordingly.
+The `LinkView` component with the literal `The link address is: ` block instead of a `` block.
+Please check if you have a CSS bound to that node and adjust accordingly.
### Rename core-sandbox fixture to coresandbox
@@ -739,20 +881,20 @@ The `getVocabulary` action has changed API. Before, it used separate positional
## Upgrading to Volto 13.x.x
-## Deprecating NodeJS 10
+### Deprecating NodeJS 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
(12 or 14 at the moment of this writing).
-## Seamless mode is the default in development mode
+### Seamless mode is the default in development mode
Not really a breaking change, but it's worth noting it. By default, Volto 13 in
development mode uses the internal proxy in seamless mode otherwise configured
differently. To learn more about the seamless mode read: {doc}`../deploying/seamless-mode`
and {doc}`../configuration/zero-config-builds`.
-## Refactored Listing block using schemas and ObjectWidget
+### Refactored Listing block using schemas and ObjectWidget
The Listing block has been heavily refactored using schema forms and `BlockDataForm`
as well as the other new internal artifacts to leverage blocks variations and extensions at the same time
@@ -766,7 +908,7 @@ The advantage of this is that now you can use the `QuerystringWidget` with schem
data forms in a reusable way in your custom blocks. See the Listing block code for
further references.
-### Migrate your existing listing blocks
+#### Migrate your existing listing blocks
**(Updated: 2021/06/12)** If you have an existing Volto installation and you are using
listing blocks, you must run an upgrade step in order to match the new listing
@@ -849,7 +991,7 @@ When an official integration package exists, these upgrade steps in the backend
will be provided in there.
```
-### Update your custom variations (templates) in your project listing blocks
+#### Update your custom variations (templates) in your project listing blocks
In the case that you have custom templates for your listing blocks in your projects, it's required that you update the definitions to match the new core variations syntax.
@@ -879,7 +1021,7 @@ To this:
]
```
-## Control panel icons are now SVG based instead of font based
+### Control panel icons are now SVG based instead of font based
It was long due, the control panel overview route `/controlpanel` is now using SVG icons
from the Pastanaga icon set, instead of the deprecated font ones. If you have customized
@@ -893,13 +1035,13 @@ import config from '@plone/volto/registry'
config.settings.controlPanelsIcons.mynewcontrolpanelid = myfancyiconSVG;
```
-## Login form UI and accessibility updated
+### Login form UI and accessibility updated
Not really a breaking change, but it's worth to note that we changed the look and feel of
the login form and improved its usability and accessibility. Another move towards the new
Quanta look and feel.
-## Changes in the Table block feature set and messages
+### Changes in the Table block feature set and messages
The "inverted" option in Table Block was removed since it was useless with the current
CSS set. Better naming of options and labels in table block (English). Updating the i18n
@@ -923,7 +1065,7 @@ dependency" problems in Volto, due to the very nature of the solution (importing
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.
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 HMR (Hot Module Reloader) not working properly.
+like (just to mention one of them) the {term}`hot module replacement` (HMR) not working properly.
That's why in this version we are introducing the new Volto's Configuration Registry.
It's a centralized singleton that is populated from the core config module and can be
@@ -1357,7 +1499,7 @@ compiling. Migrate your code or if you want to use the proposal anyways, you'll
provide the configuration to your own project (babel.config.js) in your project root
folder.
-You might still be using the old-style connecting of your components to the Redux store using
+You might still be using the old-style connecting of your components to the {term}`Redux` store using
`@connect` decorator, in that case, take a look at any connected component in Volto to
have a glimpse on how to migrate the code.
@@ -1366,7 +1508,7 @@ you are good to go, and you don't have to do anything.
### Hoisting problems on some setups
-Some people were experimenting weird hoisting issues when installing dependencies. This
+Some people were experimenting weird {term}`hoisting` issues when installing dependencies. This
was caused by Babel deprecated proposals packages and its peer dependencies that
sometimes conflicted with other installed packages.
@@ -2040,7 +2182,9 @@ The blocks engine now takes care of the keyboard navigation of the blocks, so yo
The focus management is also transferred to the engine, so it's not needed for your block to manage the focus. However, if your block does indeed require to manage its own focus, then you should mark it with the `blockHasOwnFocusManagement` property in the blocks configuration object:
-``` js hl_lines="10"
+```{code-block} jsx
+:linenos:
+:emphasize-lines: 10
text: {
id: 'text',
title: 'Text',
diff --git a/docs/source/user-manual/blocks.md b/docs/source/user-manual/blocks.md
new file mode 100644
index 0000000000..9e4c744d4d
--- /dev/null
+++ b/docs/source/user-manual/blocks.md
@@ -0,0 +1,604 @@
+---
+myst:
+ html_meta:
+ "description": "User manual for how to edit blocks in Volto, the Plone 6 frontend."
+ "property=og:description": "User manual for how to edit blocks in Volto, the Plone 6 frontend."
+ "property=og:title": "How to edit content using Volto blocks"
+ "keywords": "Volto, Plone, frontend, React, User manual, edit blocks"
+---
+
+(edit-content-using-blocks-label)=
+
+# Edit content using blocks
+
+Volto features the [Pastanaga UI](https://github.com/plone/pastanaga), allowing you to visually compose a page using blocks.
+The blocks editor allows you to add, modify, reorder, and delete blocks given your requirements.
+Blocks provide the user the ability to display content in a specific way, although they can also define behavior and have specific features.
+
+
+(manage-blocks-label)=
+
+## Manage blocks
+
+In Volto, "blocks" are individual pieces of content that can be added to a page or other content area.
+These blocks can be used to add different types of content—such as text, images, or multimedia—and can be arranged and customized to create a wide range of different layouts.
+
+Blocks are a key feature of Volto, and are designed to make it easy for users to add and manage content on their website.
+They are created using React components, which are modular pieces of code that can be easily reused and customized.
+
+
+(create-a-block-label)=
+
+### Create a block
+
+To create or add an empty block after an existing block, click in the block, then hit the {kbd}`Enter` key.
+A new empty block appears.
+
+```{image} ../_static/user-manual/blocks/add-new-block.gif
+:alt: Add new block
+```
+
+```{note}
+There is a new experimental feature that places a `+` below a block when it is active or moused over, and when clicked inserts an empty block below the current block.
+
+See https://github.com/plone/volto/pull/3815 for details of the feature and how to enable it.
+```
+
+(configure-a-block-label)=
+
+### Configure a block
+
+When you select a block, its block editor appears in the right margin of the page.
+Almost all blocks have some configuration options.
+
+
+(rearrange-blocks-label)=
+
+### Rearrange blocks
+
+To rearrange blocks, to the right of the block you want to move, click on its drag handle, move the block where you want it in the page, and release the drag handle.
+
+
+(delete-a-block-label)=
+
+### Delete a block
+
+To delete a block, to the right of the block, click its delete button, a trash can icon.
+
+
+(default-block-types-label)=
+
+## Default block types
+
+Volto offers several default block types out of the box.
+You can access and choose a block type to add to your content type when you have an empty block in it.
+
+Now with your empty block available, you can select its type in one of two ways.
+
+1. Click the `+` button to the left of the empty block.
+
+ ```{image} ../_static/user-manual/blocks/block-left-add-icon.png
+ :alt: Add block button
+ ```
+
+2. Type `/` inside the empty block to open the block types menu.
+ You can type a few letters to filter available block types.
+ You can use the up and down arrow keys to navigate within the list of block types.
+ To select the block type, you can click or tap on it, or use the {kbd}`Enter` key.
+
+ ```{image} ../_static/user-manual/blocks/block-types-menu.png
+ :alt: Block types menu
+ ```
+
+
+(user-manual-description-block-label)=
+
+### Description block
+
+A description block accepts plain text.
+When displayed, it appears as the description in the page, and for search engine optimization in HTML meta tags as `` and ``.
+
+
+(user-manual-grid-block-label)=
+
+### Grid block
+
+A grid block creates a single row of columns in a grid, which can be used to display content in a structured, organized way.
+You can select the number of columns to insert.
+
+```{image} ../_static/user-manual/blocks/grid-block-number-of-columns.png
+:alt: Choose the number of columns to insert in a grid block.
+```
+
+After choosing the number of columns to insert in a grid block, you can manage the columns.
+
+```{image} ../_static/user-manual/blocks/grid-block-manage-blocks.png
+:alt: Add a specific block type into a grid block's column
+```
+
+- Specify the block type in a column by clicking its `+` button.
+- Rearrange the order of columns in the grid block by dragging and dropping them.
+- Add a column to the grid block by clicking the `+` button above and to the left of it.
+- Remove a column from a grid block by clicking its `×` button.
+
+
+(user-manual-html-block-label)=
+
+### HTML block
+
+An HTML block allows users to add custom HTML code to a page.
+This can be useful for adding custom functionality or styling to a page, or for integrating with external services or applications.
+For example, you can insert an HTML snippet or widget from a third party service to embed a calendar, payment or donation button, or social media into a page.
+
+```{image} ../_static/user-manual/blocks/html-block.png
+:alt: HTML block
+```
+
+To use an HTML block, you need to have some knowledge of how to write HTML, unless you are provided an HTML code snippet from a third party that you can copy and paste into the block.
+
+
+(user-manual-hero-block-label)=
+
+### Hero block
+
+A hero block creates a full-width banner or header for a page.
+It is typically used to highlight important content or to create a visual impact at the top of a page.
+
+```{image} ../_static/user-manual/blocks/hero-block.png
+:alt: Hero block
+```
+
+Hero blocks typically include a background image or color.
+They can also include a title, description, and links to other pages in your site.
+
+You can use the block editor to configure its options.
+You can set the background image or color, its title and description, and links.
+For links, you can enter an external URL or select a page in your site by clicking the list icon, and give the link a title.
+
+
+(user-manual-image-block-label)=
+
+### Image block
+
+An image block lets a user insert an image into a page and configure its attributes.
+
+```{image} ../_static/user-manual/blocks/image-block.png
+:alt: Image block
+```
+
+After inserting an image block, an image must be specified by any of the following methods.
+- Choose an existing image in the site by clicking the block's list icon.
+- Upload a new image by either clicking the block's upload icon or drag and drop.
+- Enter a remote image's URL in the block's text area.
+ Click the arrow icon to save the URL.
+
+Once you have specified an image, its configurable options become available.
+```{image} ../_static/user-manual/blocks/image-block-configuration-options.png
+:alt: Image block configuration options
+```
+
+Source
+: The path or URL to the image.
+
+Alt text
+: Alternative text (alt text) is used by screen readers and search engines to describe the image.
+ Alt text should not be used for decorative images, as it adds noise to the screen reader.
+
+Alignment
+: Options for alignment include left, right, center, and full width.
+
+Image size
+: The image size determines its relative display width, either small, medium, or large.
+
+Link to
+: You can enter a URL in the text field, or click the list icon and choose a page in your website, as the target for a link.
+ You can optionally have the link open in a new tab when the user clicks it by checking the checkbox {guilabel}`Open in a new tab`.
+
+
+(user-manual-images-grid-block-label)=
+
+### Images grid block
+
+An images grid block displays a row of images on a page.
+It is typically used to showcase a collection of images in a visually appealing way.
+It can be configured to display the images in different layouts and styles.
+
+```{image} ../_static/user-manual/blocks/images-grid-block-number-of-columns.png
+:alt: Choose the number of images to insert in an images grid block.
+```
+
+After choosing the number of images to insert in an images grid block, you can configure the images exactly as you would configure a single image in an image block.
+
+```{image} ../_static/user-manual/blocks/image-block-configuration-options.png
+:alt: Image block configuration options
+```
+
+Source
+: The path or URL to the image.
+
+Alt text
+: Alternative text (alt text) is used by screen readers and search engines to describe the image.
+ Alt text should not be used for decorative images, as it adds noise to the screen reader.
+
+Alignment
+: Options for alignment include left, right, center, and full width.
+
+Image size
+: The image size determines its relative display width, either small, medium, or large.
+
+Link to
+: You can enter a URL in the text field, or click the list icon and choose a page in your website, as the target for a link.
+ You can optionally have the link open in a new tab when the user clicks it by checking the checkbox {guilabel}`Open in a new tab`.
+
+You can also manage the images in the images grid block.
+
+```{image} ../_static/user-manual/blocks/images-grid-block-manage-images.png
+:alt: Manage images in an images gride block
+```
+
+- Rearrange the order of images in the images grid block by dragging and dropping them.
+- Add an image to the images grid block by clicking the `+` button above and to the left of it.
+- Remove an image from an images grid block by clicking its `×` button.
+
+
+After inserting an image grid block, an image must be specified by any of the following methods.
+
+
+(user-manual-listing-block-label)=
+
+### Listing block
+
+A listing block allows users to display a list of content items in your Plone site on a page.
+A site editor can configure the criteria to use for retrieving content items, including text, title, dates, and creator.
+The retrieved results can be configured with a sort order, limit of results, and whether to batch the results with pagination.
+
+```{image} ../_static/user-manual/blocks/listing-block.png
+:alt: Listing block
+```
+
+The listing block has several configuration options.
+
+```{image} ../_static/user-manual/blocks/listing-block-configuration.png
+:alt: Listing block configuration
+```
+
+Variation
+: Options for variation include {guilabel}`Default`, {guilabel}`Image gallery`, and {guilabel}`Summary`.
+
+Headline
+: Optionally add a headline to the listing block.
+
+Headline level
+: Headline level sets the level of the headline to either {guilabel}`H2` or {guilabel}`H3`.
+
+Criteria
+: Add criteria for the search.
+ Options include searching metadata, dates, and text.
+ Each criterion has its own options.
+ For example, you can configure a search for content that was created between two dates, or for its location within a path of your Plone site.
+
+Sort on
+: Sort the retrieved results by a given option.
+ Options include metadata, dates, and text.
+
+Results limit
+: Limit the number of results returned.
+
+Item batch size
+: Batch the search result items into a specified batch size.
+
+
+(user-manual-maps-block-label)=
+
+### Maps block
+
+A map block allows a user to add a map to a page.
+It is typically used to display a geographic location or region, or provide travel directions.
+
+```{image} ../_static/user-manual/blocks/maps-block.png
+:alt: Maps block
+```
+
+To use a map block, the third party map service must provide a snippet of HTML code that you can copy and paste into the map block.
+Usually the snippet includes an `