Skip to content

Latest commit

 

History

History
199 lines (109 loc) · 14.1 KB

README.md

File metadata and controls

199 lines (109 loc) · 14.1 KB
Raw

Flexible Editor for Directus

A rich text editor (WYSIWYG) with JSON output that allows the integration of M2A relations to make it extremely flexible.

Under the hood, it integrates the Tiptap editor as an extension to the Directus app and uses an optional many-to-any (M2A) field to place and link relation nodes in the editor. This combination makes Flexible Editor a truly rich editor.

Features

🚀 Composable Blocks: Compose blocks as you would with the built-in builder interface and insert these referenced items directly into Flexible Editor as a “Relation Block”.

Show example

🚀 Inline Blocks: Use relation blocks inline by inserting them directly into the text flow as “Relation Inline Blocks”.

Show example

🚀 Internal Linking: Create your own custom link collection(s) and apply it as “Relation Mark” to selected text within Flexible Editor.

Show example

🚀 Single Line Mode: Turn Flexible Editor into an inline editor that only allows marks and inline blocks. This way, you can have a simple text input field that could contain a link or any other mark (including Relation Marks and Relation Inline Blocks).

Show example

🚀 Adjustable Toolbar: Choose between a static, sticky or floating toolbar.

Show example

🚀 Render Interactive Components: On your front-end, you can render any node (especially “Relation Nodes”) with your own custom component using Flexible Editor Content.

Installation

Basic Usage

In your Directus app simply click the Create Field button and select Flexible Editor.

Show example

Interface Options

Navigate to the interface tab to adjust the settings.

Option Description
M2A Reference Field
  • Relation Blocks
  • Relation Inline Blocks
  • Relation Marks
 Described in detail below (Usage with relation nodes)
Placeholder Display a placeholder text when empty
Tools Select the editor tools you want to use
Toolbar Static … The toolbar appears at the top of the editor
Sticky … The toolbar stays at the top of the viewport as you scroll
Floating … The toolbar floats above the current cursor position
Formats Button Appearance Display the active format name instead of just an icon
Input Mode Multi-line text … Default behavior
Single-line text … Turns into an inline editor that only allows marks and inline blocks
Editor Height Grow till Overflow … The height grows with its content as long as it remains in the viewport
Grow … The height grows with its content
Fixed … The editor has a fixed height
Font Font that is used in the editor
Spellcheck Enable spell checking in the editor

Display

Navigate to the Display tab and select Flexible Editor to display the editor content as plain text in the Directus app.

Usage with relation nodes

You can insert items from your Directus collections into Flexible Editor. This is optional but gives you extreme flexibility when creating rich content. To do this, you need to add a many-to-any (M2A) field, that the editor field can connect to. For Flexible Editor to work in this way, you must create the junction collection before adding a M2A field.

  1. Create a new (junction) collection and give it a name like xxxx_editor_nodes and set the Type of the Primary Key to Generate UUID. Finish the setup to create the collection.

    Show example

  2. Open the data model of the collection to which you want to add Flexible Editor, click Create Field in Advanced Mode, and select Many to Any Relationship.

    Show example

  3. Enter a name for the field, such as editor_nodes and uncheck Auto Fill on the Relationship tab, so that you can manually select the junction collection you created earlier (such as xxxx_editor_nodes). Select the Related Collections you want to integrate into your Flexible Editor field. You don’t need to set a sort field, but you do want to set the Relational Triggers to cascade when an item is deleted or deselected.

    Show example

  4. On the Field tab, set the field to Hidden on Detail because we are managing the M2A items through Flexible Editor. Therefore, no interface is required for the M2A field.

    Show example

    Note: If you use Flexible Editor inside groups – especially inside nested groups –, make sure you put your editor_nodes field in the same group as your Flexible Editor field, otherwise they may lose their connection!

  5. Now that you have created your M2A field, open the interface settings for your Flexible Editor field and connect to the M2A field by selecting it in the M2A Reference Field.

    Show example

    Once you have selected a valid M2A field, three additional fields appear:

    • Relation Block … A block, you can insert in Flexible Editor, that references an item of a collection you can compose yourself.

      Use Cases: gallery, video, related content, complex content structure, …

    • Relation Inline Block … Same as “Relation Block”, but appears inside text.

      Use Cases: link to referenced item using item data for link text, inline image/icon, placeholders/variables for templates (e.g. email), …

    • Relation Mark … A mark, you can apply to selected text, that references an item of a collection you can compose yourself.

      Use Cases: classic link (compose your own), link to referenced item, button that opens a modal/overlay/video, …

    All three fields have the same options, which correspond to the collections you selected in your M2A field. Here you can select which collection should appear as a Relation Block, Relation Inline Block or Relation Mark within Flexible Editor.

  6. Set the Item Duplication Fields for your junction collection (xxxx_editor_nodes) in the data model settings. This is required for copy & paste or drag & drop to work.

    Show example

    Tip: If you set up Flexible Editor in the same way for different collections, you can copy and paste the duplication settings via Copy Raw Value from the field menu — by clicking on the “Item Duplication Fields” label.

Things to keep in mind

You cannot use the same M2A junction collection for multiple collections (where you use Flexible Editor). This would only work with an any-to-any relationship, which Directus doesn't support at the time of writing.

You should not set Item Duplication Fields for nested Flexible Editor fields as they are managed by their own junction collections.

If you want to duplicate nested M2A items (e.g. a Related Content collection, that references several other collection items), you want to duplicate only the IDs (in the junction collection) without copying the whole item!

Duplication currently only works within the same editor field or between Flexible Editor fields, that use the same M2A Reference Field. (This will be improved in future releases.)

This also means that you can use the same M2A Reference Field for multiple Flexible Editor fields, although this is not recommended as this will change in future releases.

The current implementation of duplicating relation nodes (M2A items) does not cover all use cases, but will be improved in future releases. If the duplication fails, you should get a warning.

Tutorial: Relation node with existing items

selecting-related-items.mp4

(Video tutorial about relation node with existing items)

Custom Editor Styles

To override the CSS of the editor content, you can add Custom CSS to your Project Settings in Directus. You can use the .flexible-editor & .flexible-editor-wrapper classes for the editor itself as well as .relation-block, .relation-inline-block and .relation-mark classes for the relation nodes.

Rendering in the front-end

To render the JSON content generated by Flexible Editor you can follow the official Tiptap guide or you can use the Flexible Editor Content tools included in this package (recommended).

Rendering with interactive components

If you want to render your JSON content with interactive components, especially when using relation nodes, follow the Flexible Editor Content guide.

Rendering plain HTML or plain text

Tiptap provides official functions to generateText() or generateHTML() from the JSON output. Note that as of this writing, there are different versions of generateHTML(): one for client-side rendering (import { generateHTML } from "@tiptap/core") and one for server-side rendering (import { generateHTML } from "@tiptap/html")!

Contribution

Contributions are welcome. Be sure to open an issue for bugs or start a discussion for feature requests, before you start writing code!