5.3. Auto Deployed Files

To make pre-configured 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:

For example to customize the control styles you can place a customized copy (or even a brand new version) of control.css under the /click folder in your web project:

/webapp/click/control.css

When Click starts up it will not override your copy of control.css with its own default version.

Different controls might deploy different stylesheet, javascript or image files, however the above principle still applies. By placing a customized copy of the stylesheet, javascript or image under the /click folder, you will override the default resource.

Be aware that some of the more complex controls (checklist, colorpicker, tree), deploys resources to subfolders under /click, for example /click/checklist/*.

A control's Javadoc will normally indicate what resources are deployed for that control.

5.3.1. Deploying resources in a restricted environment

Some environments place restrictions on the file system and Click won't be able to deploy its resources. WebLogic and Google App Engine are examples of such environments. (Note that WebLogic has a property to allow access to the file system. From the Admin Console go to the Server node > Web Applications tab and check the Archived Real Path Enabled parameter.)

If Click cannot deploy its resources because of limited file system access or permissions, warning messages will be logged.

Note: if your application is running on a Servlet 3.0 compliant server, there is no need to deploy resources. Servlet 3.0 specifies that if the server cannot find a resource in the root directory of the webapp, it will look for the resource under 'META-INF/resources', and if found, serve it up. Click is Servlet 3.0 compliant and packages its resources under 'META-INF/resources'.

Click provides a number of options to make resources available in restricted environments which is covered below:

  • The first option (which will work in all environments) is to deploy the resources at build time. Click ships with an Ant Task called DeployTask that deploys Click static resources to a web application. With this option Click's static resources can be copied to the root directory of your webapp, where you can customize the resources further if needed. The DeployTask can easily be incorporated into your build script.

    Currently the DeployTask is part of the click-dev-tools-xxx.jar that can be found in your Click distribution under the lib folder.

    Here is a basic example:

    <target name="deploy" description="Deploy static resources">
        <taskdef name="deploy"
                 classname="org.apache.click.tools.deploy.DeployTask"
                 classpath="<click-distribution>/lib/click-dev-tasks-1.1.jar"/> 1
    
        <deploy dir="<webapp-root>/WEB-INF"
                todir="<webapp-root>"/> 2
    </target> 
    1

    <click-distribution> is the location where Click is installed on your machine, for example: C:\software\click-2.1.0\.

    2

    <webapp-root> is the root directory of your webapp, for example: C:\dev\my-webapp\.

    We use the <deploy> Ant Task and specify the attributes dir and todir.

    dir specifies the source directory to scan for JARs and folders containing static resources, while todir specifies the target directory where the resources should be copied to.

    dir should point to your web application's WEB-INF folder, since that is where Click's JARs will be located. todir should point to your web application's root directory, since that is where Click's resources will be served from.

    The DeployTask also supports nested FileSets if you need to deploy resources from multiple source locations. For example:

    <target name="deploy" description="Deploy static resources">
        <taskdef name="deploy"
                 classname="org.apache.click.tools.deploy.DeployTask"
                 classpath="<click-distribution>/lib/click-dev-tasks-1.1.jar"/>
    
        <deploy todir="${dir.webapp}">
            <fileset dir="<webapp-root>/WEB-INF">
                <include name="**/classes"/>
                <include name="**/*.jar"/>
            </fileset>
            <fileset dir="/some/folder/with/jars">
                <include name="lib-with-resources.jar"/>
                <include name="another-lib-with-resources.jar"/>
            </fileset>
        </deploy>
    </target> 

    The DeployTask also generates an HTML report in the same folder where the build script is executed from. The report will indicate which resources was deployed successfully and which resources in your webapp root directory is outdated. (An outdated resource means that the resource in the click-xxx.jar differs from the resource currently present in your webapp root directory. This can happen when upgrading to a new version of Click)

  • Another option is to add a mapping in web.xml to inform ClickServlet to serve static resources. This feature is made available through the ResourceService interface and its default implementation, ClickResourceService. Below is an example:

    <servlet>
      <servlet-name>ClickServlet</servlet-name>
      <servlet-class>org.apache.click.ClickServlet</servlet-class>
      <load-on-startup>0</load-on-startup>
    </servlet>
    
    <servlet-mapping>
      <servlet-name>ClickServlet</servlet-name>
      <url-pattern>*.htm</url-pattern>
    </servlet-mapping>
    
     <!-- Inform ClickServlet to serve static resources contained under the /click/*
           directory directly from Click's JAR files. -->
    <servlet-mapping>
      <servlet-name>ClickServlet</servlet-name>
      <url-pattern>/click/*</url-pattern>
    </servlet-mapping>

    With this setup, ClickServlet will serve all static /click/* resources directly from Click's JAR files.

    One restriction of ClickResourceService is it only serves resources from the /click/* folder. So if you use third-party Click libraries that serve their resources from a different folder e.g. /clickclick/*, this option won't work out-of-the-box.

    Also note that with this option Click's resources are served directly from the JAR files, you won't be able to customize the resources, if for example you want change the default styling through CSS.

  • Another option is to manually deploy the resources. Click resources are packaged in JARs under the directory META-INF/resources. You can use your IDE to navigate into the JARs and copy all the resources from META-INF/resources to your webapp root directory.

    For example, to deploy the resources from click-core.jar, copy the /click folder and its contents to your web application root folder.

  • And finally you can access Click's resources by deploying your application on a development machine where there are no file system restrictions and the WAR/EAR can be unpacked. You can then copy the deployed resources to your webapp root directory.

5.3.2. Deploying Custom Resources

Click supports two ways of deploying pre-configured resources (templates, stylesheets, JavaScript etc.) from a Jar to a web application. (This assumes that the environment Click is running in supports having write access to the file system and that the WAR is unpacked.)

  1. Through a Control's onDeploy() event handler. See the Controls section above.

  2. By packaging the resources (stylesheets, JavaScript, Images etc.) into a special folder called 'META-INF/resources'.

As option #1 was already discussed above in section Controls, lets look at option #2.

When Click starts up, it scans each Jar and folder on the classpath for specially marked entries starting with 'META-INF/resources/'. (Please note that even though Click will scan the entire classpath it is strongly recommended to host your Jar files under your WAR lib folder e.g. WEB-INF/lib. Sharing Jars on the classpath can lead to class loading issues.)

Click will then copy all files found under 'META-INF/resources/' to the root directory of the webapp.

For example, given a Jar file with the following entries:

  • META-INF/resources/mycorp/edit_customer.js

  • META-INF/resources/mycorp/edit_customer.css

  • mycorp/pages/EditCustomerPage.class

Click will copy the files '/mycorp/edit_customer.js' and '/mycorp/edit_customer.css' to the web application folder.

Thus if the web application is called 'webapp', the files will be deployed as 'webapp/mycorp/edit_customer.js' and 'webapp/mycorp/edit_customer.css'.

Option #2 is the recommended approach for deploying your own resources since it makes the managing and maintenance of resources much easier.