The wiki calendar extension is currently very primitive, and is mainly for personal use only. The code is not ready for release yet, but as it is in use on a couple of my private wikis I am documenting usage and features here.
Feel free to contact me if you have any interest in this extension. Note that there are several more developed calendar extensions on the MediaWiki website.
To create a calendar, you enclose a set of appointments in calendar tags. Each line is a single appointment. All dates currently need to be in SQL format, but I hope to make this more flexible in the future.
- style: Set the format of display. Allowed values: "weeks" or "months" (default). "weeks" is a bit experimental and probably best avoided...
- start: Sets the start date for the calendar. If omitted it will use the date of the first appointment, rounded to the start of the month/week (depending on chosen style). "now" is a valid start date.
- end: Sets the end date for the calendar. If omitted uses the latest appointment end date, rounded to the end of the month/week (depending on chosen style).
- dateformat: The format for displaying dates, using the PHP strftime() format.
Appointment rows are any rows that begin with a recognised date. Currently only MySQL dates are allowed. Any other lines are ignored, so blank lines may be used to separate appointments, and comments may be added by starting a line with #. (It currently doesn't need to begin with #, but for forward-compatibility purposes it is recommended that you use this character.)
The row contains the following elements separated by colons, in this order, with only the start date being required:
- DATE - Either a single date in MySQL format (YYYY-MM-DD) indicating a start date, or two dates separated by commas (YYYY-MM-DD,YYYY-MM-DD) indicating a start and (optional) end date.
- DESCRIPTION - Text description of the appointment. May contain any characters.
- FLAGS - One or more flags may be added to the end of the string, separated from each other with colons. There are two types of flags, and only one of each group can be set (if more are set, only the last is used):
- Type: One of 'busy' or 'tentative'. These currently modify the item's Color (busy, the default, leaves it as is, and tentative makes it paler) but this is liable to change greatly in the future.
- Color - One of the recognised colours (default: 'blue'). Changes the base color. Liable to change in the future. Current list of colours: 'red', 'green', 'blue', 'orange', 'yellow', 'purple', 'cyan'.
<calendar start="2007-12-01"> # Comment line - this is ignored. 2007-12-13:Buy turkey:red 2007-12-19,2008-01-03:Christmas hols 2007-12-26:Visit the relatives?:tentative:green 2008-01-02:Doctor's appointment, 9:15am </calendar>
A note about parsing
Each line is currently parsed in the following manner:
- Split the line up on colons, to give a set of data elements
- First element is the date - if not a valid date (or pair of dates) then the line is ignored
- Look at the remaining elements, working backwards from the end:
- Blank elements are ignored
- Valid Colors are removed - the first match sets the Color property for the line, the rest are ignored
- Valid Types are removed - the first match sets the Type property for the line, the rest are ignored
- Once we get to an item that is not a valid color or type, and is not blank, then we stop our parsing and anything that is left is the description. We join the remaining elements back together with colons to give a single string.
The upshot of this is
- Flags can be in any order
- Empty flags are ignored
- The description cannot end in a colon, or a colon followed by a valid flag. If it does, they are removed (with any flags being acted upon as appropriate)
- However the description may contain colons elsewhere (i.e. not at the end)