Use Smart Date for Events in Acquia CMS

Goal

Upgrade the events system in Acquia CMS using the Smart Date module

Overview

This tutorial assumes you have an existing install of Acquia CMS. If you don't, you can set up a project using a Cloud IDE and Code Studio, or locally using DDEV.

Why upgrade? The Smart Date module provides a more intuitive widget for content authors and more intelligent, natural-language output of date and time ranges. It allows a simple checkbox to set an event as all day and can handle timezones and recurring events as well. It also integrates with the Date Augmenter API for additional capabilities like add-to-calendar links. Some additional capabilities are mentioned in the steps below.

Even if you already have Event content in your Acquia CMS website, this tutorial will guide you through the steps to add Smart Date's robust features to your site, and convert your existing event data into a new Smart Date field.

• Add and install Smart Date

  copy

  composer require drupal/smart_date:^4.0 -W
  drush en smart_date

  If you want to use recurring events, also install the submodule for this.

  copy

  drush en smart_date_recur

• Add a Smart Date field

  Go to the Manage fields form at /admin/structure/types/manage/event/fields and click "Add field". Select "Smart date range", and some of the later steps in this tutorial will work better if you name the field "When".

  The later steps will also work better if you choose to allow unlimited values, and this also allows for the use of recurring events.

• Configuring the new field

  If you've decided to use recurring events, enable them in the field configuration now (though you can also enable them later if you choose).

  Set the field's default date to "Next hour", and you can optionally customize what duration values will be allowed, and what the default will be. Note that if you remove "custom" from the allowed values, then content authors will only be able to use one of the listed durations.

  

• Migrate existing data

  If you have existing event content, we can migrate the existing Start Date and End Date data into our new field using a drush command:

  copy

  drush smart_date:migrate event field_when field_event_start field_event_end

  Go to the edit form for an event to validate that the existing values have been migrated (the new Smart Date field will be at the bottom).

• Configure the form display

  Go to the Event content type's Manage form display page at /admin/structure/types/manage/event/form-display to update how the Smart Date widget appears in our form. Move it near the top, and select the widget appropriate for how your site needs to manage dates and times. You can choose a widget that includes timezones if your site will need to set times in multiple timezones.

  Use the cogwheel on the right to access a variety of additional options for how the widget will be used. There's a checkbox to disable the All day checkbox, and for the timezone widget you can choose specific timezones to show in the Event form, if your content authors don't need the full, global set.

  Scroll to the bottom and click Save.

  

• Configure the display

  The are also a variety of options for how the values will be displayed. By default Smart Date will intelligently deduplicate parts of time and date ranges that are common to both the start and end. In the formatter you can choose which among the start, end, and duration will be output, and also choose whether or not Smart Date will add an HTML5 time tag around the output. There is also an option to add extra spans around the time and date parts of the output, for theming. A Javascript localization option will automatically change the times to the timezone of any visitor to the website. There is also a Recurring formatter that provides additional options to only output a configured number of recent and upcoming dates.

  If your site is using Site Studio, you will need to update your templates for the Event content type. If you want to leverage Smart Date’s intelligent date formatting, you can place the When field directly, or you can leverage Smart Date’s tokens to include the time and date information in more custom ways, using tokens such as .

  Don’t forget to follow the steps above for all the view modes that you plan to use for events on your site.

  

• Update the views

  Acquia CMS includes three views by default: Event Cards, Events, and Events (Fallback). If you want to keep them, the only change you need to make for each is to change the sort to use the new When field. Click to add a new sort value, and filter it to “start”, which will give you the option to select the start of your new Smart Date field. Next, click “Rearrange” to drag the Smart Date value to the top (making it the primary sort) and remove the Start Date value.

  

• Replace the Events view

  Optionally, you might choose to replace the default Events view with the one provided in the Smart Date Starter Kit, which includes some advanced configuration, in particular for working with recurring events. If you want to make this replacement, it’s a simple process, though it does require adding and installing the Add Content By Bundle module. Once that’s done, delete the existing Events view. Copy the code from the Smart Date Starter Kit's view using the “Copy file contents” button in the top right. Paste that into the form at /admin/config/development/configuration/single/import within your site to import a single configuration, and set the Configuration type to View. Click the Import button, and then confirm the import. Once that’s done you will now have a new Events view, which lists Events using the Teaser view mode. If you prefer, you can change it to use a view template instead.

  
  

• Add a calendar view

  If your site would benefit from adding an interactive calendar display, this can be easily accomplished in a similar way. This time we will import a view from the Smart Date Calendar Kit. First you will need to add and install the Fullcalendar View module. Copy the code from the Smart Date Calendar Kit's view configuration file and paste it in the Single import form, again set as a View configuration. Once you click Import and confirm, you will now have a calendar view that supports drag-and-drop rescheduling of events.

  

• Delete default fields

  The final step is to remove the original Start Date, End Date, and Duration fields. If you don’t need the Door Time field, this is a good time to remove that too. With that done, you’re ready to start using your upgraded event handling.