Getting Started with Apache Click and NetBeans IDE

Note: this post is from my project wiki pages, please read https://github.com/hantsy/click4nb/wiki/Getting-Started-with-Apache-Click-and-NetBeans-IDE for the newest version. If you have some suggestion or find some errors, please file an issue. Thanks.

After moved from Google Code, I have cleaned the codes and just released a new version of click4nb, which was tested against the stable NetBeans IDE 7.2.

Installation

Following the steps in Installation wiki page to install click4nb into your NetBeans IDE.

Create a web project with Apache Click Support

Create a Web Application in NetBeans is very easy, follow the following steps to create one for yourself.

1. Click the New Project button or click "File/New Project" menu from main menu in NetBeans IDE.
2. In the popup New Project dialog, select Java Web in the Categories list, and Web Application in the "Projects", click Next button.
3. In the Name and Location dialog, input the project related info, such Project Name, Project Location, Project Folder, click Next button.
4. In the Server and Settings dialog, select an application server, for example, tomcat. If there is no servers in your NetBeans IDE, click Add... button to add one.
5. In the Frameworks dialog, click the check box of the Click Framework in the list, make "Click" is selected.
   The basic configuration pane of Click framework will be showed in the below.
   There are two tabs in the panel.
   The main panel includes basic configuration, such defining a basic package name, and choose a mode in development phase, you can also add some extra features, such as Add Spring for adding Spring Click configuration and Spring Libraries, Enable Compression Filter for adding CompressionFilter to web.xml file, Enable Performance Filter for adding PerformanceFilter to web.xml file.
   CompressionFilter and PerformanceFilter are shipped with Apache Click release distribution.
   The Libraries panel includes two options to add Click library(jar files grouped by NetBeans) to the project. This plugin(click4nb) provides a configured a Click Library after you installed the plugin files. You can also define your own Click library, it will be organized by this plugin. You can also select None to skip adding Click Library directly.
6. Click Finish button to complete the project creation.

Explore the project codes

Let us have a look at the codes generated click4nb.
Open web.xml under the Web Pages/WEB-INF in Projects view or you can find web.xml in Configuration Files folder, there is a web.xml bookmark for web.xml.
By default, it created a Click Servlet registration.

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

It also created click.xml and menu.xml configuration files at the same time.
If you enabled Add Spring when you created the project, it will use a Spring specified Servlet.

<servlet>
    <servlet-name>ClickServlet</servlet-name>
    <servlet-class>org.apache.click.extras.spring.SpringClickServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>ClickServlet</servlet-name>
    <url-pattern>*.htm</url-pattern>
</servlet-mapping>

And also add extra Spring configuration.
For example, registered a contextConfigLocation context-param.

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>

And registered Spring ContextLoaderListener.

<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

And a spring configuration file named applicationContext.xml under WEB-INF was created.
In this file, it registered the Spring Click specific ScopeResovler.

<context:component-scan base-package="example.page" scope-resolver="org.apache.click.extras.spring.PageScopeResolver "/>

If you enabled CompressionFilter or PerformanceFilter in the creation phase, it will add extra codes into web.xml.

<filter>
    <filter-name>CompressionFilter</filter-name>
    <filter-class>org.apache.click.extras.filter.CompressionFilter</filter-class>
</filter>
<filter>
    <filter-name>PerformanceFilter</filter-name>
    <filter-class>org.apache.click.extras.filter.PerformanceFilter</filter-class>
    <init-param>
        <param-name>cachable-paths</param-name>
        <param-value>/assets/*</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>CompressionFilter</filter-name>
    <servlet-name>ClickServlet</servlet-name>
</filter-mapping>
<filter-mapping>
    <filter-name>PerformanceFilter</filter-name>
    <servlet-name>ClickServlet</servlet-name>
</filter-mapping>
<filter-mapping>
    <filter-name>PerformanceFilter</filter-name>
    <url-pattern>*.css</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>PerformanceFilter</filter-name>
    <url-pattern>*.js</url-pattern>
</filter-mapping>

But in the development stage, it is better to disable the two filters.

Run the project

In NetBeans IDE, running a project is easy work. Just right click the project node, and select Run or click the Run button in the toolar, and wait for few seconds, it will start the application server if it is stopped, and then deploy the web application into the application server.
After all are done, it will open a browser window and display the index page of the web application.

Hello, Click

We have created a Clicked based web application and have run it on application server.
Now let us add some codes into this project.
By default, it includes a simple home.htm and Home.java to display the current datetime.
The content of Home.java.

public class Home extends Page {

    private Date time = new Date();    

    public Home() {
       addModel("time", time);
    }
}

A click page must be derived from Click Page class.
The content of the home.htm(only copied the content of the body tag here).

<div id="header">
<span id="title">Home</span>
</div>
<div id="container">
Greetings from Click Framework at $time.
</div>

No surprise, it is very simple and direct. By default, Apache Click use Apache Velocity as template engine. It can be configured the click.xml file, the popular Freemarker template engine is also supported.
Let us create a new Click page now.
There are two ways to open the Creation wizard. The generic way is using the wizard.
If your cursor is focusing on the click.xml, and Alt+Insert to select New Page to open the Click Page creation dialog.

1. Click New File from File menu or New File button on the toolbar to open New File dialog.
2. In the popup New File dialog, choose Apache Click Framework from "Categories" list and Click Page from "File Types", click Next button.
3. In the New Click Page dialog, you can fill the page.
   This wizard provides two templates for you, "Blank" and "Simple Form". If "Blank" is selected, it will create a blank template page and page for you. The "Simple Form" one add an extra form tag for you by default.
   By default, it will create a Java class and a template file for you.
   You can input the Page Class name, the template name will be generated by the Apache Click rule automatically.
   The package name, you can select a existing package or input a new one.
   The Add mapping to click.xml provides an option for you if your page class and template do not apply the Click rule. A custom mapping will be added into click.xml file.
   In this exercise, input the following values.
   Template: select "Simple Form"
   Class Name: Greeting
   Package Name: select the existing example.page
   Leave other fields as default, click Finish button.
4. Change the content of GreetingForm class.
   
   

   private Form form = new Form("form"); 
    public GreetingForm() {
        addControl(form);
        form.add(new TextField("name", "Greeting Name", 50,  true));
        form.add(new Submit("OK"));
        form.setListener(this, "onSubmit");
    } 
   
    public boolean onSubmit() {
        if (form.isValid()) {
            String  msg = "Your name is " + form.getFieldValue("name");
            addModel("msg", msg);
        }
        return true;
    }

   We added a Form control in the page, and add a TextField field to the form, and add a Submit button to the form to submit the form.
   When the form is submitted, the form will invoke Form listener(onSubmit) to process to the submit action, firstly fetch the input value from text field, and display it in the page.
   Open the greeting-form.htm file, and chnage the content slightly, just add some code fragments to display msg.
   
   

   $form
   #if ($msg)
      <div id="msgDiv">
   $msg </div>
   #end

5. Run the project again, open web browser and navigate http://localhost:8080/ /greeting-form.htm.

Next step

Now it is your turn.
Read the official user guide from official Apache Click website.
Enjoy programming with Apache Click and NetBeans IDE. ;)