Apostrophe Events

This module bundle helps developers quickly add event content to Apostrophe 3 websites. It provides the event piece type (@apostrophecms/event) as well as a special page type (@apostrophecms/event-page) for editors to create an event listing.

Installation

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

npm install @apostrophecms/event

Usage

Configure the event modules in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // The main event piece type module
    '@apostrophecms/event': {},
    // The event page module
    '@apostrophecms/event-page': {}
  }
});

Enable the page type

To enable the event page type for editor to select, add it to the @apostrophecms/page configuration:

// modules/@apostrophecms/page/index.js
module.exports = {
  options: {
    types: [
      {
        name: '@apostrophecms/home-page',
        label: 'Home'
      },
      // Adding the event page type
      {
        name: '@apostrophecms/event-page',
        label: 'Event Page'
      }
    ]
  }
};

Note: The index page template (index.html), filters template partial (filters.html), and show page template (show.html) are primarily meant as a starting point for a project. They demonstrate much of the available template data, but developers will almost always want to override them to implement proper styles and layout.

Filtering by year, month, and day

The event page module, @apostrophecms/event-page, provides query filters to refine event results by year, month, and day. These are primarily used for index page filters (see the filters.html file), but can also be used in REST API requests and server-side queries. Events that span multiple consecutive days are included in results if the query is at least partially included in their date span.

Multiple event piece types

Sometimes a website needs multiple, distinct types of events. If the event types can be managed together, it might be easiest to add a new field and query builder to customize event views. But if the event types should be managed completely separately, it may be better to create separate piece types for each.

Just as we extend @apostrophecms/piece-type to create a new piece type, we can extend @apostrophecms/event to create a new event type. The event type will need its own module directory and UI labels. It can simply inherit the original templates, fields, and other configuration or override them in the event type's index.js file.

A special event type that has an event URL field might look like this:

// modules/special-event/index.js
module.exports = {
  extend: '@apostrophecms/event',
  options: {
    label: 'Special Event',
    pluralLabel: 'Special Events'
  },
  fields: {
    add: {
      eventUrl: {
        label: 'Event URL',
        type: 'url'
      }
    },
    group: {
      basics: { fields: [ 'eventUrl' ] }
    }
  }
}

To display custom event types on a page, we would need to do the same for the event page module. All custom modules would need to be instantiated in the app.js file like any other module.

// modules/special-event-page/index.js
module.exports = {
  extend: '@apostrophecms/event-page'
}

Do this as many times as you need custom event types. Adding filtering and new fields to the base event module is usually enough for most use cases, but organizations with more complex event needs will find this strategy helpful.