Task 6 - Create Tapestry 5 components library

One of the promises of Tapestry 5 is easy creation of components. The word component can trigger lots of different associations in people’s minds. I guess for the majority of web developers the component means a GUI thing. For someone from the middle management a component might as well be a forum system with all the bells and whistles. For old school guys the first impression when the word component is a word of discussion might mean an architectural thing.

To me, the term components, is quite a familiar for a number of years now. When I started with web application development I was a lucky man as Web Objects were my first contact in a jungle of languages and frameworks out there. You can imagine (I hope) the disappointment when I had to switch to JSP. Only now I got an opportunity to use similar technology again!

Until now, all my posts were talking about preparing the development environment and this one feels like I am jumping ahead of time. In a sense this is true, but I think creating a place to put the goodies you will create and reuse is a good start. Why would you create a component and later copy it to a library? Let’s do it right now.

The tools are: Eclipse Ganymede, m2eclipse 0.9.7, Maven 2.0.10 and Java 6.

In Eclipse click the New button
then type maven in the filter box and select Maven Project
Click Next and select Create a simple project.
Click Next and fill-in the configuration details.
All of the values I have filled-in do not have any special meaning. You can name your GroupId and ArtifactId anything you want.

Now we will skip the last step of the wizard (adding dependencies) and just press Finish. You should see a new project in the Project Explorer.
Now double click the pom.xml to open it in Maven POM Editor. The content should be something like:

  4.0.0
  bb.webcraft.tapestry
  components-library
  bbWebCraft Tapestry 5 components library
  0.0.1-SNAPSHOT
  A collection of Tapestry 5 components

We need to add some more elements in the pom for this project to become a Tapestry 5 components library. A bare minimum is:

  4.0.0
  bb.webcraft.tapestry
  components-library
  bbWebCraft Tapestry 5 components library
  0.0.1-SNAPSHOT
  A collection of Tapestry 5 components
  
      
          org.apache.tapestry
          tapestry-core
          ${tapestry-release-version}
      
  
  
      
          
              org.apache.maven.plugins
              maven-compiler-plugin
              
                  1.5
                  1.5
                  true
              
          
          
              org.apache.maven.plugins
              maven-jar-plugin
              
                  
                      
                          bb.webcraft.tapestry.library.services.LibraryModule
                      
                  
              
          
      
  
  
      5.0.18
  

Please note that Tapestry-Module-Classes could as well be

com.acme.services.MyModule

but would be a bad practice. The java packages you will create in this library project will have the same root as the GroupId (bb.webcraft.tapestry).

Let’s create a package bb.webcraft.tapestry.library.services
and then a java class named LibraryModule.
This is now your library’s IoC module. In order for Tapestry to know where to search for your component’s classes you need to make a contribution to the ComponentClassResolver service configuration

package bb.webcraft.tapestry.library.services;

import org.apache.tapestry5.ioc.Configuration;
import org.apache.tapestry5.services.LibraryMapping;

public class LibraryModule {
  public static void contributeComponentClassResolver(Configuration<LibraryMapping> configuration) {
      configuration.add(new LibraryMapping("bbwcraft", "bb.webcraft.tapestry.library"));
  }
}

The project is now ready. If it had any components, you would just put the jar on your web application’s class path and use it. You can create a jar by typing mvn package in the console or by right clicking on a project root (or pom.xml) and selecting Run As / Maven package.
A jar named components-library-0.0.1-SNAPSHOT.jar should be created in the target folder. As you may know a jar has to be installed (mvn install) in your local maven repository to be used by other mavenized projects. You can then use the library by referencing it in your application’s pom like this:

  bb.webcraft.tapestry
  components-library
  0.0.1-SNAPSHOT

Now would be the time and place to mention how to use the component from the library in some T5 application, but since we haven’t actually created one, we will leave this for the next post.

Before we end, let’s add another section in the library’s pom (under the <project> element).

  
      
          org.apache.tapestry
          tapestry-component-report
          ${tapestry-release-version}
          
              bb.webcraft.tapestry.library
          
      
  

This is very important, as you and Tapestry will create a good documentation about your components. I will also talk about how to write the documentation for the components in the next post where we will actually create a component – a date input component composed of three combo boxes (day, month, year) suitable for selecting dates far in the past or future.