Ten Things Every Wicket Programmer Needs to Know
Models — In Wicket, one of the most beneficial things you can do to help yourself is gain a thorough understanding of models (that is, implementations of the IModel interface). And then as one user said 'once you think you understand them, go back and learn them again'. Models are not really a difficult concept to grasp, so don't despair. But using them (and in general, storing state in real Java objects for web programming) is such a different way of doing things, that most newcomers struggle with this for quite some time. See the Wicket Models page for a more complete discussion of them.
Pull, don't push — This goes along with the model discussion. Your components need a plethora of data to render — the data that they actually render (which comes from the model), whether or not they are visible or hidden, enabled or disabled, or many other possible configuration options. The key to all of these is that in general the component should be able to pull its state rather than having some other component push the state on it. The example below demonstrates what this means and why it's important. The key is that the constructor only runs once, but many things on the page might change state after the constructor is run. If you push your state into components in your constructor, they are out-of-date as soon as another component changes state. The only alternative is that every component must know about all other components that share state — and that's not "the Wicket way". Your components should be independent and reusable.
// assuming children is an instance of IModel<Collection<DomainObject>> // DON'T do this: this is PUSHING data: link.setVisible(children.getObject().isEmpty()); // DO this instead: Label label = new Label("label", someModel) { public boolean isVisible() { return children.getObject().isEmpty(); } }; // WHY? Because you may have this elsewhere on the page: Link<Void> link = new Link<Void>("link") { public void onClick() { children.getObject().add(new DomainObject()); } };Wicket is a UI framework — This seems like something that could go unsaid. Unfortunately, it needs to be stated. Use Wicket to render your UI and handle interactions with the user. But push all non-UI code down into other layers like your shared services and persistence layers. Your business logic doesn't need to be in your UI code.
Keep markup and code clean and compact — Become familiar with and use the various aspects of Wicket that allow for reusability. For instance, create custom panels for pieces of interface that are used on multiple pages. Use markup inheritance in your panels and pages to reuse common interface pieces like headers, footers and navigation bars. Become familiar with fragments, which are like anonymous panels. They are especially helpful to use inside data tables and other repeating components that can only have a single component added to them — add your fragment that contains the other necessary components..
Match your hierarchies — It won't take you long at all to learn this rule, but the hierarchy of components in your markup (tags with a wicket:id attribute) must match the hierarchy in your Java code. In other words, if you have "<a wicket:id="link"><span wicket:id="label"></span></a>" in your markup, you need to call link.add(label) in your Java code. The label must be added to the link, and the link must be added to the page or component that hosts the markup.
Form processing lifecycle — When dealing with forms, it is important to understand the order of operations of the form post processing. If any step in the process fails the onError method of your form and submitting button will be called rather than the onSubmit method. First, all components that are required (isRequired() returns true) are checked to make sure that some input was received for them. Then, the input is converted from the string that came with the form post to the type that the component requires. There are built-in converters for dates, numbers and other standard types, but you can add converters for custom types. If conversion succeeds, validators are run to make sure the input meets your validation requirements. This is where you check for string length, values in the proper range, and any business rules you have. Validators validate the converted input, dealing directly with the Java types for the component (Integer, Date, et cetera) rather than the raw posted string. The last step before onSubmit is called is to take the converted input that has passed validation and call model.setObject(convertedValue) on the form component's model. Thus, if onSubmit is called, you can call getModel to get the form values but if onError is called, you can not.
Java nuances — There are two Java nuances that catch many Wicket newcomers off-guard.
The first is serialization. Wicket uses Java serialization to store the state of your component hierarchy (the page and all its components and their components and so-on) in memory or on disk between page requests. This means you need to be careful because things can get serialized by accident. The most common cause of this is declaring a variable "final" outside of an anonymous inner class and then using it inside that anonymous inner class. Doing this causes the compiler to add a member variable to the anonymous inner class. If that final variable is a large collection or a service from your middle-tier, this can cause a gigantic explosion of memory usage and can be hard to track down. In short: be very cautious with what you reference within anonymous inner classes and use member variables in your classes sparingly.
The second is anonymous inner classes. You don't have to use them, but when used sparingly, they can make your code more readable. However, if you use them too much, they can make your code look like spaghetti. Hopefully you start refactoring them into concrete classes before that happens. The key is: be familiar with the syntax and usage of anonymous inner classes because you are likely to encounter them frequently in Wicket code.
Unit testing — Testing your Wicket code is made relatively easy by using WicketTester. Most frameworks do not allow the level of unit testing that can be accomplished with Wicket. Though it is often pushed aside, unit testing your components and pages can be invaluable to assist in avoiding regressions.
i18n — Internationalization is made very easy with Wicket. Become familiar with and use wicket:message to insert localized strings into your markup. It can also be used inside a markup tag to add a localized string as an attribute of the tag (i.e. title or alt attributes). Images can easily and transparently be internationalized by adding the locale to the end of the filename (i.e. somefile.jpg and somefile_es.jpg).
Where to find help — There are many resources available to you to see how to do something in Wicket. First of all, if you don't know how to do something just look for a class by the name you'd expect it to have (i.e. Checkbox, RadioChoice, RadioGroup, DropDownChoice, Grid...). If you find a class that looks right, read the JavaDocs. Most of the Wicket codebase is extremely well-documented. Also, see wicket-examples, which is a suite of small applications that show how to do common things in Wicket. They are part of the main codebase, or can be viewed online at http://wicketstuff.org/wicket. Additionally, Wicket has one of busiest and most helpful mailing lists of any open source project. Searching the mailing list archives will generally yield helpful hints with most problems you may encounter. Emailing the list will almost certainly get you a plethora of helpful answers. Joining and reading the mailing list posts will certainly help you learn new things as you enjoy your Wicket adventure. For more information on the Wicket mailing lists, see http://wicket.apache.org/help/email.html