The DatePicker and Shell Components of Apache Tapestry

In the previous article in this series we came to adding a component for accepting a date input, to specify the date of birth for the newly added celebrity. DatePicker, a standard Tapestry component, is an excellent choice for this, and we are going to learn today how to add a DatePicker to a page.

However, DatePicker has a few downsides, and I am going to mention them, preparing you for the necessity of creating your own custom component for date input. Before building such a custom component, however, we’ll need to have a clear understanding of the PropertySelection component and the IPropertySelectionModel interface — this will be the topic for the next issue.

Meet DatePicker

To begin with, let’s add a DatePicker to the AddCelebrity page. Mark the remaining text box (labeled "Date of Birth") as a Tapestry component:

<td>Date of Birth:</td>


   <input type="text" jwcid="dateOfBirth"/>


Configure the new component in the page specification:

<component id="dateOfBirth" type="DatePicker">

   <binding name="value" value="dateOfBirth"/>


It has a familiar value binding. The only difference with what we dealt with before is that the data type for this binding has to be java.util.Date. Let’s configure a corresponding property in the page class:

public abstract Date getDateOfBirth();

Everything is as usual so far, but now DatePicker will require an additional configuration. This is because the functionality of this component is enabled by JavaScript. First of all, we need to make JavaScript libraries available for the page, and then we shall assist Tapestry in inserting the JavaScript required for DatePicker to work properly.

Tapestry 4.1 comes with an excellent Dojo JavaScript toolkit built into it. All we need to do to make this toolkit available to our page is to use a Shell component.

{mospagebreak title=Shell component}

The Shell component is quite useful and we are going to look at it properly in a later article in this series. For now, just a brief introduction: Shell is used to add to an HTML page a number of standard elements. It adds a <!DOCTYPE …> element, a <head> element with a <title> in it, can optionally add references to style sheets, and also adds all the necessary code to make the Dojo toolkit accessible for the page.

The only required binding for this component is title, which is a title for the page. Let’s define this component implicitly in the opening <html> tag of the page:

<html jwcid="@Shell" title="Add New Celebrity">

Now we have all JavaScript libraries available, but another problem arises: Shell will automatically insert its own DOCTYPE and head elements, in addition to already existing ones. And we don’t want our page to have two heads, do we? So let’s mark those that we’ve written ourselves for removal at runtime:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"



<html jwcid="@Shell" title="Add New Celebrity">

<head jwcid="$remove$">

   <title>Add New Celebrity</title>


Note that the page template still can be previewed by any browser as a browser simply ignores those things it doesn’t understand.

The last step in preparations is to make the <body> element of the page template a Tapestry’s Body component. This is very simple:

<body jwcid="@Body">

The purpose of this is to tell Tapestry where the page’s <body> tag is located, as it will need to insert two bits of JavaScript, required specifically for DatePicker, directly under that tag.

With this, we have completed the preparations for using a DatePicker, so run the application and see how the new component works. Initially, you should see a small calendar image to the right of the Birth Date text box, like this:

When you click this image, a glorious calendar opens, allowing you to pick a date:

Finally, the chosen date is inserted into the text box:

The component is quite impressive, but it has a few deficiencies.

{mospagebreak title=Possible deficiencies of DatePicker}

Some developers might not like all those preparations required for a single DatePicker to work, but in fact this is not a problem. The Shell component is so useful that in a real life application you will most probably have it in almost every page (you will see in a later tutorial why). And it is not difficult to implicitly declare a Body component.

One of the potential real problems is that some users will not have JavaScript support in their browsers, for different reasons. There might not be too many of these users, of course, and it is up to you to decide whether this is a serious problem. Also, they can always type in the date, as the text box remains available for date entry no matter what. In fact, many web users with advanced typing skills might prefer to type in the date instead of using the beautiful calendar, even if they have JavaScript working properly. And here the second potential problem arises.

Say the user has entered a date: 12/06/2007. How should your application interpret it: as the sixth of December, according to the pattern used in the USA, or as the twelfth of June, as the date would be understood in most other countries? The user will be very surprised if you will book her holiday in December instead of June!

One might think that to solve the problem, it will be enough to provide a notification like this:


But the reality of the Web is that many, many users will never notice your notification and will happily type in whatever they consider appropriate.

Finally, and this is yet another potential problem, some of your customers might not appreciate a pop-up calendar in the application you are building for them, just out of aesthetic considerations. I had such a customer in my first commercial Tapestry project, and I had to suggest some more serious looking control for date input.

Please understand me properly: I am not saying that the DatePicker component is bad. It is excellent and might be everything you want in the majority of your projects. But sometimes you will want something else, and this is exactly what moves us to consider the creation a custom component.

Thankfully, creating a custom component is very easy in Tapestry. However, we are going to do this a little bit later, after becoming familiar with the methods of IPropertySelectionModel in the next article. For now, all we have to do is complete the AddCelebrity page, so that the current iteration of our project can work properly.

First of all, let’s add to the DataSource a method for storing a newly added celebrity, as simple as this:

public void addCelebrity(Celebrity celebrity) {



We also need some way to generate a unique ID for every new celebrity. Here is one simple solution:

public int getNewId() {

   return list.size() + 1;


As long as we don’t remove any celebrities from the list, this solution will work.

Next, we need to create a new Celebrity object, fill it with information and save it using the DataSource. But where are we going to do all this? We need a listener method associated with the form on the AddCelebrity page. We already have an implicit Form component there, but let’s define it in the page specification now.


<form jwcid="@Form">


<form jwcid="addCelebrityForm">

and then add the following component declaration to AddCelebrity page specification:

<component id="addCelebrityForm" type="Form">

   <binding name="listener" value="listener:onAddCelebrity"/>


After the form is submitted, but before the listener method is called, Tapestry will put all the values submitted by the user into the properties of the page class, so we can simply take them from there. Here is the code to add a celebrity to the DataSource:

public String onAddCelebrity() {


   DataSource ds = getDataSource();


   Celebrity celebrity = new Celebrity();







   String occupation = getOccupation();


   if ("Actor/Actress".equals(occupation)) {

     if ("F".equals(getGender())) {

       occupation = "Actress";


     else {

       occupation = "Actor";








   return "CelebritiesList";


The code is quite simple. We are filling a new Celebrity object with values received from the user and only perform some manipulations when we need to decide whether this is an "Actor" or an "Actress." Finally, we add the new Celebrity to the DataSource and, by returning the "CelebritiesList" string, ask Tapestry to show the page with the table of celebrities.

Let’s see how it works. Run the application, navigate to the page for adding a new celebrity and enter some data. Here is an example:

Press Submit, and you should see the new celebrity added to the table:

Click on the Last Name link, and you should see the details:

So it works! And you will probably agree that the amount of code we have written wasn’t overwhelming.

Before completing this article, we need to look at one technical issue yet again.

{mospagebreak title=To cache or not to cache?}

In an earlier article I’ve advised you to disable caching page templates and page specifications by Tapestry, so you can immediately see any changes you have made to these files. However, soon after that a Tapestry developer emailed me to point out that disabling caching is not a good idea. You can read his message in full at the discussion page for that article.

I do agree that it is not a good idea to disable caching when working on a big complicated project, but I am tempted to think that it is still acceptable for our simple projects. On the other hand, it is better to set everything up properly from the very beginning, so we need an alternative solution. How do we reload page templates and specifications without disabling caching?

In my current project I avoid this issue by using a Maven script that rebuilds and redeploys the whole project when I need to test it. While the script works, I can take a breather, which is okay for me, but can madden some of the more impatient folks. Another option is to reload the project in Tomcat’s Application Manager. You can find a detailed description of how to do this in the first free chapter of the book by Kent Tong (a link to it is given in the first article of this series).

However, NetBeans offers yet another option, and it has worked well for me so far. As soon as you’ve made a change to a page template or specification, right-click on the project in the Projects view and select Clean and Build Project. Or maybe just Clean Project will do the same thing. When you run the project after such a cleanup, everything is deployed anew, and you can see all your changes.

I am still quite new to NetBeans (but I like this IDE), so suggestions from NetBeans gurus are welcome.

What comes next

In the next issue we are going to look into the details of how the PropertySelection component works and why IPropertySelectionModel is a powerful and flexible solution for providing options to a drop-down list.

See you in the next issue.

Google+ Comments

Google+ Comments