Effective Volto 2023

docs/effective-volto/about_effective_volto.md

@@ -23,7 +23,7 @@ Tiberiu Ichim
 
 Víctor Fernández de Alba
 
-: Víctor is CTO at kitconcept GmbH, a Plone solution provider from Bonn, Germany. Member of the Plone Community since 2006, author of a Plone book, co-author of Plone 5’s multilingual feature and its default theme Barceloneta. He is the Plone 6 Volto Release Manager, member of the Volto Team and Plone REST API contributor. He was also organizer of the Barcelona Plone Conference in 2017, sprints and other Plone events in Barcelona and Bonn and he is deeply involved in several Plone Community Teams including the Plone Foundation Board of directors.
+: Víctor is CTO at kitconcept GmbH, a Plone solution provider from Bonn, Germany. Member of the Plone Community since 2006, currently he's the Release Manager of Plone Volto and Volto Team leader.Author of a Plone book, co-author of Plone 5’s multilingual feature and its default theme Barceloneta. He is the Plone 6 Volto Release Manager, member of the Volto Team and Plone REST API contributor. He was also organizer of the Barcelona Plone Conference in 2017, sprints and other Plone events in Barcelona and Bonn and he is deeply involved in several Plone Community Teams.
 
 ## License
 

docs/effective-volto/addons/blockdataform.md

@@ -13,7 +13,7 @@ The BlockDataForm renders an form fully integrated with a block's extension
 mechanisms: variations and block styles. To use it, instantiate the schema and
 pass it down to the component. A full Volto block edit component could be like:
 
-```
+```jsx
 export const MyBlockSchema = ({data, intl}) => {
   return {
     title: "My block",
@@ -62,6 +62,9 @@ export const MyBlockEdit = (props) => {
             });
           }}
           formData={data}
+          onChangeBlock={onChangeBlock}
+          block={block}
+          blocksConfig={blocksConfig}
         />
       </SidebarPortal>
     </>
@@ -76,7 +79,7 @@ If there's any registered variations for this block, they will be displayed as
 a Select control for the active variation, in the sidebar.
 
 
-```
+```js
   myblock: {
     id: 'myblock',
     title: 'My Block',
@@ -112,3 +115,59 @@ a Select control for the active variation, in the sidebar.
 Note: you can assign the schema to `blockSchema` in the block configuration. It
 is used only to extract the block default values. This integration will be
 improved, in the future.
+
+## Using a dataAdapter pattern
+
+Sometimes is useful to adapt the incoming data to other data format, structure or type.
+You can use the dataAdapter pattern in `BlockDataForm` as this:
+
+```jsx
+  const schema = blocksConfig[data['@type']].blockSchema({ intl });
+  const dataAdapter = blocksConfig[data['@type']].dataAdapter;
+
+    <BlockDataForm
+      schema={schema}
+      title={schema.title}
+      onChangeField={(id, value) => {
+        dataAdapter({
+          block,
+          data,
+          id,
+          onChangeBlock,
+          value,
+        });
+      }}
+      onChangeBlock={onChangeBlock}
+      formData={data}
+      block={block}
+      blocksConfig={blocksConfig}
+    />
+```
+
+and define `dataAdapter` as this:
+
+```js
+import { isEmpty } from 'lodash';
+
+export const TeaserBlockDataAdapter = ({
+  block,
+  data,
+  id,
+  onChangeBlock,
+  value,
+}) => {
+  let dataSaved = {
+    ...data,
+    [id]: value,
+  };
+  if (id === 'href' && !isEmpty(value) && !data.title && !data.description) {
+    dataSaved = {
+      ...dataSaved,
+      title: value[0].Title,
+      description: value[0].Description,
+      head_title: value[0].head_title,
+    };
+  }
+  onChangeBlock(block, dataSaved);
+};
+```

docs/effective-volto/getting-started/add-on.md

@@ -18,7 +18,7 @@ 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.
 
 Although you could simply use `npm init` to generate an addon initial code,
-we now have a nice
+we have a
 [Yeoman-based generator](https://github.com/plone/generator-volto) that you can use:
 
 ```shell
@@ -32,90 +32,141 @@ use the final ones from the very beginning. This means that you can use imports
 such as `import { Something } from '@plone/my-volto-addon'` without any extra
 configuration.
 
-## Developing in isolation with a vanilla Volto project
+## Developing in isolation using a full dockerized project approach
 
-You can develop an add-on in isolation using the `@plone/scripts` `addon` command line.
-This script creates and configures a vanilla project using the Volto generator.
+You can develop an add-on in isolation using the boilerplate already provided by the add-on generator.
 The project is configured to have the current add-on installed and ready to work with.
-This script is useful to bootstrap an isolated environment that can be used to quickly develop the add-on or for demo purposes.
+This is useful to bootstrap an isolated environment that can be used to quickly develop the add-on or for demo purposes.
 It's also useful when testing an add-on in a CI environment.
 
 ```{note}
 It's quite similar when you develop a Plone backend add-on in the Python side, and embed a ready to use Plone build (using buildout or pip) in order to develop and test the package.
 ```
 
-Unfortunately, the NodeJS tooling does not work well with symlinks or outside the root of the project.
-This script proceeds in the following way:
+The dockerized approach performs all these actions in a custom built docker environment:
 
 1. Generates a vanilla project using the official Volto Yo Generator (@plone/generator-volto)
 2. Configures it to use the add-on with the name stated in the `package.json`
-3. Copies over the root of the add-on (`src` and essential files) inside the created project
+3. Links the root of the add-on inside the created project
 
-After this, you can change directory to the created project, by default `addon-testing-project`.
-The name of the created project is parameterizable.
+After that you can use the inner dockerized project, and run any standard Volto command for linting, acceptance test or unit tests using Makefile commands provided for your convenience.
 
-After that you can use the full fledged project, and run any standard Volto command for linting, acceptance test or unit tests.
+### Setup the environment
 
-### clone (git)
+Run once
 
-Given the add-on remote git repository, it pulls and configures it into the vanilla project generated by the script.
+```shell
+make dev
+```
+
+which will build and launch the backend and frontend containers.
+There's no need to build them again after doing it the first time unless something has changed from the container setup.
+
+In order to make the local IDE play well with this setup, is it required to run once `yarn` to install locally the required packages (ESlint, Prettier, Stylelint).
+
+Run
+
+```shell
+yarn
+```
+
+### Build the containers manually
+
+Run
+
+```shell
+make build-backend
+make build-addon
+```
+
+### Run the containers
+
+Run
+
+```shell
+make start-dev
+```
+
+This will start both the frontend and backend containers.
+
+### Stop Backend (Docker)
+
+After developing, in order to stop the running backend, don't forget to run:
+
+Run
 
-`npx -p @plone/scripts addon clone [options] <source> [destination]`
+```shell
+make stop-backend
+```
+
+### Linting
+
+Run
+
+```shell
+make lint
+```
+
+### Formatting
+
+Run
+
+```shell
+make format
+```
 
-```console
-    Usage: addon clone [options] <source> [destination]
+### i18n
 
-    clone a repository into a newly created directory
+Run
 
-    Options:
-      -p, --private          set if the repo is private, then GITHUB_TOKEN is used
-      -b, --branch <branch>  set the repo branch, defaults to main
-      -c, --canary           downloads latest Volto canary (alpha) version
-      -h, --help             display help for command
+```shell
+make i18n
 ```
 
-This next command downloads the `volto-blocks-grid` add-on from its git repository's `main` branch, and will generate a project with the latest Volto canary (alpha) version.
+### Unit tests
+
+Run
 
 ```shell
-npx -p @plone/scripts addon clone https://github.com/kitconcept/volto-blocks-grid.git --branch main --canary
+make test
 ```
 
-This will create a directory named `addon-testing-project`, and will bootstrap a new project using Volto's standard project generator.
-It will adjust the configuration of this project to setup the add-on in the project using `mrs-developer`, and the git URL given to fetch the add-on contents.
-You can specify the branch to be used, if the project should use the latest alpha available.
-For private repositories, it uses the `GITHUB_TOKEN` present in your environment variables to fetch it.
+### Acceptance tests
 
-After this, as a developer you can use the usual project commands to run tests (unit, linting, acceptance) inside the generated `addon-testing-project`.
-You can configure the CI of your choice for automated testing, you can take a look at how it's done in: https://github.com/kitconcept/volto-blocks-grid/tree/main/.github/workflows
+Run once
 
-The idea is to issue commands inside the generated `addon-testing-project` project and do your checks.
-Take special care on how to pass down to the `npx` command the current pull request branch.
-Depending on your CI system, this might be different.
+```shell
+make install-acceptance
+```
 
-### clone local
+For starting the servers
 
-You can also clone the local add-on using:
+Run
 
 ```shell
-npx -p @plone/scripts addon clone .
+make start-test-acceptance-server
 ```
 
-This only works if you execute the command from the root of your add-on directory.
+The frontend is run in dev mode, so development while writing tests is possible.
 
-### consolidate
+Run
 
-While developing, you might have done changes inside the generated project, and you most probably want to consolidate them, back into the root of the repository.
-By running this script, it copies over from `addon-testing-project/src/addons/<my-addon>` to the root of your repository.
+```shell
+make test-acceptance
+```
 
-It should be run at the root of the add-on, and it gets an optional `source` argument in case you have specified a directory other than `addon-testing-project`.
+To run Cypress tests afterwards.
 
-`npx -p @plone/scripts addon consolidate --help`
+When finished, don't forget to shutdown the backend server.
 
-```console
-    Usage: addon consolidate [options] [source]
+```shell
+make stop-test-acceptance-server
+```
 
-    Consolidate a cloned project
+### Release
 
-    Options:
-      -h, --help  display help for command
+Run
+
+```shell
+make release
 ```

docs/effective-volto/getting-started/project.md

@@ -11,7 +11,7 @@ myst:
 
 # Bootstrapping a full Plone 6 project
 
-We can use the new [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) repository.
+We will use the official [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) repository.
 
 ```{note}
 The introduction of more tools are in store in order to ease the creation of the boilerplate for a full Plone 6 project, but they might revolve around this cookiecutter template.
@@ -35,12 +35,10 @@ After that, install Yeoman according to the [Plone documentation](https://6.docs
 
 Finally, install `yarn` according to the [Plone documentation](https://6.docs.plone.org/volto/getting-started/install.html#yarn-nodejs-package-manager).
 
-
-### Docker (optional)
+### Docker (optional, but recommended)
 
 Install `Docker` according to the [official documentation](https://docs.docker.com/get-docker/).
 
-
 Generate a new Plone 6 Project:
 
 ```shell
@@ -79,18 +77,14 @@ make build
 
 and restart backend and frontend by stopping and re-running
 
-
 ```shell
 make start-backend
 ```
 
-
 ```shell
 make start-frontend
 ```
 
-
-
 ## Project Generation Options
 
 These are all the template options that will be prompted by the [Cookiecutter CLI](https://github.com/cookiecutter/cookiecutter) prior to generating your project.