Composr Tutorial: Running a calendar/diary
- 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.
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 typesEvent types are used to categorise events. There is a good selection of default event types which have their own icons:
- Public Holiday
- System command.
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.
- 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.
- 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
Social > Calendar on the default menus).
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.
Time-zone issuesSpecial 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.
InternationalisationThe 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.
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.
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.
ExampleIf 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 commandsTo 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.
FeedsUsers 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 / CultureIt 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.
- 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
Have a suggestion? Report an issue on the tracker.