Introduction

Click is a simple J2EE 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 an examples.

Click Example

A Hello World example in Click would look something like this. You would have a click.xml configuration file which defines our Hello World page class and its Velocity page template:

<click-app>  
  <pages> 
    <page path="hello-world.htm" classname="examples.page.HelloWorld"/> 
  </pages>
</click-app>

Next we have our page class examples.page.HelloWorld:

package examples.page;

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

public HelloWorld extends Page {

    /**
     * @see Page#onGet()
     */
    public void onGet() {
        addModel("time", new Date());
    }
}

And then we have the page template hello-world.htm:

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

At runtime the ClickSerlvet maps a GET hello-world.htm request to our page class example.page.HelloWorld and creates a new instance. The ClickServlet then invokes the page's onGet() method. This method creates a new Date object and adds it to the page's model as a value called 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

Form Example

Click also includes a library Controls which provide user interface functionality. The example below provides a login Page which demonstrate Click controls.

First we have a Login page class which setups up a login form in the onInit() method.

public class Login extends Page {

    private Form form = new Form("form");

    /**
     * @see Page#onInit()
     */
    public void onInit() {
        addControl(form);
 
        form.add(new TextField("username", true));
        form.add(new PasswordField("password", true));
        form.add(new Submit("ok", "   OK   ", this, "onOkClicked"));
        form.add(new Submit("cancel", this, "onCancelClicked"));
    }

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

            if (UserDAO.isAuthenticatedUser(user)) {
                getContext().setSessionAttribute("user", user);
                setRedirect("secure.htm");

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

    public boolean onCancelClicked() {
        setRedirect("index.htm");
        return true;
    }
}

Next we have the Login page template login.htm:

<html>
  <body>
  
    <h2>Login</h2>
    
    $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 secure.htm page.

If the user clicks on the Cancel button the onCancelClicked() event handler is invoked and the request is redirected to the index.htm page.

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.