Java Web Application Development With Click Framework/Introduction

Click is a simple JEE web application framework for commercial Java developers. youtube Click is an open source project, licensed using the Apache license.

Click uses the event based programming model for processing Servlet requests and Velocity for rendering the response.

This framework uses a single servlet, called ClickServlet, to act as a request dispatcher. When a request arrives ClickServlet creates a Page object to processes the request and then uses the page's Velocity template to render the results.

Pages provide a simple thread safe programming environment, with a new page instance is created for each servlet request.

Possibly the best way to see how Click works is to dive right in and look at some examples:


 * The Hello World classic
 * An ActionLink control listener example
 * A simple Table control example
 * A more advanced Table example
 * A simple Form example
 * A more advanced Form example

Hello World Example
A Hello World example in Click would look something like this.

First we would have a HelloWorld page class:

Next we would have a page template hello-world.htm:

And finally we have a click.xml configuration file which tells our Click application to map hello-world.htm requests to our HelloWorld page class.

At runtime the ClickSerlvet maps a GET hello-world.htm request to our page class <tt>example.page.HelloWorld</tt> and creates a new instance. The HelloWorld page creates a new public <tt>Date</tt> object, which is automatically added to the page's model using the field's name <tt>time</tt>.

The page model is then merged with the template which substitutes the <tt>$time</tt> parameter with the <tt>Date</tt> object. Velocity then renders the merged template which looks something like

Control Listener Example
Click includes a library (Controls) which provide user interface functionality.

One of the commonly used controls is the ActionLink, which you can use to have a HTML link call a method on a Page object. For example:

In the Page class we create an ActionLink called <tt>myLink</tt> and define the control's listener to be the page method <tt>onMyLinkClick</tt>. When a user clicks on myLink control it will invoke the listener method <tt>onMyLinkClick</tt>.

In Click a control listener method can have any name but it must return a boolean value. The boolean return value specifies whether processing of page events should continue. This control listener pattern provides a short hand way wiring up action listener methods without having to define anonymous inner classes.

Back to our example, in the page template we define a HTML link and have the <tt>myLink</tt> control render the link's href attribute:

At runtime this page would be rendered as:

Click myLink control here.

When a user clicks on the link the <tt>onMyLinkClick</tt> method is invoked. This method then creates <tt>msg</tt> model value, which is rendered in the page as:

Click myLink control here. ControlListenerPage#12767107 object method <tt>onMyLinkClick</tt> invoked.

Simple Table Example
One of the most useful Click controls is the <tt>Table</tt> control.

An example usage of the <tt>Table</tt> control in a customer's <tt>Page</tt> is provided below:

In this Page code example a Table control is declared, we set the table's HTML class, and then define number of table <tt>Column</tt> objects. In the column definitions we specify the name of the column in the constructor, which is used for the table column header and also to specify the row object property to render.

The last thing we need to do is populate the table with data. To do this we override the Page <tt>onRender</tt> method and set the table row list before it is rendered.

In our Page template we simply reference the <tt>$table</tt> object which is rendered when its <tt>toString</tt> method is called.

Note above we also specify the $cssImports reference so the table can include any CSS imports or styles in the header, and the $jsImports reference so any JavaScript imports or scripts at the bottom.

At runtime the Table would be rendered in the page as:



Advanced Table Example
The Table control also provides support for:


 * automatic rendering
 * column formatting and custom rendering
 * automatic pagination
 * link control support

A more advanced Table example is provided below:

In this <tt>Page</tt> code example a <tt>Table</tt> control is declared and a number of <tt>Column</tt> objects are added. A deleteLink ActionLink control is used a decorator for the "Action" column. This control will invoke the Page <tt>onDeleteClick</tt> method when it is clicked. Finally we have the Page <tt>onRender</tt> method which is used to populate the Table control with rows before it is rendered.

In our Page template we simply reference the $table object which is rendered when its <tt>toString</tt> method is called.

At runtime the Table would be rendered in the page as:



In this example if a user click on the Delete link the <tt>onDeleteClick</tt> method will be called on the Page deleting the customer record.

Simple Form Example
The <tt>Form</tt> and <tt>Field</tt> controls are also some of the most commonly used controls in the Click Framework.

The SimpleForm page below provides a demonstration of using these controls.

In our example code we have the page's constructor adding a <tt>TextField</tt> field and a <tt>Submit</tt> button to the form. A page method is also set as a control listener on the form. Also note in this example the page's public <tt>form</tt> field is automatically added to its list of controls.

Next we have the SimpleForm template simple-form.htm. The Click application automatically associates the <tt>simple-form.htm</tt> template with the <tt>SimpleForm</tt> class.

When the SimpleForm page is first requested the $form object will automatically render itself as:


 * Name*

Now if the user does not enter their name and presses the OK button to submit the form. The ClickServlet creates a new SimpleForm page and processes the form control.

The form control processes its fields and determines that it is invalid. The form then invokes the listener method <tt>onSubmit</tt> method. As the form is not valid this method simply returns true and the form renders the field validation errors.


 * [# You must enter a value for Name]


 * Name*

Note the form will automatically maintains the entered state during the post and validate cycle.

Now if the user enters their name and clicks the OK button, the form will be valid and the <tt>onSubmit</tt> add a msg to the Pages model. This will be rendered as:


 * Name*


 * Your name is John Masters

Advanced Form Example
facebook The <tt>AdvancedForm</tt> page below provides a more advanced demonstration of using Form, Field and FielsSet controls.

First we have a <tt>AdvancedForm</tt> class which setups up a <tt>Form</tt> in the constructor. The form's investment <tt>Select</tt> list is populated in the page's <tt>onInit</tt> method. At this point any page dependencies such as the CustomerService should be available.

Note in this example the page's public <tt>form</tt> field is automatically added to its list of controls. The <tt>msg</tt> field is added to the page's model.

Next we have the AdvancedForm template advanced-form.htm. The Click application automatically associates the <tt>advanced-form.htm</tt> template with the <tt>AdvancedForm</tt> class.

When the AdvancedForm page is first requested the $form object will automatically render itself as:


 * Customer


 * Name*


 * Email*


 * Investment BondsCommerical PropertyOptionsResidential PropertyStocks


 * Date Joined* [[Image:Calendar_-_2.png|Calendar]]


 * Active

In this example when the OK button is clicked the <tt>onOkClicked</tt> method is invoked. If the form is valid a new customer object is created and the forms field values are copied to the new object using the Form <tt>copyTo</tt> method. The customer object is then saved, the form's field values are cleared and an info message is presented to the user.

If the user clicks on the Cancel button the request is redirected to the applications HopePage.

Form Layout
In this example we use the form control to automatically render the form and the fields HTML. This is a great feature for quickly building screens, and the form control provides a number of layout options.

For fine grained page design you can specifically layout form and fields in your page template.