Apache Click Apache Click User Guide V 2.3.0 Copyright © 2001-2010 The Apache Software Foundation Table of Contents 1. Introduction to Apache Click ............................................................................................................ 1 1.1. Hello World Example ........................................................................................................... 1 1.2. Control Listener Type 1 Example ............................................................................................ 2 1.3. Control Listener Type 2 Example ............................................................................................ 4 1.4. Simple Table Example .......................................................................................................... 5 1.5. Advanced Table Example ...................................................................................................... 6 1.6. Simple Form Example ........................................................................................................... 9 1.7. Advanced Form Example ..................................................................................................... 11 1.7.1. Form Layout ........................................................................................................... 13 2. Pages .......................................................................................................................................... 14 2.1. Classes .............................................................................................................................. 14 2.2. Execution .......................................................................................................................... 15 2.3. Request Parameter Auto Binding ........................................................................................... 19 2.3.1. Customizing Auto Binding ......................................................................................... 19 2.4. Security ............................................................................................................................ 21 2.4.1. Application Authentication ......................................................................................... 21 2.4.2. Container Authentication ........................................................................................... 21 2.4.3. Container Access Control .......................................................................................... 22 2.4.4. Logging Out ............................................................................................................ 22 2.5. Page Navigation ................................................................................................................. 22 2.5.1. Forward .................................................................................................................. 22 2.5.1.1. Forward Parameter Passing .............................................................................. 23 2.5.1.2. Page Forwarding ............................................................................................ 23 2.5.2. Template Path ......................................................................................................... 24 2.5.3. Redirect .................................................................................................................. 25 2.5.3.1. Redirect Parameter Passing .............................................................................. 25 2.5.3.2. Post Redirect ................................................................................................. 26 2.6. Page Templating ................................................................................................................. 26 2.7. Page Actions ...................................................................................................................... 28 2.7.1. Page Action Execution .............................................................................................. 29 2.7.2. ActionResult ............................................................................................................ 30 2.7.3. Page Action Example ................................................................................................ 30 2.7.4. Accessing Request Parameters .................................................................................... 31 2.7.5. Set response headers and status code ........................................................................... 31 2.8. Direct Rendering ................................................................................................................ 32 2.9. Stateful Pages .................................................................................................................... 33 2.9.1. Page Creation .......................................................................................................... 33 2.9.2. Page Execution ........................................................................................................ 34 2.9.3. Page Destruction ...................................................................................................... 34 2.10. Error Handling ................................................................................................................. 34 2.11. Page Not Found ................................................................................................................ 35 2.12. Page Message Properties .................................................................................................... 35 2.13. Page HEAD Elements ........................................................................................................ 35 3. Controls ....................................................................................................................................... 38 Click V 2.3.0 Apache Click ii Apache Click 3.1. Control Interface ................................................................................................................ 38 3.2. Control Listener ................................................................................................................. 39 3.3. Control Classes .................................................................................................................. 40 3.4. Message Properties ............................................................................................................. 41 3.4.1. Message Resolution .................................................................................................. 42 3.4.2. Control Properties .................................................................................................... 42 3.4.3. Accessing Messages ................................................................................................. 43 3.5. Control HEAD Elements ...................................................................................................... 44 3.6. Container .......................................................................................................................... 45 3.6.1. AbstractContainer ..................................................................................................... 45 3.6.2. AbstractContainerField .............................................................................................. 46 3.7. Layouts ............................................................................................................................. 47 3.7.1. Template layout ....................................................................................................... 47 3.7.2. Programmatic layout ................................................................................................. 49 3.8. Behavior ........................................................................................................................... 52 3.8.1. Behavior Execution .................................................................................................. 53 3.8.2. Behavior Example .................................................................................................... 53 4. Ajax ............................................................................................................................................ 56 4.1. Ajax Overview ................................................................................................................... 56 4.2. AjaxBehavior ..................................................................................................................... 56 4.3. AjaxBehavior Execution ...................................................................................................... 58 4.4. First Ajax Example ............................................................................................................. 60 4.4.1. Ajax Trace Log ....................................................................................................... 62 4.4.2. Ajax Trace Log - No Ajax Target Control Found ........................................................... 63 4.4.3. Ajax Trace Log - No Target AjaxBehavior Found .......................................................... 63 4.5. Ajax Page Action ............................................................................................................... 64 4.6. Ajax Response Types .......................................................................................................... 65 4.7. Ajax Error Handling ........................................................................................................... 66 5. Configuration ............................................................................................................................... 67 5.1. Servlet Configuration .......................................................................................................... 67 5.1.1. Servlet Mapping ....................................................................................................... 67 5.1.2. Load On Startup ...................................................................................................... 67 5.1.3. Type Converter Class ................................................................................................ 68 5.1.4. Config Service Class ................................................................................................. 68 5.2. Application Configuration .................................................................................................... 68 5.2.1. Click App ............................................................................................................... 69 5.2.2. Pages ..................................................................................................................... 70 5.2.2.1. Multiple Pages Packages ................................................................................. 70 5.2.3. Page ....................................................................................................................... 70 5.2.3.1. Page Automapping ......................................................................................... 71 5.2.3.2. Automapping Excludes ................................................................................... 72 5.2.3.3. Page Autobinding .......................................................................................... 73 5.2.3.4. Page Autobinding - Using Annotations .............................................................. 75 5.2.4. Headers .................................................................................................................. 75 5.2.4.1. Browser Caching ........................................................................................... 75 5.2.5. Format ................................................................................................................... 76 Click V 2.3.0 Apache Click iii Apache Click 5.2.6. Mode ..................................................................................................................... 77 5.2.6.1. Page Auto Loading ........................................................................................ 77 5.2.6.2. Click and Velocity Logging ............................................................................. 78 5.2.7. Controls .................................................................................................................. 78 5.3. Auto Deployed Files ........................................................................................................... 78 5.3.1. Deploying resources in a restricted environment ............................................................. 79 5.3.2. Deploying Custom Resources ..................................................................................... 81 6. Best Practices ............................................................................................................................... 83 6.1. Security ............................................................................................................................ 83 6.1.1. Declarative Security .................................................................................................. 83 6.1.2. Alternative Security solutions ..................................................................................... 86 6.1.3. Resources ............................................................................................................... 86 6.2. Packages and Classes .......................................................................................................... 86 6.2.1. Page Classes ........................................................................................................... 87 6.3. Page Auto Mapping ............................................................................................................ 89 6.4. Navigation ......................................................................................................................... 89 6.5. Templating ........................................................................................................................ 90 6.6. Menus .............................................................................................................................. 91 6.7. Logging ............................................................................................................................ 91 6.8. Error Handling ................................................................................................................... 92 6.9. Performance ....................................................................................................................... 93 Click V 2.3.0 Apache Click iv Chapter 1. Introduction to Apache Click Apache Click is a simple JEE web application framework for commercial Java developers. Apache Click is an open source project, licensed under the Apache license . Click uses an event based programming model for processing Servlet requests and Velocity for rendering the response. (Note other template engines such as JSP and Freemarker are also supported) This framework uses a single servlet, called ClickServlet, to act as a request dispatcher. When a request arrives ClickServlet creates a Page object to process the request and then uses the page's Velocity template to render the results. Pages provide a simple thread safe programming environment, with a new page instance created for each servlet request. Possibly the best way to see how Click works is to dive right in and look at some examples. (The examples are also available online at http://click.avoka.com/click-examples/ under the menu "Intro Examples".) 1.1. Hello World Example A Hello World example in Click would look something like this. First we create a HelloWorld page class: package examples.page; import java.util.Date; import org.apache.click.Page; public HelloWorld extends Page { private Date time = new Date(); ❶ public HelloWorld() { addModel("time", time); ❷ } } ❶ Assign a new Date instance to the time variable. ❷ Add the time variable to the Page model under the name "time". Click ensures all objects added to the Page model is automatically available in the Page template. Next we have a page template hello-world.htm, where we can access the Page's time variable using the reference $time: <html> <body> Click V 2.3.0 Apache Click 1 Introduction to Apache Click <h2>Hello World</h2> Hello world from Click at $time </body> </html> Click is smart enough to figure out that the HelloWorld page class maps to the template hello-world.htm. We only have to inform Click of the package of the HelloWorld class, in this case examples.page. We do that through the click.xml [68] configuration file which allows Click to map hello-world.htm requests to the examples.page.HelloWorld page class. <click-app> <pages package="examples.page"/> </click-app> At runtime the following sequence of events occur. The ClickSerlvet maps a GET hello-world.htm request to our page class example.page.HelloWorld and creates a new instance. The HelloWorld page creates a new private Date object, which is added to the page's model under the name time. The page model is then merged with the template which substitutes the $time reference with the Date object. Velocity then renders the merged template as: Figure 1.1. Hello World Screenshot 1.2. Control Listener Type 1 Example Click includes a library of Controls [38] which provide user interface functionality. One of the commonly used controls is the ActionLink, which you can use to have an HTML link call a method on a Page object. For example: public class ControlListenerType1Page extends Page { /* Set the listener to this object's "onLinkClick" method. */ private ActionLink myLink = new ActionLink("myLink", this, "onLinkClick") private String msg; // Constructor ------------------------------------------------------------ public ControlListenerType1Page() { addControl(myLink); ❶ } // Event Handlers --------------------------------------------------------- Click V 2.3.0 Apache Click 2 Introduction to Apache Click /** * Handle the ActionLink control click event. */ public boolean onLinkClick() { String msg = "ControlListenerPage#" + hashCode() + " object method <tt>onLinkClick()</tt> invoked."; addModel("msg", msg); return true; } } ❶ Add the link to the page. The link will be made available to the page template under the variable myLink, which is the name of the control. In the Page class we create an ActionLink called myLink and define the control's listener to be the page method onLinkClick(). When a user clicks on myLink control it will invoke the listener method onLinkClick(). In Click a control listener method can have any name but it must return a boolean value. The boolean return value specifies whether processing of page events should continue. This control listener pattern provides a short hand way for wiring up action listener methods without having to define anonymous inner classes. The advantage of this style of control listener binding is that you have to write fewer lines of code. The disadvantage of this type of control listener binding is that no compile time safety is provided, and you miss out on the compiler refactoring capabilities provided with modern IDEs. Back to our example, in the page template we define an HTML link and have the myLink control render the link's href attribute: <html> <head> <link type="text/css" rel="stylesheet" href="style.css"></link> </head> <body> Click myLink control <a href="$myLink.href">here</a>. #if ($msg) <div id="msgDiv"> $msg </div> #end </body> </html> At runtime this page would be rendered as: Click myLink control here. When a user clicks on the link the onLinkClick() method is invoked. This method then creates the msg model value, which is rendered in the page as: Click myLink control here. Click V 2.3.0 Apache Click 3 Introduction to Apache Click ControlListenerPage#12767107 object method onLinkClick() invoked. 1.3. Control Listener Type 2 Example The second type of control listener binding uses the ActionListener interface to provide compile time safety. This compile time binding also supports code refactoring using modern IDE tools. public class ControlListenerType2Page extends Page { private ActionLink myLink = new ActionLink("myLink"); // Constructor ------------------------------------------------------------ /** * Create a new Page instance. */ public ControlListenerType2Page() { addControl(myLink); myLink.setActionListener(new ActionListener() { public boolean onAction(Control control) { String msg = "ControlListenerPage#" + hashCode() + " object method <tt>onAction()</tt> invoked."; addModel("msg", msg); return true; } }); } } In the Page class we create an ActionLink called myLink. In the Page constructor we set the control's action listener to an anonymous inner class which implements the method onAction(). When a user clicks on the myLink control it will invoke the action listener method onAction(). As with our previous example, in the page template we define a HTML link and have the myLink control render the link's href attribute: <html> <head> <link type="text/css" rel="stylesheet" href="style.css"></link> </head> <body> Click myLink control <a href="$myLink.href">here</a>. #if ($msg) <div id="msgDiv"> $msg </div> #end </body> </html> Click V 2.3.0 Apache Click 4 Introduction to Apache Click At runtime this page would be rendered as: Click myLink control here. When a user clicks on the link the onAction() method is invoked. This method then creates the msg model value, which is rendered in the page as: Click myLink control here. ControlListenerPage#12767107 object method onAction() invoked. 1.4. Simple Table Example One of the most useful Click controls is the Table control. An example usage of the Table control in a customers Page is provided below: public class SimpleTablePage extends Page { @Bindable protected Table table = new Table(); // Constructor ------------------------------------------------------------ public SimpleTablePage() { table.setClass(Table.CLASS_ITS); table.addColumn(new Column("id")); table.addColumn(new Column("name")); table.addColumn(new Column("email")); table.addColumn(new Column("investments")); } // Event Handlers --------------------------------------------------------- /** * @see Page#onRender() */ @Override public void onRender() { List list = getCustomerService().getCustomersSortedByName(10); table.setRowList(list); } } In this Page code example a Table control is declared, we set the table's HTML class, and then define a number of table Column objects. In the column definitions we specify the name of the column in the constructor, which is used for the table column header and also to specify the row object property to render. The last thing we need to do is populate the table with data. To do this we override the Page onRender() method and set the table row list before it is rendered. In our Page template we simply reference the $table object which is rendered when its toString() method is called. <html> Click V 2.3.0 Apache Click 5 Introduction to Apache Click <head> $headElements </head> <body> $table $jsElements </body> </html> Note from the example above that we specify the $headElements reference so that the table can include any HEAD elements, which includes Css imports and styles, in the header. Also note we specify the $jsElements reference which include any JavaScript imports and scripts at the bottom. At runtime Click automatically makes the variables $headElements and $jsElements available to the template. At runtime the Table would be rendered in the page as: Figure 1.2. Simple Table 1.5. Advanced Table Example The Table control also provides support for: • automatic rendering • column formatting and custom rendering • automatic pagination • link control support A more advanced Table example is provided below: public class CustomerPage extends Page { private Table table = new Table("table"); private PageLink editLink = new PageLink("Edit", EditCustomer.class); private ActionLink deleteLink = new ActionLink("Delete", this, "onDeleteClick"); // Constructor ------------------------------------------------------------ Click V 2.3.0 Apache Click 6