Frontend Library
You will make use of the Visual Editing Frontend Library available via NPM to ensure communication between your website’s HTML elements and the Directus visual editor module. This is done through data attributes and helper functions built into the library and imported into your website.
npm install @directus/visual-editing
API
The visual editing library consists of a few imported methods, only one of which is required to make the basic functionality work.
| Method | Description | Options |
|---|---|---|
apply() | Connects each data-directus attribute to your Directus instance. This is required. | directusUrl, elements, customClass, onSaved |
setAttr() | Helper function for dynamically generating data-directus attributes. | collection, item, fields, mode |
remove() | Removes all elements. | |
disable() | Temporarily disable all elements. Re-enable those elements with returned enable() function const { enable } = disable();. |
Since this is a client-side library, be sure to run its methods only in the client environment and not on the server.
Configuring Attributes
The association between individual website elements and Directus collections and items is made through data-directus attributes rendered within the HTML of your website.
The preferred method for generating your data-directus attributes is by using the included setAttr helper method in order to render these attributes dynamically.
For example when using setAttr in Vue:
<template>
<h1 :data-directus="setAttr({ collection: 'posts', item: post.id, fields: 'title',
mode: 'popover' })">
{{ post.title }}
</h1>
</template>
The generated attribute will be:
<h1 data-directus="collection:posts;item:12;fields:title;mode:popover">
I Love Visual Editing
</h1>
fields property in the setAttr function can also accept an array of strings, which will render a comma separated list like: data-directus="collection:posts;item:12;fields:title,subtitle,slug"| Option | Type | Description |
|---|---|---|
collection | string | Name of the relevant collection. This is required. |
item | string, number | Primary key of the item. This is required. |
fields | string, string[] | The specific fields to show when editing. Optional, otherwise all fields will be shown. |
mode | 'drawer', 'modal', 'popover' | Determines how the edit field(s) should be rendered. Optional, but defaults to 'drawer' |
It is recommended that you conditionally render sensitive
data-directus attributes only when your webpage renders within the Directus visual editor in order to avoid leaking this data publicly. There are a number of ways to achieve this. For example you might develop your website to only render sensitive attributes in the presence of a certain query string included in your visual editor URL settings, for example
?visual-editing=true&token=123.Connecting to Directus
Once all your data-directus attributes have been configured, you need to call the apply() method on the page. This method will establish the connection to Directus and make your editable elements interactive within the visual editor module. This must be done only after all the relevant elements on the page have fully mounted or rendered with their generated attributes.
apply({ directusUrl: 'http://localhost:8000' });
| Option | Type | Description |
|---|---|---|
directusUrl | string | URL of your Directus instance. This is required. |
elements | HTMLElement, HTMLElement[] | Could have one or more elements. If the elements themselves don’t contain a data-directus attribute, their children will be selected. Optionally, otherwise will be applied to all elements on page. |
customClass | string[] | Adds a class to overlay elements to enable custom styles. Optional. |
onSaved | (data) => void | Callback function called after the fields are saved in Directus. Optional, otherwise current page will be reloaded using window.location.reload(). |
The apply() method also returns the remove, enable and disable methods. These can then be used on the selected elements in question. Make sure to await them.
const { disable, enable, remove } = await apply({ directusUrl });
Once you specify an elements property, the customClass and onSaved options cannot be overridden afterwards. You can use the elements property to scope a section of your page and apply different options than you might have applied with a previous apply call that already included those elements. The returned object can also be used to disable, enable, or remove these scoped elements separately from the other elements. To customize scoped elements see the customization page.
const scopedElements = document.querySelector('.header');
const { disable, enable, remove } = await apply({
directusUrl,
elements: scopedElements,
customClass: 'my-scoped-elements',
onSaved: ({ collection, item, payload }) => refreshData(),
});
The optional onSaved callback function of the apply() method provides an object as a parameter which properties may be useful.
| Property | Type | Description |
|---|---|---|
collection | string | Name of the relevant collection. |
item | string, number | Primary key of the item. |
payload | Record<string, any> | The changed values. |
It is recommended to call the global
remove() method on client-side navigation to avoid unnecessarily bloating the underlying store.If you have CSP configured, be sure to make your site available for use inside an iFrame in Directus. If you’re unsure where your CSP is defined, check your web server configuration files, your site’s build configuration, or your hosting platform’s security settings.
Usage in Non-JS Environments
Given this library is built as a Node package, environments that can’t take advantage of NPM will need to take a slightly different approach to including the functionality in their websites.
This can then be included in your website like as follows:
<script src="path-to/visual-editing.js" type="text/javascript"></script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function () {
DirectusVisualEditing.apply({ directusUrl: 'http://localhost:8000' });
});
</script>