Skip to content

area

An area field allows editors to add, edit, and arrange a series of widgets. There are two ways to configure an area. The first adds widgets to a pop-up list menu for the editor selection. For this configuration, widgets are added through a widgets property in the options. Alternatively, the expanded preview menu provides a fly-in menu that allows grouping and a visual preview of widgets. This is configured through a groups option in which each individual group takes a widgets property.

Module field definition

Configuring an area for the pop-up list menu

javascript
// Configuring a `main` area field in a `fields.add` subsection of a module:
main: {
  label: 'Main column',
  type: 'area',
  options: {
    widgets: {
      '@apostrophecms/rich-text': {}
    }
  }
}

Configuring an area for the expanded preview menu

javascript
// Configuring the `main` area field in a `fields.add` subsection of a module:
main: {
  label: 'Main column',
  type: 'area',
  options: {
    expanded: true,
    groups: {
      basics: {
        label: 'Basic Content',
        widgets: {
          '@apostrophecms/rich-text': {},
          '@apostrophecms/image': {}
        },
        columns: 2
      }
    }
  }

Settings

Required

PropertyTypeDefaultDescription
labelStringn/aSets the visible label for the field in the UI
typeStringn/aSpecifies the field type (area for this type)
optionsObjectn/aAn object containing widget configuration. Contained within the individual groups for the expanded preview method.

Optional

PropertyTypeDefaultDescription
requiredBooleanfalseIf true, the field is mandatory.
helpStringn/aHelp text for the content editor
htmlHelpStringn/aHelp text with support for HTML markup
ifObject{}Conditions to meet before the field is active. See the guide for details.
requiredIfObject{}Conditions to meet before the field is required. See the guide for details.
hiddenBooleanfalseIf true, the field is hidden

options

Area inputs have additional settings configured in an options object.

PropertyTypeExpanded menu only?Description
maxIntegerNoSets the maximum number of widgets allowed in the area.
widgetsObjectNoTakes widget names as keys and associated widget options as values.
expandedBooleanYesActivates the expanded widget preview menu.
groupsObjectYesAccepts an object composed of named group objects.

max

The maximum number of widgets allowed in the area.

Example using the simple menu

javascript
add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      max: 1, // 👈 Limits the area to a single image widget.
      widgets: {
        '@apostrophecms/image': {}
      }
    }
  }
}

Example using the expanded preview menu

javascript
add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      max: 1, // 👈 Limits the area to a single widget.
      expanded: true,
      groups: {
        basics: {
          label: 'Basic Content',
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          },
          columns: 2
        }
      }
    }
  }
}

widgets

Widgets names are added as keys to the widgets object, with their individual configurations (if needed) as the key value objects. This widgets object is added directly to the options for the pop-up list menu or within the named group objects in the groups option for the expanded preview menu. Note: widget keys in area configuration are their associated module names minus the -widget suffix (e.g., 'callout-widget' is configured as simply 'callout'). Since all widget module names end with that suffix, it is not required for less repetition.

Configuring a widget type in an area field applies that configuration to the widget type only in this area's context. So a rich text widget with configured toolbar and styles in the area field would not automatically apply to a rich text widget in a different area field. (Though some widgets, including the core rich text widget, may support default configurations.)

javascript
add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      // Configuring four widget types as options in this area,
      // one of which has its own configuration when used in this
      // specific area. ⬇
      widgets: {
        '@apostrophecms/image': {},
        '@apostrophecms/rich-text': {
          toolbar: [ 'bold', 'italic' ]
        },
        '@apostrophecms/video': {},
        '@apostrophecms/html': {}
      }
    }
  }
}

groups

The groups option takes an object and is used to organize widgets in the expanded preview menu. Each group of widgets is passed as a named object in the groups object. Each of the groups have three configuration settings - label, widgets and columns.

The label property takes a string that is displayed for the widget group in the menu.

The widgets property is configured just like the one for the simple pop-up menu. It takes an object containing the widget names as properties and any options as values.

The columns property takes an integer from 1-4 and defaults to 3. This determines how many widgets previews will be displayed per line.

Example

javascript
add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      max: 3, // 👈 Limits the area to three total widgets.
      expanded: true,
      groups: {
        // Adding two groups of widgets to the menu
        basics: {
          label: 'Basic Content',
          // Configuring five widget types as options in this group,
          // one of which has its own configuration when used in this
          // specific area. ⬇
          widgets: {
            '@apostrophecms/image': {},
            '@apostrophecms/rich-text': {
              toolbar: [ 'bold', 'italic' ]
            },
            '@apostrophecms/video': {},
            '@apostrophecms/html': {},
            '@apostrophecms/svg-sprite': {}
          },
          // Configuring for 2 columns of widgets
          // This will result in 3 rows since there are 5 widgets
          columns: 2
        },
        layout: {
          lable: 'Layout Options',
          widgets: {
            'two-column': {},
            'three-column': {},
            'four-column': {}
          },
          // We don't have to add a column property if we want 3 columns
        }
      }
    }
  }
}

INFO

If you configure an area to use the expanded preview menu you can further customize how the widget is displayed through options in the individual widget's configuration.

Use in templates

Use the area template tag with arguments for the context and the name of the area field in that context:

{% area context, area-name %}

The "context" may be a page, piece, widget, or array field item, as referenced in the template. All configuration from the field definition is applied automatically from the relevant schema configuration.

nunjucks
<!-- Inserting the `main` area field for a page. -->
<section>
  {% area data.page, 'main' %}
</section>
<!-- Inserting the `photo` area field for array items. -->
<div>
  {% for item in data.page.photos %}
    {% area item, 'photo' %}
  {% endfor %}
</div>

INFO

For more information on how areas changed from Apostrophe 2, see the Coming from 2.x guide section on areas.