Add "examples" directory for example frontends (#73)

* add examples directory with nextjs example frontend

* update readme of example and volto hydra

* update pnpm workspace & import of hydrajs

* fix pnpm-lock.yaml

* CHANGE DIRECTORY NAME & update makefile and package.json

* update readme

---------

Co-authored-by: me@jeffersonbledsoe.com <me@jeffersonbledsoe.com>

Makefile

@@ -117,3 +117,13 @@ acceptance-test: ## Start Cypress in interactive mode
 .PHONY: ci-acceptance-test
 ci-acceptance-test: ## Run cypress tests in headless mode for CI
 	pnpm --filter @plone/volto exec cypress run --config-file $(CURRENT_DIR)/cypress.config.js --config specPattern=$(CURRENT_DIR)'/cypress/tests/**/*.{js,jsx,ts,tsx}'
+
+## Examples
+.PHONY: example-nextjs-admin
+example-nextjs-admin: ## Starts Volto, allowing reloading of the add-on during development
+	RAZZLE_DEFAULT_IFRAME_URL=http://localhost:3002 pnpm start
+
+## Examples
+.PHONY: example-nextjs-frontend
+example-nextjs-frontend: ## Starts nextjs example frontend
+	pnpm example:nextjs

README.md

@@ -15,7 +15,7 @@ It's Volto without having to learn any Volto.
 
 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:
+Available example frontends (go to `examples` directory for source code):
 - https://hydra-blogsite-nextjs.vercel.app
 
 Note: not everything works yet. Follow the progress on the [Hydra Roadmap](https://github.com/orgs/collective/projects/3/views/4)
@@ -74,6 +74,20 @@ To test against a local hydra instance
     make backend-docker-start
     ```
   ***Note :***  This will also set `CORS_ALLOW_ORIGIN` to `'*'`, 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 and then let us know by creating a ticket and we will advertise your frontend
@@ -255,7 +269,7 @@ function handleEditChange(updatedData) {
 }
 
 // Set up the onEditChange listener
-onEditChange(initialData, handleEditChange);
+onEditChange(handleEditChange);
 ```
 
 ### Level 4: Enable Managing Blocks directly on your frontend

examples/hydra-nextjs/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

examples/hydra-nextjs/.gitignore

@@ -0,0 +1,130 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*

examples/hydra-nextjs/README.md

@@ -0,0 +1,137 @@
+# Next.js Example frontend for Volto Hydra
+
+This provides instructions on integrating your frontend built with Next.js into the Volto Hydra decoupled editor for headless Plone.
+Follow these steps to set up and run your frontend with Volto Hydra.
+
+***Note:*** This example frontend uses already deployed [Volto Hydra Demo](https://hydra.pretagov.com/).
+You can also set up your own local instance of Volto Hydra by following [this guide](https://github.com/collective/volto-hydra/?tab=readme-ov-file#test-your-frontend).
+
+### Running the application
+
+Start the development server:
+```bash
+npm run dev
+```
+
+### Deploying the frontend
+
+We are using vercel to deploy our frontend which will automatically set up CI/CD as you go.
+For more information on deployment, Follow [vercel guide](https://vercel.com/docs/getting-started-with-vercel).
+
+### Editing your content using Volto Hydra
+
+Once your frontend is deployed you can visit [the Demo site](https://hydra.pretagov.com/) or the local instance of Volto Hydra, login with demo username & password (mentioned in login page) and paste your frontend url in the adminUI (Volto Hydra).
+
+Now, you can access private content and start editing!
+
+**Follow and star the [Volto Hydra Repo](https://github.com/collective/volto-hydra) to know about latest features you can use.**
+
+### Available Features:
+
+List of currently working features of Volto Hydra and short explanation on how they are integrated:
+
+#### Authenticating frontend to access private content
+
+When you input your frontend URL at the Volto Hydra (adminUI) it will set 2 params in your frontend URL. You can extract the `access_token` parameter directly from the URL for the `ploneClient` token option.
+
+Usage:
+```js
+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>
+  )
+}
+```
+
+#### Initiating Hydra Bridge for 2-way communication with Hydra
+
+```js
+  // In Layout.js
+  import { initBridge } from './hydra.js';
+  initBridge("https://hydra.pretagov.com");
+```
+
+#### Enabling Click on Blocks
+
+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](https://github.com/collective/volto-hydra/issues/25)) 
+and border ([TODO](https://github.com/collective/volto-hydra/issues/24)) when selecting a block.
+Without this, you can still manage blocks via the blocks navigation in the sidebar.
+
+Usage:
+
+```js
+// components/BlockList
+import React from "react";
+import SlateBlock from "@/components/SlateBlock";
+
+const BlocksList = ({ data }) => {
+  return (
+    <ul className="blog-list">
+      {data.blocks_layout.items.map((id) => {
+        if (data.blocks[id]["@type"] === "slate") {
+          const slateValue = data.blocks[id].value;
+          return (
+            <li key={id} className="blog-list-item" data-block-uid={`${id}`}>
+              <SlateBlock value={slateValue} />
+            </li>
+          );
+        } else if (data.blocks[id]["@type"] === "image") {
+          const image_url = data.blocks[id].url;
+          return (
+            <li key={id} className="blog-list-item" data-block-uid={`${id}`}>
+              <img src={image_url} alt="" width={100} height={100} />
+            </li>
+          );
+        }
+        return null;
+      })}
+    </ul>
+  );
+};
+
+export default BlocksList;
+```
+
+#### 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](https://6.docs.plone.org/volto/client/quick-start.html?highlight=data#query-or-mutation-options-factories).
+
+`onEditChange` takes following args:
+| Args         | Description |
+| :-----------:| :-------|
+| *callback*   | A function to call with the updated data when a change is detected. |
+
+Usage:
+
+```js
+  useEffect(() => {
+    onEditChange((updatedData) => {
+      if (updatedData) {
+        setValue(updatedData);
+      }
+    });
+  },[]);
+```
+

examples/hydra-nextjs/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

examples/hydra-nextjs/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;