Configuration

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

Servlet Configuration - how to setup the ClickServlet
Application Configuration - how to configure the Click application descriptor
Velocity Properties - how to configure the Velocity runtime properties
Auto Deployed Files - automatically deployed Click files

The Click configuration files include:

WEB-INF/click.xml - Application Configuration (required)
WEB-INF/velocity.properties - Velocity Properties (optional)
WEB-INF/web.xml - Servlet Configuration (required)

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.

<web-app>
  <servlet>
    <servlet-name>click-servlet</servlet-name>
    <servlet-class>net.sf.click.ClickServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>click-servlet</servlet-name>
    <url-pattern>*.htm</url-pattern>
  </servlet-mapping>
</web-app>

By default the ClickServlet will attempt to load an application configuration file using the path: /WEB-INF/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 "click.xml" config file.

Application Configuration

The heart of a Click application is the click.xml configuration file. This file specifies the application pages, headers, the format object and the applications mode.

See Click DTD for the click-app XML definition.

A simple Click app config file is provided below:

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

Alternatively Page classes can be mapped mannually to page paths:

<click-app> 
  <pages automapping="false">
    <page path="home.htm" classname="com.mycorp.page.Home"/>
    <page path="login.htm" classname="com.mycorp.page.Login"/>
    <page path="logout.htm" classname="com.mycorp.page.Logout"/>    
    <page path="search.htm" classname="com.mycorp.page.Search"/>
    <page path="results.htm" classname="com.mycorp.page.Results"/>
  </pages>
</click-app>

An example of a fully optioned up config file is:

<click-app charset="UTF-8" locale="de"> 
  <pages package="com.mycorp.page">
    <page path="index.htm" classname="com.mycorp.page.Home"/>
  </pages>
  <headers>
    <header name="Pragma" value="no-cache"/>
  </headers>
  <format classname="com.mycorp.util.Format"/>
  <mode value="debug"/>
</click-app>

Click App

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

<!ELEMENT click-app (pages?, headers?, format?, mode?, controls?)>
  <!ATTLIST click-app charset CDATA #IMPLIED>
  <!ATTLIST click-app locale CDATA #IMPLIED>

The charset attribute defines the character encoding set for:

Velocity templates
HttpServletRequest character encoding
Page Content-Type charset, see Page getContentType()

The locale attribute defines the default application Locale. If this value is defined it will to override Locale returned by the request. Please see the Context getLocale() for details.

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

<click-app charset="UTF-8" locale="de"> 
  ..
</click-app>

Pages

The first child element of the click-app is the mandatory pages element which defines the list of Click pages.

<!ELEMENT pages (page*)> 
   <!ATTLIST pages package CDATA #IMPLIED>
   <!ATTLIST pages automapping (true|false) "true">

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 which is discussed in the Page Automapping topic.

Page

The page element defines the Click application pages.

<!ELEMENT page (header*)>
   <!ATTLIST page path CDATA #REQUIRED>
   <!ATTLIST page classname CDATA #REQUIRED>

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 ERROR 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:

index.htm                     =>  com.mycorp.page.Home
search.htm                    =>  com.mycorp.page.Search
contacts/contacts.htm         =>  com.mycorp.page.contacts.Contacts
security/login.htm            =>  com.mycorp.page.security.Login
security/logout.htm           =>  com.mycorp.page.security.Logout
security/change-password.htm  =>  com.mycorp.page.security.ChangePassword

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

<click-app>
  <pages package="com.mycorp.page" automapping="false">
    <page path="index.htm"                    classname="Home"/>
    <page path="search.htm"                   classname="Search"/>
    <page path="contacts/contacts.htm"        classname="contacts.Contacts"/>
    <page path="security/login.htm"           classname="security.Login"/>
    <page path="security/logout.htm"          classname="security.Logout"/>    
    <page path="security/change-password.htm" classname="security.ChangePassword"/>    
  </pages>
</click-app>

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

<click-app>
  <pages package="com.mycorp.page">
    <page path="index.htm" classname="Home"/>
  </pages>
</click-app>

The page template name to classname convention is:

change-password.htm  =>  ChangePassword
change_password.htm  =>  ChangePassword
changePassword.htm   =>  ChangePassword
ChangePassword.htm   =>  ChangePassword

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:

customer.htm         =>  CustomerPage
change-password.htm  =>  ChangePasswordPage

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 .htm 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 excludes element.

<!ELEMENT excludes (#PCDATA)>
   <!ATTLIST excludes pattern CDATA #REQUIRED>

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

<click-app>
  <pages package="com.mycorp.page">
    <excludes pattern="/tiny_mce/*"/>
  </pages>
</click-app>

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

<click-app>
  <pages package="com.mycorp.page">
    <excludes pattern="/dhtml/*, /tiny_mce/*, banner.htm, about.htm"/>
  </pages>
</click-app>

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

Headers

The optional headers element defines a list of header elements which is applied to all pages.

<!ELEMENT headers (header*)>

The header element defines header name and value pairs which are applied to the HttpServletResponse.

<!ELEMENT header (#PCDATA)>
   <!ATTLIST header name CDATA #REQUIRED>
   <!ATTLIST header value CDATA #REQUIRED>
   <!ATTLIST header type (String|Integer|Date) "String">

Page headers are set after the Page has been constructed and before onInit() is called. Pages can then modify their headers property using the setHeader() 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 headers element in your application:

  <headers>
    <header name="Pragma" value="no-cache"/>
    <header name="Cache-Control" 
            value="no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
    <header name="Expires" value="1" type="Date"/>
  </headers>

Alternatively you can define you 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:

<page path="login.htm" classname="com.mycorp.page.Login"/>
  <header name="Pragma" value="no-cache"/>
  <header name="Expires" value="1" type="Date"/>
</page>

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

<click-app> 
  <pages>
     ..
  </pages>
  <headers>
    <header name="Pragma" value="no-cache"/>
    <header name="Cache-Control" 
            value="no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
    <header name="Expires" value="1" type="Date"/>
  </headers>
</click-app>

Format

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

<!ELEMENT format (#PCDATA)>
    <ATTLIST format classname CDATA #FIXED "net.sf.click.util.Format">

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 $format.

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

<click-app> 
  ..
  <format classname="com.mycorp.util.CustomFormat"/>
</click-app>

Mode

The optional mode element defines the application logging and caching mode.

<!ELEMENT mode (#PCDATA)>
    <ATTLIST mode value (production|profile|development|debug|trace) "development">
    <ATTLIST mode logto (console|servlet) "console">

By default Click applications run in development mode, which switches off page template caching, and the logging level is set to INFO. Also by default log messages are sent to the console [System.out].

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

<click-app>
  ..
  <mode value="production">
</click-app>

The application mode configuration can be overridden by setting the system property "click.mode". This can be use in the scenario of debugging a problem on a production system, where you change the mode to trace 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:

Application mode	Page auto loading	Velocity caching	Load templates on startup	Click logging level	Velocity logging level
`production`	No	Yes	Yes	WARN	ERROR
`profile`	No	Yes	Yes	INFO	ERROR
`development`	Yes	No	No	INFO	ERROR
`debug`	Yes	No	No	DEBUG	ERROR
`trace`	Yes	No	No	TRACE	WARN

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:

webapp.resource.loader.cache=true
webapp.resource.loader.modificationCheckInterval=0
velocimacro.library.autoreload=false

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:

webapp.resource.loader.cache=false
velocimacro.library.autoreload=true

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.

By default the runtime loggers will send messages to the console [System.out]. To configure the loggers to send their logging messages to the ServletContext.log set the mode logto attribute. For example:

<mode value="production" logto="servlet">

Any unhandled Throwable errors are logged by the ClickServlet.

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

Controls

The optional controls element defines a list of control elements which will be deployed on application startup.

<!ELEMENT controls (control*)>

The control registers Control classes which will have their onDeploy() method invoked when the click application starts.

<!ELEMENT control (#PCDATA)>
   <!ATTLIST control classname CDATA #REQUIRED>

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

<click-app>
   ..

   <controls>
     <control classname="com.mycorp.control.CustomField"/>
   </controls>
</click-app>

Velocity Properties

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

resource.loader=webapp

webapp.resource.loader.class=org.apache.velocity.tools.view.servlet.WebappLoader
webapp.resource.loader.cache=[true|false]   depending on application mode
webapp.resource.loader.modificationCheckInterval=0 depending on application mode

velocimacro.library.autoreload=[true|false] depending on application mode
velocimacro.library=click/VM_global_library.vm

See the Velocity Developer Guide for details about these properties. Note in trace 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 velocity.properties file in the WEB-INF directory. Click will automatically pick up this file and load these properties.

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

velocimacro.library=mycorp.vm

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 macro.vm 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 click/VM_global_library.vm.

Auto Deployed Files

The Click framework uses the Velocity Tools WebappLoader for loading templates. This avoids issues associate with using the Velocity 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 (if not already present).

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

click/error.htm - the Page Error Handling template
click/control.css - the Controls cascading stylesheet
click/control.js - the Controls JavaScript library
click/not-found.htm - the 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.