Composr Tutorial: Running a calendar/diary

Written by Chris Graham (ocProducts)

A calendar is provided in Composr, which also features an advanced scheduling system. The calendar may be used as:

a normal calendar
a personal diary/schedule
a system command scheduling system (automatically executed background tasks)
or a mixture of the above, depending on the properties chosen for the various events in the system.

Table of contents

Composr Tutorial: Running a calendar/diary

Introduction

Each entry in the calendar is called an 'event'. It is important to understand that an event is not a single point in time, or even a range in time, but rather something that may happen regularly. This is achieved through 'recurrence', which has a particularly powerful implementation in Composr.

For this tutorial I have just added a single recurring event into the system for clarity: you will see how this single event is shown on the various calendar views, and get an impression on how the system works. In reality, the calendar may be used by any number of members, with any number of events. Composr will actually recognise conflicting events, and display conflicting events in parallel activity streams on the day view screen.

Event types

Event types are used to categorise events. There is a good selection of default event types which have their own icons:

Anniversary
Appointment
Birthday
General
Public Holiday
Task
Vacation
System command.

System commands are a special type, as events added to this define code to be executed (and permissions protect members adding to it by default).

You may wish to add new event types for your website; for example, a business website might wish to add an 'Appraisal session' event type. This is done from under Content Management > Calendar.
You can delete an event type from the bottom of its edit form.

Adding events

Adding and editing events is done from either:

Under Content Management > Calendar
Simply clicking in one of the boxes on the calendar view; this will fill in the date and time automatically for you (although you may wish to adjust that)
Clicking the 'Add Event' button from a calendar view

You can delete an event from the bottom of its edit form.

When you add an event, you may define the following special settings:

The event type.
The start date and time. This defaults to an arbitrary time in the future. For a recurring event, this is the first time the event happens.
The end date and time. This is optional, and should only be set for an event that specifically has an end (many events can be considered points in time).
The recurrence type. For example, you can decide that recurrence is on a weekly basis.
The recurrence pattern. This is a source of popular confusion, but it is actually a very powerful tool. Significant in-line help is given for this, but basically it allows you to say things like 'this happens every weekday'. In our example, we have allowed the Cricket team to have a week off after every three weeks of practice.
The number of recurrences. In our example, the Cricket team only practices 25 times (therefore they have around 32 weeks between the start and end of their season, because of the weeks off).
Whether the event is public. Private events are generally used if the event is intended (by the event submitter) for a diary-like usage of the calendar system.
Priority. This is displayed in the interface, to help make it clear how a calendar user should plan their time.
Reminder signing-up. You can sign yourself, and members of select usergroups, up for reminders. You may also select how much notice there is for that reminder.

For monthly events you can also specify a special day-of-week position, from the start or end of the month. For example, the 2nd Tuesday of the month. If you wish to specify something like this, but once a year (e.g. the 2nd Tuesday of April, each year), specify a monthly recurrence with a recurrence pattern of 100000000000.

A member may remove reminders for events, and also have multiple reminders with different notice times.

Views

The calendar has 5 views:

at the top level, you can view a whole year
you can view a whole month
you can view a whole week
you can view a whole day
you can view a specific event

The views are a part of the calendar module
(site:calendar page-link,
Social > Calendar on the default menus).

The user interface has been very carefully designed so as to allow very quick and easy navigation between these views, allowing you to focus in and out, and move along, from where you are viewing.

The less focused the view, the less detail that is shown. On the year view you not see detail on any specific event happening on a day, but you can see trends and gauge how busy the individual days are. On the month view you can see specific events, but it is less easy to see how a day is time-tabled. On the week view you can can see a full time-table, but you can only see event titles by hovering the mouse. On the day view, you can see parallel activity streams, and actual event details.

The views support filtering of event-types via a series of check-boxes (tick-boxes).

You may also declare your 'interests', which marks you down for auto-reminding for new events of the types you have said you consider interesting.

From the screen-shots of the calendar views you can see how the recurrence pattern causes a gap where for one week in four, there is no shown event.

Block

The side_calendar block allows embedding of a mini-month view of the calendar, or a listing of upcoming events.

Time-zone issues

Special temporal events such as 'Daylight saving time', 'Leaps', 'Relativistic effects' and '4th dimensional wormholes' (joke) are not handled by the Composr calendar. It is probably better that they are not, because they would lead to extremely confusing situations. For example, for those with daylight saving time, there is an hour of the year that happens twice: instead of having a ambiguity for placement of events in that time, there will just be non-harmful anomalies as the server clock jumps in time.

Internationalisation

The Composr calendar is strongly tied to the Gregorian calendar, as well as the yyyy/mm/dd ISO standard for display of dates.
Changing this is not really viable: the internals of the calendar are extremely complex, as dates and time are inherently extremely complex.

Recurrence fixing

Important – take a backup

It is advisable to take a database backup before fixing an event, just in case the process does not complete as you expect it to. The recurrence programming code in the calendar system is (has to be) extremely complex, and this is a place where a minor bug or user mistake could wreak havoc.

If you have a recurring event, but for some reason, the event stops recurring, or there is a break in the recurrence pattern, then you will be pleased to hear that Composr has a feature for coping with this. The process of using the feature is labelled 'fixing an event'.

To fix an event, you just edit the event as if it was starting afresh, but select the edit action (at the bottom of the form) of 'Edit with fixing past recurrences'. This will cause all past recurrences of the event to be hard-coded into the system as individual events, and the edited event will now be completely separate to anything that has happened before.

Example

If with the Cricket Practice example, one of the practices is cancelled because the cricket pitch had been taken over by travelling folk, the cricket practice event will need some tweaking (assuming of course we don't just handle this by phone call and ignore the incorrect data in the system).

We would choose to edit the cricket practice event:

to start on the date of the next expected practice
to end 1 hour after that date
and select 'Edit with fixing past recurrences'

It is preferable that we did this before the actual cancelled event recurrence. If we were too late, we would undergo the same process, but delete the last hard-coded event that was added.

Scheduling commands

To schedule a command for execution, add an event with the event type of 'System command'. All settings (including recurrence) are as for any event, except the event text should be either:

a URL for Composr to call up (the process of calling a URL can be used to invoke some function of a web application)
a portion of Commandr code

For scheduled commands to be executed you need to have the Composr scheduling system configured as specified in the basic configuration tutorial.

Feeds

Users may choose to overlay RSS or Atom feeds of their choice onto the calendar. A time based view of feed entries is very useful in some situations.

Internationalisation / Culture

It is possible to customise the calendar to have a different start-of-week-day, or to use a 24 hour clock. This is done by editing the time strings in the global language file. For more information, see the Localisation and internationalisation tutorial.

Concepts

Event: An entry in the calendar system that may recur
Recurrence pattern: A pattern, written in binary, that indicates the on/off sequences of an events recurrence, masked and repeating over the recurrences that would happen by default
Event fixing: The process of hard-coding recurring events into individual events, so as to allow a change in the recurrence
Event type: The classification of an event; appointment for example

Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.