Event syncing

Events are pulled from iModules every 15 minutes using a cron process which checks for newly updated events. It works by pulling a list of events that have been updated or created since the time of last sync, and importing them one by one, either creating a new event or modifying an existing one.

That means that any event updated in the WordPress admin will be overwritten if the event is also updated in iModules. The exception to this is an event's featured image, which can be safely updated in WordPress and will never be replaced.

The main functionality for this sync and import process are located in the custom plugin "Cornell Events"

Field Mapping

When fields are imported from the iModules API, they are mapped to our existing WordPress data structure. The title is pulled from the iModules title field, content from the full text field, and excerpt from preview text. Start and end dates for both the event itself and registration are also pulled and then added to the proper metadata fields in WordPress.

Start and end dates are returned from the iModules API as GMT times. iModules does not provide a timezone, only an offset that does not take into account daylight savings time, so geolocation is then used to get the event's timezone, and each start and end dates are converted to their local times before being added to WordPress.

If a custom registration URL it will be used, but by default the registration link is generated automatically from event data. For registration, both a start date and an end date must be added in order for the registration link to work on individual event pages.

The Location Name and Location Directions fields are used in order to create a new Venue in WordPress. Before a venue is created, existing venues are checked and if existing venue with the same address is found, it will be used instead of creating a new one, to avoid duplication.

Organizers for events are created in WordPress from Primary and Secondary contacts in iModules. Both Primary and Secondary contacts are added, along with their First Name, Last Name, Phone, and Email. Like Venues, if an organizer is found with the same email, it will not create a new one. A contact must have at least their first name, last name and email filled out in order to be imported.

Content Listings are used to create categories in the back-end, though these are not currently displayed on the front-end. If an event has the content listing of "Do Not Display on Site" then it will be skipped altogether.

Full list of iModules API fields, and what they map to in WordPress:

  • ContentName: Post Title
  • PreviewText: Post Excerpt
  • FullText: Post Content
  • CustomUrl: Registration URL
  • ContentListing: Category
  • StartDateTime: UTC Start Time
  • EndDateTime: UTC End Time
  • RegistrationStartDateTime: Registration Start
  • RegistrationEndDateTime: Registration End
  • Organizers are added with:
    • PrimaryContactFirstName
    • PrimaryContactLastName
    • PrimaryContactPhone
    • PrimaryContactEmail
    • SecondaryContactFirstName
    • SecondaryContactLastName
    • SecondaryContactPhone
    • SecondaryContactTitle
  • Venues are added with:
    • LocationName : Address
    • LocationDirections : Directions, not shown on front-end

 

Featured Images

Featured images are imported directly from iModules during the sync process. The first image in the iModules content field, if one exists, will be used as the imported events featured image. Featured images will be imported, optimized and resized based on standard image specifications. In general, events featured images follow the same specifications as all other images, meaning they will be imported, optimized and resized to accomodate both archive and single page listings. Like posts, these images should be as large as possible when added in iModules so that they can be resized, and should use the same aspect ratio as individual post images, 840 x 560.

If an alt tag is added to the image in iModules, this alt tag will also be imported with the featured image.

Venues and Timezones

Venues are also imported from iModules if one needs to be created. Each time a new venue is created, it's timezone will also be set based on geographic location so that timezones for events are properly updated.

Event Archives and Listings

The Events Calendar and Events Calendar Pro plugin are used to actually display a list of events on the front-end, and organize the data.

Any functionality available from this plugin can also be used on the site. To see a list of settings for the plugin, go to "Events -> Settings" in the WordPress admin.

The main archive template file is located in the theme folder, cornell/archive-events.php. All individual template partials can be found in the tribe-events folder in the theme.

WP CLI Commands

There are also a few helpful WP CLI commands which can be used to manually run a sync or disable cron. They can be run using terminus, once logged in.

To manually sync an individual event based on its iModules ID bash terminus wp cornell-alumni.live -- cornell events sync --id=<IMODULES_ID>

To manually sync all events updated from the time of last sync: bash terminus wp cornell-alumni.live -- cornell events sync --all

There is also a --force parameter which will ignore the time of last sync and sync all events.

To temporarily disable cron, so that events are not automatically imported every 15 minutes: bash terminus wp cornell-alumni.live -- cornell events cron --off

To reenable cron: bash terminus wp cornell-alumni.live -- cornell events cron --on