| <!DOCTYPE' HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" | |
| "http://www.w3.org/TR/html4/loose.dtd"> | |
| <!-- | |
| Licensed to the Apache Software Foundation (ASF) under one | |
| or more contributor license agreements. See the NOTICE file | |
| distributed with this work for additional information | |
| regarding copyright ownership. The ASF licenses this file | |
| to you under the Apache License, Version 2.0 (the | |
| "License"); you may not use this file except in compliance | |
| with the License. You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, | |
| software distributed under the License is distributed on an | |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| KIND, either express or implied. See the License for the | |
| specific language governing permissions and limitations | |
| under the License. | |
| --> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> | |
| <meta name="Author" content="Malcolm Edgar"/> | |
| <meta name="description" lang="en" content="Apache Click Java web application framework"/> | |
| <meta name="keywords" lang="en" content="Apache Click, Click Framework, Java, JEE, J2EE, web application framework, open source"/> | |
| <title>Apache Click</title> | |
| <link rel="stylesheet" type="text/css" href="../help.css"/> | |
| </head> | |
| <body> | |
| <h1>Quick Start Guide</h1> | |
| This section discusses how to get a Click web application up and running quickly. We | |
| will not look at how to configure your build system or IDE, but will focus on all | |
| the basic pieces you need to get a Click application running. | |
| <p/> | |
| The following topics are covered: | |
| <ol> | |
| <li><a href="#web">Web Application Structure</a> | |
| </li> | |
| <li><a href="#jars">JAR Files</a> | |
| </li> | |
| <li><a href="#welcome">Welcome File</a> | |
| </li> | |
| <li><a href="#home">Home Page</a> | |
| </li> | |
| <li><a href="#border">Border Template</a> | |
| </li> | |
| <li><a href="#logging">Logging</a> | |
| </li> | |
| <li><a href="#where">Whats Next</a> | |
| </li> | |
| <li><a href="#ant">Quick Start Project Builder</a> | |
| </li> | |
| </ol> | |
| <p> </p> | |
| <a name="web" class="heading"></a><h2>1. Web Application Structure</h2> | |
| First up add a <tt>click.xml</tt> and <tt>web.xml</tt> configuration file to | |
| your applications <tt>WEB-INF</tt> directory: | |
| <table style="margin: 1em"> | |
| <tr valign="top"> | |
| <td> | |
| <img alt="Click application configuration files" src="../images/quick-start-1.png"/> | |
| </td> | |
| <td> | |
| <ul> | |
| <li>WEB-INF/<a target='topic' href="configuration.html#application-configuration">click.xml</a> | |
| - Application Configuration | |
| </li> | |
| <li>WEB-INF/<a target='topic' href="configuration.html#servlet-configuration">web.xml</a> | |
| - Servlet Configuration | |
| </li> | |
| </ul> | |
| </td> | |
| </tr> | |
| </table> | |
| <blockquote> | |
| <h3>click.xml</h3> | |
| Your <tt>click.xml</tt> file should contain: | |
| <pre class="codeConfig"> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <click-app> | |
| <pages package="com.quickstart.page"/> | |
| </click-app> </pre> | |
| <h3>web.xml</h3> | |
| Your <tt>web.xml</tt> file should contain: | |
| <pre class="codeConfig"> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <web-app> | |
| <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> | |
| <welcome-file-list> | |
| <welcome-file><span class="blue">redirect.html</span></welcome-file> | |
| </welcome-file-list> | |
| </web-app> </pre> | |
| </blockquote> | |
| <a name="jars" class="heading"></a><h2>2. JAR Files</h2> | |
| Add the following JAR files to your application <tt>WEB-INF/lib</tt>: | |
| <ul> | |
| <li>click-x.x.x-incubating.jar</li> | |
| <li>click-extras-x.x.x-incubating.jar</li> | |
| </ul> | |
| where <tt>x.x.x</tt> is the version of Click. | |
| <p/> | |
| You can obtain these files from the Click distribution <tt>dist</tt> directory. | |
| <a name="welcome" class="heading"></a><h2>3. Welcome File</h2> | |
| To ensure default application requests | |
| (e.g. <span class="blue">http://localhost:8080/quickstart/</span>) | |
| are sent to your applications home page we will add a <tt>redirect.html</tt> file | |
| to the web root directory. This file should contain: | |
| <pre class="codeHtml"> | |
| <html> | |
| <head><meta http-equiv="Refresh" content="0;URL=<span class="blue">home.htm</span>"></head> | |
| </html> </pre> | |
| This <tt>redirect.html</tt> file is configured in our <tt>web.xml</tt>, and any | |
| default requests will be served this file: | |
| <p/> | |
| When the browser processes the <tt>redirect.html</tt> it will redirect to the | |
| applications <span class="blue">home.htm</span> page. | |
| <a name="home" class="heading"></a><h2>4. Home Page</h2> | |
| Now we are ready to add our first Click page which will be our applications home page. | |
| <p/> | |
| 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: | |
| <pre class="codeJava"> | |
| <span class="kw">package</span> com.quickstart.page; | |
| <span class="kw">import</span> org.apache.click.Page; | |
| <span class="kw">public class</span> HomePage <span class="kw">extends</span> Page { | |
| } </pre> | |
| Next we add a corresponding Home page <span class="blue">home.htm</span> in the web root directory: | |
| <pre class="codeHtml"> | |
| <html> | |
| <head> | |
| <title>Home</title> | |
| <link rel="stylesheet" type="text/css" href="style.css" title="Style"/> | |
| </head> | |
| <body> | |
| <div id="header"> | |
| <span id="title">Home</span> | |
| </div> | |
| <div id="container"> | |
| <b>Welcome</b> to Home page your application starting point. | |
| </div> | |
| </body> | |
| </html> </pre> | |
| Next add a <span class="blue">style.css</span> file to your web root directory: | |
| <pre class="codeHtml"> | |
| body { | |
| font-family: Arial; | |
| } | |
| #header { | |
| background-color: navy; | |
| } | |
| #title { | |
| color: white; | |
| font-size: 18px; | |
| font-weight: bolder; | |
| } | |
| #container { | |
| padding-top: 1em; | |
| padding-left: 1.5em; | |
| position: relative; | |
| z-index: 0; | |
| } | |
| h3.title { | |
| margin-top: 0em; | |
| margin-bottom: 1em; | |
| } </pre> | |
| You should now have the following web files: | |
| <blockquote> | |
| <table> | |
| <tr valign="top"> | |
| <td> | |
| <img alt="Click application web files" src="../images/quick-start-2.png"/> | |
| </td> | |
| </tr> | |
| </table> | |
| </blockquote> | |
| Now if your web application is deployed to the context path <span class="blue">quickstart</span> | |
| you should now be able to make the request: | |
| <blockquote> | |
| <span class="blue">http://localhost:8080/quickstart/</span> | |
| </blockquote> | |
| Your browser should be redirected to your <tt>HomePage</tt> and you should see your page | |
| rendered as: | |
| <table class="htmlExample" cellspacing="12" width="100%"> | |
| <tr> | |
| <td> | |
| <h2 style="color: white; background-color: navy; padding: 0.25em; margin-top: 0em;"> | |
| Home | |
| </h2> | |
| <p> | |
| <b>Welcome</b> to Home page your application starting point. | |
| <p/> | |
| </td> | |
| </tr> | |
| </table> | |
| 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. | |
| <a name="border" class="heading"></a><h2>5. Border Template</h2> | |
| Now we want to create a page border template so application pages will have | |
| a common look and feel. | |
| <p/> | |
| First create a <span class="blue">border-template.htm</span> file in the web | |
| root directory. In this file include the HTML content: | |
| <pre class="codeHtml"> | |
| <html> | |
| <head> | |
| <title><span class="blue">Click Quickstart - $title</span></title> | |
| <link rel="stylesheet" type="text/css" href="$context/assets/style.css" title="Style"/> | |
| </head> | |
| <body> | |
| <div id="header"> | |
| <span class="title"><span class="blue">$title</span></span> | |
| </div> | |
| <div id="container"> | |
| <span class="red">#parse</span>(<span class="blue">$path</span>) | |
| </div> | |
| </body> | |
| </html> </pre> | |
| Now we define a <tt>BorderPage</tt> class which specifies its template as the | |
| new <tt>border-template.htm</tt> file: | |
| <pre class="codeJava"> | |
| <span class="kw">package</span> com.quickstart.page; | |
| <span class="kw">import</span> org.apache.click.Page; | |
| <span class="kw">public class</span> BorderPage <span class="kw">extends</span> Page { | |
| <span class="kw">public String</span> getTemplate() { | |
| <span class="kw">return</span> <span class="st">"border-template.htm"</span>; | |
| } | |
| } </pre> | |
| 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. | |
| <p/> | |
| Now we are going to modify our <tt>HomePage</tt> class to extend <tt>BorderPage</tt> | |
| and define a <span class="blue">title</span> value. | |
| <pre class="codeJava"> | |
| <span class="kw">package</span> com.quickstart.page; | |
| <span class="kw">public class</span> HomePage <span class="kw">extends</span> BorderPage { | |
| <span class="kw">public</span> String <span class="blue">title</span> = <span class="st">"Home"</span>; | |
| } </pre> | |
| Next we modify our <span class="blue">home.htm</span> to remove the page border and | |
| only include the specific Home page content. | |
| <pre class="codeHtml"> | |
| <b>Welcome</b> to Home page your application starting point. </pre> | |
| You should now have the following web files: | |
| <blockquote> | |
| <table> | |
| <tr valign="top"> | |
| <td> | |
| <img alt="Click application web files" src="../images/quick-start-3.png"/> | |
| </td> | |
| </tr> | |
| </table> | |
| </blockquote> | |
| Now if you make browser request to your updated home page you should see identical | |
| HTML content being rendered. | |
| <table class="htmlExample" cellspacing="12" width="100%"> | |
| <tr> | |
| <td> | |
| <h2 style="color: white; background-color: navy; padding: 0.25em; margin-top: 0em;"> | |
| Home | |
| </h2> | |
| <p> | |
| <b>Welcome</b> to Home page your application starting point. | |
| <p/> | |
| </td> | |
| </tr> | |
| </table> | |
| <a name="logging" class="heading"></a><h2>6. Logging</h2> | |
| 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: | |
| <pre class="codeConfig"> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <click-app> | |
| <pages package="com.quickstart.page"/> | |
| <mode value="<span class="blue">debug</span>"/> | |
| </click-app> </pre> | |
| When the Click application starts up it will write out the following logging messages: | |
| <pre class="codeLog"> | |
| [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 </pre> | |
| 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. | |
| <p/> | |
| When making a request to our home page we may get the following output: | |
| <pre class="codeLog"> | |
| [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 </pre> | |
| 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 | |
| <p/> | |
| If you need more detailed debugging information change the application mode to | |
| <tt>trace</tt>. Now if we make the browser request: | |
| <blockquote> | |
| <span class="blue">http://localhost:8080/quickstart/home.htm?user=malcolm&password=secret</span> | |
| </blockquote> | |
| We will see the request parameters logged. This can be very handy for debugging | |
| form posts. | |
| <pre class="codeLog"> | |
| [Click] [debug] GET http://localhost:8080/quickstart/home.htm | |
| [Click] [trace] request param: <span class="yellow">password=secret</span> | |
| [Click] [trace] request param: <span class="yellow">user=malcolm</span> | |
| [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 </pre> | |
| <br/> | |
| <a name="where" class="heading"></a><h2>7. Whats Next ?</h2> | |
| After you have the Quick Start application up and running you might be wondering, | |
| where do I go from here? At this point you are recommended to: | |
| <ol> | |
| <li> | |
| Use the <a href="#ant">Quick Start Project Builder</a> to generate a more | |
| complete project example. | |
| </li> | |
| <li> | |
| Read the Click <a href="best-practices.html">Best Practices</a> topic. | |
| </li> | |
| <li> | |
| Review the Click <a href="examples.html">Examples</a> application. | |
| <p/> | |
| There is a lot of good code examples and patterns you can lift into your application. | |
| </li> | |
| </ol> | |
| <br/> | |
| <a name="ant" class="heading"></a><h2>8. Quick Start Project Builder</h2> | |
| The fastest way to get a Click web application up and running is to use the | |
| Ant task <tt>project-quick-start</tt>. This ant task will build you a functional | |
| application which includes: | |
| <ul> | |
| <li>JEE container security integration, with login screen</li> | |
| <li>Menu control for application wide navigation</li> | |
| <li>Border Template</li> | |
| </ul> | |
| <h3>8.1 Prerequisites</h3> | |
| To run the <tt>project-quick-start</tt> ant task please ensure the following | |
| requirements are met: | |
| <ol> | |
| <li>Ensure <tt>JAVA_HOME</tt> environment variable is set and points to | |
| a JDK installation (1.4 or later).<p/> | |
| </li> | |
| <li>Ensure <tt>ANT_HOME</tt> environment variable is set and points to | |
| an Ant installation (1.7.0 or later).<p/> | |
| </li> | |
| <li>Ensure you have run the <tt>ant get-deps</tt> task to download any library | |
| dependencies.<p/> | |
| </li> | |
| </ol> | |
| <h3>8.2 Running Quickstart</h3> | |
| To run the quick start application builder simply follow the example below: | |
| <blockquote> | |
| <pre class="codeLog"> | |
| <span class="yellow">ant project-quick-start</span> | |
| Buildfile: build.xml | |
| project-quick-start: | |
| [input] Please enter the project name (e.g. quickstart): [quickstart] | |
| <span class="yellow">quickstart</span> | |
| [input] Please enter the root package name (e.g. com.quickstart): [com.quickstart] | |
| <span class="yellow">com.quickstart</span> | |
| [input] Please enter the web app context path: [quickstart] | |
| <span class="yellow">quickstart</span> | |
| [input] The directory 'C:\quickstart' will be deleted. Continue (y/n)? (y, n) | |
| <span class="yellow">y</span> | |
| [copy] Copying 20 files to C:\quickstart\WebContent | |
| [copy] Copied 9 empty directories to 2 empty directory under C:\quickstart\WebContent | |
| [copy] Copying 1 file to C:\quickstart\WebContent\WEB-INF\lib | |
| [copy] Copying 1 file to C:\quickstart\WebContent\WEB-INF\lib | |
| [copy] Copying 1 file to C:\quickstart\WebContent\WEB-INF\lib | |
| [copy] Copying 1 file to C:\quickstart\lib | |
| [copy] Copying 1 file to C:\quickstart\ | |
| [copy] Copying 1 file to C:\quickstart\ | |
| [copy] Copying 11 files to C:\quickstart\src\com\quickstart | |
| BUILD SUCCESSFUL | |
| Total time: 18 seconds</pre> | |
| </blockquote> | |
| Once the task has been completed you should have a directory structure something | |
| like the one below. | |
| <table style="margin: 1em 0em;" class="codeConfig"> | |
| <tr valign="top"> | |
| <td> | |
| <img alt="Quickstart directory structure" src="../images/quick-start-0.png"/> | |
| </td> | |
| <td style="padding-left:1em;"> | |
| <pre> | |
| [quickstart] Project root directory | |
| | | |
| +---[lib] Build time JAR libs directory | |
| | | |
| +---[src] Java source files directory | |
| | | |
| +---[WebContent] Web application root directory | |
| | | | |
| | +---[admin] Admin role pages directory | |
| | | | |
| | +---[assets] Application static assets directory | |
| | | | |
| | +---[click] Click static assets directory | |
| | | | |
| | +---[META-INF] Tomcat context.xml directory | |
| | | | |
| | +---[user] User role pages directory | |
| | | | |
| | +---[WEB-INF] Protected Web Inf directory | |
| | | | |
| | +---[lib] Run time JAR libs directory | |
| | | |
| +---build.xml Ant build script file | |
| | | |
| +---README.txt Read Me description file </pre> | |
| </td> | |
| </tr> | |
| </table> | |
| <h3>8.3 Deploying to Tomcat</h3> | |
| To run the quickstart application on Tomcat you need to configure | |
| <tt>user</tt> and <tt>admin</tt> security roles and add some users. To do this add a | |
| <tt>tomcat-users.xml</tt> file to the <tt>$TOMCAT\conf</tt> directory. For example: | |
| <pre class="codeConfig"> | |
| <?xml version='1.0' encoding='utf-8'?> | |
| <tomcat-users> | |
| <role rolename="user"/> | |
| <role rolename="admin"/> | |
| <user username="user1" password="password" roles="user"/> | |
| <user username="admin1" password="password" roles="user,admin"/> | |
| </tomcat-users> | |
| </pre> | |
| For other JEE application server you will need to study their specific security | |
| configuration. | |
| <p/> | |
| Next copy the quickstart.war file to the <tt>$TOMCAT\webapps</tt> directory and | |
| login to your application as the user: <tt>admin1 / password</tt> | |
| <table style="margin: 1em;border:1px solid #c0c0c0;"> | |
| <tr valign="top"> | |
| <td> | |
| <img alt="Quick Start Home Page" src="../images/quick-start-4.png"/> | |
| </td> | |
| </tr> | |
| </table> | |
| </body> | |
| </html> |