otter-editor

v1.0.18

Published

10 months ago

Content editor with declaratively defined content blocks.

Downloads

0High
0Medium
0Low

bhallstein

Otter, an embeddable content editor

Otter is perhaps the ~~furriest~~ easiest way in the universe to embed a content editor in your react/preact application.

An Otter editor 👆

Create a full-blown content editor by simply ~~splashing about in a river~~ defining some content models 🏔
Simple and ~~estuarine~~ declarative block-’n-field syntax for your models 🌿
Generates post data in an ~adorable~ accessible JSON format 💧
Delivered as a React component that’s really ~~into fish~~ easy to use 🐟

🐟 🐟 🐟
npm i -S otter-editor --legacy-peer-deps
🐟 🐟 🐟
<Otter.Editor blocks={blocks}
              initial_data={data} />
🐟 🐟 🐟

<Otter.Editor>

The <Otter.Editor /> element renders the editor.

<Otter.Editor blocks={blocks}
              initial_data={data} />

Blocks

The Otter editor is based on content models that you define. These block definitions are succinct and declarative. Within a block, there will be one or more Fields. This system lets you rapidly arrange fields into blocks to create rich content editors.

An example Block of type PageHeader might contain the Fields: title, subtitle, and background_image.

{
  type: 'MyBlock',
  description: 'My block',
  fields: [
    <Field>,
    <Field>,
    ...
  ],
}

Block properties

Block picker

When supplying your content blocks to Otter, (<Otter.Editor blocks={blocks} />), you can either use a simple, flat array of blocks, or group them into categories.

// Simple blocks
const blocks = [
  <Block>,
  <Block>,
  ...
]

// Grouped blocks
const blocks = {
  text: {
    name: 'Text blocks',
    blocks: [ <Block>, <Block>, ... ],
  },
  media: {
    name: 'Media blocks',
    blocks: [ <Block>, <Block>, ... ],
  },
}

If simple blocks are provided, otter renders a popover-style block picker.
If grouped blocks are provided, otter renders a popup-style, graphical block picker. This can provide a better user experience:

| Popover (simple) block picker | Popup (grouped) block picker | | :----------------------------------- | :------------------------------------ | | | |

Block tabs

Within a block, fields may be grouped into tabs. This can help you keep the user experience clean when your blocks are more complex:

// Create tabs:
// - 'Text' containing heading and subheading fields
// - 'Settings' containing align field
export const header_block = {
  type:      'Header',
  fields:    [
    { name: 'heading', ... },
    { name: 'subheading', ... },
    { name: 'align', ... },
  ]
  tabs: [
    {
      label: 'Text',
      fields: ['heading', 'subheading'],
    },
    {
      label:   'Settings',
      fields: ['align'],
    },
  ],
}

You can optionally use an icon instead of text to label your tab. When using icon tab labels, the tab icons are placed inside the header of the Block or Repeater item, next to the delete button:

export const header_block = {
  ...
  tabs: [
    {
      Icon: PencilSolid,
      fields: ['heading', 'subheading'],
    },
    {
      Icon:   Cog8ToothSolid,
      fields: ['align'],
    },
  ],
}

Fields

Each block should contain at least one field.

{
  name: 'content',
  description: 'Content',
  type: Otter.FieldTypes.TextArea,
}

Field properties

Properties on fields:

*(default_value is supported on all fields except: TextEditor, MediaPicker, NestedBlock, Repeater, Searchable.)
**(class_wrapper, class_label & class_field are supported on all fields except: Repeater, NestedBlock. See custom layout.)

type should be specified using the Otter-defined constants: type: Otter.FieldTypes.TextInput, etc. (See field types.)

With display_if you can show or hide the field based on the value of one or more of its siblings. Each DisplayRule specifies the name of the sibling and a value. You can test against more than one sibling field using an array of multiple DisplayRule objects.

// display_if example:
{
  name: 'url',
  description: 'URL',
  type: Otter.FieldTypes.TextInput,
  display_if: {
    sibling: 'is_link',
    equal_to: true,
  },
}

Beside equal_to, DisplayRule supports these rule types:

| Rule type | Value | | | :------------- | :------------------------------- | -------------------------------------------------------------------------- | | equal_to | <value> | Show the field if the sibling's value === <value> | | not_equal_to | <value> | ...if !== <value> | | matches | <string> (compiled to RegExp) | Show the field if the sibling's value is a string which matches the regex | | doesnt_match | <string> (compiled to RegExp) | ...which doesn't match the regex |

Note that using matches and doesnt_match may impact the performance of typing into the targeted sibling field, as it causes relayout to occur on input.

Field types:

The supported field types and their options are documented below.

| Type | :------------------ | TextInput | TextArea | | | TextEditor | | | | | | | | | | | NumberInput | Bool | | | | | Radios | | | | | ColorSwatchRadios | | | Select | | | NestedBlock | | | | | | | Repeater | | | | | | | Searchable | | | | | MediaPicker | | | Description | Options | Default | | | :------------------------------------------ | :-------------------------------------------------------| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Plain text input | | | | | Textarea (multi-line plain text) | | | | | mono (bool) | false | Use a monospace font | | Rich text editor | | | | | heading_levels (array) | [1, 2] | Heading types to display in the paragraph style dropdown | | bullets (bool) | true | Enable bullets | | blockquote (bool) | false | Enable blockquote | | hr (bool) | false | Enable horizontal rule | | paste_as_plain_text | false | Clear text formatting on paste | | Number input with min, max, step etc | | | | | A toggle | | | | | no_label (string) | "Yes" | Label for true option | | yes_label (string) | "No" | Label for false option | | Radio buttons | | | | | options (object) | | Radio options. Key pairs are in the form value: "Label". | | icons (object) | | Use icons to label the radios instead of labels. Format: {opt_value: IconComponent, ...} | | Color swatch radio buttons | | | | | palette (array) | | In the form [{ label: 'Row', colors: [ {value: 'text-white', output_class_or_hex: 'bg-white'} ]}]. | | Select dropdown | | | | | options (object) | | Select options. Key pairs are in the form value: "Label". | | Embed another block into this block | | | | | nested_block (string or Block object) | | The block to embed inside this block. May be either a Block object or the string name of a block defined elsewhere in the blockset. | | optional (bool) | false | If true, render a toggle that enables/disables the Nested Block | | seamless (bool) | false | If false, a subtle border + padding surrounds the blocks contents, which can aid grouping (visually). If true there is no visual indication that a nested block has been used. | | Embed an array of blocks within this block | | | | | nested_blocks (array: strings or Block objects) | | The blocks available in this Repeater. Value is an array of either Block objects or name strings of blocks defined elsewhere in the blockset. | | max (number) | No limit | Optionally limit the number of items the user can add. | | item_headers (bool) | false | If true, repeater items are rendered with a header displaying the name/description of the repeater field. Note: 'with_header' is required to use icon tabs within repeater items. | | Text input with custom search | | | | | search (function -> promise) | | A function that takes a search term as its argument, performs a search, and returns a promise. The promise should resolve to an array of search results in the form {value, display}. If the promise rejects, it should return an error message string which will be displayed to the user below the search field. | | debounce_ms (number) | 500 | Adjust search callback rate limiting. | | Select item from media library | | | (Note: you must implement a media library, Otter does not include one.) | | label (string) | "Select" | Button label. |

Testing for optional repeaters and nested blocks

When an optional block is saved, the data item has an extra boolean property, __enabled. When outputting the document, templates can check this property to see if the block should be rendered or ignored:

header.image.__enabled && <img src="header.image.src" alt="header.image.alt" />

Custom layout

By default, fields take up the full width of their container, with the field label above the field. You can customize this layout by passing classes to these field definition options: class_wrapper, class_label, class_field.

Fields are rendered in a flex container, which gives you a lot of power to customize how fields are laid out in a block.

For example, setting class_wrapper='w-1/2' would allow you to align two fields side by side horizontally. Similarly, you could use class_wrapper and class_label to place the label next to the field instead of above it.

Note that you can easily break the layout using these options. You should take particular care over how layout behaves when the viewport width changes.

For custom layout examples, see the demo.

Demo

The demo project in /demo renders a complete Otter editor, and demonsrates NestedBlock fields, Repeaters, and customisation options.

npm run demo
  # or: parcel demo/index.html

CSS and Tailwind

Otter uses Tailwind (3.0) for styling. Ideally, your application should compile Tailwind.

When using your own compiled Tailwind, your bundle must also must import Otter’s small amount of its own CSS and that of the Quill editor:

import 'otter/dist/css/quill.snow.css'
import 'otter/dist/css/otter.css'
``

If you are not compiling tailwind yourself, you can instead import everything (including a compiled copy of tailwind) from otter/dist:

```js
import 'otter/dist/css/all.css

(Note that while the all-in-one-go all.css method may be a quick way to get started, your project should ultimately take on the tailwind compilation instead of relying on Otter to do so.)

Custom CSS classes

You can customise the look and feel of the editor by passing a nested object of CSS classes to the <Editor /> custom_classes prop.

const custom_classes = {
  typography: {
    heading: 'font-bold tracking-tight',
  }
}
<Otter.Editor custom_classes={custom_classes} ... />

The demo includes a substantial example use of custom CSS classes, see /demo/custom-classes.js.

For all support custom classes, see /src/core/definitions/classes.js.

Selective importing

Sometimes one of your application bundles may not need to import the whole of the Otter library. You can import the field type definitions separately:

import FieldTypes from 'otter-editor/dist/core/definitions/field-types'

And you can also import individual otter utils:

import {set_dynamic_data} from 'otter-editor/dist/core/definitions/utils'

Tests

npm run t   # run all tests
npm run tw  # run all tests, --watch
npm run ts src/test/<file>  # run a single test, --watch

Local development within another project

Delete your-app/node_modules/otter-editor
From otter, run a build to generate CSS and initial JS:

DIST=/path/to/my-app/node_modules/otter-editor/dist LOCALDEV=yes bash scripts/build.sh

If desired, then begin live-compiling from otter into DIST:

DIST=/path/to/my-app/node_modules/otter-editor/dist LOCALDEV=yes WATCH=y bash scripts/babel.sh

License

To enable Wordpress integration, Otter is dual-licensed. The license is:

GPLv2 for the purpose of embedding within Wordpress themes
MIT for all other purposes

See LICENSE.md.