OAFsCalendar Extension

From OttawaRasc
Jump to: navigation, search

OAFs has an event calendar on their Wiki site that has the following features

  • Basic calendar is in a familiar monthly-calendar format;
  • The calendar can be embedded in any Wiki page;
  • The Width of the calendar can be specified, to create large or small versions of it for various embedding purposes.
  • Events are listed in the appropriate days;
  • Anyone can add or modify events directly from the Wiki (but there is an option, easy to turn on, to restrict this to registered users);
  • Each event has an optional Wiki page with more information.

Contents

Usage

Adding the Monthly Calendar to a Page

The calendar is embedded in a page simply by inserting the following tags:

<OAFsCalendar>Title Text</OAFsCalendar>

The title text is optional and, personally, I find I prefer to omit it to keep the page tidier.

The <OAFsCalendar> tag can also take optional arguments of the form

<OAFsCalendar arg1=value1 arg2=value2 . . . >

The possible arguments are based on a subset of the HTML IFRAME tag

width="value" specifies width of the generated calendar. Any valid HTML <iframe> width argument may be used - i.e. a simple integer for pixels, or an integer followed by "%" for percent of window frame.
height="value" specifies height of the generated calendar. Any valid HTML <iframe> height argument may be used - i.e. a simple integer for pixels, or an integer followed by "%" for percent of window frame.
align="xxx" Alignment of frame in page. Can be "left", "right", "top", "middle", or "bottom"
frameborder="xxx" Visual border around the frame - can be 0 or 1.
categories="a,b" Comma-separated list of categories to list. e.g. categories="starParties,RASC". Categories="*" gives all categories. Leaving categories out entirely will automatically use the categories defined with the "include in events list" flag on. Categories="**" gives all events, including those assigned to no category.

Interacting with the Calendar

From the monthly view of the calendar displayed, you can

  • scroll to different months;
  • click on a date to see a list of events on that day, or add events for that day;
  • click on an event name to go to the event detail or the event's wiki page.

If an event is set to click directly to its wiki page and you want to get, instead, to its detail page (for example to turn off the "click goes to wiki" setting), click on the date to see all events on that day, and click on the event in the list.

Implementation Documentation

Pages documenting the implementation of this extension can be found here.

Sample

Monthly Calendar View

The following tag:

<OAFsCalendar width="100%" height="420" frameborder="0"></OAFsCalendar>

Generates this calendar (this is live - try it):

Agenda List View

On an excellent suggestion from Attilla, the calendar has the ability to associate events with "categories" - short descriptive words, and a second way to view the data - a simple tabular list of events. The list can be filtered to include only certain categories, allowing a concise "what's coming up" table to be added to other wiki pages without taking up a lot of real estate.

Categories are added and modified by using the OAFs Calendar Administration Page.

Tag Syntax

The event list is added to a page by using the <OAFsEventList> tag. The format of this tag is

<OAFsEventList option list>field list</OAFsEventList>

The "field list" is a list of field names to be displayed, separated by blanks. Possible values are

date The date recorded for the event.
start The start time recorded for the event.
end The end time recorded for the event.
name The short name defined for the event (which will be linked to the event's wiki page).
description The long description text for the event. (This is the description entered when the event was defined, not the text on the wiki page. Maybe limited use.)
categories A list of the categoris to which this event is assigned.
csc The thumbnail of the Clear Sky Chart associated with this event, if any.

If the field list is omitted, "date start name" will be used.

The "options list" is a list of "keyword=value" pairs separated by blanks. The possible keywords are

border Can be 0 or 1, sets whether there is a border around the cells. (This is just passed through as the BORDER option on the HTML TABLE tag.)
titles Can be 0 or 1, controls whether there is a title row on the events table.
categories Comma-separated list of categories to list. e.g. categories="starParties,RASC". Categories="*" gives all categories. Leaving categories out entirely will automatically use the categories defined with the "include in events list" flag on. Categories="**" gives all events, including those assigned to no category.
days Limits the events displayed to those within the given number of days from the current date. e.g. days=60 will display the events happening in the next 60 days.
limit Limits the number of events displayed to the given number.
align Alignment of the table in the wiki page. Can be any valid HTML TABLE alignment value ("right", "left", etc.).
width Width of the table in the wiki page. Can be an integer (setting width in pixels) or a percentage such as "50%".
valign Vertical alignment of the table cells. Can be "top", "bottom", "middle".
halign Horizontal alignment of the table cells. Can be "left", "right", or "center".
cellpadding Number passed through as HTML TABLE padding option.
cellspacing Number passed through as HTML TABLE spacing option.

If the options are omitted, a generally good set will be chosen, and the events associated with categories with the "on agenda by default" flag will be used.

Examples

The following tag:

<OAFsEventList></OAFsEventList> generates the following table:

DateStartName
More events, with CSCs. this tag:

<OAFsEventList categories="**" limit=8>date start name csc</OAFsEventList> generates:

DateStartNameCSC
DateStartEndName

This example shows what is probably a more common use - an agenda list right-justified beside a block of text. The tag used in this case is

<OAFsEventList align="right" width="50%" categories="**" limit=10>date start end name</OAFsEventList>

CSC References

The clear sky charts that can be included in an event listing go through a layer of indirection. You use the OAFs Calendar Administration Page to define a CSC and give it a useful local name, and you define there the URL for the CSC's thumbnail image. The idea is to name CSCs in a way that associate them with event types, allowing the actual CSC URL to be changed.

For example, we define a CSC called "Kanata Chapters Sidewalk" and point it to the closest CSC. At the time I write this, that is Hillier Observatory's CSC. But by going through this level of indirection, it could be changed to some other CSC (e.g. Pinhey's Point) without having to go back and change all the events that use it. This indirection also minimizes the number of places you have to copy-n-paste the complex URL for a CSC, reducing the chances for error.

Administration Page

The addition of categories and CSCs required the creation of an administration page where categories and CSCs can be defined and edited.

To-Do List

Ideas for the calendar.

  • A "categories to reject" filter, applied after the "categories to include" filter, would allow some very basic boolean logic. I'd prefer to avoid having to do a full boolean algebra parser - want to try to live with a very basic category filtering system.
  • Maybe a "status" field for events: "confirmed", "tentative", "cancelled" etc.
    • Status could be reflected in some manner in monthly views (font, strikethrough, colour)
    • Status could be directly displayed in event views
Personal tools