From 5072ce55d3e295183f42d932137efb6166372c2e Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sun, 19 Jan 2025 00:07:01 +0100 Subject: [PATCH 01/10] Add route shape --- packages/registry/docs/how-to-guides/instantiate-registry.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/registry/docs/how-to-guides/instantiate-registry.md b/packages/registry/docs/how-to-guides/instantiate-registry.md index f915e983fe..40db6fce10 100644 --- a/packages/registry/docs/how-to-guides/instantiate-registry.md +++ b/packages/registry/docs/how-to-guides/instantiate-registry.md @@ -46,6 +46,7 @@ export type ConfigData = { widgets: WidgetsConfig | Record; addonReducers?: AddonReducersConfig; addonRoutes?: AddonRoutesConfig; + routes?: Array; slots: SlotsConfig | Record; components: ComponentsConfig | Record; utilities: UtilitiesConfig | Record; From a65800eae9ba9b342e36bcfb8f7abbe623d9b5ad Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sun, 19 Jan 2025 20:49:47 +0100 Subject: [PATCH 02/10] Add docs for the routes API --- .../docs/how-to-guides/register-routes.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 packages/registry/docs/how-to-guides/register-routes.md diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md new file mode 100644 index 0000000000..e3f23300f4 --- /dev/null +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -0,0 +1,54 @@ +--- +myst: + html_meta: + "description": "How to register new routes in @plone/registry" + "property=og:description": "How to register new routes in @plone/registry" + "property=og:title": "How to register new routes" + "keywords": "Volto, Plone, frontend, React, configuration, routes, React Router" +--- + +# How to register new routes + +````{admonition} Warning! This feature is experimental and only applies to register routes for React Router 7 applications. Click to accept the risks and read details. +:class: warning + +The `config.registerRoute` method will add a new route to the configuration registry. +This route is intended to be loaded by the `@plone/react-router` helper and loaded in a React Router 7 app. +Under the hood, it saves the routes in the `config.routes` key in the configuration object. +You should provide one route at a time and should have this shape: + +```ts +type ReactRouterRouteEntry = { + type: 'route' | 'index' | 'layout' | 'prefix'; + path: string; + file: string; + options?: { + id?: string; + index?: boolean; + caseSensitive?: boolean; + }; + children?: ReactRouterRouteEntry[]; +}; +``` + +The `type`, `path` and `file` are mandatory. +The `type` key specify the route type to be created, more specifically, one of `route`, `index`, `layout` or `prefix`. +The type `route` can contain nested routes. +Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes. + +You register a route like this: + +```ts +config.registerRoute({ + type: 'route', + path: '/login', + file: '@plone/cmsui/components/login.tsx', + options: { + id: 'login', + index: true, + }, +}); +``` + +It is required that you set the full module path name for the registered route component in order to make `@plone/registry` to it address correctly when it's going to be used. +```` From 2d54d58653cebab330c6a6bdde16c4ba6f4d57ed Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sun, 19 Jan 2025 20:51:43 +0100 Subject: [PATCH 03/10] Changelog --- packages/registry/news/6604.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/registry/news/6604.documentation diff --git a/packages/registry/news/6604.documentation b/packages/registry/news/6604.documentation new file mode 100644 index 0000000000..bd10235aba --- /dev/null +++ b/packages/registry/news/6604.documentation @@ -0,0 +1 @@ +Document the route API. @sneridagh From 5bd4a317f8ca0adb444c5dd4f718aa874157e191 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 19 Jan 2025 18:51:51 -0800 Subject: [PATCH 04/10] Grammar improvements to register-routes.md --- .../docs/how-to-guides/register-routes.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md index e3f23300f4..47c9f390b0 100644 --- a/packages/registry/docs/how-to-guides/register-routes.md +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -3,19 +3,19 @@ myst: html_meta: "description": "How to register new routes in @plone/registry" "property=og:description": "How to register new routes in @plone/registry" - "property=og:title": "How to register new routes" + "property=og:title": "How to register new routes in @plone/registry" "keywords": "Volto, Plone, frontend, React, configuration, routes, React Router" --- -# How to register new routes +# Register new routes -````{admonition} Warning! This feature is experimental and only applies to register routes for React Router 7 applications. Click to accept the risks and read details. +````{admonition} Warning! This feature is experimental and only applies to registering routes for React Router 7 applications. Click to accept the risks and read details. :class: warning -The `config.registerRoute` method will add a new route to the configuration registry. -This route is intended to be loaded by the `@plone/react-router` helper and loaded in a React Router 7 app. -Under the hood, it saves the routes in the `config.routes` key in the configuration object. -You should provide one route at a time and should have this shape: +The `config.registerRoute` method adds a route to the configuration registry. +The `@plone/react-router` helper loads the route and configures it in a React Router 7 app. +It saves the routes in the `config.routes` key in the configuration object. +You should provide one route at a time in the following structure. ```ts type ReactRouterRouteEntry = { @@ -31,12 +31,12 @@ type ReactRouterRouteEntry = { }; ``` -The `type`, `path` and `file` are mandatory. -The `type` key specify the route type to be created, more specifically, one of `route`, `index`, `layout` or `prefix`. +The `type`, `path`, and `file` are mandatory. +The `type` key specifies the route type to create, specifically one of `route`, `index`, `layout`, or `prefix`. The type `route` can contain nested routes. Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes. -You register a route like this: +Register a route as shown in the following example. ```ts config.registerRoute({ @@ -50,5 +50,5 @@ config.registerRoute({ }); ``` -It is required that you set the full module path name for the registered route component in order to make `@plone/registry` to it address correctly when it's going to be used. +You must set the module's full path name of the registered route component to make `@plone/registry` correctly address it. ```` From d46982f739c384868010b22d0e3adb44ffceeeed Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 19 Jan 2025 19:05:46 -0800 Subject: [PATCH 05/10] Add how-to-guides/register-routes to index.md --- packages/registry/docs/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/registry/docs/index.md b/packages/registry/docs/index.md index ad433cc9b6..d70b5ce51c 100644 --- a/packages/registry/docs/index.md +++ b/packages/registry/docs/index.md @@ -4,7 +4,7 @@ myst: "description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps." "property=og:description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps." "property=og:title": "@plone/registry" - "keywords": "@plone/registry, registry, add-on, configuration, component, utility, JavaScript, TypeScript, app" + "keywords": "@plone/registry, registry, add-on, configuration, component, routes, React Router, utility, JavaScript, TypeScript, app" --- # `@plone/registry` @@ -29,6 +29,7 @@ how-to-guides/access-registry how-to-guides/register-and-retrieve-components how-to-guides/register-and-retrieve-utilities how-to-guides/shadow-a-component +how-to-guides/register-routes ``` From eb14803cf6eca4a7eb34d4ace3bc90d441b9c77a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 19 Jan 2025 22:20:35 -0800 Subject: [PATCH 06/10] Add `sphinx-togglebutton` extension and markup --- packages/registry/docs/conf.py | 1 + packages/registry/docs/how-to-guides/register-routes.md | 2 +- requirements-docs.txt | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/registry/docs/conf.py b/packages/registry/docs/conf.py index fa39be8168..a3230a6029 100644 --- a/packages/registry/docs/conf.py +++ b/packages/registry/docs/conf.py @@ -60,6 +60,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx_copybutton", + "sphinx_togglebutton", # Toggle admonitions in @plone/registry "sphinxext.opengraph", ] diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md index 47c9f390b0..df7d556e5e 100644 --- a/packages/registry/docs/how-to-guides/register-routes.md +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -10,7 +10,7 @@ myst: # Register new routes ````{admonition} Warning! This feature is experimental and only applies to registering routes for React Router 7 applications. Click to accept the risks and read details. -:class: warning +:class: warning, toggle The `config.registerRoute` method adds a route to the configuration registry. The `@plone/react-router` helper loads the route and configures it in a React Router 7 app. diff --git a/requirements-docs.txt b/requirements-docs.txt index 3dad3b11f9..b2ed6d6401 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -5,6 +5,7 @@ plone-sphinx-theme sphinx-autobuild sphinx-copybutton sphinx-examples +sphinx-togglebutton sphinxcontrib-video sphinxcontrib-youtube sphinxext-opengraph From 5e66e4a7bb55d869fc3df9ceb88ccb8de38f9ed4 Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Tue, 21 Jan 2025 22:48:48 +0100 Subject: [PATCH 07/10] Amend the docs so they are more agnostic and @plone/registry oriented. --- .../registry/docs/how-to-guides/register-routes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md index df7d556e5e..67f286ac27 100644 --- a/packages/registry/docs/how-to-guides/register-routes.md +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -9,13 +9,9 @@ myst: # Register new routes -````{admonition} Warning! This feature is experimental and only applies to registering routes for React Router 7 applications. Click to accept the risks and read details. -:class: warning, toggle - The `config.registerRoute` method adds a route to the configuration registry. -The `@plone/react-router` helper loads the route and configures it in a React Router 7 app. It saves the routes in the `config.routes` key in the configuration object. -You should provide one route at a time in the following structure. +You should provide one route at a time and must have the following shape: ```ts type ReactRouterRouteEntry = { @@ -34,7 +30,12 @@ type ReactRouterRouteEntry = { The `type`, `path`, and `file` are mandatory. The `type` key specifies the route type to create, specifically one of `route`, `index`, `layout`, or `prefix`. The type `route` can contain nested routes. + +```{info} +The routes registered with this method are intended to be React Router 7 compliant routes. +They are meant to be loaded via a helper provided by `@plone/react-router` in an existing React Router 7 app. Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes. +``` Register a route as shown in the following example. @@ -51,4 +52,3 @@ config.registerRoute({ ``` You must set the module's full path name of the registered route component to make `@plone/registry` correctly address it. -```` From aa20c76c0354a5f7feb05faf00a88474677199ba Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 21 Jan 2025 23:33:37 -0800 Subject: [PATCH 08/10] Remove now unnecessary requirement --- requirements-docs.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements-docs.txt b/requirements-docs.txt index b2ed6d6401..3dad3b11f9 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -5,7 +5,6 @@ plone-sphinx-theme sphinx-autobuild sphinx-copybutton sphinx-examples -sphinx-togglebutton sphinxcontrib-video sphinxcontrib-youtube sphinxext-opengraph From f34456a23aa02f3655861b0dc1d876b77c7a0616 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 21 Jan 2025 23:33:58 -0800 Subject: [PATCH 09/10] Remove now unnecessary configuration --- packages/registry/docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/registry/docs/conf.py b/packages/registry/docs/conf.py index a3230a6029..fa39be8168 100644 --- a/packages/registry/docs/conf.py +++ b/packages/registry/docs/conf.py @@ -60,7 +60,6 @@ "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx_copybutton", - "sphinx_togglebutton", # Toggle admonitions in @plone/registry "sphinxext.opengraph", ] From cd4dbfe452b769a47b50b8e4a563a33def96812b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Wed, 22 Jan 2025 11:52:25 +0100 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Steve Piercy --- packages/registry/docs/how-to-guides/register-routes.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md index 67f286ac27..41b79656c0 100644 --- a/packages/registry/docs/how-to-guides/register-routes.md +++ b/packages/registry/docs/how-to-guides/register-routes.md @@ -11,7 +11,8 @@ myst: The `config.registerRoute` method adds a route to the configuration registry. It saves the routes in the `config.routes` key in the configuration object. -You should provide one route at a time and must have the following shape: +You should provide one route at a time. +Each route must have the following data shape. ```ts type ReactRouterRouteEntry = { @@ -32,8 +33,8 @@ The `type` key specifies the route type to create, specifically one of `route`, The type `route` can contain nested routes. ```{info} -The routes registered with this method are intended to be React Router 7 compliant routes. -They are meant to be loaded via a helper provided by `@plone/react-router` in an existing React Router 7 app. +The routes registered with this method must be compliant with React Router 7 routes. +They are loaded by a helper provided by `@plone/react-router` in an existing React Router 7 app. Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes. ```