This development guide assumes you have a good understanding of Java, JSP and the architecture of your application server. It describes how to use the CalendarTag for the most common situations. Full syntax of the CalendarTag attributes can be found in the Syntax guide.
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" %>
The uri attribute defines the path to where the tag library definition file
calendar.tld is found. Normally these are placed in the WEB-INF folder of your application.
The second attribute prefix defines the prefix used by the tags within the
rest of the JSP. The examples below and the samples use 'cal' for this prefix but you may
use some other term instead especially if you are already cal for another tag library.
The look and feel of the CalendarTag is controlled by a Cascading
Style Sheet, CSS. First place the calendar style sheet 'calendar.css' in a suitable
location on your web application such as the root folder. Then you can declare the
use of the style sheet in your JSP by placing the following line in the
head section of the page.
<link rel="stylesheet" type="text/css" href="calendar.css">
Below we will look at how to modify the look and feel of the calendar using CSS.
OK we have now referenced our tag within a JSP so let us now look at the different ways in which we can display the tag.
The CalendarTag will render an HTML table that displays the days of the month in typical calendar format of seven columns, one for each day of the week. You can place the CalendarTag anywhere you like within your JSP that allows an HTML table as a nested tag.
The simplest CalendarTag is one that just displays the current month. This is done by adding the following to your JSP,
<cal:calendar />
An example of a complete JSP is as follows,
<%@ taglib uri="/WEB-INF/calendar.tld" prefix="cal" %> <%@page contentType="text/html"%> <%@page pageEncoding="UTF-8"%> <html> <head> <link rel="stylesheet" type="text/css" href="calendar.css"> <title>A Simple CalendarTag Example</title> </head> <body> <p>A calendar for this month:</p> <cal:calendar /> </body> </html>
By defining attributes for the CalendarTag we can start to add functionality. We will look at these next.
You can specify a particular month and year for the CalendarTag to display.
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. Note that months a numbered from 0 to 11 rather than 1 to 12; this may seem unusual but it is in keeping with the convention used in the JDK classes that work with dates.
The main use of the CalendarTag is to allow an end user of your application to easily select a date. CalendarTag supports 2 methods that allow this: first is when the user selects a date the tag executes a client side script that may write the selected date to a form. The second technique is to allow the CalendarTag submit a request that contains parameters that define the selected date. These two techniques are discussed below.
Note these features are only available in the licensed version
The url attribute defines a URL which generates hyperlinks for each date
of the calendar. These hyperlinks are all suffixed with request parameters identifying the date,
month and year selected by the user. The parameters are,
Day - the value of the day selectedMonth - 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
For example if you defined a url in the CalendarTag as follows,
<cal:calendar url="/setStartDate.jsp" />
then the hyperlink that is constructed for first of January 1973 would be
<a href="/setStartDate.jsp?Day=1&Month=0&Year=1973"> 1 </a>
and similar hyperlinks for all other dates displayed in the tag.
An alternative to defining hyperlinks is to have the CalendarTag execute a client side JavaScript function. You create this function to do whatever you require; a common example is to write the date selected to a input box of an HTML form.
To do this you define the script attribute with the name of the
the name of the JavaScript function that is called when the user selects a date.
When the user clicks on a date in the calendar this function is called and is passed
three parameters: day, month and year. You therefore need to ensure that the function
can accept these three parameters. For example, we could have
<cal:calendar script="setDate" />
which would define hyperlinks in the generated HTML similar to,
<a href="" onclick="return setStart(3,8,2003)"> 3 </a>
and then have a suitable Javascript function similar to,
function setStart(day, month, year)
{
document.bookingForm.dateElement.value = day + "/" + (month + 1) + "/" + year;
return false;
}
Working examples of using the url and script attributes
can be found in the demo that comes with the CalendarTag packaged.
As mentioned earlier the calendar look and feel is wholly controlled by CSS. This then allows you to fully customise the look and feel of the generated calendar to fit your web application without having to modify any HTML. This section discusses these style sheet elements.
If you are new to CSS then it is recommended that you familiarise yourself with this technology. The CSS tutorial is a good place to start.
The CalendarTag package provides several example style sheets which serve as a starting point for customisation to suit your look and feel of the calendar.
Within the CalendarTag package you can find several example style sheets that illustrate the very different calendar styles that can be created just using CSS. If you have created a style sheet that you wish to share with others then please contact the support team and after review may well be added to the style gallery on gulland.com.
The following defines the styles of this style sheet and how the effect the rendered calendar.
This style defines the outer table that contains the calendar. You can use this style element for a variety of purposes: to define overall font size and face for the calendar, to define an outer border and background colour or to define a background image for the whole calendar. For example,
table.calendar
{
font-size: 0.8em;
border-left: #c97070 1pt solid;
border-top: #c97070 1pt solid;
border-right: #000000 1pt solid;
border-bottom: #000000 1pt solid;
background: #cccccc 1px solid;
}
Defines the style of the displayed month label and year text.
Defines the style for all cells and hyperlinks used in the calendar. Note this style will be overridden by other named styles such as td.calendar_thismonth.
Defines the style for the weekday labels.
Defines the style for the dates of the current month. This allows you to higlight the dates that are of the current month.
This is used to highlight the current day. This allows you to highlight the current day.
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;
}
Defines the style of the cell that contains the yesterday, today and tomorrow buttons. This is new in version 1.2