Upgrade the events system in Acquia CMS using the Smart Date module
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
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.
drush en smart_date_recur
Add a Smart Date field
Go to the Manage fields form at
/admin/structure/types/manage/event/fieldsand 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:
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-displayto 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
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/importwithin 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.