Rich-Text Editor

The module doesn't ship a rich-text editor. The template has one, app/app/components/TipTapHtmlEditor.vue, built on TipTap. Its HtmlContent component shows the editor to admins in edit mode, and the HTML through v-cwa-html to everyone else. This page covers the editor; HTML Content covers rendering the HTML.

Loading an Editor Lazily

A rich-text component often shows an editor to admins, such as TipTap. Import the editor with defineAsyncComponent, not statically. A static import puts the editor into the preloads of every page with body text, for anonymous visitors too. In the template, that was about 424 KB of TipTap and ProseMirror (135 KB gzipped).

<template>
  <article>
    <TipTapHtmlEditor v-if="$cwa.admin.isEditing" :model="resourceModel" :iri="iri" />
    <div v-else ref="container" v-cwa-html="content" class="prose" />
  </article>
</template>

<script setup lang="ts">
import { defineAsyncComponent } from 'vue'

// Fetched only when an admin starts editing.
const TipTapHtmlEditor = defineAsyncComponent(() => import('~/components/TipTapHtmlEditor.vue')) // ...
</script>

Anywhere else that only needs the editor's type, use import type. A value import keeps the editor in the dev bundle.

import type TipTapHtmlEditor from '~/components/TipTapHtmlEditor.vue'

const editorComponent = ref<typeof TipTapHtmlEditor | undefined>()

Nuxt still adds a prefetch hint for the async chunk, so browsers may download it in the background. The template removes that hint with a build:manifest hook in nuxt.config.ts. It filters the editor out of each chunk's dynamicImports. The editor still loads on demand when it is first shown.

// nuxt.config.ts
const isEditorSource = (id: string) => id.endsWith('components/TipTapHtmlEditor.vue')

export default defineNuxtConfig({
  modules: [
    (_options, nuxt) => {
      nuxt.hook('build:manifest', (manifest) => {
        for (const chunk of Object.values(manifest)) {
          chunk.dynamicImports = chunk.dynamicImports?.filter(id => !isEditorSource(id))
        }
      })
    },
  ],
})

The module already keeps its own admin UI out of visitors' prefetch hints. It can't see your editor, because the editor is app code, so keep this hook.

Choosing the Editor's Buttons

The template's app/app/components/TipTapHtmlEditor.vue shows a menu of formatting buttons: H1, H2, Bold, Italic, Underline, Link and Bullet List. Every button shows by default. Pass the config prop to hide some of them for one field.

For example, a short description that allows only bold, italic and links:

<TipTapHtmlEditor
  v-if="$cwa.admin.isEditing"
  :model="resourceModel"
  :iri="iri"
  :config="{ h1: false, h2: false, underline: false, bulletList: false }"
/>

The keys are h1, h2, bold, italic, underline, link and bulletList. Set a key to false to hide that button. The prop is typed, so a misspelt key fails the type check. A project whose copy of the file has no config prop can copy the current file from the template.

H1, H2 and Bullet List also appear in the menu shown on an empty line. That menu is hidden when all three are off.

Editing Together

The editor takes the HTML field's useCwaResourceModel as :model, and the component's IRI as :iri. With them, it works with other admins like the kit fields do:

• Who's in the field. Another admin with the editor in focus outlines it in their colour, with their name above it (<CwaUiFieldPresence>).
• Their carets. Each admin's caret and selection show in their colour while they're in the field. The editor sends them with useCwaRealtime.
• Their saves. Another admin's save is applied in place: only the changed part is replaced, so your caret stays where it was, and Undo doesn't undo their change.
• Typing at once. Your typing and theirs merge as you both type (see Typing at the Same Time). When a save can't be merged, Use theirs / Keep mine shows below the editor (<CwaUiRemoteChangeConflict>).

How an editor of your own does the same is in useCwaResourceModel › Your Own Field Editor.

Typing at the Same Time

When two admins type in the same field at once, the template's editor merges their typing with Yjs:

• Each admin sees the other's keystrokes as they type, with live carets.
• Undo only undoes your own typing.
• Each window saves its own typing, so Publish includes it. One window also saves the merged text.
• A change saved from outside the editor, such as from another tab of the manager panel, is applied into the shared text for everyone.
• The shared Yjs state for each field is kept in the API, so an admin who opens the field later starts from it (see API › Versions & Conflicts › Collaboration States).

It needs api-components-bundle 2.0.0-alpha.37 or later, which stores the Yjs state. With an older bundle, the editor logs a warning and starts from the saved HTML.

The editor is app/app/components/TipTapHtmlEditor.vue with the Yjs files in app/app/tiptap/ (co-editing.ts, y-sync.ts, y-seed.ts, y-session.ts, y-state.ts and y-cursors.ts), and it uses the yjs, @tiptap/extension-collaboration and @tiptap/y-tiptap packages. Pass it the name of the field it edits, as field:

<TipTapHtmlEditor
  v-if="$cwa.admin.isEditing"
  :model="resourceModel"
  :iri="iri"
  field="html"
/>

Load the editor lazily, as in Loading an Editor Lazily, so Yjs never reaches visitors.