Presents your 
XML E-NEWSLETTER for May 28, 2003

<------------------------------------------->

USING THE DATE FUNCTIONS IN THE XSLT STANDARD LIBRARY

The XSLT-SL project provides a rich set of functions that you can use
within your XSL stylesheets. These functions include string manipulation,
node processing, URI processing, and date functions. Let's look at some 
of the date functions and how you can use them in your stylesheets.

DAY NAME

The day name function allows you to specify a date and get back the name
of the day (e.g., Monday, Tuesday). This can be helpful when you're
formatting XML data for a person to read.

LISTING A is a sample XML document that we'll use as the input for our
formatting examples throughout this article. LISTING B illustrates the use
of the day name function in an XSL stylesheet.

Listing A: mydoc.xml
<?xml version="1.0" ?>
<MyDoc>
  <SomeDate>
    <Year>2003</Year>
    <Month>1</Month>
    <Day>1</Day>  
  </SomeDate>
  <SomeTime>
    <Hour>12</Hour>
    <Minute>30</Minute>
    <Second>00</Second>
    <TZ>-05:00</TZ>
  </SomeTime>
</MyDoc>

Listing B: getday.xsl
<?xml version="1.0"  ?>
<xsl:stylesheet version="1.0"
    xmlns:xsl=http://www.w3.org/1999/XSL/Transform
    xmlns:dt="http://xsltsl.org/date-time">

<xsl:import href="http://xsltsl.sourceforge.net/modules/stdlib.xsl"/>

<xsl:template match="/">
  <MyDoc>
    <xsl:variable name="dow">
      <xsl:call-template name="dt:calculate-day-of-the-week">
        <xsl:with-param name="year" select="MyDoc/SomeDate/Year"/>
        <xsl:with-param name="month" select="MyDoc/SomeDate/Month"/>
        <xsl:with-param name="day" select="MyDoc/SomeDate/Day"/>
      </xsl:call-template>
    </xsl:variable>
    <DayOfWeek>
      <xsl:value-of select="$dow" />
    </DayOfWeek>
    <NameOfDay type="long">
      <xsl:call-template name="dt:get-day-of-the-week-name">
        <xsl:with-param name="day-of-the-week" select="$dow"/>
      </xsl:call-template>         
    </NameOfDay>
    <NameOfDay type="abbreviated">
      <xsl:call-template name="dt:get-day-of-the-week-abbreviation">
        <xsl:with-param name="day-of-the-week" select="$dow"/>
      </xsl:call-template>         
    </NameOfDay>
  </MyDoc>
</xsl:template>

</xsl:stylesheet>
http://www.w3.org/1999/XSL/Transform

This code listing illustrates three different date templates in the XSLT
Standard Library. First, we want to show the name of the day; however,
the template that returns the name of the day only takes one
parameter--the numeric day of the week. The Library gives us a function 
for that as well--the calculate-day-of-the-week template.

We use the calculate-day-of-the-week template to find the day of the
week for a specific date, store that value in an XSL variable, and then call
the get-day-of-the-week-name template to find the name, which, in this case,
is Wednesday.

We also illustrate the get-day-of-the-week-abbreviation template, which
returns Wed, as shown in LISTING C.

Listing C: gotday.xml
<?xml version="1.0" encoding="UTF-8"?>
<MyDoc xmlns:dt="http://xsltsl.org/date-time">
  <DayOfWeek>3</DayOfWeek>
  <NameOfDay type="long">Wednesday</NameOfDay>
  <NameOfDay type="abbreviated">Wed</NameOfDay>
</MyDoc>

DATE AND TIME FORMATTING

One of the most useful functions in the XSLT Standard Library is the
date and time formatting function. It allows you to format dates and times
in whatever particular format you want. This function takes several input
parameters, such as the day, year, month, and time variables. It also
takes a formatting parameter that specifies the output format for the date and time.

LISTING D shows an example XSL stylesheet that illustrates a basic call
to the formatting function. In this example, we don't specify a format,
which means the template uses the default format.

Listing D: mydoc.xsl
<?xml version="1.0"  ?>
<xsl:stylesheet version="1.0"
    xmlns:xsl=http://www.w3.org/1999/XSL/Transform
    xmlns:dt="http://xsltsl.org/date-time">

<xsl:import href="http://xsltsl.sourceforge.net/modules/stdlib.xsl"/>

<xsl:template match="/">
  <MyDoc>
    <NewDateTime>
      <xsl:call-template name="dt:format-date-time">
        <xsl:with-param name="year" select="MyDoc/SomeDate/Year"/>
        <xsl:with-param name="month" select="MyDoc/SomeDate/Month"/>
        <xsl:with-param name="day" select="MyDoc/SomeDate/Day"/>
        <xsl:with-param name="hour" select="MyDoc/SomeTime/Hour"/>
        <xsl:with-param name="minute" select="MyDoc/SomeTime/Minute"/>
        <xsl:with-param name="second" select="MyDoc/SomeTime/Second"/>
        <xsl:with-param name="time-zone" select="MyDoc/SomeTime/TZ"/>
      </xsl:call-template>
    </NewDateTime>
  </MyDoc>
</xsl:template>

</xsl:stylesheet>
http://www.w3.org/1999/XSL/Transform

LISTING E shows the output of this stylesheet:

Listing E: mynewdoc.xml

<?xml version="1.0" encoding="UTF-8"?>

<MyDoc xmlns:dt="http://xsltsl.org/date-time">

  <NewDateTime>2003-01-01T12:30:00</NewDateTime>
</MyDoc>

We can use the format parameter to specify our own format. There are
many options that you can specify in the format parameter. For example, you
can specify a local time format or any combination of date and time
components. The full documentation is available online.

Let's suppose we want to display our date and time in the following format:

  Wednesday January 01, 2003

We could use the following call to the format-date-time template:

      <xsl:call-template name="dt:format-date-time">
        <xsl:with-param name="year"
 select="MyDoc/SomeDate/Year"/>
        <xsl:with-param name="month"
 select="MyDoc/SomeDate/Month"/>
        <xsl:with-param name="day"
 select="MyDoc/SomeDate/Day"/>
        <xsl:with-param name="hour"
 select="MyDoc/SomeTime/Hour"/>
        <xsl:with-param name="minute"
 select="MyDoc/SomeTime/Minute"/>
        <xsl:with-param name="second"
 select="MyDoc/SomeTime/Second"/>
        <xsl:with-param name="time-zon"
 select="MyDoc/SomeTime/TZ"/>
        <xsl:with-param name="format" select="'%A %B %d,
 %Y'"/>
      </xsl:call-template>

In this example, %A represents the full name of the day, %B represents
the full name of the month, %d represents the day of the month, and %Y
represents the year (with the century).

MORE OPTIONS

The XSLT Standard Library can augment your XSL stylesheets by providing
increased functionality. There are a handful of other date functions in
the XSLT Standard Library, but most are available by calling the
format-date-time function. You can find out about these options and other
formatting parameters by visiting the XSLT Standard Library Web site.
http://xsltsl.sourceforge.net/

Brian Schaffner is an associate director for Fujitsu Consulting. He provides
architecture, design, and development support for Fujitsu's Technology
Consulting practice.

----------------------------------------