Kalendus uses the Perl library FT.pm to handle HTML templates. FT.pm is a Perl library inspired by FastTemplate, a Perl and PHP3 library enabling CGI scripts to use HTML templates. The basic premise is to break an HTML page down into blocks that can be conditionally included or repeated, plus having variables that can be substituted into the HTML. I won't describe the Perl code to use FT.pm right now since it doesn't concern the design of the HTML pages.
An HTML template is a valid HTML file with comments inserted where conditional or repeated blocks are defined. These look like:
<!-- FT block_name --> Some HTML code... <!-- /FT block_name -->
where block_name is the name of the block. Since these
names are used in the Perl script, you don't want to change them.
Blocks can also be defined in a seperate file, if need be, and
inserted using a variable substitution. Blocks can be nested to
arbitrary depths. Block names must be globally unique.
Variables are also listed in the HTML files, surrounded by curly braces:
<P>The {variable_name} brown fox...</P>
In the Perl script, variable_name can be set to any
value, such as 'quick', 'lazy', or 'clever'.
The template for the month calendar is defined in month.html. Several variables are defined for the entire page.
| Variable | Description |
|---|---|
| {calendar} | The name of the displayed calendar. IVP has a calendar for each department and conference room. |
| {calendar_esc} | The name of the displayed calendar, encoded for use in a URL. |
| {calendar_image} | An image file associated with the displayed calander, typically used in the header. |
| {month} | The number of the displayed month, 1 through 12. |
| {month_name} | The name of the displayed month, January through December. |
| {month_image} | An image file associated with the displayed month, typically used in the header. |
| {year} | The four digit year. |
| {prev_month} | The number of the month before the displayed month. |
| {prev_month_name} | The name of the month before the displayed month. |
| {prev_year} | The four digit year of the month before the displayed month. (When displaying January, December is in the previous year.) |
| {next_month} | The number of the month after the displayed month. |
| {next_month_name} | The name of the month after the displayed month. |
| {next_year} | The four digit year of the month after the displayed month. (When displaying December, January is in the next year.) |
| {weekday} | The weekday block is repeated for each weekday, with {weekday} being assigned to the name of the weekday, Sunday through Saturday. |
Each week is a seperate row. The days use either day, today, or outside blocks, depending on what day of the month they are.
| Block | Description |
|---|---|
| <!-- FT day --> | Used for each normal day. Default background is light gray. |
| <!-- FT today --> | Used for the current day. Default background is darker gray. |
| <!-- FT outside --> | Used for days outside the current month. For instance, if the first of the month is Tuesday, outside blocks are used for the Sunday and Monday before the first. Default background is white. |
| Variable | Description |
| {mday} | The day of month, 1 through 31. |
| {EVENTS} | The events for the day. This is obtained from an FT.pm template defined in the event.html file. |
The FT.pm template for events is defined in the event.html file. Each day has at least three lines of events, filled out using the blank block if needed. This makes the rows roughly the same height unless numerous events are defined.
| Block | Description |
|---|---|
| <!-- FT stime --> | Conditionally includes the start time of the event, if it is defined for the event. |
| <!-- FT etime --> | Conditionally includes the end time of the event, if it is defined for the event. |
| <!-- FT blank --> | Repeated to fill out at least three lines, if there are less than three events for the day. |
| Variable | Description |
| {event_id} | The unique ID for the event; useful in URLs. |
| {color} | The user-selected color for the event, as an HTML hex color code. |
| {start} | The start time of the event, like '12:15 pm' or '1 pm'. |
| {end} | The end time of the event. |
| {subject} | The subject of the event. |
Each spanning event appears on a seperate row. The empty cells of the row use spanday, spantoday, and spanoutside blocks; the actually spanning event uses a spanevent block.
| Block | Description |
|---|---|
| <!-- FT spanday --> | Used for each normal day. Default background is light gray. |
| <!-- FT spantoday --> | Used for the current day. Default background is a darker gray. |
| <!-- FT spanoutside --> | Used for days outside the displayed month. For instance, if the first of the month is Tuesday, outside blocks are used for the Sunday and Monday before the first. Default backgroud is white. |
| <!-- FT spanevent --> | Used for the spanning event itself. Default background is set for each spanning events seperately. |
| Variable | Description |
| {bgcolor} | The background color for a spanning event. |
| {days} | The number of days, in this row, the spanning event spans. |
| {event_id} | The unique ID for the event; useful in URLs. |
| {start} | The first day of the spanning event, like '4/15'. |
| {end} | The last day of the spanning event. |
| {subject} | The subject of the spanning event. |
The form to select the calendar, month, and year (at the bottom of
the month calendar) is defined in the
select.html file. Each menu has a block
that is repeated for each menu item. The {selected}
variable is set to 'SELECTED' for the initially selected menu item,
and is empty otherwise.
| Block | Description |
|---|---|
| <!-- FT select_calendars --> | Menu of calendars to display. |
| <!-- FT select_months --> | Menu of months to display. |
| <!-- FT select_years --> | Menu of years to display. |
| Variable | Description |
| {calendar} | The name of the calendar. Either the displayed calendar, or the calendar for the calendar's menu item. |
| {calendar_esc} | The name of the displayed calendar, encoded for use in a URL. |
| {month} | The number of the month. Either the displayed month, or the month for the month's menu item. |
| {month_name} | The name of the month. Either the displayed month, or the month for the month's menu item. |
| {year} | The four digit year. Either the displayed year, or the year for the year's menu item. |
When editing an event, the
auth/edit.html template is used. In
general this uses straight substitions and menus, as described above,
of the event parameters. You may also use RADIO button or CHECKBOX
inputs instead of SELECT menus, using {checked} instead
of {selected} for the item to be checked.
| Block | Description |
|---|---|
| <!-- FT calendars --> | Menu of calendars. The user can select multiple calendars to put the event on. |
| <!-- FT colors --> | Radio group of colors. The selection of colors is configurable. |
| <!-- FT months --> | Menu of months. |
| <!-- FT years --> | Menu of years. I limit to the previous year and 5 years in the future, but that is configurable. |
| <!-- FT hours --> | Menu of hours. |
| <!-- FT minutes --> | Menu of minutes. I limit the user to quarter hours, but that is configurable. One could also use a free text INPUT instead of a SELECT menu. |
| <!-- FT repeat --> | Conditionally includes the code to choose how frequently an event is repeated. It only appears when creating a new event; when editing an event one cannot change the repeat frequency. |
| <!-- FT new --> | Conditionally includes the 'new event' button, if one is creating a new event. |
| <!-- FT update --> | Conditionally includes the 'update' and 'delete' buttons, if one is editing a one-time event. |
| <!-- FT update_many --> | Conditionally includes the 'update', 'update_many', 'delete' and 'delete_many' buttons, if one is editing a repeated event. |
| Variable | Description |
| {event_id} | The unique ID for the event. |
| {repeat_id} | The unique ID of a set of repeated events. |
| {calendar} | The name of the calendar to put the event on. (Repeated for each calendar.) |
| {subject} | The subject of the event. |
| {body} | The long description of the event. This is currently only displayed on the edit event form. |
| {color} | The HTML hex value of the color. (Repeated for each color.) |
| {color_name} | The name of the color. (Repeated for each color.) |
| {subject} | The subject of the event. |
| {calendar} | The name of the calendar to put the event on. (Repeated for each calendar.) |
| {month} | The number of the month, like 1. (Repeated for each month.) |
| {calendar} | The name of the month, like January. (Repeated for each month.) |
| {mday} | The month day, like 21. (Repeated for each day of the month.) |
| {year} | The four digit year. (Repeated for each year.) |
| {hour} | The hour in 24 hour format (0 through 23). (Repeated for each hour.) |
| {hourampm} | The hour in 12 hour format (12 am through 11 pm). (Repeated for each hour.) |
| {hourampm} | The hour in 12 hour format (12 am through 11 pm). (Repeated for each hour.) |
| {minute} | The minutes (00, 15, 30, 45). (Repeated for each available minute.) |
| {user} | The user name that entered or updated the event, if HTTP authentication is used. We just use basic authentication, not secure SSL. |
| {prev_calendar} | A small calendar of the previous month. |
| {curr_calendar} | A small calendar of the current month. (The current month is the month the event is being edited or added to.) |
| {next_calendar} | A small calendar of the next month. |
After creating or updating an event, the auth/confirm.html template is used. In general, this uses straight substitutions of the event parameters. Depending on whether the event is spanning or not, repeated or not, various blocks and variables are used.
| Block | Description |
|---|---|
| <!-- FT continuous --> | Used for continuous events (as opposed to repeated events). |
| <!-- FT datespans --> | Used for spanning events. |
| <!-- FT weekly --> | Used for events that are repeated weekly (or every 2 or 4 weeks) on the same day of week. |
| <!-- FT monthly --> | Used for events that are repeated monthly on the same day of month. |
| <!-- FT monthly_wday --> | Used for events that are repeated monthly based on 1st, 2nd, etc. day of week. (E.g. 2nd Tuesday of every month.) |
| <!-- FT dates --> | Used for non-spanning events. Repeated for each occurance of the event. |
| Variable | Description |
| {weekday} | The name of the weekday of the start date, like Sunday. |
| {month_name} | The name of the month of the start date, like January. |
| {mday} | The day of month of the start date, like 21. |
| {year} | The four digit year of the start date. |
| {end_weekday} | For spanning events, the name of the weekday of the end date. |
| {end_month_name} | For spanning events, the name of the month of the end date. |
| {end_mday} | For spanning events, the day of month of the end date. |
| {end_year} | For spanning events, the four digit year of the end date. |
| {nth} | For events repeated weekly, the period of weeks. Can be empty
(for 'every week'), '2nd', or '4th'.
For events repeated monthly, the week of the month. Can be '1st', '2nd', '3rd', '4th', '5th', 'last', '2nd to last', '3rd to last', '4th to last', or '5th to last'. |