documentation/docs/quick-start.html - click - Git at Google

 <!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>&nbsp;</p>


 <a name="web" class="heading"></a><h2>1.&nbsp; 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="user-guide/html/ch04s02.html">click.xml</a>
  &nbsp; - &nbsp; Application Configuration
  </li>
  <li>WEB-INF/<a target='topic' href="user-guide/html/ch04.html#servlet-configuration">web.xml</a>
  &nbsp; - &nbsp; Servlet Configuration
  </li>
 </ul>
   </td>
 </tr>
 </table>

 <blockquote>

 <h3>click.xml</h3>

 Your <tt>click.xml</tt> file should contain:

 <pre class="codeConfig">
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;click-app&gt;

   &lt;pages package="com.quickstart.page"/&gt;

 &lt;/click-app&gt;  </pre>

 <h3>web.xml</h3>

 Your <tt>web.xml</tt> file should contain:

 <pre class="codeConfig">
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;web-app&gt;

   &lt;servlet&gt;
     &lt;servlet-name&gt;ClickServlet&lt;/servlet-name&gt;
     &lt;servlet-class&gt;org.apache.click.ClickServlet&lt;/servlet-class&gt;
     &lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
   &lt;/servlet&gt;

   &lt;servlet-mapping&gt;
     &lt;servlet-name&gt;ClickServlet&lt;/servlet-name&gt;
     &lt;url-pattern&gt;*.htm&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;

   &lt;welcome-file-list&gt;
     &lt;welcome-file&gt;<span class="blue">redirect.html</span>&lt;/welcome-file&gt;
   &lt;/welcome-file-list&gt;

 &lt;/web-app&gt;  </pre>

 </blockquote>


 <a name="jars" class="heading"></a><h2>2.&nbsp; JAR Files</h2>

 Add the following JAR files to your application <tt>WEB-INF/lib</tt>:

 <ul>
 <li>click-x.x.x.jar</li>
 <li>click-extras-x.x.x.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.&nbsp; 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">
 &lt;html&gt;
 &lt;head&gt;&lt;meta http-equiv="Refresh" content="0;URL=<span class="blue">home.htm</span>"&gt;&lt;/head&gt;
 &lt;/html&gt;  </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.&nbsp; 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">
 &lt;html&gt;
 &lt;head&gt;
   &lt;title&gt;Home&lt;/title&gt;
   &lt;link rel="stylesheet" type="text/css" href="style.css" title="Style"/&gt;
 &lt;/head&gt;

 &lt;body&gt;

   &lt;div id="header"&gt;
     &lt;span id="title"&gt;Home&lt;/span&gt;
   &lt;/div&gt;

   &lt;div id="container"&gt;
     &lt;b&gt;Welcome&lt;/b&gt; to Home page your application starting point.
   &lt;/div&gt;

 &lt;/body&gt;
 &lt;/html&gt; </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.&nbsp; 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">
 &lt;html&gt;
 &lt;head&gt;
 &lt;title&gt;<span class="blue">Click Quickstart - $title</span>&lt;/title&gt;
 &lt;link rel="stylesheet" type="text/css" href="$context/assets/style.css" title="Style"/&gt;
 &lt;/head&gt;

 &lt;body&gt;

   &lt;div id="header"&gt;
     &lt;span class="title"&gt;<span class="blue">$title</span>&lt;/span&gt;
   &lt;/div&gt;

   &lt;div id="container"&gt;
     <span class="red">#parse</span>(<span class="blue">$path</span>)
   &lt;/div&gt;

 &lt;/body&gt;
 &lt;/html&gt; </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 {

     @Bindable <span class="kw">protected</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">
 &lt;b&gt;Welcome&lt;/b&gt; 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.&nbsp; 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">
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;click-app&gt;

   &lt;pages package="com.quickstart.page"/&gt;

   &lt;mode value="<span class="blue">debug</span>"/&gt;

 &lt;/click-app&gt;  </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&amp;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.&lt;&lt;init&gt;&gt;
 [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.&nbsp; 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="user-guide/html/ch05.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.&nbsp; 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&nbsp; 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&nbsp; 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&nbsp; 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">
 &lt;?xml version='1.0' encoding='utf-8'?&gt;
 &lt;tomcat-users&gt;
   &lt;role rolename="user"/&gt;
   &lt;role rolename="admin"/&gt;
   &lt;user username="user1" password="password" roles="user"/&gt;
   &lt;user username="admin1" password="password" roles="user,admin"/&gt;
 &lt;/tomcat-users&gt;
 </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>
	<!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="user-guide/html/ch04s02.html">click.xml</a>
	-   Application Configuration
	</li>
	<li>WEB-INF/<a target='topic' href="user-guide/html/ch04.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.jar</li>
	<li>click-extras-x.x.x.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 {

	@Bindable <span class="kw">protected</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="user-guide/html/ch05.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>