Serlo Editor as a web component

This is an early version of the web component wrapping the Serlo Editor. Be aware that we are actively working on both packages and thus there will be breaking changes in minor versions before version 1 is reached. The repositories serlo/serlo-editor-lit and serlo/block-serlo-editor-with-vue-js show how this package can be used.

If you are using React, we recommend using the Serlo Editor as a React component. Please also read the documentation of all the properties we expose there. The latest supported attributes and properties of the editor-web-component can be found here.

Installation and usage

1. yarn add @serlo/editor-web-component
2. Register the web component customElements.define('serlo-editor', EditorWebComponent).
3. Render the web component

Below is an example of how to use the web component in a Vue.js application.

<template>
  <div>
    <button @click="toggleMode">{{ isEditing ? 'READ' : 'EDIT' }}</button>
    <serlo-editor
      :mode="isEditing ? 'write' : 'read'"
      :initial-state="initialExampleState"
      @state-changed="handleStateChange"
    ></serlo-editor>
  </div>
</template>

<script>
import { defineComponent, ref } from 'vue'
import { EditorWebComponent } from '@serlo/editor-web-component'

customElements.define('serlo-editor', EditorWebComponent)

export default defineComponent({
  name: 'SerloEditorComponent',
  setup() {
    const isEditing = ref(false)
    const initialState = ref({
      plugin: 'rows',
      state: [
        {
          plugin: 'text',
          state: [
            {
              type: 'h',
              level: 1,
              children: [{ text: 'Example Heading' }],
            },
          ],
        },
      ],
    })

    const toggleMode = () => {
      isEditing.value = !isEditing.value
    }

    const handleStateChange = (event) => {
      console.log('New state:', event.detail.newState)
    }

    return {
      isEditing,
      initialState,
      toggleMode,
      handleStateChange,
    }
  },
})
</script>

To familiarize yourself with our JSON structure, for each plugin, you can look at example JSONs here. You can also go to our editor preview page, enter any plugin and through the menu in the top right corner, click "copy plugin". If you paste it in your code editor, you will see the JSON structure of the plugin you selected through the toolbar.

If you want to display a certain plugin as an initial state of the Serlo Editor, we recommend importing the pluginMenuEn / pluginMenuDe object and Plugin enum. Check out the documentation for more information.

import { pluginMenuEn, Plugin } from '@serlo/editor'

const singleChoiceKey = Plugin.SingleChoiceExercise
const initialStateOfSingleChoice = pluginMenuEn[singleChoiceKey].initialState

How to disable/remove plugins

The Serlo Editor Web Component allows you to customize which plugins are available in the editor. By default, it uses all available plugins (defaultPlugins), but you can modify this list to remove specific plugins.

import { EditorPluginType, defaultPlugins } from '@serlo/editor-web-component'

// Filter out specific plugins like the video plugin here
const filteredPlugins = defaultPlugins.filter(
  (plugin) => plugin !== EditorPluginType.Video
)

Then you can pass the filteredPlugins to the plugins array of the editor-web-component via a property by holding a reference to the Serlo Editor or via HTML attribute as seen below.

<serlo-editor plugins='["text", "image", ...]'> </serlo-editor>

The plugins attribute/property accepts an array of plugin types. You can reference EditorPluginType for all available plugin options. Note that upon first render, the object will be frozen. You can't change the available plugins dynamically, so make sure to filter out the plugins you don't want before the first render!

Shadow DOM vs. normal DOM

Version 0.10.3 was the last stable version where you can render the Serlo Editor within the Shadow DOM. All future versions will only work in the regular DOM and the editor expects window/document objects to be available! If you are already rendering your whole app within a Shadow Root, you could consider wrapping the Serlo Editor in an iFrame which should allow you to keep having a Shadow Root, while making the global window/document objects available and isolating the Serlo Editor styles from your existing styles completely.

For versions <= 0.10.3

We give you the option whether you want to render the web-component within the Shadow DOM or not. Both have their pros and cons. Outside of the Shadow DOM, it's easier to run into style collisions. However, the Serlo Editor within the Shadow DOM is buggy in a lot of places, especially when it comes to focus management. By default we are rendering the Serlo Editor within the normal DOM. If you want to render it within the Shadow DOM, you can pass true to the use-shadow-dom argument.

<editor-web-component use-shadow-dom="true"></editor-web-component>

Releasing a new version to npm

Bump the version number in the package.json and the github workflow seen inside editor-web-component.yaml will take care of the publishing.

Local development with editor package

Go to the package.json and use "@serlo/editor": "workspace:*" instead of a fixed version. This way, you don't need to release a new version of the editor every time you make a change in the repo.

Linking for local development with integrations

In order to avoid publishing the editor to NPM or dealing with tarballs every time you need to test your changes in an integration locally, you can use yalc to link the editor web component package to your integration locally.

Prerequisites:

• Yalc: yarn global add yalc

Initial steps:

1. From this workspace -> run yarn yalc:publish
2. From consumer repo -> run yalc add @serlo/editor-web-component

After making some changes in the editor:

• From this workspace -> run yarn yalc:publish (pushes dist, updates version and cache)

To remove the local link to Serlo Editor:

• From consumer repo -> run yalc remove @serlo/editor-web-component