flow diagram

README.md

@@ -8,11 +8,11 @@ It should not be used in production.
 
 Why does it matter?
 - If you **want a Headless CMS**: 
- - You get the best editor UX for a headless CMS with inplace editing like Volto with the bonus of being open source
-- If you **are new to Volto**:
- - You get a lower learning curve if you already know a frontend framework 
+ - You get the best editor UX for a headless CMS with inplace visual editing with the bonus of being open source
+- If you **don't know Volto**:
+ - You get a lower learning curve if you already know a frontend framework, or just use one of the included starter frontends.  
 - If you **already use Volto**:
- - you can develop frontends with faster load times and less risky Volto upgrades with no downgrade in editor UX
+ - you can develop frontends with faster load times, higher security and less risky Volto upgrades, with no downgrade in editor UX
 - If you are **already using Plone Headless**:
  - this will improve the editor UX with just a few lines of code
 
@@ -24,6 +24,55 @@ What is Quanta?
 - [Quanta](https://github.com/plone/volto/issues/4332) is an iteration on the design system and editing UI that Volto impliments
 - Hydra is using Volto as it's base and where parts are reimplimented it is being done closer to the Quanta design.
 
+## How Hydra works
+
+Instead of combining editing and rendering into one framework and codebase, these are seperated and during editing
+a two way communication channel is opened across an iframe so that the editing UI is no longer
+part of the frontend code. Instead a small js file called ```hydra.js``` is included in your frontend during editing
+that handles the iframe bridge communication to hydra which is running in the same browser window. Hydra.js also 
+handles small parts of UI that need to be displayed on the frontend during editing.
+
+You could think of it as spliting Volto into two parts, Rendering and CMSUI/AdminUI while keeping the same UI and then 
+making the Rendering part easily replacable with other implementations.
+
+```
+ Browser RestAPI Server 
+
+
+ ┌──────────────┐ ┌─────────────┐ 
+ │ │ │ │ 
+ Anon/Editing │ Volto │◄─────────────────────►│ Plone │ 
+ │ │ │ │ 
+ └──────────────┘ └─────────────┘ 
+
+
+─────────────────────────────────────────────────────────────────────────────────────
+
+
+ │ ┌──────────────┐ ┌─────────────┐ 
+ │ │ │ │ │ 
+ │ │ Frontend │◄──────────────────────┤ Plone │ 
+ │ │ │ │ │ 
+ │ └──hydra.js────┘ └─────────────┘ 
+ │ ▲ ▲ 
+ Editing UI │ iFrame Bridge │ 
+ │ ▼ │ 
+ │ ┌──────────────┐ │ 
+ │ │ │ │ 
+ │ │ Hydra │◄─────────────────────────┘ 
+ │ │ │ 
+ │ └──────────────┘ 
+
+
+ ┌──────────────┐ ┌─────────────┐ 
+ │ │ │ │ 
+ Anon │ Frontend │◄──────────────────────┤ Plone │ 
+ │ │ │ │ 
+ └──────────────┘ └─────────────┘ 
+
+```
+
+
 
 ## Want to try the editor?
 
@@ -33,18 +82,20 @@ Go to user preferences in the bottom left to select one of the available preset
 Available example frontends (go to `examples` directory for source code):
 - https://hydra-blogsite-nextjs.vercel.app
 
+Note: These are simple test frontends made with minimal effort and don't include support for all the navigation and block of volto yet.
+
 ## Building a Frontend for Headless Plone
 
 ### Choose Your Framework
 
-- You can use any frontend framework (e.g., Next.js, Nuxt.js, Astro etc or plain js).
+- You can use any frontend framework (e.g., Next.js/React, Nuxt.js/Vue, Astro etc or plain js).
  - Static site generators like Gatsby and server side rendering like Flask could work but without realtime updates
  and inline editing. Your frontend would lack browser based code to render content dynamically but in the future
  it could be possible for these edits to go via the backend making near realtime editing possible.
 - Fetch content from the Plone backend using the [@plone/client](https://github.com/plone/volto/tree/main/packages/client) 
- library or the simple Fetch API. You should be able to use [Plone GraphQL api](https://2022.training.plone.org/gatsby/data.html) also.
+ library or directly use [Plone restAPI](https://plonerestapi.readthedocs.io/en/latest/). You should be able to use [Plone GraphQL api](https://2022.training.plone.org/gatsby/data.html) also.
 - You can start small with just simple navigation and just a few basic blocks and work up to supporting more kinds of blocks as you need them.
-
+- There is a [set of example frontends](https://github.com/collective/volto-hydra/tree/main/examples) in different frameworks.
 
 TODO: link to more documentation on creating a frontend using @plone/client
 
@@ -55,61 +106,14 @@ You can either run a local hydra instance (see below) or connect it directly to
 If you are testing against https://hydra.pretagov.com/++api++ you will need to ensure you are running on https locally via a proxy to ensure there
 are no CORS errors
 
-To test against a local hydra instance
-
-**1. Clone the Volto-Hydra Repository**
-
-- Clone the Volto-Hydra repository from GitHub:
-
- ```bash
- git clone https://github.com/collective/volto-hydra.git
- cd volto-hydra
- ```
-**2. Start Volto-Hydra**
-
-- Run the following command to start the Volto-Hydra site:
- ```bash
- make start
- ```
-- You can also set your preset frontend URLs with environment variables, making them available in the admin UI. This allows you to switch between them seamlessly:
- ```bash
- RAZZLE_DEFAULT_IFRAME_URL=http://localhost:3002,https://hydra-blogsite-nextjs.vercel.app pnpm start
- ```
- You can find `.env.example` at root directory of the project.
-- Ensure Volto is running on port 3000.
-
-**3. Start the Plone Backend**
-
-- You can start the Plone backend using Docker images:
- ```bash
- make backend-docker-start
- ```
- ***Note :*** This will also set [`CORS_ALLOW_ORIGIN` to `'*'`](https://6.docs.plone.org/install/containers/images/backend.html?highlight=cors#cors-variables), so there are no cors error.
-
-### Using the example frontend
-
-You can use one of the example frontends available at `./examples` directory.
-
-- Running Volto Hydra:
- ```bash
- make example-nextjs-admin
- ```
-- Running example frontend:
- ```bash
- make example-nextjs-frontend
- ```
-
 ### Deploy your frontend
 
-Use netlify or similar and make your frontend public.
+Use netlify or similar and make your frontend publicly accessible.
 Ensure you have correctly set the CORS headers to allow access by the hydra editor. How to do this will depend
 on how you host your frontend.
 
 You can then log into https://hydra.pretagov.com and set the frontend to edit in the user settings.
 
-If want others to try editing using your demo frontend
-then let us know by [creating a ticket](https://github.com/collective/volto-hydra/issues)
-
 
 ## Make your Frontend editable
 
@@ -393,6 +397,57 @@ e.g.
 
 You have now made your frontend fully editable.
 
+If deployed your frontend and want others to try editing it
+then let us know by [creating a ticket](https://github.com/collective/volto-hydra/issues)
+
+
+## Local Development
+
+To test against a local hydra instance
+
+**1. Clone the Volto-Hydra Repository**
+
+- Clone the Volto-Hydra repository from GitHub:
+
+ ```bash
+ git clone https://github.com/collective/volto-hydra.git
+ cd volto-hydra
+ ```
+**2. Start Volto-Hydra**
+
+- Run the following command to start the Volto-Hydra site:
+ ```bash
+ make start
+ ```
+- You can also set your preset frontend URLs with environment variables, making them available in the admin UI. This allows you to switch between them seamlessly:
+ ```bash
+ RAZZLE_DEFAULT_IFRAME_URL=http://localhost:3002,https://hydra-blogsite-nextjs.vercel.app pnpm start
+ ```
+ You can find `.env.example` at root directory of the project.
+- Ensure Volto is running on port 3000.
+
+**3. Start the Plone Backend**
+
+- You can start the Plone backend using Docker images:
+ ```bash
+ make backend-docker-start
+ ```
+ ***Note :*** This will also set [`CORS_ALLOW_ORIGIN` to `'*'`](https://6.docs.plone.org/install/containers/images/backend.html?highlight=cors#cors-variables), so there are no cors error.
+
+### Using the example frontend
+
+You can use one of the example frontends available at `./examples` directory.
+
+- Running Volto Hydra:
+ ```bash
+ make example-nextjs-admin
+ ```
+- Running example frontend:
+ ```bash
+ make example-nextjs-frontend
+ ```
+
+
 ## Code Examples
 
 There is a [set of example frontends](https://github.com/collective/volto-hydra/tree/main/examples) in different frameworks