Extending Page Editor

Overview

Developers may need to extend the functionality of the Page editor. You can provide the Editor extension to achieve this. The Editor extension is delivered as JavaScript and uses the Page editor API.

Note

The Page editor API remains under development. Detailed specifications will be provided in the future.

Registering extension

To define the Editor extension you must create a JavaScript file, which will be loaded in the Page editor by Web Fragments.

Web Fragments allows you to register JavaScript files (JavaScript module) that will be imported using dynamic import in the application runtime. The Web Fragments scripts should provide default export to deliver object, function and so on, depending on the given case. Web Fragments defines the key that a given fragment is related to. The expected type of default export should be checked in the specification of a given extension point. In numerous parts of the application, Web Fragments with particular keys are imported, making it possible to extend WebSight CMS.

The key of Web Fragments loaded by Page editor to get extensions is websight.editor.spi.extension. The expected default export should provide an object with the init function with a single argument, which will be the Page editor object.

To register the fragment, provide the OSGi components that implement the pl.ds.websight.fragments.registry.WebFragment interface to provide information about the fragment key, the location of the JavaScript file and the ranking used to order imports.

There is a required Maven dependency (see the version of the websight-fragments-registry bundle used in your system in Apache Felix Web Console in your local instance:

<dependency>
  <groupId>pl.ds.websight</groupId>
  <artifactId>websight-fragments-registry</artifactId>
  <version>1.0.3</version>
  <scope>provided</scope>
</dependency>

Example component:

package com.myapp.fragments;

import org.osgi.service.component.annotations.Component;
import pl.ds.websight.fragments.registry.WebFragment;

@Component
public class ExamplePageEditorExtensionWebFragment implements WebFragment {

  @Override
  public String getKey() {
    // Web Fragment key - different extension points use different keys.
    // This key is used for Page editor extensions, so the script file specified in the getFragment
    // method will be imported by the Page editor and used as a Page editor extension.
    return "websight.editor.spi.extension";
  }

  @Override
  public String getFragment() {
    // JavaScript module to import. Must provide default export in format expected by the
    // extension point related to the Web Fragment key in use.
    return "/app/myapp/author/editor/extensions/ExampleExtension.js";
  }

  @Override
  public int getRanking() {
    // Web Fragments are imported in order according to the ranking value, starting with the lowest.
    return 100;
  }
}

The JavaScript file returned by the getFragment method should be a bundle resource provided by your application and must be available in the CMS authoring runtime (specifically, it must be accessible for content author browser requests). Example content:

export default {
  init: (editor) => {
    // Use editor object here.
  }
}

Using Page editor extensions

Below you can find examples of Page editor extensions usage.

Editor events

Page editor uses an API for working with events. You can register a handler for events used in Page editor. To register an event listener use editor.addEventListener and pass the event type and listener function (you can use the event data object parameter if needed).

Event type	Description	Event data
component-dom-updated	This event is thrown after component's dom is updated.	`target` - component

Example extension registering the event listener:

export default {
  init: (editor) => {
    editor.addEventListener('component-dom-updated', () => {
      // React to DOM update, for example reload edited document:
      editor.componentTree.get().parentDocument.location.reload();
    });
  }
}