text:
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.


text:
Java Web Application Development With Click Framework/Why Click

This topic discusses the design philosophy and background behind Click, and hopefully explains why someone would build another Java web application framework.

Click is modern JEE web application framework, providing a natural rich client style programming model. Key features of Click include:

Simple to Learn
Click is designed to be simple learn so that new developers can get up and running in a day. This is very important with commercial development teams where you have a wide range of skill levels and motivation.

My experience introducing Tapestry (2.3) to development teams was that it is too complex and difficult to learn for the average developer. The two development teams I introduced to Tapestry eventually dropped it and revert to Struts.

Click is also significantly easier to learn than Struts. The Struts framework, while essentially a simple command pattern design, has quite a convoluted and confusing design.

To support ease of adoption Click has some of the best documentation available for an open source framework and includes many working examples.

Component and Page Oriented Design
If you have done traditional GUI programming with Swing, VB or Delphi you will know that there is something very wrong with JEE web development. JEE web development is painfully slow, complex and error prone.

One of the first generation JEE web frameworks was Struts, which provides a command pattern design and a set of JSP tag libs. Unfortunately with Struts you are still down in the weeds, mapping URLs to Actions working with primitive ActionForms. Its not giving you much leverage at all.

Tapestry was one of first the component base JEE web frameworks, introducing the component hierarchies, pages and an event based programming model. This is a much more productive way of working, and is what we have come to expect in when developing desktop GUI applications.

The idea with Click was to take this page and component design approach, and make it much easier to use and more accessible.

Click provides an Page oriented design, featuring Control components and an event based programming model. Click includes 40 Controls out of the box, which correspond to the major HTML elements. It's a great way of programming more simply.

Click Forms and Controls provide automatic validation and rendering, making form development very fast and robust.

JSP & MVC Free
Click is JSP and MVC Free. This is a good thing!

JSP's combined with the miss application of the MVC pattern have been holding back JEE web development for many years. It's a big statement I know, please let me explain.

MVC is a desktop GUI design pattern, which supports a separation of roles in UI design. Model is the data, the View does the rendering and the Control is for modifying the data. Now MVC is a fairly sophisticated UI pattern which solves the problem of multiple views and controls sharing the same data.

For most UI development however MVC is overkill. The control and the view are usually the same thing. For example, a Select box is the view and the control and also holds the model. In Swing fortunately, most of the MVC design is hidden away below the surface. In VB and Delphi there is no MVC at all.

In the early days of JEE web development design patterns were highly converted, and MVC was grabbed and early Servlet/JSP designs were branded as MVC. In their analysis the model was usually a DAO, the view was the JSP and control was a Servlet.

The effect of this was to lock in the design concept where the UI MVC roles were strictly separated. This fits well with the generalized architectural principle separating layers, and with the fact that JSPs are only really suitable for rendering output.

Unfortunately the cost of this strict separation was the encapsulation. Most rich client UI components encapsulate their rendering and control functionality. Click components (Controls) are responsible for both rendering themselves (view) and then understanding what they mean (control).

To see this concept in action take a simple Click page where we have an ActionLink Control.

We include our myLink ActionLink control in the HTML page template:

At runtime the control href attribute renders as:

If the user clicks the link, the ActionLink control then invokes the invokes the Page's  method.

Conversely with the JSP MVC architecture a JSP can tell you something, but it can't understand what it has just said. Think about this for a second. There is no single UI component is taking responsibility for its own actions. Guess where the responsibility then falls to...

You become responsible for wiring up the numerous pieces to make it work. In Struts this can include:

 * writing a custom Action class
 * writing a custom ActionForm class
 * specifying the action elements in the struts-config.xml file
 * specifying the form-bean element in the struts-config.xml file
 * specifying the form element in the <tt>validation.xml</tt> file
 * specifying the form <tt>field</tt> validation elements in the <tt>validation.xml</tt> file
 * ensure all bindings are correct between the XML elements: <tt>action</tt>, <tt>form-bean</tt>, <tt>form</tt>, <tt>field</tt>
 * specifying the tag lib includes in the JSP file
 * specifying the <htm:form> and <html> field tag XML elements and attributes correctly in the JSP file

In development of large applications this becomes a volumous, tedious and error prone task.

Another aspect of these designs is the transfer of logic from Java code into XML configuration files. Tapestry and Spring MVC also make extensive use of XML. The problem with this is compile time errors now only become apparent at runtime. Also writing and maintaining large volumes of XML is more difficult than Java code. The Java IDE refactoring tools are much more sophisticated than the XML tools available.

Click enables you to apply Object Oriented design principles such as subclassing to extend other Controls, or aggregation to build more sophisticated UI components. For example the Click control <tt>CreditCardField</tt> "is a" subclass of <tt>TextField</tt> and "has a" <tt>Select</tt> control for specifying the card type.

Velocity
For rendering HTML Click uses the Velocity templating engine. Velocity has a simple instruction set which is very easy to learn and use. For example take a look at the template below.

No items have been ordered.
 * 1) else
 * end

You should have a pretty good idea of what this code does without having to consult any taglib documentation. Velocity's ease of use made it the ideal choice for Click.

The one tricky part of Velocity, configuration is handled automatically by Click.

Please note you can also use JSPs for rendering in Click. It should be said that JSP 2.0 and the JSP Expression Language has improved the usability of JSP in recent years.

license: Creative Commons - Attribution Share-Alike - https://creativecommons.org/licenses/by-sa/4.0/


text: User talk:Tbernhard

title: User talk:Tbernhard


text: User talk:81.30.27.235

title: User talk:81.30.27.235


text:
Java Web Application Development With Click Framework/Pages

Pages are the heart of web applications. In Click, Pages encapsulate the processing of HTML requests and the rendering of HTML responses. The section discusses Click pages and covers to following topics:

 * Page Java classes
 * Page execution sequence
 * Request parameter to page field auto binding
 * Navigation between pages
 * Templating common page content
 * Page security model
 * Stateful pages
 * Page error handling
 * Page not found handling
 * Pages message properties

In Click, a logical page is composed of a Java class and a Velocity template, with these components being defined in page elements of the click.xml file.

The path attribute specifies the location of the page Velocity template, and the classname attribute specifies the page Java class name.

Alternatively you can also configure Click to use JSP pages for rendering.

Classes
All custom Click pages must subclass the [click-api/net/sf/click/Page.html Page] base class. The Page class and its associated companion classes, Context and Control, are depicted below in Figure 1.

'''Figure 1. Page Class Diagram''' - created with Enterprise Architect courtesy Sparx Systems

The Page class provides a model attribute which is used to hold all the objects that are rendered in the page's Velocity template. The model may also contain Control objects, which provide user interface controls on the Page.

Pages also have an associated Context object which references all the javax.servlet objects associated with the request. When programming in Click you use the Context object to access HttpServletRequest attributes, parameters and the HttpSession object.

The Page class provide a number of empty handler methods which subclasses can override to provide functionality:

 * onSecurityCheck
 * onInit
 * onGet
 * onPost
 * onRender
 * onDestroy

The ClickServlet relies on instantiating Pages using a public no arguments constructor, so when you create Page subclasses you must ensure you don't add an incompatible constructor.

Execution
The GET request execution sequence for Pages is summarized below in the Figure 2.

'''Figure 2. GET Request Sequence Diagram''' - created with Enterprise Architect courtesy Sparx Systems.

Stepping through this GET request sequence, a new Page instance is created and the attributes for the Page are set (context, format, headers, path). Next request parameter values are then bound to any matching public Page fields.

Then the onSecurityCheck handler. This method can be used to ensure the user is authorized to access the page, and if necessary can abort any further processing.

The next method invoked is the onInit, this is where you place any post constructor initialization code.

The next step is the processing of the Page's controls. The ClickSerlvet gets the list of Controls from the page and then iterates through the list calling onProcess. If any of the Control's onProcess methods return false, processing of subsequent controls and the Page's onGet method is aborted.

If everything is executing normally the Page's onGet method is now called.

The next step is rendering the page template to generate the displayed HTML. The ClickServlet gets the model (Map) from the Page then adds the following objects to the model:

 * any public Page fields using the field's name
 * context - the Servlet context path, e.g. /mycorp
 * cssImports - the CSS imports and style blocks to include in the page's header.
 * format - the Format object for formatting the display of objects.
 * imports - the CSS and JavaScript imports to include in the pages header.
 * jsImports - the JavaScript imports and script blocks to include in the page's footer.
 * messages - the MessagesMap adapter for the Page getMessage method
 * path - the path of the page template to render
 * request - the page's HttpServletRequest object
 * response - the page's HttpServletResponse object
 * session - the SessionMap adapter for the user's HttpSession

It then merges the template with the page model and writes out results to the HttpServletResponse. When the model is being merged with the template, any Controls in the model may be rendered using their toString method.

The final step in this sequence is invoking the Page's <tt>onDestroy</tt> method. This method can be used to clean up resource associated with the Page before it is garbage collected. The <tt>onDestroy</tt> method is guaranteed to be called even if an exception occurs in the previous steps.

The execution sequence for POST requests is almost identical, except the <tt>onPost</tt> method is invoked instead on <tt>onGet</tt>. See the [../images/post-sequence-diagram.png POST Request Sequence Diagram].

Another view on the execution flow of Pages is illustrated in the Activity diagram below.

'''Figure 3. Page Execution Activity Diagram''' - created with Enterprise Architect courtesy Sparx Systems.

Request Param Auto Binding
Click will automatically bind any request parameter values to public Page fields with the same name. When binding these values it will also attempt to convert them to the correct type.

The best way to understand this is to walk through an example. Our application receives a GET request:

''' http://localhost:8080/mycorp/customer-details.htm? customerId = 7203 '''

This request is automatically handled by our <tt>CustomerDetails</tt> page:

After the CustomerDetails page has been created the "customerId" request parameter value "7023" will be converted into an Integer and assigned to the public page field <tt>customerId</tt>.

Another feature of Click is that any public Page fields are automatically added to the page's model before it is rendered. This will make these values available in the page template for display. In our example the public <tt>customerId</tt> field will be added to the Page model and will be available for rendering in the page template:

Our customer-details.htm page template contains:

After processing the request our page would be rendered as:

 * Customer ID: 7203

Customizing Auto Binding
Auto binding supports the conversion of request string parameters into the Java classes: Integer, Double, Boolean, Byte, Character, Short, Long, Float, BigInteger, BigDecimal, String and the various Date classes.

By default type conversion is performed by the [click-api/net/sf/click/util/RequestTypeConverter.html RequestTypeConverter] class which is used by the ClickServlet method [click-api/net/sf/click/ClickServlet.html#getTypeConverter getTypeConverter].

If you need to add support for additional types, you would write your own type converter class and subclass the ClickSerlvet to use your custom converter.

For example if we wanted to automatically load a <tt>Customer</tt> object from the database when a customer id request parameter is specified, you could write your own type converter:

This type converter would handle the following request:

''' http://localhost:8080/mycorp/customer-details.htm? customer = 7203

Loading the customer object from the database using given the "7203" customer id value. The ClickServlet would then assign this customer object to the matching page field:

To make your custom type converter available you will need to subclass ClickServlet and override the <tt>getTypeConverter</tt> method. For example:

Navigation
Navigation between pages is achieved by using forwards, redirects and by setting the page template path.

Forward
To forward to another page using the servlet RequestDispatcher set the Page's forward property. For example to forward to a page with a path index.htm:

This will invoke a new Page class instance mapped to the path index.htm. Note when a request is forwarded to another Page, the controls on the second page will not be processed. This prevents confusion and bugs, like a form on the second page trying to process a POST request from the first page.

Forward Parameter Passing
When you forward to another page the request parameters are maintained. This is a handy way of passing through state information through with the request. For example to you could add a customer object as request parameter which is displayed in the template of the forwarded page.

Forwarded to page template view-customer.htm:

Request attributes are automatically added to the Velocity Context object so are available in the page template.

Page Forwarding
Page forwarding is another way of passing information between pages. In this case you create the page to be forwarded to using the Context createPage method and then set properties directly on the Page. Finally set this page as the page to forward the request to. For example:

When creating a page with the <tt>createPage</tt> method ensure you prefix the page path with the "/"</tt> character.

You can also specify the target page using its class as long as the Page has a unique path. Using this technique the above code becomes:

This Page forwarding technique is best practice as it provides you with compile time safety and alleviates you from having to specify page paths in your code.

Please always use the Context <tt>createPage</tt> methods to allow Click to inject Page dependencies.

Template Path
An alternative to forwarding to a new page is to simply set the path to the new page template to render. With this approach the page template being rendered must have everything it needs without having its associated Page object being created. Our modified example would be:

Note how the customer object is passed through to the template in the Page model. This approach of using the Page model is not available when you forward to another Page, as the first Page object is "destroyed" before the second Page object is created and any model values would be lost.

Redirect
Redirects are another very useful way to navigate between pages.

The great thing about redirects are that they provide a clean URL in the user's browser which matches the page that they are viewing. This is important for when users want to bookmark a page. The downside of redirects are that they involve a communications round trip with the users browser which requests the new page. Not only does this take time, it also means that all the page and request information is lost.

An example of a redirect to a logout.htm page is provided below:

If the redirect location is begins with a "/" character the redirect location will be prefixed with the web application's context path.

For example if an application is deployed to the context "mycorp" calling <tt>setRedirect("/customer/details.htm")</tt> will redirect the request to: "/mycorp/customer/details.htm"

You can also obtain the redirect path via the target Page's class. For example:

Note when using this redirect method, the target Page class must have a unique path.

A short hand way of redirecting is to simply specify the target Page class in the redirect method. For example:

Redirect Parameter Passing
You can pass information between redirected pages using URL request parameters. The ClickServlet will encode the URL for you using HttpServletResponse.encodeRedirectURL(url) method.

In the example below a user will click on an OK button to confirm a payment. The <tt>onOkClick</tt> button handler processes the payment, gets the payment transaction id, and then redirects to the trans-complete.htm page with the transaction id encoded in the URL.

The Page class for the trans-complete.htm page can then get the transaction id through the request parameter <tt>" transId "</tt> :

Post Redirect
The parameter passing example above is also an example of a Post Redirect. The Post Redirect technique is a very useful method of preventing users from submitting a form twice by hitting the refresh button.

Page Templating
Click supports page templating (a.k.a. Tiles in Struts) enabling you to create a standardized look and feel for your web application and greatly reducing the amount of HTML you need to maintain.

To implement templating define a border template base Page which content Pages should extend. The template base Page class overrides the Page getTemplate method, returning the path of the border template to render. For example:

The BorderedPage template border.htm:

Other pages insert their content into this template using the Velocity #parse directive, passing it their contents pages' path. The $path value is automatically added to the VelocityContext by the ClickServlet.

An example bordered Home page is provided below:

The Home page's content home.htm:

When a request is made for the Home page (home.htm) Velocity will merge the border.htm page and home.htm page together returning:

Which may be rendered:

Home

Welcome to Home page your application starting point.

Note how the Home page class defines a title model value which is referenced in the border.htm template as $title. Each bordered page can define their own title which is rendered in this template.

Templating with JSP pages is also supported using the same pattern. Please see the Click Examples application for a demonstration.

Security
Pages provide an onSecurityCheck event handler which application pages can override to implement programmatic security model.

Please note you generally don't need to use this capability, and where possible you should use the declarative JEE security model.

Application Authentication
Applications can use the <tt>onSecurityCheck</tt> method to implement their own security model. The example class below provides a base Secure page class which other pages can extend to ensure the user is logged in. In this example the login page creates a session when a user successfully authenticates. This Secure page then checks to make sure the user has a session, otherwise the request is redirected to the login page.

Container Authentication
Alternatively you can also use the security services provided by the JEE Servlet Container. For instance to ensure users have been authenticated by the Serlvet Container you could use a Secure page of:

Container Access Control
The Servlet Container also provides facilities to enforce role based access control (authorization). The example below is a base page to ensure only users in the "admin" role can access the page, otherwise users are redirected to the login page. Application Admin pages would extend this secure page to provide their functionality.

Logging Out
To logout using the application or container based security models you would simply invalidate the session.

Stateful Pages
Click supports stateful pages where the state of the page is saved between the users requests. Stateful pages are useful in a number of scenarios including:

 * Search page and edit page interactions, in this scenario you navigage from a stateful search page which may have filter criteria applied to an object edit page. Once object update has been completed on the edit page, the user is redirected to the search page and the stateful filter criteria still applied.
 * Complex pages with multiple forms and or tables which need to maintain their state between interactions.

To make a page stateful you simply need to set the page [click-api/net/sf/click/Page.html#stateful stateful] property to be true and have the page implement the <tt>Serializable</tt> interface. For example:

Stateful page instances are stored in the user's HttpSession using the page's class name as the key. In the example above the page would be stored in the user's session using the class name: <tt>com.mycorp.page.SearchPage</tt>

Page Creation
With stateful pages they are only created once, after which they are retrieved from the session. However page event handlers are invoked for each request, including the <tt>onInit</tt> method.

When you are creating stateful pages you typically place all your control creation code in the Pages constructor so it is invoked only once, and don't put this code in the <tt>onInit</tt> method which will be invoked with each request.

If you have dynamic control creation code you would typically place this <tt>onInit</tt> method, but you will need to take care that controls and or models are not already present in the page.

Page Execution
The default Click page execution model is thread safe as a new Page instance is created for each request and thread. With stateful pages a user will have a single page instance which is reused in multiple requests and threads. To ensure page execution is thread safe, a users page instances are synchronized so only one request thread can execute a page instance at any one time.

Page Destruction
After normal page instances have been executed, they are de-referenced and garbage collected by the JVM. However with stateful pages they are stored in the user's <tt>HttpSession</tt> so care needs to be take not store too many objects in stateful page instances which may cause memory and performance issues.

When pages have completed their execution, all the Page's controls <tt>onDestroy</tt> methods are invoked, and then the Page's <tt>onDestroy</tt> method is invoked. This is your opportunity to de-reference any large sets or graphs. For example the Table control by default de-references its rowList in its onDestroy method.

Error Handling
If an Exception occurs processing a Page object or rendering a template the error is delegated to the registered handler. The default Click error handler is the ErrorPage, which is automatically configured as:

To register an alternative error handler you must subclass ErrorPage and define your page using the path " click/error.htm ". For example:

When the ClickSevlet starts up it checks to see whether the error.htm template exists in the click web sub directory. If it cannot find the page the ClickServlet will automatically deploy one. You can tailor the click/error.htm template to suit your own tastes, and the ClickServlet will not overwrite it.

The default error template will display extensive debug information when the application is in <tt>development</tt> or <tt>debug</tt> mode. Example error page displays include:

 * NullPointerException - in a page method
 * ParseErrorException - in a page template

When the application is in <tt>production</tt> mode only a simple error message is displayed.

Page Not Found
If the ClickServlet cannot find a requested page in the <tt>click.xml</tt> config file it will use the registered not-found.htm page.

The Click not found page is automatically configured as:

You can override the default configuration and specify your own class, but you cannot change the path.

When the ClickSevlet starts up it checks to see whether the not-found.htm template exists in the click web sub directory. If it cannot find the page the ClickServlet will automatically deploy one.

You can tailor the click/not-found.htm template to suit your own needs. This page template has access to the usual Click objects.

Message Properties
The Page class provides a messages property which is a MessagesMap of localized messages for the page. These messages are made available in the VelocityContext when the page is rendered under the key <tt>messages</tt>. So for example if you had a page title message you would access it in your page template as:

This messages map is loaded from the page classes property bundle. For example if you had a page class <tt>com.mycorp.page.CustomerList</tt> you could have an associated property file containing the page's localized messages:

/com/mycorp/page/CustomerList.properties

You can also defined a application global page messages properties file:

/click-page.properties

Messages defined in this file will be available to all pages through out your application. Note messages defined in your page class properties file will override any messages defined in the application global page properties file.

Page messages can also be used to override Control messages.


text:
Java Web Application Development With Click Framework/Controls

Click provides a rich set of Controls which support client side rendering and server side processing. This section covers the following topics:

 * The Control interface
 * Control event callback pattern
 * Control Java classes
 * Control message properties

While this section provides an overview how Controls work please see the Javadoc which provides extensive information and examples.

Control Interface
In Click Controls provide the server side components that process user input, and render their display to the user. Controls are equivalent to Visual Basic Controls or Delphi Components.

Controls handle the processing of user input with the onProcess method and rendering their HTML display using the toString method. The execution sequence for Control being processed and rendered is illustrated below in Figure 1.

'''Figure 1. Post Sequence Diagram''' - created with Enterprise Architect courtesy Sparx Systems

In Click all control classes must implement the Control interface. The Control interface is depicted below in Figure 2.

'''Figure 2. Control Interface Diagram''' - created with Enterprise Architect courtesy Sparx Systems

Methods on the Control interface include:

 * getContext - provides access to the request Context.
 * getHtmlImports - defines the controls HTML header imports.
 * getId - defines the controls HTML id attribute.
 * setListener - set the control action callback listener.
 * getMessages - defines the controls localized messages map.
 * getName / setName - defines the controls name in the Page model or Form fields.
 * getParent / setParent - defines the controls parent.
 * onDeploy - deploy resources on startup.
 * onInit - on initialize event handler.
 * onProcess - process request event handler.
 * onDestroy - on destroy event handler.

Control Callback
Click Controls provide an event callback mechanism similar the java.awt.ActionListener callback.

To define a control listener, simply set the listener object instance and the name of the listener method to be invoked. For example:

The listener method can have any name but it must have take no parameters and must return a boolean or java.lang.Boolean value.

When a callback method returns true the processing of other Controls will continue and the Pages onGet or onPost event handler will be called. If a controls returns false not further Control processing will be performed and neither of the Page onGet or onPost methods will be invoked.

Being able to stop further processing and do something else can be very handy. For example your Pages onGet or onPost method may perform an expensive database operation. By using returning false in a event handler you can skip this step and forward to the next page.

Control Classes
Core control classes are defined in the package net.sf.click.control. This package includes controls for the essential HTML elements.

Extended control classes are provided in the Click Extras package net.sf.click.extras.control. Click Extras classes can contain dependencies to 3rd party frameworks.

A subset of these control classes are depicted below in Figure 3.

'''Figure 3. Package Class Diagram''' - created with Enterprise Architect courtesy Sparx Systems

The key control classes include:

 * ActionLink - provides a anchor link which can invoke callback listeners.
 * Field - provides the abstract form field control.
 * Form - provides a form control for processing, validation and rendering.
 * Submit - provides a input type submit control which can invoke callback listeners.
 * TextField - provides a input type text control which can invoke callback listeners.

The control classes are designed to support subclassing for customized behaviour. All control fields have protected visibility and have public accessor methods.

You can also aggregate controls to build more complex controls. For example the CreditCardField uses a Select control to render the different credit card types.

Message Properties
Control strings for field validation messages and HTML formatting strings are externalized in the properties file. By using these properties files you can localize a Click application for your particular language and dialect.

Message Resolution
Messages are looked up in a particular order enabling tailor specific messages, for your controls, individual pages or across your entire application. The order in which localized messages are resolve is:

 * Page scope messages
 * Message lookups are first resolved to the Page classes message bundle if it exists. For example a Login page may define the message properties:
 * /com/mycorp/page/Login.properties
 * If you want to tailor messages for a particular page this is where to place them.

 * Global page scope messages
 * Next message lookups are resolved to the global pages message bundle if it exists.
 * /click-page.properties
 * If you want messages to be used across your entire application this is where to place them.

 * Control scope messages
 * Next message lookups are resolved to the Control classes message bundle if it exists. For example a CustomTextField control may define the message properties:
 * /com/mycorp/control/CustomTextField.properties

 * Global control scope messages
 * Finally message lookups are resolved to the global application control message bundle if the message has not already found. The global control properties file is:
 * /click-control.properties

Control Properties
To customize the click-control.properties simply add this file to your classpath and tailor the specific values.

Note when customizing the message properties you must include all the properties, not just the ones you want to override.

Accessing Messages
Field classes support a hierarchy of resource bundles for displaying validation error messages and display messages. These localized messages can be accessed through the Field methods:

 * getMessage(String)
 * getMessage(String, Object)
 * getMessage(String, Object[])
 * getMessages
 * setErrorMessage(String)
 * setErrorMessage(String, Object)

These methods use the Locale of the request to lookup the string resource bundle, and use MessageFormat for any string formatting.


text:
User talk:Dncarley

Welcome, !

Come introduce yourself at the new users page. If you have any questions, you can ask there or contact me personally. --Derbeth talk 14:54, 22 February 2008 (UTC)

title: User talk:Dncarley


text:
Java Web Application Development With Click Framework/Configuration

This section discusses how to setup configure a Click web application and covers to following topics:

 * How to set up the ClickServlet
 * How to configure the Click application descriptor
 * How to configure the Velocity runtime properties
 * Automatically deployed Click files

The Click configuration files include:

Servlet Configuration
For a Click web application to function the ClickServlet must be configured in the web application's /WEB-INF/web.xml file. A simple web application which maps all  *.htm  requests to a ClickServlet is provided below.

By default the ClickServlet will attempt to load an application configuration file using the path: /WEB-INF/click.xml

If this file is not found under the WEB-INF directory, then the ClickServlet will attempt to load it from the classpath as /click.xml.

Servlet Mapping
By convention all Click page templates should have a .htm extension, and the ClickServlet should be mapped to process all *.htm URL requests. With this convention you have all the static HTML pages use a .html extension and they will not be processed as Click pages.

Load On Startup
Note you should always set load-on-startup element to be 0 so the servlet is initialized when the server is started. This will prevent any delay for the first client which uses the application.

The ClickServlet performs as much work as possible at startup to improve performance later on. The Click start up and caching strategy is configured with the Click application mode element in the "<tt>click.xml</tt>" config file.

Application Configuration
The heart of a Click application is the <tt>click.xml</tt> configuration file. This file specifies the application pages, headers, the format object and the applications mode.

See Appendix C: Click DTD for the click-app XML definition.

A simple Click app config file is provided below:

An example of an optioned up config file is:

Click App
The root click-app element defines two application localization attributes charset and locale.

The charset attribute defines the character encoding set for:

 * Velocity templates
 * HttpServletRequest character encoding
 * Page Content-Type charset

The locale attribute defines the default application Locale. If this value is defined it will to override Locale returned by the request.

For example the following configuration sets the application character set to UTF-8 and the default Locale as German (de):

Pages
The first child element of the click-app is the mandatory <tt>pages</tt> element which defines the list of Click pages.

The pages element can specify a default package name which is prepended to the classname of any pages defined.

The pages element also defines the automapping attribute.

Page
The page element defines the Click application pages.

Each page path must be unique, as the Click application maps HTTP requests to the page paths.

The Click application will create a new Page instance for the given request using the configured page classname. All pages must subclass Page and provide a public no arguments constructor, so they can be instantiated.

Pages can also define header values which are discussed in the next topic.

When the Click application starts up it will check all the page definitions. If there is a critical configuration error the ClickSerlvet will log an <tt>ERROR</tt> message and throw a UnavailableException. If this occurs the click application will be permanently unavailable until the error is fixed and the web app is restarted.

Page Automapping
Page automapping will automatically configure application pages using a simple set of rules. This enables you to greatly streamline your configuration file as you only need to define pages which don't fit the automapping rules.

Automapping will attempt to associate each page template (*.htm) and JSP file in the web application (excluding those under the WEB-INF and click directories) to a Page class. Automapped pages are loaded after the manually defined pages are loaded, and manually defined pages taking preference. When automapping is enabled the Click application will log the page mappings when in debug or trace mode.

For example given a page path to class mapping:

This would be defined configured manually using the package prefix as:

Using automapping you only need to define the Home page which doesn't automatically map to index.html.

The page template name to classname convention is:

When automapping pages, if a class cannot be found Click will attempt to add the 'Page' suffix to the classname if not already present and map this. For example:

Automapping Excludes
With Page automapping there can be resources where you don't want automapping applied. For example when using a JavaScript library with lots of <tt>.htm</tt> files, you don't want automapping to try and find Page class for each of these files.

In these situations you can use the pages <tt>excludes</tt> element.

For example if our application uses the TinyMCE JavaScript library we could configure our pages automapping to exclude all <tt>.htm</tt> files under the <tt>/tiny_mce</tt> directory.

The excludes pattern can specify multiple directories or files using a comma separated notation. For example:

HTM files excluded from Page automapping are handled by an internal Page class with caching headers enabled.

Page Autobinding
By default all pages have autobinding enabled. With autobinding enabled the ClickServlet will automatically:

 * add any public controls to the page, after the page constructor has been invoked
 * bind any request parameters to public fields, after page constructor has been invoked
 * add any public fields to the page model, before rendering

You can turn this behaviour off by setting the autobinding attribute to false, for example:

Headers
The optional <tt>headers</tt> element defines a list of <tt>header</tt> elements which is applied to all pages.

The <tt>header</tt> element defines header name and value pairs which are applied to the HttpServletResponse.

Page headers are set after the Page has been constructed and before <tt>onInit</tt> is called. Pages can then modify their <tt>headers</tt> property using the <tt>setHeader</tt> method.

Browser Caching
Headers are typically used to switch off browser caching. By default Click will use the following no caching header values if you don't define a <tt>headers</tt> element in your application:

Alternatively you can define your headers individually in pages or for all application pages by setting headers values. For example to switch off caching in the login page, note the value for a Date type should be a long number value:

If you wanted to enable caching for a particular page you could set the following page cache control header. This will mark the page as cachable for a period of 1 hour after which it should be reloaded.

To apply header values globally define header values in the headers element. For example:

Format
The optional <tt>format</tt> element defines the Format object classname which is applied to all pages.

By default all Click pages are configured with a net.sf.click.util.Format object. The format object made available in the Velocity page templates using the name <tt>$ format </tt>.

To specify a custom format class configure a <tt>format</tt> element in the click-app descriptor. For example:

Mode
The optional <tt>mode</tt> element defines the application logging and caching mode.

By default Click applications run in <tt>development</tt> mode, which switches off page template caching, and the logging level is set to <tt>INFO</tt>.

To change the default application mode configure a mode element in the click-app descriptor. For example to specify <tt>production</tt> mode you would add the following mode element:

The application mode configuration can be overridden by setting the system property <tt>"click.mode"</tt>. This can be use in the scenario of debugging a problem on a production system, where you change the mode to <tt>trace</tt> by setting the following system property and restarting the application.

 * -Dclick.mode=trace

The Click Application modes and their settings for Page auto loading, Velocity caching, template loading on startup and logging levels are:

Page Auto Loading
When Page Auto Loading is enabled any new page templates and classes will be automatically loaded at runtime. These pages are loaded using the Page Automapping rules.

Page auto loading is a very handy feature for rapid development as you do not have to restart you application server to pick up new pages.

Velocity Caching
When Velocity Caching is enabled Velocity page templates and macros files are loaded once and cached. With caching enabled following Velocity runtime properties are set:

When Velocity Caching is disabled Velocity templates and macros file are reloaded when ever they change. With caching disabled the following Velocity runtime properties are set:

Template reloading is useful for application development as you can edit page templates on a running application server and see the changes immediately. Note however, this should not be used for production as Velocity can use a lot of memory when introspecting templates and template reloading is significantly slower.

Click and Velocity Logging
The Click and Velocity runtimes use ClickLogger for logging messages. The runtime loggers will send messages to the console <tt>System.out</tt>. For example the following logging output is for a HomePage request when the application mode is <tt>trace</tt>: [Click] [debug] GET http://localhost:8080/quickstart/home.htm [Click] [trace]   invoked: HomePage.<<init>> [Click] [trace]   invoked: HomePage.onSecurityCheck : true [Click] [trace]   invoked: HomePage.onInit [Click] [trace]   invoked: HomePage.onGet [Click] [trace]   invoked: HomePage.onRender [Click] [info ]   renderTemplate: /home.htm - 6 ms [Click] [trace]    invoked: HomePage.onDestroy [Click] [info ] handleRequest: /home.htm - 24 ms

Any unhandled <tt>Throwable</tt> errors are logged by the ClickServlet.

When an application is not in <tt>production</tt> mode the error page displays detailed debugging information. When the application mode is <tt>production</tt> no debug information is displayed to prevent sensitive information being revealed. This behaviour can be changed by modifying the deployed <tt>click/error.htm</tt> page template.

Controls
The optional <tt>controls</tt> element defines a list of <tt>control</tt> elements which will be deployed on application startup.

The <tt>control</tt> registers Control classes which will have their onDeploy method invoked when the click application starts.

For example to register a <tt>CustomField</tt> control class you would add the following elements to your <tt>click.xml</tt> file:

File Item Factory
The optional <tt>file-item-factory</tt> element defines the Commons FileUpload FileItemFactory object to be used for processing multipart file upload requests.

By default file upload requests are processed using the DiskFileItemFactory.

Factory properties can also be set by specifying property elements. These property values will be applied to the FileItemFactory using OGNL type coercion. For example:

Velocity Properties
The Velocity runtime engine is configured through a series of properties when the <tt>ClickServlet</tt> starts up. The default Velocity properties set are:

See the Velocity Configuration Keys and Values Developer Guide for details about these properties. Note in <tt>trace</tt> mode the ClickServlet will log the Velocity properties used when in starts up.

If you want to add some of your own Velocity properties, or replace Click's properties, add a <tt>velocity.properties</tt> file in the <tt>WEB-INF</tt> directory. Click will automatically pick up this file and load these properties.

As a example say we have our own Velocity macro library called <tt>mycorp.vm</tt> we can override the default <tt>velocimacro.library</tt> property by adding a <tt>WEB-INF/velocity.properties</tt> file to our web application. In this file we would then define the property as:

Note do not place Velocity macros under the WEB-INF directory as the Velocity ResourceManager will not be able to load them.

The simplest way to set your own macro file is to add a file named <tt>macro.vm</tt> under your web application's root directory. At startup Click will first check to see if this file exists, and if it does it will use it instead of <tt>click/VM_global_library.vm</tt>.

Auto Deployed Files
The Click framework uses the Velocity Tools <tt>WebappLoader</tt> for loading templates. This avoids issues associate with using the Velocity <tt>FileResourceLoader</tt> on JEE application servers.

To make preconfigured resources (templates, stylesheets, etc.) available to web applications Click automatically deploys configured classpath resources to the <tt>/click</tt> directory at startup (if not already present).

You can modify these support files and Click will not overwrite them. These files include:

 * click/error.htm - the Page [pages.html#page-error-handling Error Handling] template
 * click/control.css - the Controls cascading stylesheet
 * click/control.js - the Controls JavaScript library
 * click/not-found.htm - the [pages.html#page-not-found Page Not Found] template
 * click/VM_Global_library.vm - an empty Velocity macro library

If Click cannot deploy these files because of restricted file system permissions warning messages will be logged.

If your application server has restricted permissions, you will need to package up these auto deployed files in your web applications WAR file. To do this you should run you application on a development machine without these restricted permissions and then package up the deployed files.


text:
Java Web Application Development With Click Framework/Quick Start

This section discusses how to get a Click web application up quickly. This section will not discuss how to configure your build system or IDE, but will focus on all the basic pieces you need to get a Click application running.

The following topics are covered:

 * Web Application Structure
 * JAR Files
 * Welcome File
 * Home Page
 * Border Template
 * Logging
 * What's Next?

Web Application Structure
First up add a click.xml and web.xml configuration file to your applications WEB-INF directory:

click.xml
Your click.xml file should contain:

web.xml
Your web.xml file should contain:

JAR Files
Add the following JAR files to your application WEB-INF/lib :

 * click-1.x.jar
 * click-extras-1.x.jar

You can obtain these files from the Click distribution dist directory.

Welcome File
To ensure default application requests (e.g. http://localhost:8080/quickstart/ ) are sent to your applications home page we will add a redirect.html file to the web root directory. This file should contain:

This <tt>redirect.html</tt> file is configured in our <tt>web.xml</tt>, and any default requests will be served this file:

When the browser processes the <tt>redirect.html</tt> it will redirect to the applications home.htm page.

Home Page
Now we are ready to add our first Click page which will be our applications home page.

First we define a <tt>HomePage</tt> class, and ensure the class file is published to our web applications <tt>WEB-INF/classes</tt> directory:

Next we add a corresponding Home page home.htm in the web root directory:

Next add a <tt>style.css</tt> file to your web root directory:

You should now have the following web files:

Now, if your web application is deployed to the context path quickstart you should now be able to make the request:

 *  http://localhost:8080/quickstart/

Your browser should be redirected to your <tt>HomePage</tt> and you should see your page rendered as:

Home

Welcome to Home page your application starting point.

In this example the Click automatically maps the <tt>home.htm</tt> request to our <tt>HomePage</tt> class and uses this class to process the request.

Border Template
Now we want to create a page border template so application pages will have a common look and feel.

First create a <tt>border-template.htm</tt> file in the web root directory. In this file include the HTML content:

Now we define a <tt>BorderPage</tt> class which specifies its template as the new <tt>border-template.htm</tt> file:

Note we named the template file <tt>border-template.htm</tt> so that it is not automatically mapped by Click to our <tt>BorderPage</tt> class.

Now we are going to modify our <tt>HomePage</tt> class to extend <tt>BorderPage</tt> and define a title value.

Next we modify our home.htm to remove the page border and only include the specific Home page content.

You should now have the following web files:

Now if you make browser request to your updated home page you should see identical HTML content being rendered.

Home

Welcome to Home page your application starting point.

Logging
Click has some handy logging features which will show you how your page templates are being automatically mapped to you page classes. To enable debug logging add a mode value of "debug" to your <tt>click.xml</tt> file:

When the Click application starts up it will write out the following logging messages:

[Click] [debug] automapped pages: [Click] [debug] /border-template.htm -> CLASS NOT FOUND [Click] [debug] /home.htm -> com.quickstart.page.HomePage [Click] [info ] initialized in debug mode

Click is telling us here that the <tt>border-template.htm</tt> template is not mapped to any Page class, while the <tt>home.htm</tt> template is mapped to our <tt>HomePage</tt> class. We are also informed that Click is running in <tt>debug</tt> mode.

When making a request to our home page we may get the following output:

[Click] [debug] GET http://localhost:8080/quickstart/home.htm [Click] [info ] renderTemplate: /home.htm,border-template.htm - 46 ms [Click] [info ] handleRequest: /home.htm - 62 ms

This is telling us the HTTP request that the ClickServlet received. Then we can see that it is rendering the page path <tt>home.htm</tt> and template <tt>border-template.htm</tt> files in 46 milliseconds. Finally we can see that the total time to handle this request was 62 milliseconds

If you need more detailed debugging information change the application mode to <tt>trace</tt>. Now if we make the browser request:

 *  http://localhost:8080/quickstart/home.htm?user=malcolm&password=secret

We will see the request parameters logged. This can be very handy for debugging form posts.

[Click] [debug] GET http://localhost:8080/quickstart/home.htm [Click] [trace]   request param: password=secret [Click] [trace]   request param: user=malcolm [Click] [trace]   invoked: HomePage.<<init>> [Click] [trace]   invoked: HomePage.onSecurityCheck : true [Click] [trace]   invoked: HomePage.onInit [Click] [trace]   invoked: HomePage.onGet [Click] [trace]   invoked: HomePage.onRender [Click] [info ]   renderTemplate: /user/home.htm,border-template.htm - 6 ms [Click] [trace]    invoked: HomePage.onDestroy [Click] [info ] handleRequest: /home.htm - 24 ms

What's Next
After you have the Quick Start application up and running you might be wondering, where do I go from here? There are lot of good code examples and patterns you can lift into your application: Use the Menu <tt>$menu.isUserInRoles</tt> method in your menu rendering macro to only display a user's authorized menu options.
 * 1) Add a Menu control to your <tt>border-template.htm</tt> to provide application wide navigation.
 * 2) Integrate J2EE Security into your application.


text:
Java Web Application Development With Click Framework/Best Practices

This section discusses Best Practices for designing and building Click application. The following topics are covered:

 * Use JEE role-based security
 * Project package structures and page classes
 * Use Convention over Configuration
 * Use Page classes to forward and redirect
 * Standardize your web application
 * Centralize your page navigation
 * Use Log4j in a base page
 * Use custom error pages

Security
For application security it is highly recommended that you use the declarative JEE Servlet path role based security model. While Click pages provide an onSecurityCheck method for rolling your own programatic security model, the declarative JEE model provides numerous advantages.

These advantages include:

 * Its an industry standard pattern making development and maintenance easier.
 * Application servers generally provide numerous ways of integration with an organisations security infrastructure, including LDAP directories and relational databases.
 * Servlet security model support users bookmarking pages. When users go to access these pages later, the container will automatically authenticate them before allowing them to access the resource.
 * Using this security model you can keep your Page code free of security concerns. This makes you code more reusable, or at least easier to write.

If your application has very fine grained or complex security requirements you may need to combine both the JEE declarative security model and a programmatic security model to meet your needs. In these cases its recommended you use declarative security for course grained access and programmatic security for finner grained access control.

Declarative Security
The declarative JEE Servlet security model requires users to be authenticated and in the right roles before they can access secure resources. Relative to many of the JEE specifications the Servlet security model is surprisingly simple.

For example to secure admin pages, you add a security constraint in your web.xml file. This requires users to be in the admin role before they can access to any resources under the admin directory:

The application user roles are defined in the web.xml file as security-role elements:

The Servlet security model supports three different authentication method:

 * BASIC - only recommended for internal applications where security is not important. This is the easiest authentication method, which simply displays a dialog box to users requiring them to authenticate before accessing secure resources. The BASIC method is relatively unsecure as the username and password are posted to the server as a Base64 encoded string.
 * DIGEST - recommended for internal applications with a moderate level of security. As with BASIC authentication, this method simply displays a dialog box to users requiring them to authenticate before accessing secure resources. Not all application servers support DIGEST authentication, with only more recent versions of Apache Tomcat supporting this method.
 * FORM - recommended applications for where you need a customised login page. For applications requiring a high level of security it is recommended that you use the FORM method over HTTPS.

The authentication method is specified in the <login-method> element. For example to use the BASIC authentication method you would specify:

To use the FORM method you also need to specify the path to the login page and the login error page:

In your Click <tt>login.htm</tt> page you need to include a special <tt>j_security_check</tt> form which includes the input fields <tt>j_username</tt> and <tt>j_password</tt>. For example:

<script type="text/javascript"> document.form.j_username.focus;

When using FORM based authentication do NOT put application logic in a Click Login Page class, as the role of this page is to simply render the login form. If you attempt to put navigation logic in your Login Page class, the JEE Container may simply ignore it or throw errors.

Putting this all together below is a <tt>web.xml</tt> snippet which features security constraints for pages under the admin path and the user path. This configuration uses the FORM method for authentication, and will also redirect unauthorized (403) requests to the <tt>/not-authorized.htm</tt> page.

Resources
For more information on using security see the resources below:

 * Form Based Authentication by Louis E. Mauget
 * Servlet Specification by Sun Microsystems
 * Basic authentication scheme
 * Digest authentication scheme
 * Https URI scheme

Packages and Classes
An excellent way to design your project package structure is the classify packages initially by technology. So in a Click application all of our pages would be contained under a <tt>page</tt> package. This also works very well with the Page automapping feature.

All the projects domain entity classes would be contained under a <tt>entity</tt> package, and service classes would be contained under a <tt>service</tt> directory. Note alternative names for the <tt>entity</tt> package include domain or model. We also typically have a <tt>util</tt> package for any stray classes which don't quite fit into the other packages.

In Java package names are singular by convention, so we have a util package rather than an utils package.

An example project structure for a MyCorp web application is illustrated below:

In this example application we use declarative role and path based security. All the pages in the <tt>admin</tt> package and directory require the <tt>"admin"</tt> role to be access, while all the pages in the <tt>user</tt> package and directory require the <tt>"user"</tt> role to be accessed.

Page Classes
A best practice when developing application Page classes is to place common methods in a base page class. This is typically used for providing access methods to application services and logger objects.

For example the BasePage below provides access to Spring configured service objects and a Log4J logger object:

Applications typically use a border template and have a <tt>BorderPage</tt> which extends <tt>BasePage</tt> and defines the template. For example:

Most application pages subclass <tt>BorderPage</tt>, except AJAX pages which have no need for a HTML border template and typically extend <tt>BasePage</tt>. The <tt>BorderPage</tt> class should not include common logic, other than that required for rendering the border template. Common page logic should be defined in the <tt>BasePage</tt> class.

To prevent these base Page classes being auto mapped, and becoming directly accessible web pages, ensure that there are no page templates which could match their class name. For example the <tt>BorderPage</tt> class above will not be auto mapped to border-template.htm.

Page Auto Mapping
You should use the Click page automapping configuration feature.

Automapping will save you from having to manually configure URL path to Page class mappings in your <tt>click.xml</tt> file. If you follow this convention it is very easy to maintain and refactor applications.

You can also quickly determine what the corresponding Page class is for a page HTML template and visa versa, and if you use the ClickIDE Eclipse plugin you can switch between a page's class and template by pressing Ctrl Alt S.

An example <tt>click.xml</tt> automapping configuration is provided below (automapping is enabled by default):

To see how the page templates are mapped to Page classes set the application mode to <tt>debug</tt> and at startup the mappings will be listed out. An example Click startup listing is provided below:

[Click] [debug] automapped pages: [Click] [debug] /category-tree.htm -> com.mycorp.dashboard.page.CategoryTree [Click] [debug] /process-list.htm -> com.mycorp.dashboard.page.ProcessList [Click] [debug] /user-list.htm -> com.mycorp.dashboard.page.UserList

Navigation
When navigating between Pages using forwards and redirects, you should refer to the target page using the Page class rather than using path. This provides you compile time checking and will save you from having to update path strings in Java code if you move pages about.

To forward to another page using the Page class:

To redirect to another page using the Page class you can obtain the pages path from the <tt>Context</tt>. In the example below we are passing through the customer id as a request parameter to the target page.

A quick way of redirecting to another page is to simply refer to the target class. The example below logs a user out, by invalidating their session, and then redirects them to the applications home page.

Templating
Use Page templating - it is highly recommended. Page templates provide numerous advantages including:

 * greatly reduce the amount of HTML you need to maintain
 * ensure you have a common look and feel across your application
 * make global application changes very easy

Menus
For many applications using the Menu control to centralize application navigation is very useful. Menus are defined in a <tt>WEB-INF/menu.xml</tt> file which changes very easy.

An menu is typically defined in the a page border template so they are available through out the application. The Menu control does not support HTML rendering, so you need to define a Velocity macro to programattically render the menu. You would call the macro in your border template with code like this:

 * #writeMenu($rootMenu)

An advantage of using a macro to render your menu is that you can reuse the code across different applications, and to modify an applications menu you simply need to edit the <tt>WEB-INF/menu.xml</tt> file. A good place to define your macros is in the webroot <tt>/macro.vm</tt> file as it is automatically included by Click.

Using macros you can create dynamic menu behaviour such as only rendering menu items a user is authorized to access with <tt>isUserInRoles</tt>.

You can also use JavaScript to add dynamic behaviour such as drop down menus..

Logging
For page logging you should use Log4j library. An alternative library is the Commons Logging. If you are using Commons Logging please be aware that there have been class loader issues with this library on some application servers. If you are using Commons Logging please make sure you have the latest version.

The best place to define your logger is in a common base page, for example:

Using this pattern all your application bases should extend <tt>BasePage</tt> so they can use the <tt>getLogger</tt> method.

If you have some very heavy debug statement you should possibly use an <tt>isDebugEnabled</tt> switch so it is not invoked if debug is not required.

Please note the Click logging facility is not designed for application use, and is for Click internal use only. When Click is running in <tt>production</tt> mode it will not produce any logging output.

Error Handling
In Click unhandled errors are directed to the ErrorPage for display. If applications require additional error handling they can create and register a custom error page in <tt>WEB-INF/click.xml</tt>. For example:

Generally application handle transactional errors using service layer code or via a servlet Filter and would not need to include error handling logic in an error page.

Potential uses for a custom error page include custom logging.

For example if an application requires unhandled errors to be logged to an application log (rather than System.out) then a custom ErrorPage could be configured. An example <tt>ErrorPage</tt> error logging page is provided below:


text:
Java Web Application Development With Click Framework/Extras

Click Extras provides a library of additional controls and components which are outside of the core Click framework. Click Extras are packaged as a separated JAR which you can deploy with your application. Extra packages include:

 * Cayenne - provides Cayenne data aware controls
 * Control - provides extra controls
 * Filter - provides GZIP compression Filter
 * Graphics - provides graphic controls
 * Hibernate - provides Hibernate data aware controls
 * Panel - provides Page Panel containers
 * Spring - provides Spring integration SpringClickServlet

Contributing
Click Extras provides a place for people to contribute their own code to the Click project and have it package with the standard distribution. Contributed code will be subject to review and may require modifications before it is included in the Click distribution.

Design
One of the overriding design principles with Click is to keep it simple, this makes to code easier to understand and more reliable.

Another guiding principle is YAGNI (You Ain't Going to Need It), or don't build it until you really really need it. Click is trying to provide an 80/20 rule framework where 80% of peoples needs are meet by a framework which is only 20% in size.

When developing Click Extras contributions please follow these principles.

Dependencies
Components and controls should have minimal dependencies. This is to support easy deployment of the click-examples and keeps the click build process simple.

Please Note the Cayenne and Spring dependencies are only required if you use these particular features. For example if you are using Hibernate for your persistence framework, the CayenneForm control will not cause any issues as this class would never be loaded by your application.

Auto File Deployment
The Click framework uses the Velocity Tools WebappLoader for loading templates. This avoids issues associate with using the Velocity ClasspathResourceLoader and FileResourceLoader on JEE application servers.

To make preconfigured resources (templates, stylesheets, etc.) available to web applications Click automatically deploys configured classpath resources to the /click directory at startup (existing files will not be overwritten).

To enable your controls to deploy resources on startup it should use the Control onDeploy method. Click extra controls which use this method should be registered in Click Extras JAR extras-controls.xml file.

Coding Style and Practices
Click follows the Sun conversions for Java code style. Other style conventions and practices include:

 * indents are 4 spaces wide and no tabs are used
 * public and protected visibility members require Javadoc
 * private and package visibility members do not require Javadoc
 * favor the use of unchecked RuntimeException and avoid creating new Exception classes
 * check method parameters and throw IllegalArguementException if parameters are null or invalid
 * avoid creating any more classes than you need to get the job done
 * localize control messages in the classe's properties files
 * use the Context.getLocale</tt> method to obtain a users locale
 * before checking in code run the Ant task: <tt>ant format-java</tt>


text:
Java Web Application Development With Click Framework/Building

Click uses an Ant based build system for creating JAR files, application WAR files and the Click distribution.

 * Build Configuration
 * Ant Targets
 * Framework Dependencies
 * Extras Dependencies

Build Configuration
The configuration of the Click Ant build system is detailed below:

--[build]                     Ant build directory |  | |    ---build.xml               Ant build script |  | |    ---build.properties        Ant build properties | --[dist]                       JAR and WAR file output directory | --[documentation]              Click documentation set application | --[examples]                   Click Examples application |  | |    ---build.xml               Ant build script |  | |    ---README.txt              Click Examples Readme file | --[extras]                     Click Extras source directory | --[framework]                  Click framework source directory | --[lib]                        Dependent JAR libraries directory | --[mock]                       Mock objects source directory

Build Requirements
Ensure the following requirements are met before performing builds:

 * 1) Ensure JAVA_HOME environment variable is set and points to a JDK installation (1.4 or later).
 * 2) Ensure ANT_HOME environment variable is set and points to an Ant installation (1.7.0 or later).
 * 3) Ensure junit.jar is present in your ANT_HOME/lib directory.

Ant Targets
ant help Buildfile: build.xml help: [echo] Click web application framework [echo] =============================== [echo] Main targets: [echo] build-all            build framework, extras, examples [echo] build-distribution   build distribution ZIP file [echo] build-examples       build click-examples WAR file [echo] build-extras         build click-extras JAR file [echo] build-framework      build click framework JAR file [echo] build-maven-bundles  build Maven repository upload bundles [echo] build-sources        build source ZIP files for use with IDEs [echo] deploy-examples      copy examples WAR files to app server [echo] get-deps             download JAR dependencies [echo] get-deps-proxy       download JAR dependencies via proxy [echo] help                 display the Help message [echo] javadoc              create Javadoc HTML files [echo] Please ensure you have configured build.properties BUILD SUCCESSFUL

Getting Dependencies
Run the Ant target get-deps to download JAR dependencies from Ibiblio Maven repository:
 * ant get-deps

If you are behind a firewall use the Ant target get-deps-proxy and configure your proxy settings in build.properties

Building Framework
To build the Click framework JAR file click.jar

 * 1) Ensure the above configurations have been made and <tt>get-deps</tt> has been run.
 * 2) Run the Ant target <tt>build-framework</tt> to build the framework:
 * ant build-framework

Building Extras
Click Extras JAR file <tt>click-extras.jar</tt>

 * 1) Ensure the above configurations have been made and <tt>get-deps</tt> has been run.
 * 2) Run the Ant targets <tt>framework</tt> and <tt>build-extras</tt> :
 * ant build-framework build-extras

Building Examples
To build the Click Examples and Click QuickStart web application WAR files:

 * 1) Please see the <tt>examples/README.txt</tt> file, ensuring the required properties have been configured and the dependencies downloaded.
 * 2) Ensure the above configurations have been made and <tt>get-deps</tt> has been run.
 * 3) Run the Ant target <tt>build-all</tt> :
 * ant build-all

Framework Dependencies
The Click framework has the following runtime dependencies.

* : marked libraries and source are included in the <tt>click.jar</tt> file.

The standard <tt>click-xx.jar</tt> includes all of the listed dependencies. Alternatively use the <tt>click-nodeps-xx.jar</tt> which includes none of these dependencies.

Extras Dependencies
The Click Extras has the following runtime dependencies in addition to the Framework dependencies.

* : marked libraries and source are included in the <tt>click.jar</tt> file.


text:
Java Web Application Development With Click Framework/ClickIDE

ClickIDE is an Eclipse plug-in for the developing Click web applications. The ClickIDE project has been lead by Naoki Takezoe.

The section discusses the ClickIDE and includes the following topics:

 * Installing
 * Features

Installing
ClickIDE requires Eclipse 3.2.x and WTP 1.5.x. The easiest way to use ClickIDE is introducing WTP using Callisto.

After WTP installed, get ClickIDE from the SF.net download page. Unzip clickide-x.x.x.zip and put 2 folders (plugins/ and features/) into your ECLIPSE_HOME.

Features
ClickIDE is based on Eclipse and the Eclipse Web Tools Project (WTP), and provides extended features for developing web applications using Click.

 * Fast switching between Page classes and templates (Ctrl Alt S)
 * Project creation wizard
 * Click page creation wizard
 * Visual editor for the Click configuration file
 * Velocity template editor
 * Integrated Click documentation

Create Dynamic Web Project
Create "Dynamic Web Project" in the J2EE perspective and select "Click" as Project Facet. The project creation wizard will add Click JARs, web.xml and template of click.xml into your project.

Configuration Editor
ClickIDE provides the visual editor for the Click configuration file (click.xml). It has some tabs. You can edit click.xml using this editor easily.

In the "Source" tab of the configuration file editor, you can edit click.xml directly and you can jump to the source code of the page class and the page template by CTRL CLICK. ClickIDE also provides the validation for click.xml. Error markers are displayed in the editor and "Problems" view.

Page Creation Wizard
You can create the page class and the page template file using the page creation wizard. In the wizard, you can choose template for the page class and the html file. These template can be configured at the preference dialog ("Window" > "Preferences" > "Click").

Velocity Template Editor
ClickIDE also provides the Velocity template editor. This editor provides code-completion, highlighting and validation as velocity syntax. You can also configure highlighting colors in the preference dialog.

Fast switch between Page classes and templates
In the JDT's Java editor and the Velocity template editor, you can switch between the page class and the html file by CTRL ALT S.

Online Help
Click documentation is integrated with the Eclipse help system.

Cayenne Integration (since ClickIDE 2.0.0)
ClickIDE also support Apache Cayenne since ClickIDE 2.0.0.

You can create new Cayenne mapping project using the New Cayenne Mapping Project wizard.


text:
Java Web Application Development With Click Framework/Velocity

Velocity is a Java-based template framework which provides the HTML rending engine for Click. Velocity is very easy to learn, simple to use, and is also very capable.

Velocity is an open source Apache project licensed using the [LICENSE.txt Apache] Software License.

Velocity's comprehensive online documentation is included in this distribution.

 * Velocity user's guide
 * Velocity developer's configuration guide
 * Velocity Template Language (VTL) reference guide

Object References
With Click you add objects to your page template using the Page's model. You can then access these objects using Velocity's $ reference notation. By default the ClickServlet adds the following objects to page templates:

 * any public Page fields using the field's name
 * context - the Servlet context path, e.g. /mycorp
 * cssImports - the CSS imports and style blocks to include in the page's header.
 * format - the Format object for formatting the display of objects.
 * imports - the CSS and JavaScript imports to include in the page's header.
 * jsImports - the JavaScript imports and script blocks to include in the page's footer.
 * messages - the MessagesMap adapter for the Page getMessage method.
 * path - the path of the page template to render.
 * request - the page's HttpServletRequest object.
 * response - the page's HttpServletResponse object.
 * session - the SessionMap adapter for the user's HttpSession.

In your page templates you can access object references using a dot path notation. For example:

 * Welcome: $[../click-api/net/sf/click/util/SessionMap.html session].user.fullName

Or by using a more explicit Java notation:

 * Welcome: $[../click-api/net/sf/click/util/SessionMap.html session].get("user").getFullName

Directives
In Velocity directives are prefixed by a # symbol. While references access stuff, directives do stuff. The full set of Velocity directives are:

 *  #if #elseif #else  - output conditional on truth of statements.
 *  #foreach  - loops through a list of objects.
 *  #macro  - allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required.
 *  #set  - establishes the value of a reference.
 *  #include  - renders local file(s) that are not parsed by Velocity.
 *  #parse  - renders a local template that is parsed by Velocity.
 *  #stop  - stops the template engine.


text:
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 [mailto:medgar@avoka.com 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:

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:

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:

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.

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:

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:

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 :

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 <tt>WEB-INF/velocity.properties</tt>.

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:

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 <tt>DispatcherServlet</tt> to route requests to <tt>Controller</tt> objects and then passes the <tt>ModelAndView</tt> results to the rendering layer.

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 <tt>ClickServlet</tt> for dispatching requests to <tt>Pages</tt> and <tt>Control</tt>s, 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 <tt>click.xml</tt> file.

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 <tt>onProcess</tt> methods traverse a list of Controls and do simple operations.

The Control <tt>toString</tt> 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:

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 <tt>MockContext</tt> and <tt>MockRequest</tt> classes found in the <tt>mock</tt> 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/.


text:
Java Web Application Development With Click Framework/Appendix B: Examples

Click provides an Examples web application to demonstrate Click features and common design patterns. The examples application is an important learning resource, and will help you to get up and running with Click as soon as possible.

This application will allows you to view the Page source code, templates and config files online.

You can view this application online at http://www.avoka.com:8080/click-examples

Deploying Examples
Pre built dist/click-examples.war file is provided in the Click distribution. Simply copy this file to your application servers deployment directory.

This WAR file will deploy to the contexts: /* murali */
 * /click-examples

Building Examples
To build the Examples application see the Building topic for details.

Please also see the examples/README.txt file for additional details.