ApostropheCMS

Appearance

Edit this page on GitHub or open an issue

@apostrophecms/area ​

Alias: apos.area

Extends: @apostrophecms/module ℹ️

This module manages areas and the widgets inside them. It renders areas, loads their widgets, and provides the editing interface for adding, selecting and changing widgets on the page.

addCreateWidgetOperation(operation) ​

Adds an entry to the "add content" menus of areas. When an editor chooses it, Apostrophe opens a modal, and the widget or widgets the modal returns are inserted into the area. Use it for ways of creating content that a single widget type can't express, such as inserting a group of widgets from a template.

Call it while your module initializes:

javascript
export default {
  init(self) {
    self.apos.area.addCreateWidgetOperation({
      label: 'Insert section template',
      description: 'Add a heading, text and image as one group',
      modal: 'SectionTemplateModal',
      props: {
        templates: [ 'intro', 'feature' ]
      },
      ifTypesIntersect: [ '@apostrophecms/rich-text', '@apostrophecms/image' ]
    });
  }
};
modules/section-template/index.js

The operation object takes these properties:

PropertyTypeDescription
labelStringThe menu entry's text or i18n key.
descriptionStringHelp text or i18n key shown under the label in the expanded "add content" menu.
modalStringThe name of the modal component to open.
propsObjectProps passed to the modal.
ifTypesIntersectArrayWidget type names. The entry appears only in areas that allow at least one of these types. Without it, the entry appears in every area.

The modal receives props, plus the area's options and fieldId. To insert content, it emits modal-result with either:

  • A widget, which is inserted at the position the editor chose.
  • An array of widgets, which are inserted in that order as one undo step and left selected. If the area's max leaves too little room for all of them, none are inserted.

Apostrophe inserts the widgets exactly as the modal returns them. If they are copies of existing widgets, give them new ids with cloneWidget, which also regenerates the ids of nested areas, arrays and objects:

javascript
import cloneWidget from 'Modules/@apostrophecms/area/lib/clone-widget.js';

// Inside the modal component
this.$emit('modal-result', sourceWidgets.map(cloneWidget));