Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve wayfinding for various Volto audiences #5809

Merged
merged 16 commits into from
Mar 4, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/configuration/how-to.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ but also the [lookup
mechanism](https://github.com/plone/volto/blob/212026a39fd9aa0e1d6c324f967b51a3daa10b01/packages/volto/src/components/manage/Form/Field.jsx#L151)
to understand how things work.

See {doc}`../recipes/widget` for more information.
See {doc}`../development/widget` for more information.

## views

Expand Down
2 changes: 1 addition & 1 deletion docs/source/configuration/internalproxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,4 +68,4 @@ This redefines the request path from the internal proxy of the server side Node.

### Advanced usage

See {doc}`../recipes/environment-variables` for recipes for internal proxy usage.
See {doc}`../development/environment-variables` for recipes for internal proxy usage.
4 changes: 2 additions & 2 deletions docs/source/configuration/settings-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ initialReducersBlacklist
loadables
A mapping of loadable libraries that can be injected into components using
the `injectLazyLibs` HOC wrapper. See the [Lazy
loading](../recipes/lazyload) page for more details.
loading](../development/lazyload) page for more details.

lazyBundles
A mapping of bundles to list of lazy library names. Create new bundles (or
Expand Down Expand Up @@ -514,7 +514,7 @@ in the `config.settings.serverConfig` object.

expressMiddleware
A list of ExpressJs middleware that can extend the built-in functionality of
Volto's server. See the [Express](../recipes/express) section for more details.
Volto's server. See the [Express](../development/express) section for more details.

criticalCssPath
A path relative to the project root that points to an optional CSS file. If
Expand Down
2 changes: 1 addition & 1 deletion docs/source/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ For developing Volto, follow {doc}`developing-core`.
## 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).
Please mark all such strings as translatable as defined in the [i18n guide](../development/i18n.md).


(contributing-branch-policy-for-translations-label)=
Expand Down
2 changes: 1 addition & 1 deletion docs/source/contributing/language-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,4 +70,4 @@ have to support.
However, Volto (or its dependencies) might not be compatible with old browsers anyways,
and you might need to provide some other workarounds to make the build work (and the
deprecated browser not crash). You can refer to {doc}`this (outdated)
document <../recipes/ie11compat>` in order to get some hints on how to do it.
document <../development/ie11compat>` in order to get some hints on how to do it.
2 changes: 1 addition & 1 deletion docs/source/deploying/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ critical-cli https://example.com/ -o critical.css

You can pass multiple URLs and screen dimmensions and the extracted CSS will be
optimized (duplicate rules will be eliminated, etc). See the [Advanced preset
of cssnano](https://cssnano.co/docs/what-are-optimisations/) for details. One last
of cssnano](https://web.archive.org/web/20230101000000*/https://cssnano.co/docs/what-are-optimisations/) for details. One last
optimization applied strips all `@import` declarations from the generated CSS.

After that, copy this file to the `public/critical.css` path (configurable
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
40 changes: 40 additions & 0 deletions docs/source/development/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
myst:
html_meta:
"description": "Volto development"
"property=og:description": "Volto development"
"property=og:title": "Development"
"keywords": "Volto, Plone, frontend, React, development"
---

# Development

This part of the documentation describes how to develop projects using Volto.

See {doc}`overview` for a reference of technologies used within the Volto stack, and for suggested topics for further learning and research.

Or jump in to any topic listed below.

```{toctree}
:caption: Table of Contents
:maxdepth: 1

overview
creating-project
folder-structure
environment-variables
customizing-components
customizing-views
creating-views
images
i18n
express
lazyload
appextras
contextnavigation
pluggables
widget
how-to-restrict-blocks
color-picker-widget
ie11compat
```
File renamed without changes.
102 changes: 102 additions & 0 deletions docs/source/development/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
myst:
html_meta:
"description": "Volto development overview"
"property=og:description": "Volto development overview"
"property=og:title": "Volto development overview"
"keywords": "Volto, Plone, frontend, React, development, overview"
---

# Overview

If you're coming to Volto as a backend or Classic UI Plone developer, you'll need to learn and adjust to the new frontend-centered development.

If you already have some frontend development experience with any JavaScript framework such as AngularJS, Vue, or React, then you'll find that Volto is a relatively shallow 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.

As a reference, here's an overview of knowledge and frameworks, to give a more complete and accurate picture of the Volto framework.


## Foundation

As is the case with similar modern JavaScript-based applications, you should be familiar the following foundational topics.

- Modern JavaScript development.
Volto uses next-generation JavaScript.
Follow the [ES6 guide](https://flaviocopes.com/es6/) to get up to speed.
- [Basic React knowledge](https://react.dev/learn/tutorial-tic-tac-toe) to start.
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/),
[npm packages](https://flaviocopes.com/npm/),
[Yarn](https://flaviocopes.com/yarn/),
[Babel](https://flaviocopes.com/babel/), and
[Webpack](https://flaviocopes.com/webpack/).


## Basic Volto development

Once you've {doc}`bootstrapped your Volto project <plone:install/create-project>`, you can immediately start hacking.
The following is a list of some the things you can do at this stage.

- Configure your text editor for JavaScript and Volto development
- Volto project-based development
- Understand and debug React errors
- Understand the React component lifecycle
- Customize (shadow) Volto's built-in components
- Write a new {doc}`block <../blocks/index>`
- Adjust Volto's {doc}`built-in settings <../configuration/index>`
- Extend the Pastanaga {doc}`theme <../theming/index>`
- Extend the {doc}`richtext editor capabilities <../configuration/volto-slate/index>` with new buttons and styles
- Use the Redux store
- {doc}`Deploy <../deploying/index>` your first project

After you've mastered the foundation and basic Volto development, the learning curve smoothes out.
Volto uses simple and familiar concepts.
There is nothing on the complexity level of ZCA that you would need to internalize before you can be really productive.


## Routine Volto development

While developing a project using Volto, you might perform the following routine tasks.

- Write new Redux actions and reducers
- Create new views for Plone content
- Install and integrate new JavaScript libraries or third-party React components
- Create a new Volto add-on
- Integrate an add-on's LESS statements with Volto's theme variables
- Use schema-based forms to write block components
- Write new form widgets
- Write tests in Jest
- Write integration tests in Cypress
- Split your code and lazy-load libraries to improve performance
- Use more advanced React concepts, including hooks, context providers, and other topics
- Make your code reusable by separating business logic and repeated behaviors as Higher Order Components (HOCs)
- Write extensible blocks


## Occasional Volto development

From time to time, you might perform the following tasks.

- Provide backend-based integration for your Volto code by writing `plone.restapi` endpoints, adapters, and other extensions
- Custom integration for blocks to the backend using the block transformers concept
- Write Express middleware for Volto's server
- Customize Volto's Webpack configuration or project loader using Razzle
- Write a Redux middleware
- Start hacking on Volto


## Add-on first approach

Developing for Plone's frontend means to add code to a Volto project.
The frontend files of the project are created in the `frontend` folder.
The generator also creates a default add-on in the `frontend/src/addons` folder.
The project is already configured to use this add-on.
Add your code and customizations to this add-on, and Volto will load them on start up or a restart.
This add-on is configured as a theme add-on, so you are able to customize the look and feel of your site as well.

```{seealso}
For more information about how to develop a Volto project as an add-on, see {doc}`training:voltoaddons/index`.
```
File renamed without changes.
17 changes: 0 additions & 17 deletions docs/source/getting-started/index.md

This file was deleted.

76 changes: 0 additions & 76 deletions docs/source/getting-started/others.md

This file was deleted.

Loading
Loading