Create a simple "Hello World" application..
Author: Florian Lippisch
|
First Steps Tutorial Create a simple "Hello World" application.. |
Last Update: 2009-04-19 Author: Florian Lippisch |
This document introduces new users into the jWic Framework. It takes about 30 minutes to go through the tutorial and get an idea what jWic is about. This tutorial applies to the jWic version 3.x.
It is recommend to use an up-to-date IDE (i.e. Eclipse) where you can develop and debug your application. If you do not have one already, you may setup a new one using our development setup guide
If you do not use an IDE that build your classes automatically, you must manually do so and copy
your .class and resource files to the WEB-INF/classes directory of your
web application. But since it is far beyond the scope of this tutorial, it is not discussed here.
Can there be a tutorial without a Hello World program? No way. So let's start with this simple lesson.
1. Create a package named de.jwic.tutorial.sample1.
To keep it simple, we will create a package for each application in this tutorial. In
the real world, it is completely up to you how you organize your code.
2. Create a new Java class in this package named HelloWorldApp that extends de.jwic.base.Application.
You should end up with a class like this:
package de.jwic.tutorial.sample1;
import de.jwic.base.Application;
/**
* My first jWic Application.
*/
public class HelloWorldApp extends Application {
public Control createRootControl(IControlContainer container) {
// TODO insert your code here.
return null;
}
}
Your IDE has most probably generated a stub for the method createRootControl(..).
Inside of this method, we must create our controls and return the control that should be displayed
as the root object. We can have any control as root object, but since we will (later) want
to have more then one control on that page, we will create a container class.de.jwic.base.Page with the name HelloWorldPage.
As we want to display our little HelloWorld message, we need a control that displays simple text.
So we have to create an instance of the LabelControl as a child of the HelloWorldPage object. After that, we can set the
text of the label to display our message: "Hello World!". jWic controls are
simple java beans that use properties with getter/setter pairs. So all we have to
do is look for a set-method that seems to do what we want. The property
Text seems to fit, so let's use .setText(String).
import de.jwic.base.IControlContainer;
import de.jwic.base.Page;
import de.jwic.controls.LabelControl;
public class HelloWorldPage extends Page {
private LabelControl label;
public HelloWorldPage(IControlContainer container, String name) {
super(container, name);
label = new LabelControl(this);
label.setText("Hello World!");
}
}
Now that we have created our page, we can create an instance of it in the HelloWorldApp class.:
public Control createRootControl(IControlContainer container) {
HelloWorldPage page = new HelloWorldPage(container, null);
return page;
}
Our class is now done, but how do we start the application from the browser? To keep it
simple, we use the TestLauncher application, that can launch any control or application
which is specified
in the URL.
http://localhost:8080/myjwic/sample/testrun.xwic?class=de.jwic.tutorial.sample1.HelloWorld
Now you should see a page with the TestLauncher header including a refresh and exit link. Under the horizontal ruler you should see our Hello World message. If not, make sure your server is up and running and your class is compiled and deployed.
So far, it has not been so exiting, so let's add a few more extra features to our little application. In the next step, we want to give the user the chance to enter his name so our message becomes a little more personal.
What we need is an input box and a confirm button. So
we add a ButtonControl and an InputBoxControl to our code:
private LabelControl label = null;
private ButtonControl btConfirm = null;
private InputBoxControl inpName = null;
public HelloWorldPage(IControlContainer container, String name) {
super(container, name);
label = new LabelControl(this);
label.setText("Hello World!");
btConfirm = new ButtonControl(this);
btConfirm.setTitle("Ok");
inpName = new InputBoxControl(this);
}
When you now start your application with the TestLauncher, you will see something like this:
| Hello World! |
When you press the Ok button, the form is submitted but nothing happens. The text entered in the field is still there, but that's all. The next step is to add some logic behind that Ok button.
jWic is an event-driven UI framework that hides entire web specific objects and methods like the HttpServletRequest from the application developer. All we have to do is to add a listener to the button that should be invoked when the button is clicked, following the standard JavaBeans listener pattern.
btConfirm = new ButtonControl(this);
btConfirm.setTitle("Ok");
btConfirm.addSelectionListener(new SelectionListener() {
public void objectSelected(SelectionEvent event) {
applyUserName();
}
});
Now whenever the button is clicked by the user (or by a test-program), the method
applyUserName() is invoked. We could have added the code to update
the label right here but that is kind a dirty and can mess up your project if it becomes
more complex and you have to look behind each button when you look for a problem.
So lets do it right and add our applyUserName() method.
/**
* Apply the username to the HelloWorld label.
*/
protected void applyUserName() {
label.setText("Hello " + inpName.getText());
}
Now run the example and see if it works. The application should work as expected.
Before we continue with the layout, let's quickly review what we have done so far. The
first step was to create a new Java class that acts as a container for the controls
we needed. This class acts as the entry point for our application and is
instantiated
when the application is launched. In the init() method, we setup the
controls by simply instantiating them in java-style and setting some properties. This
follows the standard JavaBean pattern, which is easy to learn and intuitive to use.
After setting up our controls, we added a listener to act on an event that was
interesting for us. And finally, we added a little code that updated the label with
a message that contained the text the user entered into the input field.
The application now still looks very basic. The controls are rendered in an undefined order, which most of the time is not desired. So our next step will be to apply a layout to our application.
Each jWic control is rendered using a registered renderer. The default renderer is based upon a Velocity specific implementation. This renderer merges the control with a velocity-template that is loaded by a resource loader. In the default configuration, the template is loaded from the classpath, using the classname of the control and adding a ".vtl" extension to find the right file.
So all we need to do is to create a new file in our package (de.jwic.tutorial.sample1) named
by our classname with a .vtl extension: HelloWorldPage.vtl.
What comes now is a bit of Velocity design. If you are unfamiliar with it you may have a
look at the Velocity User Guide
for an introduction, but it is not required for this tutorial.
The template contains static HTML code with placeholders for our dynamic content. For now, just copy & paste the code as it is listed here:
<h1>jWic Tutorial - HelloWorld Sample</h1>
<p>$insert.control("c0")</p>
<p>For your personalized greeting enter your name here:<br>
$insert.control("c2")<br>
$insert.control("c1")</p>
Now save the file and check test the application. The controls should be at the right place now, but how?
The controls are inserted by the function $insert.control(<name>). Since we
have not specified a name when we have added the control to the container, it has been
automatically created with the pattern c#, where # is the control count. If there is already
a control with that name, the next number is taken.
While the auto-naming function is nice if you do not work with layouts, it becomes a mess when you want to layout a page and have to work with these names.
So let us correct this and give the controls a name before we add them to the container:
label = new LabelControl(this, "lblHello");
label.setText("Hello World!");
btConfirm = new ButtonControl(this, "btConfirm");
btConfirm.setTitle("Ok");
btConfirm.addSelectionListener(new ObjectSelectedListener() {
public void objectSelected(ObjectSelectedEvent event) {
applyUserName();
}
});
inpName = new InputBoxControl(this, "inpName");
And fix the template (HelloWorldPage.vtl):
<h1>jWic Tutorial - HelloWorld Sample</h1>
<p>$insert.control("lblHello")</p>
<p>For your personalized greeting enter your name here:<br>
$insert.control("inpName")<br>
$insert.control("btConfirm")</p>
If it works now, you have done everything right :-). If it does not, you might have to restart the server/webapp because the velocity templates are cached if the velocity engine is configured to do so.
Until now, we have launched our application using the TestLauncher. For a real
application, you will want to start it directly. This is done using an
ApplicationSetup.
The ApplicationSetup specifies what is required to launch and manage the lifetime of an application. For our application, we just have to specify the application name and the name and classname of the root control.
The jWic DispatcherServlet builds an ApplicationSetup from .xwic files,
which are simple XML files. Our next step is to create such a file, named hello.xwic. The location
of the file should be the sample directory, where the jwic.page file
is.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//jWic//DTD xwic 3.2//EN' 'http://jwic.sourceforge.net/xwic-3.2.dtd'>
<application>
<name>my Hello World</name>
<class>de.jwic.tutorial.sample1.HelloWorldApp</class>
</application>
Now try to start your application using the file: http://localhost:8080/myjwic/sample/hello.xwic
That's all for now. I hope you have been able to get a basic understanding of how things work with jWic. More documentation and tutorials are being written, so keep a look out for more!