This Anchors module adds a wrapping element with an anchor linking target around all widgets. Developers may customize or opt-out individual widget types.

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms/anchors

Usage

Configure the anchor modules in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/anchors': {},
  }
});

When the modules are active, all widget type will have a new "HTML Anchor Value" field. When an editor populates that field with a slug-style string the widget HTML markup will be wrapped with a new div with an attribute, an id by default, set to the anchor value. This attribute can be targeted by anchor links, e.g., href="#anchor-id-value".

The only Apostrophe core widget type with this feature disabled is the rich text widget, @apostrophecms/rich-text-widget.

The "HTML Anchor Value" field is a "slug" type field, which means it is limited to lowercase characters and dashes for consistent usage.

Options

anchorAttribute

By default the anchor attribute is an id. This makes it easy to link to the widget with a hash href matching the anchor value as described above. Developers have the option to use another anchor attribute if they prefer to target the HTML element with custom JavaScript instead.

To do this, include an anchorAttribute option on the individual widget type. You can also add this option on the root @apostrophecms/widget-type module or the @apostrophecms/anchors-widget-type module to set this for all widget types.

// modules/my-banner-widget/index.js
module.export = {
  options: {
    anchorAttribute: 'data-anchor'
  }
};

In this example the wrapping div element would look like this:

<div data-anchor="anchor-id-value">
  <!-- Normal widget markup here -->
</div>

anchors: false

Developers can choose to disable this module's features for any widget type by setting an anchors: false option on the widget type.

// modules/my-banner-widget/index.js
module.export = {
  options: {
    anchors: false
  }
};

This is automatically set for the rich text widget. That can be reversed by setting anchors: true on @apostrophecms/rich-text-widget.

anchorDefault

To help content editors populate anchor values automatically, set the anchorDefault option to the name of an existing field on a widget type. The "HTML Anchor Value" field will populate automatically based on the value of the named field using the following field option mechanism.

// modules/my-banner-widget/index.js
module.export = {
  options: {
    anchorDefault: 'heading'
  },
  fields: {
    add: {
      heading: {
        type: 'string',
        label: 'Heading'
      }
    }
  }
};