<!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>