Visual editing
On a preview of your site, editors can point at a title, an image or a paragraph and open that exact field in the studio. You add one attribute to the elements that show content, and one script to your preview pages.
Mark the elements#
editAttr from @galerne/overlay builds the attribute value from the document and the field path:
npm i @galerne/overlayimport { editAttr } from '@galerne/overlay'
export function PostHeader({ post, branch }) {
const at = (path: string) => editAttr(post, path, { project: 'acme', branch })
return (
<header>
<h1 data-galerne-edit={at('title')}>{post.title}</h1>
<img data-galerne-edit={at('cover')} src={post.cover.url} alt={post.cover.alt} />
<p data-galerne-edit={at('seo.description')}>{post.seo.description}</p>
</header>
)
}editAttr(doc, path, options) takes the document (it needs _id), a field path in the same form as patch_doc (title, seo.description, content[k3f9].heading), and { project, branch }. The branch defaults to main. The value is project:branch:id:path, each part URL-encoded, so you can also write it by hand.
Load the overlay#
Add the script to preview deployments only:
<script src="https://api.galerne.cloud/overlay.js" data-project="acme" defer></script>| Attribute | What it does |
|---|---|
data-project | Project used when an element's attribute leaves the project empty |
data-studio | Studio URL, when you run your own. Default: the Galerne studio |
The script needs no token and reads no content. It only uses the attributes on the page.
What editors see#
Hovering a marked element draws an outline with an edit link. The link, or Alt+click on the element, opens the document in the studio in a new tab, scrolled to that field, on the right branch. A preview that queries a branch (see query API) and passes the same branch to editAttr sends editors to that branch.
Keep the script off your production pages: there, the attribute values do nothing and cost a few bytes.
Inside the studio#
With a preview URL, the document editor shows the site next to the fields. In that pane, the edit link and Alt+click focus the field in the editor instead of opening a new tab. Sites built with the Next.js kit also refresh after each save and send plain clicks on marked elements: galerne.LivePreview loads the overlay and does both, and galerne.editable() returns the attributes with the right project and branch.