======= calibr

A simple opening hours calendar loading and rendering system. We use it for our library hours (bilingually, see below). It could be useful beyond that.

Based on code posted a long time ago by Andrew Darby to code4lib mailing list (then written up in its journal) which used Google Calendar. The Calendar API (or was it the Zend-based PHP library that called it?) was returning incorrect responses to some queries, so we looked for alternatives. The code was completely rewritten and then refactored along with the database schema, so none of Andrew's implementation is intact AFAICS.

Though it fits our current purposes, there's plenty more that can be done with this. They shall be logged as tickets.

Reference implementation

Feel free to use our implementation as your reference, but the committed version is de-branded and attempts to be plain/vanilla. The HTML metadata element generator shows the version deployed there.

Assumptions

These probably won't change anytime soon. If they don't suit then this code might not be for you:

• One opening per day. No lunch breaks, sorry.
• Opening hours for every day are within the calendar day. You can't open through the midnight hour. Thanks to Bohyun Kim for pointing that out.
• index.php is the default document. That's easily fixed in your web server config if you don't like it.

These are current assumptions we plan to make go away:

• Hours are loaded in ahead of time. Just how we roll right now. If you want to publish data from days past, you missed your chance. You'll get gaps. Pretty sure it's an easy fix. Just keep up for now.
• HTML display period is a calendar month. That's what we wanted without thinking too much about other options, which would admittedly be handy.
• MySQL and PHP. We'll be more specific about that in the installation section.

How to install and make it useful

So if all of the above is acceptable, here's how you do it.

Requirements

We run it on IIS with MySQL and PHP 5.x where x < 2. Importantly, the DateTime object isn't required. A test install on standard LAMP with Fedora went very smoothly indeed.

You will need to set up index.php as a default document for your directory in your web server. It probably already is. Nothing else I can think of is non-standard.

Installing

Copy the files within the web server path you want.

Create a MySQL database that the web server can see (or use an existing one), select it, and create a single table using this SQL. Switch the table name if you don't like "libhrs":

CREATE TABLE libhrs (
  id int(11) NOT NULL AUTO_INCREMENT, -- can be dropped, but is handy for debugging
  day date NOT NULL,
  opens datetime DEFAULT NULL,
  closes datetime DEFAULT NULL,
  PRIMARY KEY (id), -- droppable, see above
  UNIQUE KEY day_UNIQUE (day)
);

(The repository file csv_load.php has this code at the top in a PHP block comment.)

Next configure your database for a load. (See below for migrating existing calendar data from Andrew Darby's orginal application.)

1. Rename the file database.EXAMPLE.php to database.php and edit the database settings there.
2. Rename the file settings.EXAMPLE.php to settings.php and edit at least $timezone and $data_file if you want to put it somewhere else.

If you were successful, you should be able to see a working HTML display in your browser at the root of the web server path where you placed it. There won't be any data in it though.

Loading data

Now it's time to create some opening times in a CSV file or spreadsheet. I strongly suggest taking the file calendar.xlsx, editing that in your favourite spreadsheet application (Open/LibreOffice should load it fine) because it will enforce cell datatypes, and then exporting as CSV. Note that if you edit the calendar.csv file directly in Microsoft® Excel (even sticking to the date and time formats already there), it will probably reformat them on save (yes, true) and your import will fail. A person who is not afraid of text files could alternatively edit the CSV file directly in a good text editor.

For the moment, open hours data after the present day are deleted when the data is loaded. There'll be a gap in your calendar if you delete these rows in your spreadsheet or CSV file. Don't delete further back than today's date.

• For continuous periods of the same opening hours, just populate the Period start and Period end columns. In the Recurrence column, list the days of the week the hours apply to, as numbers. 1 is Monday through to 7 is Sunday. Don't delimit multiple numbers. For example, "5" is every Friday and "123" is Monday to Wednesday.
• For a single day, just populate the Period start column and leave Period end blank.
• Populate the opening hours in the Opens and Closes columns. For closed days, leave both of those columns blank.
• Use the Notes column for your own convenience. It goes nowhere else. In future, it might be used to show users extra information, e.g. in a tooltip ("Summer holidays" or "Labour Day").
• You can add exceptions to recurring period hours by creating another row any time after the original period's row. So for example, add a public holiday as you would any other day after the period in which it occurs. The example in the repository contains one such example for October 28, 2013 (exception to line 11).

If you did this on the .xlsx file (recommended), export it as CSV.

If that's a bit tricky to follow, load the example data as a trial, but edit it first to make sure it's in the future (to work around a current bug/feature). The easiest way to do this would be to change the year on all dates to a future one. If you do that, you might need to edit $populate_months in settings.php to make it load that far into the future.

Now in your web browser, open csv_load.php under the path you placed your files. If you did everything above right, you should get happy output. If not, check your database settings, file names (did you rename the settings files?), and CSV file. Try try again.

If you successfully loaded data, you should now be able to see it in HTML in your browser at the root of the web server path where you placed it. Remember that if you used future-dated test data you might need to page forward in your browser to see it. By default, the current month is shown.

Customising

Unfortunately content is still quite mixed with logic as far as files go. In order of importance, these are probably the files you want to edit after a successful load:

• lib/config/settings.php
• lib/config/translations.php
• lib/templates/top.php
• lib/templates/bottom.php
• styles/hours.css

The translations configuration file allows you to choose which languages and translatable text your calendar displays. It comes pre-configured for en and mi (Ngāi Tahu dialect) as an example/template. There is also a sample translation for German you can simply add to the $languages array to see what a trilingual display looks like. You need to provide translated text for any new languages and currently also one setting for the language's time format.

You probably don't want to leave files on the web server so that your data can be re-imported by anyone on the internet. It wouldn't have any real effect, but it's not the safest of practices the way it's set up currently. (It's not safe in the RESTful sense.) Get rid of (or rename obscurely) either csv_load.php or calendar.csv to make such attempts fail.

Migrating

To load data from the database structure used in Andrew Darby's script, there is a piece of SQL you can run included in the file lib/config/database.EXAMPLE.php. It worked for us.

Issues

Please report or peruse any issues, or suggest enhancements at the Github repository master:

http://github.com/LincolnUniLTL/calibr/issues

The project's home is at http://github.com/LincolnUniLTL/calibr and some links in this README are relative to that.