iPlanet Calendar Server 5.0 Customization Tips |
Customization Tips
WARNING!
This document is an in-progress document defining a not-entirely-frozen schema. Use it to familiarize yourself with the calendar XML schema but recognize that it is:
Not entirely complete.
This document provides basic information useful for programmers customizing the Calendar Express interface for iPlanet Calendar Server 5.0. It includes the following sections:Not written in stone. It is possible we will want to improve upon tag name or output before freezing this document.
Customization Overview
Customization Overview
The Calendar Express interface for iPlanet Calendar Server 5.0 is written using XML and XSLT to generate the HTML for each view. This architecture was selected, in part, in order to provide ease of customization. The XML files and the corresponding XSL files are what make up the user interface. The customer can customize the user interface by modifying the existing files, or writing their own XML and XSL files. The customer cannot change what XML tags the iCS 5.0 XSLT processor understands, but they can change which of those tags the XML files contain, and they can change how the XSL files use the XML data. Thus, anyone customizing the user interface will need to understand the XML schema detailed in this document in the section titled Calendar Express XML Tags.The HTML that creates the Calendar Express user interface is a frameset with two or more frames in it. For example, the main views (overview, weekview, etc.) consist of a header frame, a toolbar frame and a data frame. While customizing, you can add frames to the frameset, or just modify those frames that already exist as part of the frameset. The way that the frameset and frames are established is explained more fully in this document in the section titled Calendar Express XML Tags".
For customers who want to write their own client, not based on the Calendar Express XML/XSLT user interface, there is an alternate protocol, WCAP, with which calendar data may be requested in several output formats. For information about WCAP please read the iPlanet Calendar Server Programmer's Reference.
XML and XSLT Introduction
As a general description, XML is not a language, and in fact it doesn't really do anything. It provides a way of structuring information and sending it from one piece of software to another. The definition of XML does not in any way dictate or limit the type of information that it can describe. It simply provides rules for the way information can be categorized and related to other information. Each application using XML defines tags or nodes (in a tree structure) that are appropriate for its needs. There is no universal definition of tags across applications. Thus, applications that plan on sharing XML data must agree on a common tag set and the relationships between the XML nodes. For example, a banking application might define tags such as <branch>, <customer> and <account>, while an application that dealt with calendaring would want tags called <calendar>, <date>, and <user>. The application also defines what attributes make sense for a given tag and what are reasonable relationships between tags. In the banking example, it makes sense to have the <customer> nodes as children of the branch node and the <account> nodes as children of the <customer> nodes in order to keep track of what customers are at what branches, but for a different application it might make sense to have a <branch> node as a child of a <customer> node (when listing all the branches with which that customer has accounts).In a standard XML/XSLT scenario, the XML file that you create is the one used by the XSLT processor. In the case of the iCS5.0 server, however, the XML files you create are really a prototype, or generalized description of the data needed. The server then preprocesses the XML prototype file for a particular view and creates a specific instance of the XML file depending on the current user, the current time and other appropriate state information.
Figure 1 illustrates this preprocessing of the XML prototype files.
Figure 1 iCS 5.0 XML Processing
This preprocessing allows a very limited set of XML files to serve the needs many users, calendars and dates. For example a particular XML file might request user context information (user name, default calendar, preferences) by using the iCS5.0 XML tag <usrctx/>. The tag does not indicate the name of the user for which it wants information, nor the current calendar being viewed (a user may have multiple calendars). The server uses current state information (provided in the original HTTP command) to expand the simple <usrctx/> tag into the completed tag set <usrctx>...</usrctx> which now also contains child nodes such as <user>...</user> (providing basic user information), <userprefs>, <calendarList>...</calendarList> and so forth. For the first pass (frameset pass), the server uses the logged-in user in the usrctx expansion.
XSLT provides a way of parsing an XML file (or tree) and generating a different type of output. It transforms (hence the T in XSLT) the XML into something else, based on one or more XSL files associated with the XML file.
In the case of iCS 5.0, the transformed output is HTML, which is best displayed on either Netscape, or Internet Explorer, 4.x and later browsers with JavaScript 1.2. In iCS 5.0, the XSLT processor is part of the server.The XSLT transformation (HTML Generator in Figure 1) will be applied to the filled in XML instance, and it will assume all the information is there when writing a header. In the earlier example, that includes the current user's name.
In summary, then, keep in mind that the XML file you write or modify will only contain the generic data required for that view. The server will create an internal copy of that XML file and modify it to contain complete data for that view. The XSL file will then be used to transform the current instance of the XML file into HTML.
Note It can be helpful to view the filled out, preprocessed XML file when working with XSL. Instructions for doing so are included in this document in the section titled Starting the Process: Request for a View.
An XSLT transformation requires three things:
The input XML file that describes the data to be displayed.
For links to more general information about XML,XSL and XSLT, see the section "XML/XSL Links".One or more corresponding XSL files that describe how the data is to be displayed.
An XSLT processor that knows how to parse the XML file, store it in some internal structure, and operate on it to create the resulting transformed output file.
The rest of this document assumes that the reader is familiar with the concepts behind XML and XSLT.
Three Levels of Customization
There are three levels of customization, progressing from the simplest to the most complex:
Change the look of an existing view without changing the data contained in the view.
Adding a new or different banner somewhere on the page.
Changing the position or look of elements on the page.
Removing some of the information on the page.
Change the content of an existing view.
- To achieve this level of customization, you will need to change one or more of the XSL files, which tell the server how to format the data from the XML file. You will not need to modify the view's XML file, since the XML file tells the server what data is needed for the view.
Adding a list of today's tasks and events to the top of the yearview calendar.
Changing the one week lookahead view on the overview page to a two week lookahead.
Create a new view to provide calendar data in some different way.
- For this level of customization, you will need to modify the view's XML file for the necessary additional data. The corresponding XSL file must also be modified to add formatting for the new data.
Providing a quarterly view showing three months at a time, with the days containing a task or event highlighted in red.
Providing a comparison view with individual calendars lined up horizontally.
- This level of customization requires creation of both a new XML file that defines the data for the view, and a new XSL file that defines how to format the new view's data. You may take advantage of reusable templates available in other XSL files. Also, you must modify at least one of the other views so that this view can be reached from somewhere in the user interface, by way of a link or a tab.
Starting the Process: Request for a View
A server receives a request for a particular view as part of a URL command line. For example:http://servername:port/command.shtml?view=viewname:subview&
id=12345678&......This command is parsed and the server picks up the view name and the optional subview. If there is no subview, this is said to be a frameset pass.
View file names must directly correspond to the value of the view parameter. For example, in the sample command above, the value of view is viewname, thus the XML file name must be viewname.xml. Once the view XML file is identified, it is loaded and preprocessed.
Preprocessing expands each of the recognized <calendar> tags (see Calendar Express XML Tags) as appropriate according to the following four criteria:
Current date/time (time context).
Each tag is expanded according to its own unique rules. The rules for each tag are detailed in the Calendar Express XML Tags" section that follows. The preprocessed and expanded XML file is then transformed into formatted HTML output by the XSLT processor as specified by the viewname.xsl file.Any additional arguments that were in the original URL line (attributes).
The current time context only ever refers to one day, defined as no more than 24 hours, from midnight of the day to one second before midnight of the next day. (It can be limited to a smaller period.).
Component information, that is, event and task information, is only ever provided for the current time context. When collecting information for longer time periods, such as a week, you are really collecting information for a set of days. Tags are provided to make this convenient for obvious sets of days, such as weeks, and months. It is more complicated, but possible, to request data one day at a time.
Note Keep in mind there may be multiple ways to request the data that you need.
Calendar Express XML Tags
This section lists the iPlanet Calendar Server 5.0 XML tags. iPlanet Calendar Server's UI generator code recognizes only these tags. You may not create your own tags. Any unrecognized tags will be treated as data and passed through to the file unmodified.
Special Framework Tags
Four of the iCS 5.0 XML tags are special tags that you use to provide a framework for the other tags:
<calendar>
<group>
- The <calendar> tag starts each of the view XML files. This tag sets up general calendaring information. All of the XSL files start processing nodes that live below this node. If it is not present, no processing will happen. This is the only tag that checks the frameset pass.
- For a frameset pass, that is, when an entire view, such as the overview, has been requested, global information is set up under the <calendar> node. Then, appropriate subview (group) commands are set up which are passed back to the server. One command is set up for each of the <group> nodes that exist under the calendar tag. Each subview command is added as a new frame text node.
- For a non-frameset pass, The same general information is set up including the current view information. In addition if there are any errors those are added to the file under the <calendar> node.
- Use <group> tags within the <calendar></calendar> tag set to indicate all the subviews that should get processed for this view.
In the frameset pass, a command is set up for each group using the current view name plus the subview corresponding to the name of the group. For example:
<usrctx>http://calendarservername/command.shtml?view=viewname:
groupname&id=12345678&....
On a non-frameset pass, only that group matching the name of the subview given in the original command will be processed.The only exception is if the subview being processed is main and we are creating a printable version of the view.
- The command also maintains any other arguments that may have existed in the original command except the username and password. Nothing below the <group> tags will get processed.
<timectx>
- The <usrctx> tag can exist anywhere in the XML file, but it is customarily placed somewhere after the <calendar> tag, and before the <group> tags. It contains information specific to this particular user. This information will not change at any point during the view. Usually only one <usrctx> tag exists in any given view file.
- The <timectx> tag must occur at least once after the <calendar> tag and before any other tags, with the exception of the <usrctx> tag. In the course of processing this tag, the server sets up internal time state information. Other tags may be dependent on this information. That is why it must be inserted before these dependent tags. Since the <usrctx> tag is not dependent on any time state information, its processing is not effected by its placement relative to the <timectx> tag.
XML Tags Recognized by Calendar Express
Table 0-1 lists the recognized tags, gives a short description of each, lists otherat.
Tag Details
<button/>
Use this tag to produce the action that will be used for this button's onclick.The attributes tell the server what type of command to set up:
name, which is used for identification and can be any text.
This tag is used in many of the calendar XML files, such as overview.xml.type, which indicates the type of command the server should create.
target, which must either be set to the value "main", or it will be assumed to be a URL.
- If it is a URL location, the command is set up to point to that target directly if it begins with "http", or to the indicated file in the server's standard http location.
- If the target is "main", the command will be set up as a text node of the original button. It will have the form:
- javascript:x(`<type>');
- where <type> is replaced by whatever the type attribute value was set to. This is a function set up in the javascript.xsl.
The following examples illustrate the types the are understood:
<button name="ok" type="store" target="main"/>
<button name="cancel" type="cancel" target="main"/>
<button name="help" type="help" target="main"/>
<button name="delete_calendar_group" type="delete_calendar_group"
target="main" /><button name="unsubscribe" type="unsubscribe" target="main" />
<button name="ok" type="ok" target="main" />
<button name="find" type="find" target="main" />
<button name="add_user" type="add_user" target="main" />
<button name="remove_user" type="remove_user" target="main" />
<button name="add_owner" type="add_owner" target="main" />
<button name="remove_owner" type="remove_owner" target="main" />
<button name="delete" type="delete" target="main"/>
<button name="add_cal" type="add_cal" target="main" />
<button name="remove_cal" type="remove_cal" target="main" />
<button name="export_add_cal" type="export_add_cal" target="main" />
<button name="export_remove_cal" type="export_remove_cal"
target="main" />
<caldata/>
This tag is expanded to contain all the data pertinent to the calendar indicated in the URL by either (in this order) e_newCalCalID, newCalCalID, or calendarID.This tag is used by new_cal.xml
An example of the expanded tag follows:
<caldata e_writeAccessAllowed="true" shortCalID="jdoe"
newCalCalID="jdoe" viewCommand="http://
calendarservername/?calid=jdoe&security=1" e_isDefaultCalendar=
"true" displayName="John Doe" description=
"Work Calendar for John Doe"
tzid="" freebusy="0" domain="calendardomainname">
<OtherOwner name="fred"/>
<privacyEntry type="otherOwners" name="Other Owners" entryIdentifier="5" grant="0" availability="1"
schedule="1" read="1" delete="1" modify="1"/>
<privacyEntry type="anyone" name="@" entryIdentifier="2"
grant="1" availability="1" schedule="1" read="1" delete="0"
modify="0"/>
</caldata>If no calid was specified, a new calendar is created. The output is:
<caldata e_isNew="1" e_writeAccessAllowed="false"/>
<calendar/>
This is the base tag for all iCS 5.0 XML documents. See general notes regarding the Special Framework Tags.This tag is used in all calendar view XML files, such as overview.xml.
The following examples show the information added as the XML tag is expanded:
For a frameset pass:
<calendar viewname="overview" staticBaseURL=
"http://calendarservername.domain.com:port" commandBaseURL=
"http://calendarservername.domain.com:port top="true"
(As attributes on the calendar tag)
<GlobalInfo gID="e2nm0b2qb2mr6s6w9" gCurView="overview"
gOldView="overview" gDate=""/>
(As child nodes:The global information that is used by the JavaScript functions.)
For a subview pass, the information added will be: (As attributes on the calendar tag)
- For each named group, a subview command string is set up:
<frame>
http://calendarservername.domain.com:port/command.shtml?
view=overview:toolbar&id=e2nm0b2qb2mr6s6w9&date=&
amp;prevView=overview&view=overview&
id=e2nm0b2qb2mr6s6w9&group=&security=1<frame>
http://calendarservername.domain.com:port/command.shtml?
view=overview:main&id=e2nm0b2qb2mr6s6w9&date=&
prevView=overview&view=overview&id=e2nm0b2qb2mr6s6w9&
amp;group=&security=1
staticBaseURL="http://calendarservername.domain.com:port"
commandBaseURL="http://calendarservername.domain.com:port"
view="toolbar" tab="1">
<calgroup/>
The <calgroup> tag is expanded to provide calendar information about a specified group of calendars, or as a default, all subscribed calendars. If the argument isAllGroup=true is part of the URL command line, then it takes precedence and all subscribed calendars will be included. If isAllGroup is not present and the argument group is present, the server attempts to find that group within the user's definitions. If the group is found, then the <calgroup> node will be filled with the calendars making up that group. If the server can't find the group, the server will default to all calendars.When filling out this tag for a specific group, the server includes an editCommand and a viewCommand. But if filling it out for all calendars, no edit or view commands will be included. The URL command line argument groupEditor indicates which view to set in the editCommand.
<calgroup groupEditor="new_group"/>
<calgroup groupEditor="new_group" calendarEditor="new_cal"/>
An example of the tag expanded:
<calgroup groupEditor="new_group"
editCommand="http://calendarservername:port/command.shtml?
view=new_group&id=b8te8vx95ut9o3h5s&date=20010207T161409
&group_index=0&tab=1&prevView=overview&
group=allgroups&security=1"
viewCommand="javascript:parent.jmain.newViewGroupCommand
('groupview','','true','allgroups')"
name="allgroups" isGroup="true"><groupcal name="John Doe" addr="jdoe"
editCommand="http://calendarservername:port&
newCalCalID=jdoe&tzid=&e_ACL=@@o^a^r^g;@@o^c^
wdeic^g;@^a^sf^g&tab=1&prevView=overview&
group=allgroups&security=1"
unsubscribeCommand="http://calendarservername:port/
command.shtml?view=calendar_groupview&security=1&
id=b8te8vx95ut9o3h5s&editCommand=unsubscribe&
calID=jdoe"
viewCommand="javascript:parent.jmain.newViewCommand
('overview','','true','calid=jdoe')"/>
</calgroup>
<command/>
This tag is used to establish an appropriate command for execution. Each command must have a defining type. The options are listed below. The <command> tag and its attributes are left in place for referencing, but the actual command is added as a text node of this command node. In some cases it will be a JavaScript command, otherwise it is a URL.For convenience, these examples are divided by type:
type="cmd_dialog"
- A cmd_dialog will set up a javascript:parent.newPopupCommand(). The dialog indicates which view to use for the popup. The rest of the arguments are established in the server, based on the dialog chosen and the current time context. Other attributes may only have meaning for the particular view, for example:
width and height will override default width and height settings.
additionalAttributes will be passed along directly to the newPopupCommand, which in turn adds them blindly in to the command string being built up.
date=from_form or date=from_user specifies where the date should be set from. from_form means get the date from the form in the same window. from_user (default behavior when not set) means get the date from the current time context.
<command name="new_event" type="cmd_dialog" dialog="new_event"/>
type="cmd_event_date"<command name="jump_to" type="cmd_dialog" dialog="jump_to"
date="from_form" width="300" height="350"/><command name="new_group" type="cmd_dialog"
dialog="new_group" additionalAttributes="e_isNew=1"/><command name="new_event" type="cmd_dialog"
dialog="new_event" prevView="dayview"
additionalAttributes="roundtime=1"/><command name="recurrence" type="cmd_dialog"
dialog="task_recurrence" date="from_form" dontSetTab=""/>
type="cmd_view"
- A cmd_event_date is a way of modifying a form's local date information relative to the dtStart of the current event.
- This is currently used in the availability popup for new events. The local date can be reset on the event. The duration attribute is required for this command type.
<command name="back" type="cmd_event_date" dur="-P1DT"/>
type="cmd_url"
- A cmd_view maintains the current time context, but changes the view as specified. It does this by creating a newViewCommand JavaScript function.
- If the nodata attribute is set then don't set the indicated value in the command line. Currently this only works for calid.
- The following two commands create the two JavaScript functions, respectively:
<command name="calendar" type="cmd_view" view="overview"/>
<command name="calendars" type="cmd_view" view="calendars"
nodata="calid" />javascript:parent.jmain.newViewCommand('overview:main',
'20010112T105051','true')javascript:parent.jmain.newViewCommand('calendars',
'20010112T105042','true')
type="cmd_action"
- The cmd_url generates a url and sends it in a JavaScript call that opens a new window. The target indicates which file to open. If the target is not absolute (starting with "http://") then set it up to pick up out of the local hostname:port/language_dir.
- The command below generates the JavaScript call which follows it:
<command name="help" type="cmd_url" dialog="help"
target="calhelp5.htm"/>javascript:var newWindow=window.open('http://calendarservername
.domain.com:port/en/calhelp2.htm');
type="cmd_window"
- Currently cmd_action is only used for logging out and is in fact hardcoded for that. It generates the command indicated below.
<command name="logout" type="cmd_action" action="logout" option="$host_address"/>
- The following JavaScript call results:
javascript:parent.jmain.newViewCommand('logout','','true')
- The cmd_window is used to create a JavaScript function that opens a new window (which is different than a dialog in that it has "chrome" meaning it has a control panel and controls). Three important attributes are:
dialog indicates the view to put in the new window (not optional).
width and height can be used to override default sizing (optional).
date=from_form or date=from_user specifies where the date should be set from. from_form means get the date from the form in the same window. from_user (default behavior when not set) means get the date from the current time context. (optional)
type="cmd_date"
- The command below generates the JavaScript call that follows it:
<command name="print" type="cmd_window" dialog="print"
width="800" height="600"/>javascript:parent.newPopupCommand('overview:print','','&
tab=1','extraargs','979325442','600','800','true')
type="cmd_subdialog"
- A cmd_date is used to change the date for the current view by modifying it using the dur string relative to the current time context. It does this by creating a newViewCommand JavaScript function with the view maintained and the date new.
- This command:
<command name="back" type="cmd_date" dur="-P1DT"/>
- generates:
javascript:parent.jmain.newViewCommand('overview:main',
'20010111T000000','true')
<config/>
This tag is not expanded. It provides a convenient way to group configuration choices. This tag is used in ui_config.xml, simple_config.xml, and the nogroup_config.xml files.<config>
<!--<userpref name="_DebugMode" default_value="on"/> -->
<datactx/>
This tag causes the current calid or group id (or default calid if none is specified on the argument line) to be added as a child. The <datactx> tag is used in the overview.xml file.The <datactx/> tag expands to:
<datactx>
<Data calid="jdoe"/>
</datactx>
<day/>
This tag isn't expanded by the server, but is a useful way to group information. The related XSL file knows to look for particular information within this tagset.The <day> tag is used int he overview.xml file.
<disable/>
This tag is used to turn off certain features so that they are not available in the user interface. It is specifically for customization and is not used by the shipped product UI. It specifies either an entire view or a particular tab of a view that should not be displayed. When parsing this tag, the view and optional tab is added to a blocking list, which is checked before any particular view processing occurs. The <disable> tag is shown in two files: simple_config.xml and nogroup_config.xml.In the first example below, only the specified tab of the new_event view would be disabled. In the second example, the entire view would be disabled.
<disable view="new_event" tab="4" />
<disable view="groupview_dialog" />
<errorslist/>
This tag is used to report all errors that the server has encountered back to the UI for display. If the URL command line argument option is set to "count" the server returns only the number of errors for the current calendars, and not the error messages. If this option is not set, the server picks up the user's current calendar list, either from a calid or group argument, or if neither exists, uses the default calendar, to retrieve any outstanding error information from the database for these calendars.If the calendars specified do not exist, or there is a permission problem for the calendar, an error will be returned also. Recurring events will not cause multiple instances of the same error. However, all errors stemming from different causes will be reported.
This tag is used in most of the main XML files, such as overview.xml. The count-only option is used in the dayview.xml file.
The following examples show that a count of the errors may optionally be requested.
<eventdata/>
This tag is used to provide information about a specific event. It causes an event child to be added to the <eventdata> tag. The event detailed is either specified by the uid on the URL command line, or if none is specified, a default is built up. This tag is used by the new_event.xml and reply_event.xml files.Note that the format of the event data is the same whenever an event is printed. So when an event is one of many in a <listEventCanvas> tag, or anywhere else, it will always have the same format as the following example.
<eventdata defaultStartHour="8" defaultEndHour="16"
includeAvailability=""/>then the filled out XML looks like:
e_Summary="LaterMeeting" e_Summary_urlencoded="LaterMeeting"
e_writeAccessAllowed="true"e_deleteAccessAllowed="true" e_Calid="jdoe" e_org_Calid=
"jdoe" e_uid="3a64c0b2000062b80000000500000fd1"e_rid="0" e_Description="a description goes here" e_Location=
"a location" e_OrganizerEmail="jdoe@domain.com"e_Organizer="jdoe" e_Language="en" e_DtStartTZID=
"timezonename" e_allday="0" e_repeatModifier=""e_dtCreated="20010116T214418Z" e_dtModified=
"20010116T224600Z" e_dtstart="20010116T233000Z"
e_existingRRule=""e_rrule_notset="true" e_rruleChanged="false" e_dtend=
"20010117T003000Z" e_durhour="01" e_durmin="00"e_iSequence="1" partstat="2" rsvp="TRUE" e_attendee_0="jdoe;
PARTSTAT=2;STATUS=2;RSVP=1;CN=John Doe;X-NSCP-CALID=jdoe"
AttendeeList="true"><StartTime iso="20010116T153000" year="2001" month="01" date=
"16" hour="15" minute="30" seconds="00" dow="3"
weeknum="3"/><EndTime iso="20010116T163000" year="2001" month="01" date=
"16" hour="16" minute="30" seconds="00" dow="3"
weeknum="3"/><attendee userid="jdoe" partstat="2" CN="John Doe" RSVP="TRUE"
X-NSCP-CALID="jdoe"/><edit_command>
javascript:var x=newWindow=window.open
('http://calendarservername:port/command.shtml?view=
new_event&tab=1&id=2mhs6bhb2meb&date=
20010116T142225&uid=3a64c0b2000062b80000000500000fd
1&calid=jdoe&i_tab=1&prevView=new_event:
main','2mhs6bhb2meb3a64c0b2000062b80000000500000fd1',
'height=550,width=650','false')
</edit_command>
<exportdata/>
This tag expands to list exportable calendars. The list is created from the argument e_ExportCalid_# in the URL command line (with the numbers starting at 0). Each exportcal item has a calid attribute set to the calendar name. There is a one-to-one correspondence to the number of e_ExportCalid_# argument entries and the number of exportcal entries in the tag expansion. Thus, if the input argument listed three calendars (any subscribed-to calendar that you have the proper permissions for), then there would be the same three calendars in the expanded tag.e_ExportCalid_0="jdoe";e_ExportCalid_1="jdoe:secondaryname1";
e_ExportCalid_2="jdoe:secondaryname2"causes the tag to expand as follows:
<exportdata>
<exportcal calid="jdoe"/>
<exportcal calid="jdoe:secondaryname1"/>
<exportcal calid="jdoe:secondaryname2"/>
</exportdata>
<formdata/>
This tag causes a formdata element to be created. This element contains the information required to set up the form, and the context information that the server will use when processing each action. The information varies according to the command URL arguments. For example if a group is specified, then group information will be added as an attribute. This tag is also state dependent. That is, if a previous tag caused an event to be set up, then the event data will also be included. The type attribute will be maintained untouched for subsequent sorting during form processing. This tag is used by any view that needs form data, such as new_task.xml.The following examples show the different types of forms available:
<formdata type="add_calendar"/>
<formdata type="change_timezone"/>
<formdata type="errors_list"/>
<formdata type="event_recurrence"/>
<formdata type="search_for_cals"/>
<formdata type="groupview_dialog"/>
<formdata type="invitations_list"/>
<formdata type="reply_event"/>
<formdata type="search_for_components"/>
<formdata type="task_recurrence"/>
The following is an example of the expanded tag after processing:
<formdata type="new_event" id="2mhs6bhb2meb" view="formstuff"
calid="jdoe" date="20010116T144622"prevView="groupview" myaction="" action=
"http://calendarservername:port/command.shtml" e_Summary=""e_Summary_urlencoded="" e_isNewEvent="true"
e_writeAccessAllowed="true" e_deleteAccessAllowed="true"e_Calid="jdoe" e_org_Calid="jdoe" e_rid="0" e_Organizer="jdoe"
e_DtStartTZID="timezonename"e_allday="0" e_repeatModifier="" e_dtstart="20010116T230000Z"
e_existingRRule="" e_rrule_notset="true"e_rruleChanged="false" e_dtend="20010117T000000Z" e_durhour="01"
e_durmin="00" e_iSequence="0"e_attendee_0="jdoe;PARTSTAT=2;STATUS=2;RSVP=1;CN=John Doe;
X-NSCP-CALID=jdoe"partstat="2" AttendeeList="true" e_alarm_on="0" i_tab="1"
i_tabswitch="0" i_mainview="main" i_subview="main">
<group/>
This tag is used to indicate all the subviews that should be processed for this view, and to define what frames are used in the HTML file. This tag is not expanded during processing.The following is an example of the listing of subviews in a view using the <group> tag:
<group name="main" view="dayview">
<invitationslist/>
This tag causes the server to output the count and a list of all outstanding invitations (those to which the user has not replied). The server picks up the user's current calendar list either from the calid or group arguments in the URL command line. If neither exists, it uses the default calendar. The server then retrieves all outstanding (unanswered) invitations from the database for these calendars. Each invitation generates an <Event> tag, which is expanded and output in the same form used for <eventdata>.Optionally, only the count of the outstanding invitations may be output.This tag is used in the invitations_list.xml file and, as the count only, in most main views.
In the example below, both the count and the list of outstanding invitations will be output between the <invitationslist> tag delimiters:
In the example below, only the count will be output:
<invitationslist option="count"/>
<listeventcanvas/>
This poorly named tag expands to show all the components, task and event data, pertinent to the day specified in the time context. If the includeavailability option is set, the freebusy status for all the included calendars for that day is also included in the expansion. It can request the data in several formats. The output format is the same as that described by the <eventdata> and <taskdata> tags.The following examples show various permutations in the use of this tag:
<listEventCanvas sort="group" defaultStartHour="8"
defaultEndHour="18"/><listEventCanvas sort="group" defaultStartHour="8"
defaultEndHour="18" includeAvailability="" option="minor"/><listEventCanvas sort="overlap"/>
<listEventCanvas sort="overlap" option="minor"/>
Table 2 explains the attributes for this tag.
The three sort types cause the listed components to be ordered differently:
Time Order
Overdue incomplete tasks.
Overlap OrderChronological listing of tasks and events due today.
Today's tasks with no time assigned to them.
Group Order
- Components are listed in the same order as with the "time" setting, but components of like type, or those sharing an overlapping time block, are listed as children of a specific component group. For example, all overdue tasks are children of a component group of type "overdue_tasks", which is itself a child of <listEventCanvas>. Components that do no overlap still exist as children of a component group of type "overlap"; they are just the only child of that group. This type of <listEventCanvas> is used in the overview view.
- The following is an example of the processed XML for overlap order:
- <listEventCanvas sort="overlap">
<ComponentGroup ComponentGroupType="overdue_tasks">
<Task>... task data goes here...</Task>
</ComponentGroup><ComponentGroup ComponentGroupType="allday_events">
<Event> ...event data goes here ...</Event>
</ComponentGroup><ComponentGroup ComponentGroupType="overlap">
<StartTime iso="20010116T103000" year="2001" month="01" date="16"
hour="10" minute="30" seconds="00" dow="3" weeknum="3"/>
<EndTime iso="20010116T113000" year="2001" month="01" date="16"
hour="11" minute="30" seconds="00" dow="3" weeknum="3"/>
<Event ...event data...</Event>
</ComponentGroup><ComponentGroup ComponentGroupType="overlap">
<StartTime iso="20010116T153000" year="2001" month="01" date="16"
hour="15" minute="30" seconds="00" dow="3" weeknum="3"/>
<EndTime iso="20010116T163000" year="2001" month="01" date="16"
hour="16" minute="30" seconds="00" dow="3" weeknum="3"/>
<ComponentGroup ComponentGroupType="overlap">
<Event>....data ...</Event>
<Task> ...data...</Task>
</ComponentGroup>
</ComponentGroup>
- </listEventCanvas>
- This mode groups the component data into consistent blocks of time, such as one hour increments. Overdue and all day tasks precede the time blocks. Tasks with no time associated with them follow the time blocks. In addition, there is a <timeblockset>, which indicate the first and last time blocks that have data. This helps make the XSLT processing of the blocks more efficient. When a component group spans multiple time blocks, it is indicated in the value of "numIntervals". The dayview.xml and groupview.xml (comparison view) use this sort ordering.
- The following examples demonstrate "group" ordering:
<ComponentGroup ComponentGroupType="group" numIntervals="1">
<StartTime iso="20010116T090000" year="2001" month="01" date="16"
hour="09" minute="00" seconds="00" dow="3" weeknum="3"/><EndTime iso="20010116T100000" year="2001" month="01" date="16"
hour="10" minute="00" seconds="00" dow="3" weeknum="3"/>
</ComponentGroup><ComponentGroup ComponentGroupType="group" numIntervals="2">
<ComponentGroup ComponentGroupType="group"
<StartTime iso="20010116T103000" year="2001" month="01" date="16" hour="10" minute="30" seconds="00" dow="3"
weeknum="3"/>
<EndTime iso="20010116T113000" year="2001" month="01"
date="16" hour="11" minute="30" seconds="00" dow="3"
weeknum="3"/>
<Event> ...data...</Event>
</ComponentGroup>
<StartTime iso="20010116T100000" year="2001" month="01" date="16"
hour="10" minute="00" seconds="00" dow="3" weeknum="3"/>
<EndTime iso="20010116T120000" year="2001" month="01" date="16"
hour="12" minute="00" seconds="00" dow="3" weeknum="3"/>
</ComponentGroup><ComponentGroup ComponentGroupType="group" numIntervals="0">
<StartTime iso="20010116T110000" year="2001" month="01" date="16"
hour="11" minute="00" seconds="00" dow="3" weeknum="3"/>
<EndTime iso="20010116T120000" year="2001" month="01" date="16"
hour="12" minute="00" seconds="00" dow="3" weeknum="3"/>
</ComponentGroup><timeblockset>
<timeblock number="9"/>
<timeblock number="10"/>
<timeblock number="11"/>
<timeblock number="12"/>
<timeblock number="13"/>
<timeblock number="14"/>
<timeblock number="15"/>
<timeblock number="16"/>
<timeblock number="17"/>
<timeblock number="18"/>
<timeblock number="19"/>
</timeblockset>
<minical/>
This tag expands to provide information about the month that the current time context is in. The basic month information is the same regardless of the option used, but the commands provided in the expanded tag vary depending on the option. The expanded tag contains the information necessary to create the miniature month calendar residing on the side of the main views. This tag is used in most main views, such as the overview.xml.A <minical> tag consists of three JavaScript newViewCommands, one for previous month, the next month, and one to go back to "today". It also has four or five <row> children, each one containing seven (one week's worth) <Time> children. These children contain the information for the specific day along with a JavaScript newViewCommand to go to the overview for that day.
The following are examples of the <minical> tag:
If the "jump_to" option is used, the commands are set up to stay in the "jump_to" view. In addition, there are many more commands set up before the individual day information.
<Time> children have the following format:
<Time iso="20010107T000000" year="2001" month="01" date="7"
hour="00" minute="00" seconds="00" dow="1" weeknum="2">
<command>javascript:parent.jmain.newViewCommand
('overview:main','20010107T000000','true','calid=jdoe')
</command>
</Time>
<monthcal/>
This tag is very similar to the minical tag. It provides information about the month the current time context is in. The tag expands with a hierarchy of children, each mapping to a day in the month. The children also include any days in the previous month and the next month that are needed to fill out the start and end weeks. A week is defined by the user's first-day-of-the-week settings choice. This tag is used by the monthview.xml file.
Figure 2 Monthcal
Figure 2, above, shows the month calendar output by this tag. To get this output, data in the expanded tag is structured in this order:
<optionsdata/>
This tag is only expanded if there is an argument in the command URL that sets "error" to a value. It is used in the options.xml file.Table 3 shows the attributes set for various values of "error". Note that all attributes are set to a value of "1".
Table 3 Attributes Set by Various Values for "error"
<panel/>
This tag is not expanded, but its use helps improve XSLT processing.<panel name="availability"> ... </panel>
<pref_group/>
This tag controls access to a series of separate preferences to be treated as a group. Each preference group has a name attribute to identify it. When processing, if the pref_group name matches a preference the user has chosen (for example, the large font size family), then the individual preferences within that preference group will be processed. Otherwise the server skips over the pref_group without doing anything.This tag is used in the default_user_prefs.xml file.
An example of this tag's usage:
<pref_group name="pref_font_size_group_1"> ... </pref_group>
<tab/>
This tag can be used to name specific tags within an explicit tabs set. It is used only as a child of a <tabs> tag set, and only if the <tabs> tag has a type="explicit" attribute. Generally, the <tab> tags are inserted by the server as children of the <tabs> pair. It is possible to define your own individual <tab> tags in order to give them a name attribute. The additional information (command to load) will then be added by the server during processing of the <tabs> tag. This tag is used by the task_list.xml file.
<tabs/>
This tag is expanded to create URL commands that will load the individual tabs within a given view. The individual tabs within the tabs set can be named explicitly or referred to according to their position within the <tabs> set. The count indicates how many tabs there are. If type="explicit" is set, then the tabs to create are picked up as child text nodes of the <tabs> parent (and must therefore must exist as such). Using the explicit attribute is a way to give specific names to individual tabs in order. This tag is used in many files such as task_list.xml.The following are examples of the unexpanded tag:
<tabs count="6" type="explicit"> ... </tabs>
<tabs count="2" type="explicit">
<tab view="new_event"/>
<tab view="new_event"/>
</tabs>The URL command built to load these explicit tabs is:
<tab view="new_event">
javascript:loadtab(1,'http://calendarservername:port/
command.shtml?view=new_event:tabs&id=2mhs6bhb2meb&
tab=1&date=20010116T144622&prevView=groupview&
calid=jdoe&security=1','new_event');
</tab>The URL command built to load the generic tab is:
<tab>
javascript:loadtab(1,'http://calendarservername:port/
command.shtml?view=new_task:tabs&id=2mhs6bhb2meb&
tab=1&date=20010116T150454&prevView=overview:main
&calid=jdoe&security=1','new_task');
</tab>
<taskdata/>
This tag is used to provide information about a specific event. It causes a task child to be added to the <taskdata> tag. The task detailed is either the one specified by the uid on the URL command line, or a default is built up. This tag is used by new_task.xml.The following is an example of the tag:
The format of the task data is the same whenever a task is printed. An example of the format of the expanded tag follows:
<taskdata>
<Task e_Summary="DueLaterTodayTask" e_writeAccessAllowed="true"
e_Calid="jdoe"
e_uid="3a64c021000031600000000200000fd1" e_repeatModifier="" e_rid="0" e_Description="This is a task due later today"
e_OrganizerEmail="jdoe@domain.com" e_Organizer="jdoe" e_Language="en" e_dtCreated="20010116T134153"
e_dtModified="20010116T134153" e_existingRRule="" e_rrule_notset="true" e_rruleChanged="false"
e_dtdue="20010116T160000" e_notdue="0" e_allday="0" e_iSequence="0">
<DueTime iso="20010116T160000" year="2001" month="01"
date="16" hour="16" minute="00" seconds="00" dow="3"
weeknum="3"/>
<edit_command>javascript:var newWindow=window.open
('http://calendarservername:port/command.shtml?
view=new_task&id=2mhs6bhb2meb&date=20010116T142225
&uid=3a64c021000031600000000200000fd1&calid=jdoe
&i_tab=1&prevView=new_task:main',
'2mhs6bhb2meb3a64c021000031600000000200000fd1',
'height=550,width=650','false')
</edit_command>
</Task>
</taskdata>
Note If the task were overdue, there would be an additional attribute on the <Task> of overdue="TRUE".
<tasklist/>
This tag is expanded to provide information about all incomplete tasks in chronological order by due date. In addition, the task count and overdue task count are added as attributes. They are added as children of the tasklist. This tab is used in the task_list.xml file.The following are examples of the tag:
If the option="count" attribute is used, no task data is listed, and only attributes for the total task count and overdue task count are added.
<tasklist option="count" taskcount="3" overduetaskcount="1"/>
<timectx/>
This is one of the special tags described in Special Framework Tags.This tag is used to set a time state for the server. This tag must exist at least once after the <calendar> tag. Other tags may depend on being able to use the information from this tag. It may exist more than once in an XML view. This tag is used in most view XML files, such as overview.xml.
The following are examples of the tag:
<timectx add="-P3MT" range="P6MT"/>
The following example shows the expanded time context:
<timectx tzid="America/Los_Angeles">
<CurrTime iso="20010112T105031" year="2001" month="01" date="12"
hour="10" minute="50" seconds="31" dow="6" weeknum="2"/>
<SelectedTime iso="20010112T105031" year="2001" month="01"
date="12" hour="10" minute="50" seconds="31" dow="6
weeknum="2"/>
<StartTime iso="20010112T000000" year="2001" month="01" date="12"
hour="00" minute="00" seconds="00" dow="6" weeknum="2"/>
<EndTime iso="20010112T235959" year="2001" month="01" date="12"
hour="23" minute="59" seconds="59" dow="6" weeknum="2"/>
</timectx>The CurrTime is always the current time picked up when processing the tag. The SelectedTime can be set either with or without the add attribute.
With the add attribute, the SelectedTime can be changed relative only to the previous time context. Therefore a <timectx> tag with an add attribute can not be the first instance of the <timectx> tag in an XML file. The value of the add attribute follows the standard duration format.
When there is no add attribute on the <timectx> tag, and if there is a "&date=..." argument on the URL command line, then the date indicated is the SelectedTime. If there is no date indicated, then the SelectedTime is the CurrTime.
The StartTime and EndTime provide the range around the SelectedTime. Currently these are always the midnight previous to one second before midnight of the following day indicated by SelectedTime.
Only one day is specified by the <timectx> tag.
<timezone/>
<timezone type="americas" displayName="America/Adak" tzid="America/Adak" offset="-10:00" daylightOffset="-09:00"/><timezone type="asiaPacific" displayName="Pacific/Kiritimati"
tzid="Pacific/Kiritimati" offset="+14:00"/>
<userpref/>
This tag is used to preset default user preference values. This tag is not expanded. It is used in default_user_prefs.xml. In addition, there are four preferences that can set up debugging runtime values.
Table 4 Preferences Used to Set Debugging Runtime Values
Table 4 shows the four user preferences used to set debugging runtime values.
The following are examples of the tag use:
<userpref name="icsFirstDay" default_value="1" type="number"
min_value="1" max_value="7"/><userpref name="icsTimeZone" default_value="America/New_York" />
<userpref name="ceDefaultAgenda" default_value="" />
<userpref name="ceToolText" default_value="1" />
<userpref name="ceToolImage" default_value="1" />
<userprefs/>
This tag is used as a delimiter around <userpref> tags. It is not expanded. It facilitates processing of the <userpref> tags. This tag is used in the default_user_prefs.xml file.The following is an example of the tag:
<usrctx/>
This is one of the special tags described in Special Framework Tags.This tag is expanded with information about the current user. The tag is used in most XML files, such as the overview.xml file. The following is an example of the tag:
When the tag is processed, an attribute is added to the <usrctx> node to indicate the selectedCalendar or selectedGroup to display, but not both. In addition four other nodes are added.
Table 5 shows the nodes added between the <usrctx> tag set.
<weekcal/>
This tag is used to provide information about the tasks and events for the week that includes the current time context. The weekview tag is used int he weekview.xml file. If no option attribute exists on the tag, then it provides the appropriate component information for each day of the week. This information is the same as would be added for a listEventCanvas in group order format with time blocks. In addition each day gets two commands, one for the dayview for each weekday and one for an arbitrary new_event for the day in question.The following is an example of the tag use:
If the option="dates" attribute occurs on the tag, then no actual component data is added; only the information about the week that includes the current time context is added. An example of the information this includes follows:
<weekcal option="dates" iso="20010116T080000Z" year="2001"
month="01" date="16" hour="08" minute="00" seconds="00" dow="3"
weeknum="3"><weekday iso="20010114T080000Z" year="2001" month="01"
date="14" hour="08" minute="00" seconds="00" dow="1" weeknum="3"/>
<weekday iso="20010115T080000Z" year="2001" month="01"
date="15" hour="08" minute="00" seconds="00" dow="2"
weeknum="3"/>
<weekday iso="20010116T080000Z" year="2001" month="01"
date="16" hour="08" minute="00" seconds="00" dow="3"
weeknum="3"/>
<weekday iso="20010117T080000Z" year="2001" month="01"
date="17" hour="08" minute="00" seconds="00" dow="4"
weeknum="3"/>
<weekday iso="20010118T080000Z" year="2001" month="01"
date="18" hour="08" minute="00" seconds="00" dow="5"
weeknum="3"/>
<weekday iso="20010119T080000Z" year="2001" month="01"
date="19" hour="08" minute="00" seconds="00" dow="6"
weeknum="3"/>
<weekday iso="20010120T080000Z" year="2001" month="01"
date="20" hour="08" minute="00" seconds="00" dow="7"
weeknum="4"/>
<timeblockset/>
</weekcal>
<yearcal/>
This tag causes a series of minicalendars to be built as children of this node. The difference between the <minical> output and the <yearcal> output if that there is only one initial command in the yearcal. It is a command to go to the monthview for that minical month. No component data is output for the days in each minical, just the time and date information.The following is an example of this tag's use:
Figure 5 shows the year calendar produced by this tag. Compare
Figure 3 and Figure 4 below and note that the year version of the minical and the month version of the minical differ. The month version appears on most of the other calendar views. The year version is produced only with this tag.
Figure 3
Year Minical
Figure 4 Month Minical
Figure 5 Year Calendar Produced by <yearcal> Tag
To produce this year calendar, data in the expanded tag is structured in this order:
row of year minicals (3 of these)
year minical (4 of these)
row of year minicals
command for current month
year minicalweek row (one for each week position in month calendar - 5 or 6)
week row
- -Day (one for each day of the week)
+Time for this context
+Command for this time context dayview
- -Day
...etc. through 7 days
...etc. through 5 or 6 weeks
...etc. through 4 months
...etc. through 3 rows
Debug Mode
A runtime option is available to help you debug. This option causes the server to reload all of the XML and XSL on each hit to the server. (The files are normally cached.) It also writes a file to the directory where the server is running (bin directory) for each processed XML file. These files contain the exact code that is being displayed on the client.The format of the name of the post-processed XML file is: _icsDebug_current user_ view_ subview.xml. Subview is the frame being processed, such as main, toolbar, or buttons. In general, the main frame is usually the most data-rich. When the post-processed file name has the same name as the view, then it resulted from the frameset pass.
Note The server slows down noticeably in this mode.
For example, when debug mode is on, it creates the following three post-processed files from the overview.xml file:
bin/_icsDebug_currentuser_overview_main.xml (generated from the main frame)
bin/_icsDebug_currentuser_overview_overview.xml (generated from the frameset pass)
bin/_icsDebug_currentuser_overview_toolbar.xml (generated from the toolbar frame)
Turning Debug Mode On
To put the server in debug mode for XML and XSL:
Remove the comment markers from this line in the file ui_config.xml:
Then, in ics.conf, point the ui.config.file preference to ui_config.xml:
Turning Debug Mode Off
To turn off debug mode and return to normal function:
Choose one of the following methods for changing the preference back:
Turn off the _DebugMode user preference by changing it to read: default_value="off".
Restart the server.Turn off the _DebugMode user preference by commenting it out.
Remove the preference ui.config.file from the ics.conf file.
Change the value of the ui.config.file to "".
Example of Pre- and Post-Processed XML Files
From Pre-processed overview.xml:
<panel name="overview-panel"><panel name="singleDayTimeHeader">
<command name="back" type="cmd_date" dur="-P1DT"/>
From _icsDebug-JoeUser_overview_main.xml:
<panel name="overview-panel"><timectx tzid="America/Los_Angeles">
<CurrTime iso="20001128T105624" year="2000" month="11"
date="28" hour="10" minute="56" seconds="24" dow="3"
weeknum="48"/><SelectedTime iso="20001128T105624" year="2000" month="11"
date="28" hour="10" minute="56" seconds="24" dow="3"
weeknum="48"/><StartTime iso="20001128T000000" year="2000" month="11" date="28" hour="00" minute="00" seconds="00" dow="3"
weeknum="48"/><EndTime iso="20001128T235959" year="2000" month="11" date="28" hour="23" minute="59" seconds="59" dow="3"
weeknum="48"/><panel name="singleDayTimeHeader">
<timectx tzid="America/Los_Angeles">
<CurrTime iso="20001128T105624" year="2000" month="11" date="28" hour="10" minute="56" seconds="24" dow="3"
weeknum="48"/><SelectedTime iso="20001128T105624" year="2000"
month="11" date="28" hour="10" minute="56" seconds="24" dow="3" weeknum="48"/><StartTime iso="20001128T000000" year="2000"
month="11"date="28" hour="00" minute="00" seconds="00"
dow="3" weeknum="48"/><EndTime iso="20001128T235959" year="2000" month="11" date="28" hour="23" minute="59" seconds="59" dow="3"
weeknum="48"/><command name="back" type="cmd_date"
dur="-P1DT">javascript:parent.jmain.newViewCommand
('overview:main','20001127T000000','true')</command>
XML/XSL Links
The primary source of information on the internet for XML and XSL is the World Wide Web Consortium found at: www.w3.org.
General information on XSL is at: http://www.w3.org/Style/XSL.
The XSL Working Draft is at: http://www.w3.org/TR/xsl.
The XSLT Recommendation is at: http://www.w3.org/TR/xslt.
The XPath Recommendation is at: http://www.w3.org/TR/xpath.
The original XSL note is at: http://www.w3.org/TR/NOTE-XSL.
An excellent source of information about XSL is the XSL page of Robin Cover's "the XML Cover Pages" found at: http://www.oasis-open.org/cover.
Dave Pawson's XSL FAQ is at: http://www.dpawson.freeserve.co.uk/xsl/xslfaq.html.
Mulberry Technologies hosts the XSL-List, an open forum for discussion of XSL, at: http://www.mulberrytech.com/xsl/xsl-list.
Zvon, a web organization dedicated to free information exchange centered on XML, has several tutorials, and an XSLT reference. Their web URL is: http://www.zvon.org.
"XML for the absolute beginner" is an excellent overview found at: http://www.javaworld.com/javaworld/jw-04-1999/jw-04-xml.html. This site also contains valuable links to other XML/XSL resources.
Tutorial Links
Finding a web tutorial on XML/XSL should not be difficult, but here are two sites to get you started:
Click on the TUTORIALS link at: http://www.zvon.org.
Several are offered at: http://www.w3schools.com.
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated February 21, 2001