HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

ocPortal Tutorial: Running a calendar/diary

Written by Chris Graham, ocProducts
A calendar is provided in the software, 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.


Thumbnail: Adding an event to the calendar

Adding an event to the calendar

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 ocPortal.

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. ocPortal will actually recognise conflicting events, and render conflicting events in parallel activity streams on the day view interface.

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 the 'Calendar' icon in the Content Management Zone.

Thumbnail: Viewing a calendar event

Viewing a calendar event

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.
Thumbnail: Adding an event type

Adding an event type

  • 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.


Thumbnail: The calendar day view

The calendar day view

Thumbnail: The calendar year view

The calendar year view

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
Thumbnail: The calendar week view

The calendar week view

Thumbnail: The calendar month view

The calendar month view

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).
Thumbnail: Calendar interest filtering

Calendar interest filtering

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.

Adding an event

To add an event, simply click 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 them.
You may also click the 'Add Event' button to add an event, but you will need to fill in more details this way.

Time-zone issues

Special temporal events such as 'Daylight saving time', 'Leaps', 'Relativistic effects' and '4th dimensional wormholes' (joke) are not handled by the ocPortal 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.


The ocPortal 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 note

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 ocPortal 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.

For 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 occurrence. 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 ocPortal to call up (the process of calling a URL can be used to invoke some function of a web application)
  • a portion of OcCLE code

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


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 '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 occurence, 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

See also