Wicket Screencast - The basics
This screencast is part of a series about apache wicket. You can find the whole series and additional information on the Wicket Newsletter Screencast page. In this episode I cover the basics of apache wicket:
- How the project is set up
- The application class
- Wicket pages, separation of design and code
- Simple components and models
Transcript
Hello, welcome to this screencast about Apache Wicket. Today I will show you the basics of wicket, that is pages, components and models. My name is David. I work as a consultant and trainer, and you can find out more about me and read my blog at davidtanzer.net.
Let’s get started! As you can see, I use Sublime Text for all my editing [For this screencast. Most of the time I use an IDE. But this screencast should not be about the IDE, it should be about wicket]. You can, of course, use eclipse or any other IDE. I use gradle to build the project and later to run the web application.
I have created a skeleton project which pretty much follows the standard gradle or maven layout. We have a source directory which has two sections: “main” and “test”. The main section contains three actual source folders: “java”, “resources” and “webapp”. The “webapp” source folder only contains the “web.xml” deployment descriptor that I have already created.
First let’s have a look at the build file. I use the java plugin because, well, it’s a java project. And the jetty plugin because I will use the jetty web server to run the web application. I have also included the sublime text plugin because I use the Sublime Text editor. You can use, for example, the eclipse plugin if you want to use eclipse. This project already has several dependencies. We need “wicket-core” and later “wicket-guice”, both in the latest version. For the backend we need JPA and a database. Later we’ll also need JUnit to test everything. The rest of the build file is not that important. It’s a little bit of book keeping and configuration for the sublime text plugin.
Let’s go back to the web.xml deployment descriptor. As you can see I have configured the wicket filter to be applied to every URL pattern, so all the URLs are passed through the wicket filter and are part of the wicket application. The wicket filter needs an application class name. The application class is the main entry point of your application. So, let’s create the application class.
As you can see here in the deployment descriptor, I want to name my application class “NewsletterApplication”, and it has to be in the package “net.davidtanzer.wicket.newsletter”. So, let’s first create the file and create the class in the correct package. The class must extend the wicket “WebApplication” class, so let’s add that. Add the import too. This is something where and IDE will probably help you a lot.
WebApplication is an abstract class and we need to implement a method that returns the home page [of the application]. For this we need to import the page class. The method that returns the home page is called “getHomePage”. And we don’t need it yet, so we return null. Let’s build everything so we see if everything works. It seems like I got the import wrong here, of course, I have to import the “Page” class, not “WebPage”. But now everything should compile and for now we are finished with the application class.
The fact that there is a method “getHomePage” and something like a page class already hints us to an important concept of wicket: Wicket has pages. A page is something that is served to the user’s browser - A html page. And anther important concept in wicket is a strict separation of design and code. The design is done in simple, standards compliant HTML files. I have prepared one such file. It only contains a form to create new newsletters and it has not any program logic yet. The form is not very pretty (yet), and we will also not implement it today, this is what we’ll do in the next episode. Today we only want to add a simple “Label” component to the page.
As I said, the design is strictly separated from the code, and the code is a simple java class that extends “WebPage”. We will now create th code for this HTML file, for “CreateNewsletter.html”. The way wicket finds the code is by looking at the name of the file. The HTML file and the Java class have to be in the same package and have to have the same name. So we create the java class in the package “net.davidtanzer.wicket.newsletter.web.admin” and we save it as “CreateNewsletter.java”.
What’s left now is: We have to extend the WebPage” class. The fact that [this class] is a WebPage and is called CreateNewsletter tells wicket that it should load “CreateNewsletter.html” when the page is served. The class WebPage is a subclass of the Page class we used earlier in the application, so we could use this class as the home page. We probably don’t want to do this because this is an administration page.
The WebPage class is a special form of pages for serving HTML pages. Most of the time it’s the only page class you need. Later we will subclass this page class ourselves to add some projct specific functionality.
As I said before, we do not want to use the administration page as the homepage of your application. But we want to be able to access it anyway, so we want to mount it. That is, we want to create a special URL, “admin/add”, where we can find this page. After that, when everything compiles again, we can start the server and access this URL. It should show the administration page. It will show the “add newsletter” form.
I start the server with “gradle jettyRun”. When you start it for the first time it will take some time to get up and running, but now it’s there and we can access the page.
As you can see, the newsletter form that we looked at before is now running in our wicket application. This brings us to another important concept of wicket: Component orientation. Everything you see on the page, the textfield, the button, can be a component. A component is some part of the HTML which you can access and modify in the code later. Now we want to create a very simple component: A label, which shows the number of newsletters.
For this we create a “span” HTML tag and assign a special ID - the “wicket:id” “numNewsletters”. What we have to do now is we have to add this component to our page and we will do this in the constructor of our page. I want to add a “Label” component so first I create a new “Label” object. Every wicket component expects a “wicket:id” as it’s first constructor parameter. This wicket id is how the component finds the markup (the HTML tag where the component should be rendered) in the HTML file. To make sure the page class finds the component I have to add the label [to the page object - “this”].
This would already work, but the label does not know what text to show yet. So, let’s first add some static text. This is a rather boring use case, because we could have added the static text directly in the HTML file. This is just to show you that the label will display the text. Now the label shows up in the page.
What we really want to do here is display some information from our domain model. For this we can use the “Model” that almost every wicket component supports. The label not only shows static text, what it really does is to take some value from a model [and display it]. A model is anything that implements the wicket “IModel” interface. We use the PropertyModel which is very handy. The property model tells wicket “Take the given object - this - and search for a property - called numNewslettersModel in our case”. We have already created a private variable “numNewslettersModel”. Wicket will use reflection to read the value of this variable and display the value in the web page.
This value, 5, is still static, but you can imagine that you can use models and PropertyModel to access data from your domain. We will do this later in this screen cast series.
So, those were the basics of apache wicket. We talked about pages, components and models. And we created a simple label that wrote some text to the screen. In the next episode I will show you how to process user input. We will talk about forms and form components.
This screencast only covers the basics of apache wicket, if you want to know more, just drop me an email! My address is business@davidtanzer.net. Then we can talk about how we can work together.
