Java Web Application Development With Click Framework/Appendix A: FAQ

How to get help?

OK you have read the documentation and reviewed the example applications, but there is still something you still don't get. What do you do?

You go to the click-user click-development mail news groups. This is where you get support from in open source projects. It's free, friendly and usually pretty responsive. These news groups are where other people ask questions, and where users and developers discuss ideas. It's highly recommended, so don't be shy.

To sign up to these mail groups click on the following links:

• click-user - for Click usage discussions and help
• click-development - for Click framework development discussions

What about Commercial Support?

If you want commercial support or training for Click, you can obtain this from Avoka Technologies.

For more details please email Malcolm Edgar.

What development tools are there?

Recommended Click development tools include:

ClickIDE

ClickIDE is an Eclipse Web Tools Project (WTP) plugin developed by Naoki Takezoe.

To use the ClickIDE plugin, create a "Dynamic Web Project" and select the "Click" Project Faclet.

NBClick

NetBeans plug-in for Click is under development by Geertjan Wielenga and Ahmed Mohombe.

Velocitywebedit

Velocitywebedit is a Velocity and HTML Editor plugin for Eclipse.

After installing Velocity Web Edit configure Eclipe *.htm file associations to use Velocity Editor. Do this via the Eclipse menus: Window > Preferences > General > File Associations

Veloeclipse

Velocity and HTML Editor plugin for Eclipse

Veloedit

Velocity and HTML Editor plugin for Eclipse

How can the GUI designer define the HTML if Click Controls generates everything?

In Click there is nothing preventing you from laying out HTML forms by hand. It just provides the option of doing it automatically for you.

There are a number of approaches you can use for generating for HTML, each with pros & cons:

Use Click forms and controls to do all the HTML rendering for you.

This a 80/20 approach where you can quickly get stuff developed, but it may not meet all your UI style requirements. Please note the Forms control provides many [click-api/net/sf/click/control/Form.html#auto-layout auto layout] options, see the [examples.html click-examples] 'Form Properties' for a demonstration. The Form control also renders the class attributes 'form', 'fields', 'errors' and 'buttons' in the form's HTML elements enabling fine grained CSS control.

As an example you could configure a form to display the labels on top, and want to increase the vertical spacing between fields. To do this simply define the CSS style in front of your form:

 <style type="text/css">
    td.fields { padding-top: 0.75em; }
 </style>

 $form

Fields are also rendered with an 'id' attribute enabling manipulation of individual fields.

Subclass Click Form/Controls to customise HTML rendering.

This is a good approach for ensuring a common LAF across your web application, but you will have to get your hands dirty and write some code.

Use Panel to class to create reusable HTML blocks.

The Panel control support custom Velocity templates, which is an ideal way to create reusable HTML sections which you can include in many pages. Panels also support nested controls, enabling your sections to support control based behaviour.

Use Velocity macros for a generic HTML layout.

This is easy to do and gives you good reuse across your web application.

Layout your HTML forms by hand.

This gives you the ultimate control in presentation, but provides no reuse across your web application.

How can I have many Pages using the same HTML template?

To do this use the Page templating technique detailed in the Page Templating topic. Page templating is highly recommended for your web applications, as it provides numerous benefits including:

• greatly reduces the amount of HTML you need to maintain
• ensures you have a common look and feel across you application
• makes your application more robust, as there is less code to test

Why do control listeners methods have to return a boolean value?

Control listener methods have to return a boolean value to state whether the Pages controls and methods should continue to be processed. To continue processing listener methods should return true, to abort they should return false. The reason you may want to abort further processing is so you can navigate directly to another page, rather than continuing to execute other control or page methods which may be time consuming. You can use this feature like a break or goto statement. For example:

public boolean onLogoutClick() 
{
   setRedirect(Logout.class);
   return false;
}

Can you exclude some fields from a Form?

To exclude some fields from being displayed in a shared Form class use the Form.removeFields() method.

You can even do this in your page template. Just make sure you call you call it before $form renders itself. For example:

$form.removeFields(["field11", "field15", "field22"])

$form

How do you internationalize Pages and Controls?

Click provides good support for application localization and internationalization (I18N) requirements.

Page Messages

The Page class supports page specific string localisation bundles using the method [click-api/net/sf/click/Page.html#getMessage(java.lang.String) getMessage(String)]. For example a Login class with three locale string property files on the classpath:

/com/mycorp/pages/Login.properties

/com/mycorp/pages/Login_en.properties

/com/mycorp/pages/Login_fr.properties

In your Login Page class you can use the getMessage() method to lookup request localized message strings.

public void onInit() 
{
    addModel("title", getMessage("title"));
}

In your HTML page template you can also access the localize message using the MessagesMap object which is added to the template using the name "messages". For example:

<h2>$messages.title</h2>

You can also define Field and ActionLink labels and title values in your pages properties file using control name lookup convention.

• ActionLink.getLabel()
• ActionLink.getTitle()
• Field.getLabel()
• Field.getTitle()
• FieldSet.getLegend()

Field Messages

The Field control classes share a common messages properties file:

/click-control.properties

The field class provides a number of getMessage(String) methods which support localized strings and message formatting.

How do you encode Pages in the UTF-8 character set?

To encode pages in the UTF-8 character set you need to create a WEB-INF/velocity.properties file with the properties:

input.encoding=UTF-8

This will configure the Velocity runtime to use UTF-8.

You will also need to set the page headers content type to UTF-8. You can do this globally for all your applications pages using the headers element in your WEB-INF/click.xml file:

<click>
 ..
 <headers>
   <header name="Content-Type" value="text/html;charset=UTF-8"/>
 </headers>
 ..
</click>

This will set the page's HttpServletResponse "Content-Type" header to be "text/html;charset=UTF-8". Alternatively you can override the Page getContentType() method to this content type.

How do you specify the character set which is used in your application?

You can specify your application character set in WEB-INF/click.xml:

<click charset="UTF-8">
 ..
</click>

This character set is used for Velocity input encoding, and response Content-Type. So if you specify the character set in WEB-INF/click.xml, you don't have to create WEB-INF/velocity.properties.

If you want to use the other character set in your Velocity templates, you can override input encoding by WEB-INF/velocity.properties.

How can you prevent multiple form posts?

You can prevent multiple form posts by using the Post Redirect pattern. With this pattern once the user has posted a form you redirect to another page. If the user then presses the refresh button, they will making a GET request on the current page.

To prevent users resubmitting a form with the browser back button use the Form onSubmitCheck() method:

public class Purchase extends Page 
{
    ..

    public boolean onSecurityCheck() 
    {
        return form.onSubmitCheck(this, "/invalid-submit.html");
    }
}

How can I use *.html Click pages?

Click does not support *.html files as Click pages. These files are not processed by the ClickServlet and are intended for use as static content.

What JARs should I use with Click and Cayenne?

To get Click and Cayenne to work happily with each other you will need to include the following JAR files in your WEB-INF/lib directory:

• ashwood-1.1.jar
• cayenne-nodeps-1.2.x.jar
• click-1.x.jar
• click-extras-1.x.jar
• log4j-1.2.x.jar
• oro-2.0.8.jar

The default Cayenne JAR includes Velocity 1.3 which is not compatible with Click which uses Velocity 1.5-dev, so instead we use the Cayenne no dependencies JAR. When using Cayenne nodeps JAR we need to add some additional Java libraries which include ashwood, log4j and oro.

How can you integrate Click into Spring?

To integrate Spring with Click configure the SpringClickServlet instead of the normal ClickServlet. The SpringClickServlet is contained in the Extras library.

The Spring MVC Framework however, is not compatible with Click. The Spring framework uses a low level command pattern design like Struts and WebWork. Spring uses a DispatcherServlet to route requests to Controller objects and then passes the ModelAndView results to the rendering layer.

public interface Controller 
{
   public ModelAndView handleRequest(HttpServletRequest request,
                                     HttpServletResponse response) throws Exception;
}

In Spring MVC the integration plugin points are the Controllers.

Click uses higher level design constructs focusing on Pages and Controls. Click uses its own ClickServlet for dispatching requests to Pages and Controls, which are Click's plugin points.

Does Click support JSP?

Click fully supports JSP pages.

JSP Pages can be automatically loaded, like Velocity templates, and can be explicitly defined in the click.xml file.

<page path="customers-table.jsp" class="com.mycorp.pages.CustomersTable"/>

The page's model data values are automatically added to the request as attributes so they are available in the JSP.

Other Click values added as request attributes include:

• context - the Servlet context path, e.g. /mycorp
• format - the [click-api/net/sf/click/util/Format.html Format] object for formatting the display of objects
• forward - the page JSP resource (.jsp file)
• messages - the [click-api/net/sf/click/util/MessagesMap.html MessagesMap] adaptor for the Page [click-api/net/sf/click/Page.html#getMessage(java.lang.String) getMessage()] method
• path - the mapped request [click-api/net/sf/click/Page.html#path path] of the page. Note this will have a .htm not a .jsp extension

What is the performance of Click?

Click is fast.

When the Click framework processes a request it creates a relatively small number of objects. These include a Page, a Context, a Format and a number of Contols which in turn contain some Lists, Maps and Strings.

The allocation of small/moderate numbers of short lived objects by modern JVMs is very, very fast.

The amount of actual work Click does is pretty small.

The onProcess() methods traverse a list of Controls and do simple operations.

The Control toString() methods can allocate large StringBuffers when rendering tables, but forms rarely get larger than 4,000 characters. When Click creates a new StringBuffer it attempts to determine the maximum likely size to avoid additional memory allocation and arraycopy operations.

There is not much reflection in Click at all. With reflection only really used by the Control call back listeners:

okButton.setListener(this, "onOkClicked");

The next step in processing the request is rendering the response. Velocity is largely responsible for this step.

Velocity is also fast.

While hard performance numbers are difficult to come by in this area, until recently Velocity was considered to be faster than JSP. However, recent discussions on Velocity mail lists indicate that JSP compilers have improved to the point where JSP has a small performance lead over Velocity. What ever the case, JSP is very fast and so is Velocity.

How do I unit test Click pages?

It is generally recommended that you don't write JUnit style automated unit tests for Click pages as the cost to benefit ratio is quite poor. If you have complex business logic in an Click page you should refactor this code into a business level service class which you can readily unit test and reuse in multiple places.

If you still need to write unit test for your Click pages please use the Click mock MockContext and MockRequest classes found in the mock distribution directory.

Why doesn't Click use Commons Logging / Log4J for logging?

Click initially did not use Log4J with Velocity because of an appender closing memory leak associated with garbage collecting VelocityEngines. This issue has been resolved with the latest Velocity 1.5 development stream.

Commons Logging is not used because of class loader issues which occur on versions of IBM's WebSphere application server.

Why doesn't Click use FreeMarker instead of Velocity?

FreeMarker is a powerful templating engine which was evaluated along side Velocity for use in Click. While FreeMarker has many sophisticated features Velocity doesn't, Velocity was chosen because it easier to learn and doesn't use an XML style markup syntax.

One of FreeMarker's strong points compared to Velocity is error reporting. This issue is addressed in Click by using the new enhanced error reporting feature of Velocity 1.5.

Click will render the source code with the error. For example:

• Page Parsing Error
• Null Pointer Error

Why develop a new Web Application Framework?

Because the existing frameworks did not meet my needs. Struts doesn't really do much, while Tapestry is too complicated. For a more comprehensive answer please see Why Click.