Add-Ins are files of pre-defined events that you can include in your calendars. For instance, you might want to include events like holidays or phases of the moon in all your calendars. Calcium comes with a few such files, and you can easily create your own additional ones.

To select which Add-Ins to include in a calendar, follow the Add-Ins link from the Settings page for that calendar.

The Add-Ins page lists all the available Add-In files. Select the checkbox for each Add-In you want to include, and if you like, specify the colors to use for the events from that Add-In. If you leave the colors blank, the default colors for events in the calendar will be used. You can also specify that a border should be drawn around each event.

You can also enter identifying text that will be displayed with each event. It will appear above the event, in a smaller font. If you like, you can use any valid HTML in this text.

Press the Save button, and the selected Add-Ins will be displayed the next time you view your calendar.

You can create your own Add-In files. To do so, create a new text file in the Calcium directory data/AddIns. This file must be in a special format; see the description below. You can also look at the existing Add-In files for examples.

Any file you place in the data/AddIns directory will be converted into a Calcium database. Simply put a new file in data/AddIns, or edit an existing one; there's no special procedure needed to import an AddIn file, or re-compile one if you make any changes.

Note: On a Unix system, file permissions on new AddIn files must allow the web server to read it.

An Add-In file can consist only of:

• blank lines
• comment lines, which start with the # character
• a single line describing the Add-In file
• multiple lines specifying events

The first non-blank, non-comment line in the file will be used as the description of the Add-In.

After the description line, any non-blank, non-comment line is interpreted as an event specification. There are three types of events you can have in Add-In files, in any order:

• Events Which Occur Once
• Events Which Repeat On The Same Day Every Year
• Events Which Repeat On the Nth Weekday of a Month

An event line consists of event text (which can contain any text except the | (vertical bar) character), followed by a vertical bar, then the date specifier.

HTML is allowed in event text, so you can included text formatting, images, links, etc.

The format of the date specifier determines whether the event repeats or not. See below for details and examples.

    # These events are on single days; make sure you use 4 digit years!
    #      yyyy/mm/dd   or   yyyy/m/d   or   yyyy/mm/d   or   yyyy/m/dd
    Man on the Moon                                | 1969/7/21
    <img src="/images/eclipse.jpg" alt="Eclipse">  | 2001/6/21
    

    # These events are on the same day every year; just specify month and day
    #    mm/dd
    Independence Day (USA)              |  7/4
    New Year's Day                      |  1/1
    The Ides of March                   |  3/15
    

    # nth/day of week/month
    # so, 4/1/9 means '4th Monday in September'
    # Use '5' for 'last', e.g. 5/3/11 means 'Last Wednesday in November'
    # Monday = 1, Tuesday = 2, ..., Sunday = 7

    Thanksgiving (USA)                  | 4/4/11

    # US DST goes from the first Sunday in April to the last Sunday in October
    Start Daylight Savings Time         | 1/7/4
    End Daylight Savings Time           | 5/7/10
    

To remove an AddIn file, first make sure no calendars are including it, then delete its text file from the data/AddIns directory, and its datafile(s) from the data/AddIns/dat directory.

(If you delete the Add-In file while a calendar is still including it, you'll see an error message when trying to display that calendar. If this happens, re-create the AddIn file in data/AddIns with the appropriate name (it can be an empty file), then go to the calendar's Setting page, deselect the AddIn from the list, and save.)