CalendarTag 1.2 Syntax

CalendarTag Development Guide

CalendarTag version 1.2

This development guide assumes you have a good understanding of Java, JSP and the architecture of your application server.

Referencing CalendarTag for use within a JSP

To use CalendarTag within a JSP you first must make a reference to the tag at the top of the page:

  <%@ taglib uri="/WEB-INF/calendar.tld" prefix="cal" %>

uri is the path to where the tag library definition file is placed which in our case is 'calendar.tld' and normally these are placed in the WEB-INF folder of your application. Note, the uri can also refer to the uri of a tag defined in the applications 'web.xml' file.

The second attribute prefix defines the prefix used by the tags within the rest of the JSP. I always use 'cal' for the CalendarTag but you may use some other term instead.

Referencing the Calendar Style Sheet

The look and feel of the CalendarTag is controlled by a style sheet. We will reference this now as working with the tag will be easier and later look at how to modify the calendar's style.

First place the calendar style sheet 'calendar.css' in a suitable location on your web application. Next add the following reference to the head section of you JSP page.

  <link rel="stylesheet" type="text/css" href="calendar.css">

The href attribute defines where the style sheet can be found in relation to the page. In this case it must be in the same folder as the JSP. A better alternative is to place the stylesheet directly in the web applications root folder and then the href for the stylesheet reference in all JSPs would be '/calendar.css'.

Defining a Simple CalendarTag

OK we have now referenced our tag within a JSP so let us now look at how to display the tag.

The simplest CalendarTag is one that just displays the current month. This is done with adding the following to your JSP,

  <cal:calendar />

This will display the current month in the typical calendar grid style with the month and year at the top.

By defining attributes for the CalendarTag we can start to do more interesting things with it. We will look at this next.

CalendarTag Attributes

Specifying a Date

You can define a particular month and year to display in CalendarTag. This is done by defining the month and year attributes

  <cal:calendar month="0" year="1973" />

This example displays the month of January in the year 1973. CalendarTag calculates the calendar with the correct days of the week so we see that the first of January was a Monday.

Defining a Display Language

We can also easily change the displayed language of the calendar by defining the locale attribute:

  <cal:calendar locale="fr" />

Here the locale is language French. The translation of months and days of the week is provided by the JDK that your application server is running on. More recent JDKs support more locales. For a list of supported locales for JDK 1.4.1 see Supported Locales. The locale attribute accepts either a single language code, e.g.'fr' or a combination of language and country, 'fr-ca' is language French and country Canada, or language, country, variant: 'th_TH_TH'.

The end user's browser can also affect the support of locales. You should use a character set for your web page that will display the characters of a locale correctly, for example, Unicode. To set the character set for a web page either define a meta tag or set a header using the response object,

  <meta http-equiv="content-type" content="text/html; charset=utf-8">

  response.setContentType("text/html; charset=utf-8");

Note, by default the CalendarTag will use the locale defined in by the end users browser which is typically the same as the locale of the machine that they are using. However in an application it is considered a good practice to provide the user with a means of changing this.

Defining the TimeZone

You can also define a time zone for the CalendarTag which can have a bearing on what 'today's date' is if your web application is international. This is defined by the timezone tag and the syntax of the value is "GMT" and then plus or minus a certain number of hours and minutes. For example,

  <cal:calendar timezone="GMT+04:00" />

Would set the time zone for the calendar tag to 4 hours ahead of GMT. You can determine the time zone of the user's browser with a call to the client side javascript function date.getTimezoneOffset(). You will need to pass this value to the server so that the server can set the time zone for that user's calendar.

So far we have concentrated on displaying a static calendar. We will now look at how the user can interact with the CalendarTag and, for example, how to use the calendar tag to allow the user to select a date in an HTML form.

Interacting with CalendarTag

There are two attributes that can be used here: url to define a url for the date hyperlinks and script to define a client side script that is called when a date is clicked. Note these features are only available in the licensed version

Defining Date Hyperlinks

The url attribute defines a URL that is used as a hyperlink for each date of the calendar. This will allow a user to select a date from the displayed calendar. The hyperlink that is sent to the server is automatically appended with the following parameters:

Day - the value of the day selected
Month - the value of the month selected from 0 January to 11 December (using 0 for January may seem strange but it is in keeping with the Java API.)
Year - a 4 digit year

So if you defined a url as

  <cal:calendar url="/setStartDate.jsp" />

the hyperlink that is constructed for first of January 1973 would be

  <a href="/setStartDate.jsp?Day=1&Month=0&Year=1973"> 1 </a>

Defining Client Side Script

By defining a client side script that will execute when a date is selected can be used to set a date within an HTML form which is useful if you don't want to keep submitting data for each date being selected.

The script attribute allows you to do this and basically you specify the name of the script that is called when the user selects a date. When this script is called it is passed three parameters: day, month and year. You need to ensure that the client side script is created to accept these 3 parameters. So for example, we could have

  <cal:calendar script="setDate" />

which would define a hyperlink as,

  <a href="" onclick="return setStart(3,8,2003)"> 3 </a>

where you have a Javascript function similar to,

  function setStart(day, month, year)
  {
    document.myForm.StartDateField.value = day + "/" + (month + 1) + "/" + year;
    return false;
  }

Calendar Styles

As mentioned earlier the calendar look and feel is controlled by a style sheet so you can easily modify this to change the look and feel of the CalendarTag. This section discusses the style sheet elements.

table.calendar

Defines the outer table that contains the calendar. Use this style element to define overall font size and face for the calendar and you can also use this style element to define an outer border and background colour. For example,

table.calendar
{
  font-size:      x-small;
  border-left:    #c97070 1pt solid;
  border-top:     #c97070 1pt solid;
  border-right:   #000000 1pt solid;
  border-bottom:  #000000 1pt solid;
  background:     #cccccc 1px solid;
}

th.calendar

Defines the style of the displayed month label and year text.

td.calendar_weekdays

Defines the style for the weekday labels.

td.calendar, a.calendar

Defines the style of a date that is not the current month.

td.calendar_thismonth, a.calendar_thismonth

Defines the style for the dates of the current month. Typically these have a dark colour and the non current month days are paler.

td.calendar_thisday, a.calendar_thisday

This is used to highlight the current day. The following example draws a raised box around today's date.

td.calendar_thisday
{
  text-align:       center;
  border-left:      #c97070 1pt solid;
  border-top:       #c97070 1pt solid;
  border-right:     #000000 1pt solid;
  border-bottom:    #000000 1pt solid;
}
a.calendar_thisday
{
  color:            black;
  text-decoration:  none;
}

Author: A Gulland
Revision date: 28 August 2003.

Back Next