Chapter 2 TagLib: Calendar

This chapter describes the Tab Library Calendar attributes:

The Calendar Tag Library consists of the following tags:

• calid

• calids

• context

• calid

• dateroll

• datetime

• delete

• deleteTask

• event

• events

• fetch

• fetchcalid

• get

• login

• opencal

• recurrence

• reminder

• set

• store

• storeTask

• task

• tasks

calid

Description

The calid tag makes the specified event bean properties available.

Tag Body

JSP

Restrictions

Only one of the id, name, or index attributes should be used at a time. If no attributes are specified then the current event in the parent collection is used. The event properties are only valid from the start tag to the end tag.

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

index

Specifies the index into the current calid list of the calid bean to find.

Properties

The tag provides the following bean properties for which the Type value is “String” and the Access value is “Get”:

value

The calendar ID referenced by the bean.

Example(s)

n/a

calids

Description

The calids tag enumerates through the current calid collection in the calendar context.

Tag Body

JSP

Restrictions

n/a

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Name of the calid collection to create.

name

Name of the calid collection to use.

iterate

A boolean that selects iteration. Default is "false", the collection will not iterate.

beanid

During iteration, specifies a name by which the current bean may be retrieved from the PageContext.

Properties

The tag provides the following bean properties for which the Type value is “Integer” or “Boolean” and Access value is “Get/Set”:

index

Index of the current bean in the collection. Integer.

count

The number of iterations the collection should perform. Integer.

start

The zero based index from which to begin iteration. Integer.

end

The zero based index that denotes the item upon which iteration will terminate. Integer.

startOne

One-based start; suitable for presentation.

endOne

One-based end; suitable for presentation.

size

The size of the collection being paged. Integer.

nextPage

Whether or not there are more items in the collection, beyond the current iterations. Boolean

prevPage

Whether there are items in the collection preceding the current iterations. Boolean

Example(s)

<%-- enumerate through the event collection --%>
<cal:calids>
	<cal:calid>
 		...
	</cal:calid>
</cal:calids>

context

Description

Ensures that a calendar context is present within the current pageContext. This tag must appear, at least once, before all other tags within the Calendar taglib. If config is not specified, then a search for a useable configuration name is performed in the following fashion: Attempt to retrieve the current calendar configuration name from the page context.  If that succeeds, use it.  If the retrieval fails... Attempt to retrieve the current calendar configuration name from the session.  If that succeeds, store it on the page context and use it.  If the retrieval fails... From the list of all SSOAdapter configuration names, try to find the first useable calendar configuration name.  If that succeeds, store it in the session and page context and use it.  If it is not possible to find a useable calendar configuration name, the context tag will fail. Once a configuration name has been determined, an attempt is made to acquire an appropriate calendar context object.  This is done in the following fashion: Attempt to retrieve a calendar context from the page context, and verify it matches the configuration (using the previously acquired configuration name).  If that succeeds, use it.  If that fails... Attempt to retrieve a calendar context from the user's cache of mail contexts. If that succeeds, store it on the page context and use it.  If the retrieval fails.. Create an SSOAdapter object using the previously acquired configuration name.  Create a calendar context, and bind it with the SSOAdapter object.  Store the calendar context in the context cache as well as the page context. In this way, if a calendar context has been previously referenced on a page, or within the session, then the config attribute may be omitted,and the most recently referenced context will be retrieved.

Tag Body

JSP or Empty.

Restrictions

Since the calendar context is saved across requests the properties are also available for use across requests.

Attributes

This tag has the following attributes for which the Required value is “No”:

config

Specifies the "configuration" for which a calendar context should be retrieved.

test

Permits testing of service availability. Operates according to the following table:

Properties

This tag provides access to the following properties for which the Type values are “String”, “Integer”, and “Boolean” and the Access value is “Get”:

errorCode

Returns errors status of failed command tags.

• CAL_001: Invalid date format.

errorCount

The size of the current event list.

eventSize

Same as eventCount.

taskCount

The size of the current task list.

calendarID

The current calendar ID.

eventsEmpty

Indicates status of the events list.

tasksEmpty

Indicates status of the tasks list.

userTheOwner

Indicates whether the user is the owner of the current calendar.

Example(s)

<%-- calendar context --%>
<Cal:context/>

dateformat

Description

The dateformat tag either formats a datetime for output or parses one from an input. The format attribute specifies the format to use either to format for output or to parse from input. If the parse attribute is specified then that value is used as the parse string to set the specified datetime. If the parse attribute is not specified then the datetime is formatted to the page output.

Tag Body

JSP

Restrictions

The datetime to operate on is located as follows. If the name attribute is specified then that datetime bean is used. Otherwise the parent datetime tag is used.

Attributes

The tag has the following attributes for which the Required values are “Yes” and “No”:

name

Specifies the name of the datetime bean to use. If not specified then the parent datetime tag is used.

format

The java.text.SimpleDateFormat format string to use to format or parse the datetime with.

parse

The string to parse into a datetime using format.

Properties

n/a

Example(s)

<%-- create now datetime and output hours/minutes --%>
<cal:datetime id="now"/>
<cal:dateformat name="now" format="hh:mm"/>

<%-- set datetime from hours/minutes parse string --%>
<cal:datetime>
<cal:dateformat format="hh:mm" parse="10:30"/>
</cal:datetime>

dateroll

Description

The dateroll tag rolls the specified datetime bean. If an error occurs during processing, the tag body will be evaluated and the remainder of the page will be skipped.

Tag Body

JSP

Restrictions

None.

Attributes

The tag has the following attributes for which the Required value is “No”:

name

Specifies the datetime bean to operate on. If not specified then search for a datetime parent tag.

field

Specifies the java.util.Calendar field of the roll; defaults to DATE.

amount

Specifies the amount of the roll; an integer value, defaults to "1". Positive values roll forward; negative values roll backward.

Properties

None.

Example(s)

<%-- roll forward one day from today --%>
<cal:datetime id="now"/>
<cal:dateroll name="now"/>

<%-- roll forward 2 weeks --%>
<cal:datetime id="now"/>
<cal:dateroll name="now"
amount="2" field="WEEK_OF_YEAR"/>

<%-- roll back 5 hours --%>
<cal:datetime id="now"/>
<cal:dateroll name="now" amount="-5" field="HOUR"/>

datetime

Description

The datetime tag makes the specified date/time bean properties available.

Tag Body

JSP

Restrictions

Only one of the id or name attributes should be used at a time. The datetime properties are only valid from the start tag to the end tag.

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

Properties

The tag provides the following bean properties for which the Type value is “Integer” and Access value is “Get/Set”:

hours

Hours of the time; in a 24 hour clock

minutes

Minutes of the time.

seconds

Seconds of the time.

day

Day of the date.

month

Month of the date.

year

Year of the date; a 4 digit year.

Example(s)

<%-- create a 'now' datetime at the current time --%>
<cal:datetime id="now"/>

<%-- create a 'start' datetime with today at 10:30 --%>
<cal:datetime id="start">
	<cal:set property="hours" value="10"/>
	<cal:set property="minutes" value="30"/>
</cal:datetime>

<%-- use a previously created datetime --%>
<cal:datetime name="now">
		Day   = <cal:get property="day"/>
		Month = <cal:get property="month"/>
		Year  = <cal:get property="year"/>
</cal:datetime>

delete

Description

This tag deletes the specified event from the current calendar set. If an error occurs during processing, the tag body will be evaluated.

Tag Body

JSP

Restrictions

If the name attribute is not specified then a parent event tag is used to find the event to operate on.

Attributes

The tag has the following attributes for which the Required value is “No”:

name

Name of the event bean to delete.

modifier

Specifies how to update an existing event. Can accept a string

THIS_INSTANCE

This event instance only.

THIS_AND_FUTURE

This and all future occurances.

THIS_AND_PRIOR

This and previous occurances.

THIS_AND_ALL

This and all occurances.

Properties

None

Example(s)

<%-- delete an event by name --%>
<cal:event id="event1">
<cal:delete name="event1">
...delete failed...
</cal:delete>

<%-- delete an event and all future occurences --%>
<cal:event>
<cal:delete modifier="THIS_INSTANCE">
...delete failed...
</cal:delete>
</cal:event>

deleteTask

Description

This tag deletes the specified task from the current calendar set. If an error occurs during processing, the tag body will be evaluated.

Tag Body

JSP

Restrictions

If the name attribute is not specified then a parent task tag is used to find the event to operate on.

Attributes

The tag has the following attribute for which the Required value is “No”:

name

Name of the event bean to delete.

Properties

None

Example(s)

<%-- delete a task by name --%>
<cal:task id="task1"/>
<cal:deleteTask name="task1">
...delete failed...
</cal:deleteTask>

event

Description

This tag makes the specified event bean properties available.

Tag Body

JSP

Restrictions

Only one of the id, name, or index attributes should be used at a time. If no attributes are specified then the current event in the parent collection is used. The event properties are only valid from the start tag to the end tag.

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

index

Specifies the index into the current event list of the event bean to find.

Properties

The tag provides the following bean properties for which the Access value is “Get/Set”:

startTime

Start time of the event; datetime.

endTime

End time of the event; datetime.

description

Long description of the event.

summary

Short summary of the event.

location

Location of the event.

allDay

Whether the event lasts all day or not; boolean.

recurrence

Whether the event is part of a recurring series of events; boolean.

recurrencePattern

RecurrencePattern of this event.

recurrenceModifier

RecurrencePattern.THIS_INSTANCE and RecurrencePattern.THIS_AND_FUTURE

modifier

Same as recurrenceModifier for backward compatible.

thisDate

String used to store the date for temparory purpose.

reply

Get and set the rsvp status of this user as an attendee in this event.Only Sun-One supported valid values.

attendees

The user invites others to this event.

removedAttendee

Remove any existing invitees to this event.

userTheOrganizer

Boolean: Indicates whether user is the organizer of this event.

reminderBean

ReminderBean for this event.

Example(s)

<%-- create a 'new' event --%>
<cal:event id="new"/>

<%-- create a 'new' event with a summary --%>
<cal:event id="new">
	<cal:set property="summary" value="Event Summary"/>
</cal:event>

<%-- use a previously created event --%>
<cal:event name="now">
		Start   = <cal:get property="startTime"/>
		End     = <cal:get property="endTime"/>
		Summary = <cal:get property="summary"/>
</cal:event>

<%-- retrieve an event by id --%>
<cal:event id="event" eventid="$(eid)">
	<cal:set property="summary" value="new summary"/>
</cal:event>

<%-- current event in the event collection --%>
<cal:events iterate="true">
	<cal:event>
	...
	</cal:event>
</cal:events>

events

Description

This tag enumerates through the current event collection in the calendar context.

Tag Body

JSP

Restrictions

n/a

Attributes

This tag has the following attributes for which the Required value is “No”:

id

Name of the event collection to create.

name

Name of the event collection to use.

iterate

A boolean that selects iteration. Default is "false", the collection will not iterate.

beanid

During iteration, specifies a name by which the current bean may be retrieved from the PageContext.

Properties

This tag provides the following bean properties for which the Type values are “Integer” and “Boolean” and the Access value is “Get/Set”:

index

Index of the current bean in the collection.

count

The number of iterations the collection should perform.

start

The zero-based index from which to begin iteration.

end

The zero based index that denotes the item upon which iteration will terminate.

startOne

One-based start; suitable for presentation.

endOne

One-based end; suitable for presentation.

size

The size of the collection being paged.

nextPage

Whether or not there are more items in the collection, beyond the current iterations.

prevPage

Whether there are items in the collection preceding the current iterations.

Example(s)

<%-- enumerate through the event collection --%>
<cal:events>
	<cal:event>
		...
	</cal:event>
</cal:events>

fetch

Description

This tag retrieves the specified range of events and tasks into the calendar context. The range is specified using datetime tags with the id attribute; see the datetime tag for details. If an error occurs during processing, the tag body is evaluated and the remainder of the page will be skipped.

Tag Body

JSP

Restrictions

Use either day or both start and end attributes to specify the range of events. If no attributes specified all events for the current day are retrieved.

Attributes

This tag has the following attributes for which the Required value is “No”:

day

Specifies an entire day to retrieve.

start

Specifies the start time of the range to retrieve.

end

Specifies the end time of the range to retrieve.

Properties

None.

Example(s)

<%-- fetch todays events --%>
<cal:fetch>
... fetch failed ...
</cal:fetch>

<%-- fetch events for a day --%>
<cal:datetime id="start"/>
... set start time ...
<cal:fetch day="start">
... fetch failed ...
</cal:fetch>

<%-- fetch events for a range --%>
<cal:datetime id="start"/>
<cal:datetime id="end"/>
... set start & end times ...
<cal:fetch start="start" end="end">
... fetch failed ...
</cal:fetch>

fetchcalid

Description

The fetchcalid tag retrieves something TBD. If an error occurs during processing, the tag body will be evaluated and the remainder of the page will be skipped.

Tag Body

JSP

Restrictions

Attributes

The tag has the following attributes for which the Required value is “No”:

search

TBD

Properties

None.

Example(s)

n/a

get

Description

This tag retrieves the specified property or field.

Tag Body

Empty

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. Either property or field attributes should be used to specify what to retrieve. The id attribute specifies the name to save the retrieved property as; useful for non-string properties.

Attributes

The tag has the following attributes for which the Required value is “No”:

name

Name of the datetime bean to use.

property

Name of the property to retrieve. If not specified then the bean itself is retrieve as a string.

field

Name of the java.util.Calendar field to retrieve.

id

Name to save the retrieved result as.

edit

Specifies the edit bean that will be applied to the returned value.

Properties

None.

Example(s)

<%-- get the eventsummary property --%>
<cal:event>
	summary=<cal:get property="summary"/>
</cal:event>

<%-- get the datetime HOURS field --%>
<cal:datetime>
	hours=<cal:get field="HOURS"/>
</cal:datetime>

login

Description

The login tag creates a calender server session using the specified host and port with the specified user and password authentication.

Tag Body

JSP

Restrictions

The authenticated calendar session is stored as calendarSession into the session context.

Attributes

The tag has the following attributes for which the Required values are “Yes” and “No”:

host

Specifies the calendar server host.

port

Specifies the calendar server port.

user

Specifies the calendar user id.

pword

Specifies the calender user password.

Properties

None.

Example(s)

<%-- login to a calendar server with authentication --%>
<cal:login host="ical" user="user-id" pword="password"/>

opencal

Description

The opencal tag verifies the user can open a calendar.

Tag Body

JSP

Restrictions

Attributes

The tag has the following attributes for which the Required value is “Yes”:

calID

ID of the calendar to open.

Properties

None.

Example(s)

n/a

recurrence

Description

This tag makes the specified recurrence bean properties available.

Tag Body

JSP

Restrictions

Only one of the id, name, or index attributes should be used at a time. If no attributes are specified then the current event in the parent collection is used.

Attributes

The tag has the following attributes

Properties

The tag provides the following bean properties. The id and name attributes have the Type value, “String” and Access value, “No”. The frequency attribute has Type values such as RecurrencePattern.DAILY, RecurrencePattern.WEEKLY, RecurrencePattern.MONTHLY, and RecurrencePattern.YEARLY and the Required value, Yes. The Type values for repeatOn, repeatUntil, and interval attributes are String, Number or DateTime, and int respectively and the Access value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

frequency

n/a

repeatOn

n/a

repeatUntil

n/a

interval

n/a

Properties

The tag provides the following bean properties:

TBD

Based on JCAPI "RecurrencePattern"

Example(s)

<%@ page import="com.sun.comclient.calendar.RecurrencePattern" %>
<cal:event id="new">
<cal:recurrence id="rec" frequency="RecurrencePattern.WEEKLY"
interval="1" repeatOn="SA,SU" repeatUntil="5" />
<cal:set id="rec" property="recurrencePattern" />
</cal:event>

reminder

Description

The reminder tag makes the specified reminder bean properties available.

Tag Body

JSP

Restrictions

n/a

Attributes

The tag has the following attributes for which the Type value is “String” and the Access value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

Properties

The tag provides the following bean properties for which the Type value is “Integer”, “DateTime”, and “String” and the Access value is “Get/Set”:

durationMin

n/a

durationHour

n/a

durationDay

n/a

durationStartDate

n/a

durationEndDate

n/a

alarmTime

n/a

trigger

n/a

reminderNote

n/a

attendee

n/a

Example(s)

n/a

set

Description

The set tag updates the specified property or field.

Tag Body

JSP

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. One of property or field attributes must be used to specify what to update. Either the value or id attributes is used to specify the value of the property to update.

Attributes

The tag has the following attributes for which the Required value is “No”:

name

Name of the datetime bean to use.

property

Name of the property to update.

field

Name of the java.util.Calendar field to update.

value

String value of the property to update.

id

Bean object value of the property to update.

edit

Specifies the edit bean that will be applied to value prior to storage.

Properties

None.

Example(s)

<%-- set the event summary property --%>
<cal:event>
	<cal:set property="summary" value="new summary"/>
</cal:event>

<%-- set the datetime HOURS field --%>
<cal:datetime>
	<cal:set field="HOURS" value="10"/>
</cal:datetime>

<%-- set the event start time to a datetime bean --%>
<cal:datetime id="now"/>
<cal:event>
	<cal:set property="startTime" id="now"/>
</cal:event>

store

Description

This tag stores the specified event into the current calendar set. It can either store a new event or update an existing event. If an error occurs during processing, the tag body will be evaluated.

Tag Body

JSP

Restrictions

If the name attribute is not specified then a parent event tag is used to find the event to operate on. The modifier attribute should only be used to update an existing event.

Attributes

This tag has the following attributes for which the Required value is “No”:

name

Name of the event bean to store.

modifier

Specifies how to update an existing event. Can accept a string.

RecurrencePatten.THIS_INSTANCE

This event instance only.

RecurrencePatten.THIS_AND_FUTURE

This and all future occurrences.

RecurrencePatten.THIS_AND_PRIOR

This and previous occurrences.

RecurrencePatten.THIS_AND_ALL

This and all occurrences.

Properties

None

Example(s)

<%-- store an event by name --%>
<cal:event id="event1">
<cal:store name="event1">
...store failed...
</cal:store>

<%-- store an event and all future occurrences --%>
<cal:event>
<cal:store modifier="<%= RecurrencePatten.THIS_INSTANCE %>" >
...store failed...
</cal:store>
</cal:event>

storeTask

Description

The storeTask tag stores the specified task into the current calendar set. It can either store a new task or update an existing event. If an error occurs during processing, the tag body will be evaluated.

Tag Body

JSP

Restrictions

If the name attribute is not specified then a parent task tag is used to find the event to operate on. The modifier attribute should only be used to update an existing task

Attributes

The tag has the following attributes for which the Required value is “No”:

name

Name of the event bean to store.

Properties

None

Example(s)

<%-- store an task by name --%>
<cal:task id="task1">
<cal:storeTask name="task1">
...store failed...
</cal:storeTask>

task

Description

This tag makes the specified task bean properties available.

Tag Body

JSP

Restrictions

Only one of the id, name, or index attributes should be used at a time. If no attributes are specified then the current task in the parent collection is used.

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

index

Specifies the index into the current event list of the event bean to find.

Properties

The tag provides the following bean properties for which the Type values are “DateTime”, “Boolean”, “String”, and “ReminderBean” and the Access value is “Get/Set”:

dueDate

The time at which the task is due.

validDueDate

If the DueDate is valid.

dueTime

If the task is due or not.

dueTimeField

If the dueTime is valid.

locationValid

n/a

completed

n/a

description

Long description of the event.

summary

Short summary of the event.

location

Location of the event.

status

n/a

allDay

Whether the event lasts all day or not; boolean.

thisDate

String to store the date for temparory purpose.

recurrencePattern

The recurrence pattern for the Task.

reminderBean

The reminder for the task.

recurrenceModifier

The instances of task needs to be modified. RecurrencePattern.THIS_INSTANCE and RecurrencePattern.THIS_AND_FUTURE.

modifier

Same as recurrenceModifier.

Example(s)

<%-- create a 'new' task --%>
<cal:task id="new"/>

<%-- create a 'new' task with a summary --%>
<cal:task id="new">
	<cal:set property="summary" value="Task Summary"/>
</cal:task>

<%-- use a previously created task --%>
<cal:task name="now">
	Due Date   = <cal:get property="dueDate"/>
	Summary = <cal:get property="summary"/>
</cal:task>

<%-- current task in the task collection --%>
<cal:tasks iterate="true">
	<cal:task>
	...
	</cal:task>
</cal:events>

tasks

Description

This tag enumerates through the current task collection in the calendar context.

Tag Body

JSP

Restrictions

n/a

Attributes

The tag has the following attributes for which the Required value is “No”:

id

Name of the task collection to create.

name

Name of the task collection to use.

iterate

A boolean that selects iteration. Default is "false", the collection will not iterate.

beanid

During iteration, specifies a name by which the current bean may be retrieved from the PageContext.

Properties

The tag provides the following bean properties for which the Type value is “Integer” and “Boolean” and Access value is “Get/Set”:

index

Index of the current bean in the collection.

count

The number of iterations the collection should perform.

start

The zero based index from which to begin iteration.

end

The zero based index that denotes the item upon which iteration will terminate.

startOne

One-based start; suitable for presentation.

endOne

One-based end; suitable for presentation.

size

The size of the collection being paged.

nextPage

Whether or not there are more items in the collection, beyond the current iterations.

prevPage

Whether there are items in the collection preceding the current iterations.

Example(s)

<%-- enumerate through the task collection --%>
<cal:tasks>
	<cal:task>
	...
	</cal:tasks>
</cal:tasks>