Revision [2693]
This is an old revision of JwCalendar made by JavaWoman on 2004-11-30 20:26:41.
Calendar action
History
GmBowen posted a nice little Calendar action on GmBowenCalendar which drew a lot of comments (and suggestions), and which JsnX proposed to include in the upcoming (1.1.6.0) version of Wikka. I commented that I'd like to see the code "cleaned up" before inclusion, and offered to do that. The result is here.Different output
Data table markup
The original (including the ultimate original which we've traced the code back to - see the comments on GmBowenCalendar) code uses a table to present the calendar but the markup is that for a "layout" table, not a data table.What's the difference? A layout table has nothing but a table tag (table), table rows (tr), and table data cells (td) within the rows. However, a data table is to present data in relation to each other; a calendar clearly is a data table, showing dates in a month with day names labelling groups of dates (and possibly more). In order to show relationships between data, a data table uses not only table data cells (td), but also header cells (th) to label the data, and preferably a caption (caption) that labels what the whole thing is about.
A good article about marking up data tables:
Looking at a common "calendar face" the candidates for header cells and caption are obvious: clearly the (abbreviated) dat names are headers, and the name of the month at the top logically is a caption. That leaves the navigation, however, which I've moved to a separate section at the bottom. While I was at it, I took up DarTar's suggestion for a link (back) to the current month since moving the navigation links to the bottom left a space in the middle.
Making it accessible
Accessible table code starts with proper data table markup, but requires a bit more. To start with, the table should have a summary to explain what it's about; also, the header cells should actually be "linked" to the data cells they refer to, and obviously the navigation links (being just symbols here) need an explanation as well, which is added in the form of a title attribute. Similarly, the data cell for "today" (if shown) gets a title as well (since we should not depend on color alone to convey information). Finally a little trick suggested on an accessibility mailing list: using the abbr attribute on the headers to expand the day names (an inverse of the original purpose of this attribute, but some screen readers used by people with a visual impairment can make use of this).More about accessible table markup:
Extra functionality
"Dynamic" and "static" calendars
My variant of the Calendar action does all that the original GmBowenCalendar does, and one thing extra:- without any parameters, it generates a calendar for the current month, with navigation links, leading to:
- it picks up on URL parameters for month and/or year, and shows the calendar for the specified month, also with navigation links
- however, if parameters are provided in the action code itself a static calendar is shown for the month specified (taking the default for a missing parameter from the URL parameter(s) or the current month)
The result is that you can show a dynamic calendar which "reacts" to URL parameters in addition to any number of static calendars for a specific month.
I'll include code for a static month below - if my proposed code is implemented, you should see here a calendar for March 2006:
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | 4 | |||
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 12 | 13 | 14 | 15 | 16 | 17 | 18 |
| 19 | 20 | 21 | 22 | 23 | 24 | 25 |
| 26 | 27 | 28 | 29 | 30 | 31 |
(Until then you'd just see a calendar for the current month.)
Different code
A pattern for an action
The new code follows a specific "pattern" which I use for all my (new or modified) action code. In general it goes like this:- Constants section: A section where all constants are defined; this includes constants used as defaults for possible optional acrion parameters as well as constants defining user-interface strings (so that whatever needs to be translated for i18n is grouped together), and any other constants needed. Also "alsmost" constants like lookup tables are defined here.
- Parameters section: A section where parameters are read, and validated, using whatever is defined as defaults for optional parameters (constants, or dynamic defaults such as "current month"). In this case, invalid or otherwise unusable parameters are silently ignored (using defaults instead); depending on the purpose of an action, an invalid parameter (or missing required parameter) may generate an error message instead.
- Data preparation section: A section where input is further processed into all variables needed to generate the output.
- Output section: At this point all data is prepared, so the final section does nothing but generate output: no new data is generated here, we only look up data prepared in the parameter or data preparation section (we can loop through an array though). (This is the same approach as with using a templating solution such as Smarty.)
This results in a clear and consistent logic of the code, and separation of process and data from presentation of the data.
Dealing with multiple calendars
The original code had a little function to derive the last day in a month; not only was this a somewhat inefficient, but having a function conflicted with including the code multiple times. The function has been replaced by (simpler) code in the data preparation section.Calendar generating logic
Another difference is in the logic used for the start of the first week (when we may need to generate "blank" cells): this is taken out of the (original) loop, resulting in more logical and efficient code. The inverse of that is added at the end so that where necessary blank cells are added at the end of the table (having fewer cells in a row is not valid markup!).Internationalization
Apart from two or three strings (defined in the constants section), the output produced by the action is completely internationalized: by using the appropriate functions the names for months and days (short and long) are already corresponding to the defined locale.Documentation
First, there is a documentation block at the start in phpDocumentor∞ format; from this documention block (combined with that for other Wikka code) we will not only be able to generate developer's documentation but also (with a special little Wikka parser) dynamic end user's documentation for the action.In addtion, there are lots of other comments throughout the code; for instance, every line that contains code dealing with internationalization is marked with 'i18n'.
