====== Apache Click ==
===== Useful Links ==
[[http://click.apache.org/|Home Page]] - [[http://click.apache.org/docs/user-guide/html/|User Guide]] - [[http://click.apache.org/docs/click-api/|API]] - [[http://click.apache.org/docs/extras-api/|Extras API]] - [[http://www.avoka.com/click-examples/|Demo and Code]]
===== General ==
Click is a web application framework. You may read the [[Java Web Programming]] Overview fist.
Click needs a servlet container such as [[:becki:linux:Apache Tomcat]].
To get the [[http://www.avoka.com/click-examples/home.htm|Click examples]] served from your own tomcat server, just copy ''click-2.1.0/dist/click-examples.war'' into ''$CATALINA_HOME/webapps'' and point your browser to http://localhost:8080/click-examples :-) Note that Tomcat extracts the .war file into the webapps dir and serves content from the extracted directory and not from the war file. [[http://tomcat.apache.org/tomcat-6.0-doc/appdev/deployment.html#Deployment%20With%20Tomcat%206|More]]
===== First Steps ==
We call our first project ''translator'' and create a directory for it. This dir is our project root.
We roughly follow the [[http://click.apache.org/docs/quick-start.html|Quick Start Guide]] and copy the most files from ''click-2.1.0/template/'' into our project to ajust them for our needs.
//Application configuration//: Copy ''click-2.1.0/template/WebContent/WEB-INF/click.xml'' from the Click distribution to ''translator/WebContent/WEB-INF/click.xml''. Specify among others your Java package name, eg. ''sb.translator.page'' and optionally the charset, the locale, the logging / caching mode and autobinding of controls in the application configuration file. [[http://click.apache.org/docs/user-guide/html/ch04s02.html|More]]
//Servlet configuration//: Copy & paste the servlet configuration file ''translator/WebContent/WEB-INF/web.xml'' directly from the quick start guide. This file is for specifying the location of the ClickServlet and the servlet is mapped to process all *.htm URL requests. [[http://click.apache.org/docs/user-guide/html/ch04.html#servlet-configuration|More]]
Copy click-2.1.0.jar and click-extras-2.1.0.jar into ''translator/WebContent/WEB-INF/WEB-INF/lib''
Create your first java file in your java package path, eg ''translator/src/sb/translator/page/HomePage.java''
Copy ''click-2.1.0/template/build.xml'' into our project root and run ''ant''
Project structure:
translator/
|-- WebContent
| |-- WEB-INF
| | |-- click.xml
| | |-- lib
| | | |-- click-2.1.0.jar
| | | `-- click-extras-2.1.0.jar
| | `-- web.xml
| |-- home.htm
| `-- redirect.html
|-- build.xml
`-- src
`-- sb
`-- translator
`-- page
`-- HomePage.java
Make a symlink from Tomcat to your project ''$CATALINA_HOME/webapps/translator'' -> ''translator/WebContent'' in order to get your page in the browser.
===== Template ⇔ Class mapping ==
- The URL request to eg ''home.htm'' is automatically mapped to the class ''Home.java'', or, if not found: ''HomePage.java''. [[http://click.apache.org/docs/user-guide/html/ch04s02.html#application-automapping|More]]
- If no associated class can be found, ''redirect.html'' is used which results in the default URL (eg. ''home.htm'') and finally in the associated default class (''HomePage.java'').
- The associated Velocity template for the class is specified by the requested file in the URL, eg. ''home.htm''
- The associated Velocity template may by modified by the class by overwriting the [[ http://click.apache.org/docs/click-api/org/apache/click/Page.html#getTemplate%28%29|getTemplate]] method of the Page class.
===== Border Page Template ==
How to add the same default bordering HTML to each Page in order to get the same look for all pages?
- Extend a Page class ''BorderedPage'' from ''Page''
- Overwrite ''getTemplate()'' so that always ''border-template.htm'' is returned as Velocity template.
- Create your bordering HTML in ''border-template.htm''
- Add the Velocity directive ''#parse($path)'' to ''border-template.htm''. This will be replaced with the real template file.
- Extend all your Page classes from BorderedPage, not from Page
[[http://click.apache.org/docs/quick-start.html#border|More]]
FIXME How to prevent caching without resart of Tomcat?
FIXME Why is @Bindable not recognized? Add more jar files?? Look in Template!
===== Template ⇔ Class Binding ==
FIXME Verify this paragraph!
Java classes can be accessed by the Velocity templates by adding them to the ''model'' Map of the Page class. Adding can be done explicitely (by calling a method), implizitely (by making them public) or by using an annotation. More: [[http://click.apache.org/docs/user-guide/html/ch02.html#classes|Page class overview]], [[http://click.apache.org/docs/user-guide/html/ch04s02.html#application-autobinding|Autobinding]]
==== Manual adding ==
Distinguish between plain dynamic data types like ''String'' or ''Date'' and Click Control types like ''Checkbox'' or ''FormTable''.
Plain data types are made available for the Velocity template by calling ''Page.addModel()'' in the constructor of the Page class or in ''Page.onInit()''.
Click Control types must be added with ''Page.addControl()'' in ''Page.onInit()''
==== Automatic adding ==
As default, all public attributes of a Page class are added automatically to the Page's ''model''.
==== Adding by annotation ==
Alle attributes of a Page, annotated with ''@Bindable'' are added automatically to the Page's ''model''.
The @Bindable annotation is only respected, when autobinding ist set to ''annotation'' in ''click.xml'':
Alle Java files must import Bindable:
import org.apache.click.util.Bindable;
Using the @Bindable annotation seems to be the best way of binding :?:
===== Request Parameter Binding ==
Parameter data, which is sent with HTTP Get (or Post?) can be made available in the page class just by creating a public attribute with the same name. [[http://click.apache.org/docs/user-guide/html/ch02s03.html|More]].
The data is also available in the velocity template, because it is automatically added to the [[http://click.apache.org/docs/click-api/org/apache/click/Page.html#model|page's model]]