Task 2 – Explore the Tapestry 5 project structure and learn where to put your stuff

This post is a continuation of the previous one.

Let’s expand all the nodes of the project in the Package Explorer.

If you have never seen a project structure for a web application by Maven convention – this is it. Well, with Tapestry flavor. This “tree of files” is created by tapestry quickstart archetype.

Two sentences of theory before continuing.

It is WHERE the files END UP in the WAR that matters, not where they are in your development environment. The IDE and tools that you use should maximize the productivity and harness the power that is provided by Tapestry framework.

I will continue to describe one project layout with one set of tools in this post. I want to describe things simple. I will rather create another post for different set of tools and/or personal preferences of where things (files) can be.

The tools of choice are: Eclipse (3.4.0), Maven (2.0.9) and m2eclipse plugin (0.9.6).

As we are not starting from scratch – the archetype did the initial work for us – let’s have a look at the existing directories and files from top to bottom.

There are two java files in two different packages: Index.java and AppModule.java. The Index.java resides in the org.driving.school.pages package and it is in this package that you will add java sources for additional pages you will create. The AppModule.java is a Tapestry Inversion of Control Module. This is your application’s module builder class. In other words – it is where you will do most of the configuration.

The accompanying template file to the Index.java controller class is Index.tml. In the above figure it is located in the src/main/webapp/ directory. This file can also reside in src/main/resources/org/driving/school/pages directory. It is of personal/team CHOICE where the template files are located.

So, what else goes to src/main/resources? As you can observe from the figure above, the log4j.properties file is one of them. Why? Because when packaged, it ends up in the WEB-INF/classes, which means on the classpath. Message catalogs (.properties) also belong here.

You can imagine what goes to src/test/java and src/test/resources. I will not go into details here because this is not a crash course in Test Driven Development.

Next, there are two libraries: JRE System Library and Maven Dependencies. The latter includes all the jars needed by the project. Only two of them are really referenced in the project’s POM: tapestry-core and testng. The others are so called transitive dependencies (dependencies of dependencies). Maven takes care of downloading and including them in the classpath.

We will skip src/main/webapp/META-INF/MANIFEST.MF.

And then there is app.properties file under src/main/webapp/WEB-INF. This is a global message catalog. It will include a default language messages. They are called messages because you will be accessing them through the message prefix, but we will not discuss that now. If your application will be multilingual then you would create a file, for example, app_sl_SI.properties which would include Slovenian messages (translations).

Next, the only XML file you will need to have in your application – web.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
   "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>school Tapestry 5 Application</display-name>
<context-param>
   <param-name>tapestry.app-package</param-name>
   <param-value>org.driving.school</param-value>
</context-param>
<filter>
   <filter-name>app</filter-name>
   <filter-class>org.apache.tapestry5.TapestryFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>app</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>

There is one context parameter. It has a value of org.driving.school. This tells Tapestry where to look for pages and components. That is why you have a package named org.driving.school.pages under src/main/java.

You can also see there is a filter named app which is implemented by TapestryFilter class. Every request that comes to application’s context (in our case http://localhost:8080/school) is processed by TapestryFilter.

Favicon.ico is a file which I think everyone knows what it is, so we will skip it.

Now the template file for the page – Index.tml. I have already mentioned it above. This is a XHTML file which includes elements in Tapestry namespace

xmlns:t=http://tapestry.apache.org/schema/tapestry_5_0_0.xsd

like

<t:pagelink page="Index">refresh</t:pagelink>

The tml files are the View part of your app and those files will be the only ones developers will meet the designers. With very little practice no one will ruin the work of the other one. There is of course a lot more to tell for the templates, but as this blog is about hands-on approach to building web apps, I have to be short in words and more expressive in examples and real world cases.

One file remains – pom.xml. This is a Maven thing. It manages our project. It is here where you configure what java libraries do we need, and what version of the compiler to use, and what should be the name of the WAR (hence context name) etc.

It includes a jetty plugin which enables us to run the web app with mvn jetty:run, but unfortunately Windows users will have to do a bit more to achieve that changing something in the CSS will be visible in the browser without restarting the Jetty container. Yes, something as basic as that and it does not work out of the box by pressing F5 (refresh) in the browser. I was quite disappointed until I dug the solution on the net. I will write about this in the next post.

The quickstart archetype is really just that – quick. It does not demonstrate the users (developers) where components are, where images and css files should be, how pages can be grouped in subfolders/subpackages and a lot of other concepts. Of course this is all explained at official site, but in many cases in a technical lingo which does not suit everyone well, especially newbies. Several more archetypes should be created and made available to public via Maven repositories which would demonstrate and kick start a new project with some additional concepts.

So, to achieve the Task 2 I have to explain where to put your components. The java files for this project would go under src/main/java/org/driving/school/components and the resources (templates, message catalogs, javascript) under src/main/resources/org/driving/school/components.

Put your images in the src/main/webapp/images (or img or similar) and CSS files as a sibling to images (src/main/webapp/css).

This post ends here. It does not provide much value as we have only walked through the files of the quickstart project template, but it pointed out to some weak points which will all be addressed in the next posts. The goal is to remove the pit holes some of us have fallen into when started to use Tapestry 5.