How-to guides

Getting started

• Create a project from the quickstart archetype Generate a ready-to-run Wicket project with Maven, know what is in it, and open it in your IDE.
• Switch between development and deployment mode Run Wicket in deployment mode on production servers, with a system property, a web.xml parameter or code, and check which mode is active.
• Add Wicket support to your IDE Install WicketForge in IntelliJ IDEA or QWickie in Eclipse to jump between Java and markup and complete wicket:id values.

Components and markup

• Show, hide or disable a component Hide a component or make it read-only depending on the state of your application, and decide that state once per request in onConfigure.
• Change a tag's attributes Set, append to or remove an attribute of a component's tag from Java, with a fixed value or one that follows a model.
• Give a component a markup id Render the HTML id attribute of a component so JavaScript, CSS, labels and Ajax can find it, and choose or generate the id yourself.
• Group components with WebMarkupContainer Attach a plain HTML element to a container component so you can hide, disable, style or repaint a group of components as one.
• Build a reusable panel Package a piece of user interface as a Panel, a Java class with its own HTML file, and use it on any page as often as you need.
• Swap markup with fragments Keep small alternative pieces of markup inside a page or panel and choose in Java which one to show, without a panel class for each.
• Wrap content with a Border Write the markup that goes around content once, as a Border, and wrap any part of a page in it while the page keeps its own components.
• Hide surrounding markup with wicket:enclosure Hide a caption, label or table row together with the component it describes, without a container component in Java.
• Render a component without its tag Leave out a component's own HTML tag and render only its content, and know what stops working when you do.
• Keep preview markup out of the output Leave sample content in your HTML files so they look complete in a browser or design tool, and make sure Wicket never sends it.
• Add behavior to a component with a Behavior Write a Behavior that changes a component's tag, adds markup around it or contributes CSS and JavaScript, and reuse it on any kind of component.
• Add components without repeating the markup hierarchy Queue components on a page or panel and let Wicket put each one in the right container by following the nesting in the markup.
• Generate markup from code Give a panel or page markup built in Java instead of an HTML file, and control whether Wicket caches it.

Models

• Read and write data with lambda models Use lambdas, method references and the default methods of IModel to show computed values and bind components to properties without strings.
• Bind components to a JavaBean Read and write bean properties with PropertyModel, and let form fields find their property by id with CompoundPropertyModel.
• Chain models Wrap one model in another so that a form, a panel or a label always works on the object the inner model currently holds.
• Load data once per request with detachable models Keep only an id in the page and load the entity fresh in every request with LoadableDetachableModel.
• Use more than one model in a component Detach the extra models a component, behavior or custom model keeps in its fields, so their data is not stored with the page.

Forms

• Validate input and show errors Make fields required, check their values with validators, show the error messages and change their text.
• Convert input to your types Tell a field which type its input becomes, write a converter for your own type and register it for one field or the whole application.
• Validate with Bean Validation Check form input against the Jakarta Bean Validation annotations on your domain classes with the wicket-bean-validation module.
• Let the user pick from a list Show a drop-down list with DropDownChoice, render objects and enums as options, and control the empty "Choose One" option.
• Use checkboxes and radio buttons Bind a checkbox to a boolean, let the user tick several options or pick one with radio buttons, and add a "select all" checkbox.
• Select several values Let the user select several values from a list with ListMultipleChoice, or move them between two lists with Palette.
• Use more than one submit button Give a form several buttons that each run their own code, pick the button for the Enter key, and add a Cancel button that skips validation.
• Nest forms Put a form inside another form, submit and validate the inner form on its own, and decide which forms take part in a submit.
• Upload files Let users upload one or more files with FileUploadField, limit their size and number, and show upload progress.
• Combine fields into one form component Build a FormComponentPanel that shows several inputs but converts, validates and stores them as one value.
• Build a stateless form Use StatelessForm so a page with a form stays stateless, never expires and does not create a session until it must.

Lists and tables

• Repeat markup with RepeatingView Render a tag once for every child you add in code, for menus, button bars and other short lists you build in the constructor.
• Show a list with ListView Render markup for every element of a java.util.List, keep form input in the rows, and avoid the pitfalls of index-based items.
• Control how items are reused with RefreshingView Build repeater items from models you supply, and keep an item's components across renders as long as its model stays in the list.
• Page through data Load one page of rows at a time with an IDataProvider, show them in a DataView or DataTable, and let users move between pages.

Ajax and JavaScript

• Update components with Ajax Re-render components, show hidden ones, refresh lists and run JavaScript in response to an Ajax request.
• Show that a request is running Show a busy indicator while an Ajax request runs, with the indicating components, your own component or your own spinner element.
• Block the page while a request runs Wicket 11+ Cover the page or one component with a veil during Ajax requests, so a second click cannot send the same request twice.
• Change how an Ajax request is sent Override updateAjaxAttributes to throttle requests, send them as POST, pass extra parameters, drop outdated ones or stop the browser's default action.
• React to Ajax requests in JavaScript Run your own JavaScript before, during and after Ajax requests, for one component with a call listener or for the whole page with global events.
• Use Ajax on stateless pages Make Ajax components and behaviors stateless with getStatelessHint, so a page such as a login page keeps working without a stored page instance.
• Write Ajax handlers as lambdas Create Ajax behaviors from lambdas with their static factory methods instead of anonymous subclasses, and do the same for Ajax links and buttons.
• Wrap a JavaScript widget in a component Package a JavaScript library with a component, initialize it with the component's markup id, keep it working after Ajax updates and call back to the server.
• Run Ajax without jQuery Wicket 11+ Switch the application to Wicket's plain JavaScript Ajax implementation, so pages no longer download jQuery.

WebSockets

• Push updates over a WebSocket Set up wicket-native-websocket, handle messages from the browser and push component updates to a page from a background thread.
• Test WebSocket behaviors Send messages to a page's WebSocket behavior and check what it pushes back with WebSocketTester, without a servlet container.

Links and URLs

• Pass parameters to a page Put values in the URL of a page with PageParameters, read them in the page constructor and convert them to the types you need.
• Link to a page Navigate to another page with a Link that runs code on the server first, or with a BookmarkablePageLink that points straight at the page.
• Turn plain links into page links with wicket:link Write ordinary anchors to page files in the markup and let wicket:link turn them into links to bookmarkable pages, without Java code.
• Link to another site Render a link to a URL outside your application with ExternalLink, build the URL from a model, and redirect to another site from code.
• Use links on stateless pages Handle clicks on a stateless page with StatelessLink and keep the state the click needs in page parameters, because every click builds a new page.
• Give pages readable URLs Mount pages on paths of your choice, put page parameters in path segments with placeholders, and mount a whole package at once.
• Encrypt URLs Wicket 11+ Hide class names and component paths behind encrypted URLs with CryptoMapper, and choose where the key lives so that stateless pages keep working.

Resources

• Serve files from your Java packages Keep images, media and other files next to the component that uses them and serve them with PackageResourceReference, from Java or from markup.
• Add CSS and JavaScript to a page Let a component or behavior add its stylesheets, script files and start-up code to the page header with renderHead and header items.
• Use files from the web application root Add stylesheets, scripts and images that live in the web application folder, such as src/main/webapp, to your pages with ContextRelativeResourceReference and ContextImage.
• Declare dependencies between resources Make a script or stylesheet pull in the libraries it needs by overriding getDependencies, so Wicket always renders them first and only once.
• Combine resources into one bundle Serve several package stylesheets or scripts as one file with ResourceBundles, and replace a resource throughout the application with addResourceReplacement.
• Put JavaScript at the end of the body Render all script header items in a container just before the closing body tag with JavaScriptFilteredIntoFooterHeaderResponse and HeaderResponseContainer.
• Control the order of header items Put a header item first with PriorityHeaderItem, let the page's own items come before those of its components, and fix where Wicket inserts items with wicket:header-items.
• Generate a resource in code Build files on request, such as a CSV export, a PDF or an image, by extending AbstractResource or writing a lambda, and offer them for download with ResourceLink.
• Give a resource a URL Mount a resource reference on a path of your choice with mountResource, read path and query parameters in the resource, and link to the mounted URL.
• Share a resource across the application Register a resource once under an application-wide key with getSharedResources and refer to it from any component with SharedResourceReference.
• Customize where resources are loaded from Make Wicket find markup, properties and package files in a folder of the web application or the file system by adding resource finders.
• Minify and compress CSS and JavaScript Serve pre-minified .min files, strip JavaScript in deployment mode, plug in your own CSS or JavaScript compressor, and rewrite URLs inside stylesheets with CssUrlReplacer.
• Serve files with NIO Serve files from the file system or from inside a ZIP archive through java.nio.file.Path with FileSystemResourceReference and FileSystemResource, including byte ranges for media.
• Show images from an external URL Render img and source tags whose URL comes from a model with ExternalImage and ExternalSource, for images on another server or a CDN.

Pages and state

• Keep a page stateless Build a page that Wicket does not store in the session, find the component that makes it stateful, and guard it with a test.
• Configure the page store Change how much page history Wicket keeps per session and where, encrypt stored pages, or replace the disk store with another store.
• Keep data in the session Store per-user data in a typed Wicket session, in session attributes or as metadata, control when the session is created, and end it on logout.

Requests and lifecycle

• Handle exceptions and show error pages Replace Wicket's error pages, choose what users see after an unexpected exception, and map your own exceptions and HTTP errors to pages.
• Handle a callback URL with IRequestListener Let a component or behavior answer requests to a URL of its own, read parameters from the request, and respond with the page or anything else.
• Send events between components Let a component notify others on the page without holding references to them, with send(), onEvent() and a payload class.
• Configure a module with an initializer Let a jar configure every Wicket application it is added to, with an IInitializer registered through the Java ServiceLoader.

Localization

• Translate component texts Move the texts of a page or panel into properties files, show them with wicket:message or from Java, and let the user switch the language.
• Put model values into translated texts Show translated texts through ResourceModel and StringResourceModel, fill in property values and MessageFormat parameters, and choose the key from the data.
• Translate the options of a choice Show translated options in a DropDownChoice, RadioChoice or other choice component, translate enum values, and change the "Choose One" text.
• Load texts from your own source Add a string resource loader that reads texts from a database or an existing Java ResourceBundle, and change the chain of loaders Wicket searches.

Security

• Log users in Add a sign-in page with wicket-auth-roles, send anonymous users there when a page needs a signed-in user, and sign them out again.
• Restrict access by role Allow pages, components, actions and resources only for users with a given role, with annotations on classes and packages or in code.
• Require HTTPS Serve pages over HTTPS with HttpsMapper and @RequireHttps, and set up the container so redirects and absolute URLs use the right host.
• Protect against cross-site request forgery Refuse link clicks, form submits and Ajax calls that another site makes on behalf of your users, with ResourceIsolationRequestCycleListener.
• Configure the Content Security Policy Work with the strict Content Security Policy Wicket sends by default, allow extra sources, report violations, and move inline scripts and styles out of the markup.
• Isolate the page with COOP and COEP Set the Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers, which Wicket sends by default, to isolate your pages from other origins.
• Control which package resources are served Allow or block files on the classpath that browsers may request as package resources, with patterns on SecurePackageResourceGuard.

Testing

• Test pages and components Render pages and single components in a unit test, click links, fire Ajax events and check what they render, with WicketTester and JUnit.
• Test forms Fill in fields, pick options, upload files and submit a form in a unit test with FormTester, then check the feedback messages and the model.
• Test markup Find tags in the rendered output with TagTester and check their attributes and content, render a component to a string, or compare a page with an expected file.
• Test with Spring Test pages that use @SpringBean with WicketTester, either with mock beans in an ApplicationContextMock or against a real Spring test context.

Integration

• Inject Spring beans Inject beans from a Spring application context into pages, components, behaviors and other objects with @SpringBean.
• Inject CDI beans Configure wicket-cdi so pages, components, behaviors and the session get CDI beans with @Inject, and choose beans that survive serialization.
• Inject EJBs Inject session beans, JNDI resources and persistence units into Wicket components with @EJB, @Resource and @PersistenceUnit, through WicketStuff's javaee-inject module.
• Inject with JSR-330 annotations Use the standard @Inject and @Named annotations instead of @SpringBean, with the Spring, Guice and CDI integrations.
• Run on Apache Karaf Install Wicket in Apache Karaf or another OSGi container with the Karaf feature that every Wicket release publishes.
• Inspect and change settings with JMX Add wicket-jmx to see a running application's settings and session counts in JConsole, clear the markup cache, and change some settings without a restart.
• Measure with Wicket metrics Count requests and time component creation, rendering and model loading with the experimental wicket-metrics module, AspectJ and Dropwizard Metrics.