Mikkel Høgh

Presenting the Opening Hours Module

Opening hours on Copenhagen Public Libraries’ web site

Do you need to tell your visitors when you are open for business? Your office hours, when the service desk is open?

Then Opening Hours might be the module for you. In this post, I'm going demonstrate how the module can be used, as well as some of the API capabilities for extending it.

The backstory

In the autumn of 2011, Copenhagen Public Libraries decided that it was about time they got a better solution for their opening hours.

Since the current site was first launched in 2009, we had been using a hacked up version of another Drupal module, “office hours”, which was, to say it mildly, rather user-hostile. It used a cascading rule system to determine the opening hours, and suffice to say that people other than myself understood how to use it.

So, we were given the task of coming up with something better, so @rasmusluckow, Joan (who sadly didn't live to see it deployed), and I made a plan, and I started building the module in november 2011.

The plan was to create an administration interface similar to Google Calender, with a very visual representation of what's going on.

Copenhagen Public Libraries was still on Drupal 6 back (in fact, it still is), so we decided to build it for both versions. That meant we could not easily take advantage of all the new fields hotness in Drupal 7, but it has made it a lot easier to maintain both versions together.

After a lot of development work, tests, and changes, we got the new system live some time in spring 2012. I remember making an informal bet with @kasperg that I had managed to fix all the wierd date and timezone bugs. As it turns out, I lost...

Since the start, the module has been available on Drupal.org, but it has seen rather limited use outside the Ding.TING project for which it was intended.

I hope to rectify that, and one of the ways is to provide more documentation, making it easier to get started with the module.

Installation and configuration

The module is fairly simple to install as Drupal modules go. It depends on the Tipsy and Date module (for date popups). If you use drush, you can get and install the requirements with a couple of commands:

drush dl date tipsy opening_hours
drush en taxonomy date_popup tipsy opening_hours

Regional settings

If not, download these modules manually, and enable Date Popup, Tipsy tooltips, as well as Opening hours on the modules page. You might also want to enable taxonomy for categorising opening hours, but more on that later.

The Date API settings will allow you to configure which day the week starts with (monday in most places, sunday in the U.S.).

Nota bene

While writing this, I found a bug in the Opening Hours module, that causes the admin interface not to load correctly, when the opening hours block is inserted on all pages. If you want to follow this tutorial, you will need to get the latest version of this module, at the time of this writing, 7.x-1.5-beta1.

Node type settings

First off, we need to enable Opening Hours on the node type. In this example, we're using car dealerships, but it could anything that needs opening hours.

Node type settings

Your first opening hours

The opening hours tab

To use the opening hours, go to a node of the type you just enabled opening hours on, and click the opening hours tab. Then you should see something like this:

No hours yet

Click the empty cells below the dates to add hours to that date. This brings up this dialog:

Empty dialog

The basic use case is quickly managed. Fill out open and closing times, and if this is the general rule, you can set it to repeat every week.

So if you have open every monday 9:00-17:30, you would do something like this:

Filled dialog

Repeating this for all week days, we get something like this:

Filled out week

If you made a repeat rule, you can use the navigation at the top to switch to one of the following weeks and see the same hours.

Displaying your hours

Now, you have your hours entered, you probably also want to display them on your site. The easiest way to accomplish this, is to insert the opening hours block on the page via the Drupal's block administration:

Block administration

Once done, you can see the opening hours on the node page, like this:

Block administration

Overriding

Now, that's all well and good, but how about exceptions. Next week, monday is closed?

No problem, just go back to the administration interface, navigate to the week in question and click the hours for the day in question.

To mark this day as closed, simply delete its opening hours by clicking “Delete this instance”.

Editing hours

If you switched weeks before deleting, you should be presented with a dialog like this one:

Editing hours

This is presented, since you’re deleting something from the middle of the chain of repeated events, so your intentions might be different, depending on the situation. You can choose between:

  1. Deleting the hours instance for just this week. In this example, that means that this monday will be closed, but all previous and following mondays will remain the same.
  2. Deleting this week and all following instances. In this example, it means that the monday in question will be close, as well as all mondays after it.
  3. Deleting the entire series. In this example, that means that all mondays ever will appear to be closed.
  4. Cancelling the deletion, leaving everything as it was.

There's a similar workflow when you edit hours, so you can go to say, week 42 and change the hours, and then apply them to all the following weeks to have different winter opening hours, for example.

To be continued

There's a lot more ground to cover – categorisation, segments, customisation and API, and this already took half a day to write, so I'm going to pick this up later and expand on it.