Introduction

Click is a simple JEE web application framework for commercial Java developers.

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.

Page 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.

Hello World Example

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

First we would have a HelloWorld page class:

package examples.page;

import java.util.Date;
import net.sf.click.Page;

public HelloWorld extends Page {

    public Date time = new Date();

}

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

<html>
  <body>
  
    <h2>Hello World</h2>
    
    Hello world from Click at $time
    
  </body>
</html>

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.

<click-app>  
  <pages package="examples.page"/> 
</click-app>

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

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

Hello World

Hello world from Click at Wed May 28 15:52:29 EST 2005

Table Example

Click also includes a library Controls which provide user interface functionality.

One of the most useful Click controls is the Table control. The Table control provides support for:

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

An example usage of the Table control in a customers Page is provided below:

public class CustomerPage extends Page {

    public Table table = new Table();
    public ActionLink deleteLink = 
        new ActionLink("deleteLink", "Delete", this, "onDeleteClick");

    public CustomersPage() {
        table.setClass("its");
        table.setPageSize(5);
        table.setShowBanner(true);
        table.setSortable(true);
    	
        table.addColumn(new Column("id"));
        table.addColumn(new Column("name"));
        
        Column column = new Column("email");
        column.setAutolink(true);
        table.addColumn(column);
        
        table.addColumn(new Column("category"));
    	
        column = new Column("Action");
        column.setDecorator(new LinkDecorator(table, deleteLink, "id"));
        column.setSortable(false);
        table.addColumn(column);
    }
    
    public boolean onDeleteClick() {
        Long id = deleteLink.getValueLong();
        getCustomerService().deleteCustomer(id);
        return true;
    }
    
    /**
     * @see Page#onRender()
     */
    public void onRender() {
    	List list = getCustomerService().getCustomersByName();
    	table.setRowList(list);
    }
}

In this Page code example a Table control is declared and a number of Column objects are added. A deleteLink ActionLink control is used a decorator for the "Action" column. This control will invoke the Page onDeleteClick() method when it is clicked. Finally we have the Page onRender() 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 toString() method is called.

<html>
  <body>
  
    <h3>Customers</h3>
    
    $table
    
  </body>
</html>

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

Customers

Id	Name	Email	Category	Action
834501	Alison Hanson	alison.hanson@gmail.com	Options	Delete
238454	Angus Mitchel	amitchel@mitchel.com	Stocks	Delete
1836512	Peter Mitchel	pmitchel@mitchel.com	Residential Property	Delete
418056	David Ofray	davido@yahoo.com	Bonds	Delete
445910	Ann Robertson	ann_robinson@surf.net	Commercial Property	Delete

31 items found, displaying 1 to 4.[First/Prev] 1, 2, 3, 4, 5, 6, 7, 8 [Next/Last]

In this example if a user click on the Delete link the onDeleteClick() method will be called on the Page deleting the customer record.

Form Example

Forms and Fiels are also some of the most commonly used controls in the Click Framework. The login Page below provides a demonstration of using Form and Field controls.

First we have a LoginPage class which setups up a login Form in the constructor.

public class LoginPage extends Page {

    public Form form = new Form();

    public LoginPage() { 
        form.add(new TextField("username", true));
        form.add(new PasswordField("password", true));
        form.add(new Submit("ok", "   OK   ", this, "onOkClicked"));
        form.add(new PageSubmit("cancel", HomePage.class));
    }

    public boolean onOkClicked() {
        if (form.isValid()) {
            User user = new User();
            form.copyTo(user);

            if (getUserService().isAuthenticatedUser(user)) {
                getContext().setSessionAttribute("user", user);
                setRedirect(SecurePage.class);
                return false;

            } else {     
                form.setError(getMessage("authentication-error"));           
            }
        }
        return true;
    }
}

Note in this example the page's public form field is automatically added to its list of controls.

Next we have the LoginPage template login.htm. The Click application automatically associates the login.htm template with the LoginPage class.

<html>
  <body>
  
    <h3>Login</h3>
    
    $form
    
  </body>
</html>

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

Login

Username*
Password*

Now the user enters their username, but forgets their password and then presses the OK button. The ClickServlet creates a new Login page and processes the form control. The form control processes its fields and determines that it is invalid.

Next the OK button onOkClicked() event handler is invoked, but as the form is invalid this method it does nothing.

With all the event processing completed the form now renders the field validation errors.

Login

Username*
Password*
You must enter a value for Password

If the user enters a correct username and password the onOkClicked() event handler will add a User object to the HttpSession and redirect the request to the SecurePage. Note how this code returns false, to abort any further processing in the page.

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

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. See the Click Examples for an interactive Form Properties demo.

For fine grained page design you can specifically layout form and fields in your page template. See the Form Javadoc for more details.