search

collective / volto-hydra

A volto addon to let you edit content in realtime when you have many frontends written in any framework
0 stars 2 forks source link

readme

Volto Hydra (volto-hydra)

A volto addon to turn Plone Volto into a decoupled editor for headless Plone.

Why Hydra? because it lets you have many frontends (heads) written in many framework all connected to the same body (plone) while still letting you edit the content directly into your frontend.

It is a GSoC project to prove with the following goals

It's Volto without having to learn any Volto.

Want to try the editor?

You can try out the editing experience now by logging into https://hydra.pretagov.com and selecting one of the available preset frontend urls from dropdown or you can paste the url of frontend deployed for the demo site.

Available example frontends (go to examples directory for source code):

Note: not everything works yet. Follow the progress on the Hydra Roadmap or the Hydra README

Want to help? Make your own frontend

You can build your own frontend in your favourite frontend framework, deploy it and then submit a ticket to have it listed as one of the test frontends.

Choose Your Framework

TODO: link to more documentation on creating a frontend using @plone/client

Test your frontend

You can either run a local hydra instance (see below) or connect it directly to https://hydra.pretagov.com/++api++

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

3. Start the Plone Backend

Using the example frontend

You can use one of the example frontends available at ./examples directory.

Deploy your frontend

Use netlify or similar and make your frontend public and then let us know by creating a ticket and we will advertise your frontend on https://hydra.pretagov.com for others to test.

But be sure to subscribe to the project so you can keep your frontend updated with changes to the hydra api as more capabilities are added. If there are bugs lets us know.

Make your frontend editable

As an integrator you have a choice on how nice you want the editor user experience to be. Each level requires more work to integrate but makes editing easier.

As the GSoC projects progresses more of these levels will be enabled so you can try them out. see Hydra GSoC project progresses

Managing multiple frontends

To switch to a different frontend in the Volto Hydra AdminUI, follow these steps:

  1. Navigate to Personal Tools:

    • In the bottom of the toolbar on the left, click on "Personal Tools".

  2. Go to Preferences:

    • From the Personal Tools menu, select "Preferences".

  3. Change Frontend URL:

    • In the Preferences section, you will find an option to select the Frontend URL.
    • You can either select a frontend URL from the available options or type in a custom URL:
      • To select a URL from the options, simply choose from the dropdown menu.
      • To enter a custom URL, click on the toggle to make the input field appear and type in your desired URL.

This allows you to switch seamlessly between different frontend URLs for testing or editing purposes.

Note: Make sure the frontend URL is correct and accessible to avoid any CORS issues.

Level 1: Show changes after save

This is the most basic form of integration. You can

To do this you will include the hydra iframe bridge which creates a two way link between the hydra editor and your frontend.

Authenticate frontend to access private content

Example Usage:

// nextjs 14 using ploneClient
import ploneClient from "@plone/client";
import { useQuery } from "@tanstack/react-query";

export default function Blog({ params }) {
  // Extract token directly from the URL
  const url = new URL(window.location.href);
  const token = url.searchParams.get("access_token");

  const client = ploneClient.initialize({
    apiPath: "http://localhost:8080/Plone/", // Plone backend
    token: token,
  });

  const { getContentQuery } = client;
  const { data, isLoading } = useQuery(getContentQuery({ path: '/blogs' }));

  if (isLoading) {
    return <div>Loading...</div>;
  }
  return (
    <div> {data.title}</div>
  )
}

How to initialise the bridge.

Note: You can also pass an options object while initializing the bridge. Currently you can pass a List of allowed blocks (by default image & text blocks are allowed if not specified). E.g. :

  // In Layout.js or App.js
  import { initBridge } from './hydra.js';
  const bridge = initBridge("https://hydra.pretagov.com", {allowedBlocks: ['slate', 'image', 'video']});

Asynchronously Load the Bridge

Since the script has a considerable size, it’s recommended to load the bridge only when necessary, such as in edit mode. To load the bridge asynchronously, add a function that checks if the bridge is already present. If it isn't, the function will load it and then call a callback function. This ensures the bridge is loaded only when needed.

function loadBridge(callback) {
  const existingScript = document.getElementById("hydraBridge");
  if (!existingScript) {
    const script = document.createElement("script");
    script.src = "./hydra.js";
    script.id = "hydraBridge";
    document.body.appendChild(script);
    script.onload = () => {
      callback();
    };
  } else {
    callback();
  }
}

// Initialize the bridge only inside the admin UI
if (window.location.search.includes('_edit=true')) {
  loadBridge(() => {
    const { initBridge } = window;
    initBridge('https://hydra.pretagov.com');
  });
}

Preventing reloads (TODO)

If you wish to make the editing experience smoother you can register for onSave and onRoute callbacks to prevent reloads of the frontend

Level 2: Click to select blocks on your frontend

You will add data attributes to your rendered block html so hydra knows where they are on the page and it will automatically handle click events and show a quanta toolbar (TODO) and border (TODO) when selecting a block. Without this, you can still manage blocks via the blocks navigation in the sidebar.

It will allow you to naviate to the parent block (TODO) but not add, remove or move blocks unless live updates (level 3) is enabled.

Add the data-block-uid={<<BLOCK_UID>>} attribute to your outer most container of the rendered block html. The data-block-uid requires the block's UID, which you need to provide in the outermost container of the block.

For example, if you are using ploneClient to fetch data, it will be data.blocks_layout.items[x]. Now, Click on your blocks in iframe and the sidebar will show its settings.

Usage:

// Vanilla JS example to render Blocks 

// Function to create the block list
function createBlockList(data) {
  const blockList = document.createElement('ul');

  data.blocks_layout.items.forEach(id => {
    if (data.blocks[id]["@type"] === "slate") {
      const slateValue = data.blocks[id].value;
      const listItem = document.createElement('li');
      listItem.className = 'blog-list-item';
      listItem.setAttribute('data-block-uid', id); // Set Attribute to enable Clicking on Blocks

      const pre = document.createElement('pre');
      pre.className = 'pre-block';
      pre.textContent = JSON.stringify(slateValue, null, 2);

      listItem.appendChild(pre);
      blockList.appendChild(listItem);
    }
  });

  document.body.appendChild(blockList);
}

// Call the function to render the blocks
createBlockList(data);

Level 3: Enable Realtime changes while editing

You will need to subscribe to an onEditChange event that will call the callback with the updated data.

The onEditChange method listens for changes in the Hydra and triggers a callback with updated data. The 'data' object follows the same format as you get from the ploneClient.

onEditChange takes following args: Args Description
callback A function to call with the updated data when a change is detected.

Usage:

// the initial data (from ploneClient)
const initialData = data;

// Define the callback function
function handleEditChange(updatedData) {
  console.log('Updated data:', updatedData);
}

// Set up the onEditChange listener
//After initiating the bridge you can use its onEditChange method
const bridge = initBridge('https://hydra.pretagov.com');
bridge.onEditChange(handleEditChange);

Level 4: Enable Managing Blocks directly on your frontend

If you completed level 2 & 3 (made blocks clickable and enabled live updates) then the editor will automatically gain the management of blocks on the frontend using the quanta toolbar.

With Quanta toobar, you can use following features:

You will still need to edit the blocks themselves via the sidebar.

Level 5: Enable Editing blocks text and images inplace (TODO)

If you want to make the editing experience the most intuitive, you can enable real-time inplace editing, where an editor can change check, links or media by typing or clicking directly on your frontend instead of via fields on the sidebar.

Inline text editing (TODO)

You will add data attributes to where a blocks text is editable and where text formatting and features are locationed (like links) and also subscribe to onBlockFieldChanged events. This will enable handling fine grained changes to text being edited such as turning text bold or creating a link. Hydra will notice where you have indicated a block field can be clicked on and will automatically make it inplace editable handling typing, shortcuts (slash (TODO), enter (TODO) and bullets etc) and selection (TODO](https://github.com/collective/volto-hydra/issues/31))for you.

Inline media uploading (TODO)

TODO

Inline link editing (TODO)

TODO