The Click configuration files include:
|
<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
<click-app>
<pages package="com.mycorp.page"/>
</click-app>
An example of an 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> <format classname="com.mycorp.util.Format"/> <mode value="profile"/> <file-item-factory classname="com.mycorp.util.AppFileItemFactory"/> </click-app>
<!ELEMENT click-app (pages?, headers?, format?, mode?, controls?, file-item-factory?)> <!ATTLIST click-app charset CDATA #IMPLIED> <!ATTLIST click-app locale CDATA #IMPLIED>The charset attribute defines the character encoding set for:
<click-app charset="UTF-8" locale="de"> .. </click-app>
<!ELEMENT pages (page*)> <!ATTLIST pages package CDATA #IMPLIED> <!ATTLIST pages automapping (true|false) "true"> <!ATTLIST pages autobinding (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.
<!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.
com.mycorp.page.Home => com.mycorp.page.Search => com.mycorp.page.contacts.Contacts => com.mycorp.page.security.Login => com.mycorp.page.security.Logout => com.mycorp.page.security.ChangePasswordThis would be defined configured mannually using the package prefix as: =>
<click-app> <pages package="com.mycorp.page" automapping="false"> <page path=" " classname="Home"/> <page path=" " classname="Search"/> <page path=" " classname="contacts.Contacts"/> <page path=" " classname="security.Login"/> <page path=" " classname="security.Logout"/> <page path=" " 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=" " 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 => ChangePasswordWhen 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
<!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.
<click-app> <pages package="com.mycorp.page" autobinding="false"/> </click-app>
<!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.
<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>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.
<page path="home.htm" classname="com.mycorp.page.Home"/> <header name="Cache-Control" value="max-age=3600, public, must-revalidate"/> </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>
<!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>
<!ELEMENT mode (#PCDATA)> <ATTLIST mode value (production|profile|development|debug|trace) "development">By default Click applications run in development mode, which switches off page template caching, and the logging level is set to INFO. 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=traceThe 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 |
webapp.resource.loader.cache=true webapp.resource.loader.modificationCheckInterval=0 velocimacro.library.autoreload=falseWhen 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=trueTemplate 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] [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 msAny 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 deployed click/error.htm page template.
<!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>
<!ELEMENT file-item-factory (property*)> <ATTLIST file-item-factory classname CDATA #FIXED "org.apache.commons.fileupload.disk.DiskFileItemFactory"> <!-- FileItem Factory property set after factory creation. --> <!ELEMENT property (#PCDATA)> <!ATTLIST property name CDATA #REQUIRED> <!ATTLIST property value CDATA #REQUIRED>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:
<click-app> .. <file-item-factory classname="org.apache.commons.fileupload.disk.DiskFileItemFactory"> <property name="sizeThreshold" name="524288"/> </file-item-factory> </click-app>
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.vmSee 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.