npm

Join us for the upcoming webinar, "Enterprise JavaScript done right: the tools you love, the security you need."Sign up here »

apostrophe-tiptap-rich-text-widgets

0.1.1 • Public • Published

Why?

Many users of ApostropheCMS are aware of our plans to use the Vue-based Tiptap editor in Apostrophe 3.x. This module provides an early technology preview of that editor for Apostrophe 2.x. When present it replaces the CKEditor 4.x-based rich text editing experience that ships with ApostropheCMS.

Stability

As a technology preview, this module currently has a special stability policy:

  • We will undertake to avoid bc breaks in the use of the module, as documented, as a rich text editor.
  • However, changes will likely be made to the way new components, tooltip extensions, etc. can be added.
  • We expect that instability to cease around the time Apostrophe 3.x is released.

So if you're just using it as a rich text editor, you may regard it as stable. But if you are extending it, you should expect to be an active participant in developing the module in parallel with the evolution of Apostrophe 3.x.

One area that may be subject to change beyond these guidelines is the link button, which may at some point be subdivided into more than one button for a better user experience.

Requirements

You must use Node 8 or better.

Installation

# First, cd to the root of your existing Apostrophe 2.x project. Then...

npm install apostrophe-tiptap-rich-text-widgets

Configuration

// in app.js
require('apostrophe')({
  modules: {
    'apostrophe-tiptap-rich-text-widgets': {}
  }
});

All rich text editor widgets on the site now use tiptap instead of CKEditor.

CKEditor-compatible toolbar configuration

tiptap and CKEditor are not the same and do not have identical features. Identical behavior is not guaranteed. However many common CKEditor toolbar options are accepted.

Native tiptap toolbar configuration

In addition, the following toolbar items are accepted natively:

bold italic strike link horizontal_rule bullet_list ordered_list blockquote code_block styles

All of these require no configuration, with the exception of styles. The styles toolbar item, if present, must be configured via the styles option. It is used to provide a choice of block elements, potentially with a choice of CSS classes:

styles: [
  // For now, for best results you MUST configure styles, and your styles MUST
  // include the paragraph tag with no classes as one of the options.
  // You may have other options based on the `p` tag that do have classes.
  // The requirement to include `p` is likely to remain due to the way
  // tiptap handles line breaks inside list items, etc.
  {
    tag: 'p',
    label: 'Paragraph'
  }
  {
    tag: 'h3',
    label: 'Heading'
  },
  {
    tag: 'h3',
    'class': 'right',
    label: 'Heading (Right)'
  }
]

The class property may contain several space-separated class names.

The name and element properties are accepted as fallbacks for label and tag, for backwards compatibility.

Adding more tiptap extensions

You can write your own tiptap extensions, either at project level in lib/modules/apostrophe-rich-text-widgets/src/apos/extensions, or in an npm module that also uses improve to enhance apostrophe-rich-text-widgets and is configured after this module. These extensions will be autoloaded if present.

Similarly you can write your own Vue components to provide UI for those extensions in src/apos/components.

See the existing src/apos/extensions and src/apos/components folders of this module for examples.

If you add extensions, you must run this task to rebuild the frontend JavaScript code:

node app apostrophe-rich-text-widgets:build

This will create the file:

lib/modules/apostrophe-rich-text/public/js/public-tiptap-bundle.js

And that will become part of the assets pushed to your browser from this point on. You should commit it and deploy it as you would any source file. If you decide you don't want any custom extensions after all, you should remoe it.

These are advanced techniques requiring a good understanding of tiptap internals.

Contributing to this module

Feel free! Be aware that if you add or modify Vue components and extensions in the npm module itself, you will need to run:

node app apostrophe-rich-text-widgets:build --npm

Otherwise the asset bundle is built at project level. Note that when you use --npm project-level extensions and components are not included in the bundle, since their source code won't be there for anyone else who installs the module.

If you have a project-level lib/modules/apostrophe-rich-text-widgets/public/js/project-tiptap-bundle.js file, that will get loaded instead when you run node app, so make sure you remove that to test your build.

install

npm i apostrophe-tiptap-rich-text-widgets

Downloadsweekly downloads

31

version

0.1.1

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability