= Wicket 8.x Reference Guide
The Apache Software Foundation
:description: Official User Guide for Apache Wicket framework. 
:keywords: Apache Wicket, User Guide, examples, AJAX, stateless
:toc: left
:icons: font
:sectlinks:

:sectnums:

//custom variables used inside the guide
:wicket_examples_url: http://examples8x.wicket.apache.org
:wicket_tutorial_examples_url: https://wicket-guide.herokuapp.com/

== Introduction
include::introduction.adoc[]

== How to use the example code

include::howToSource.adoc[]

== Why should I learn Wicket?

include::whyLearn.adoc[]

=== We all like spaghetti :-) ...

include::whyLearn/whyLearn_1.adoc[leveloffset=+1]

=== Component oriented frameworks - an overview

include::whyLearn/whyLearn_2.adoc[leveloffset=+1]

=== Benefits of component oriented frameworks for web development

include::whyLearn/whyLearn_3.adoc[leveloffset=+1]

=== Wicket vs the other component oriented frameworks

include::whyLearn/whyLearn_4.adoc[leveloffset=+1]

== Wicket says “Hello world!”

include::helloWorld.adoc[]

=== Wicket distribution and modules

include::helloWorld/helloWorld_1.adoc[leveloffset=+1]

=== Configuration of Wicket applications

include::helloWorld/helloWorld_2.adoc[leveloffset=+1]

=== The HomePage class

include::helloWorld/helloWorld_3.adoc[leveloffset=+1]

=== Wicket Links

include::helloWorld/helloWorld_4.adoc[leveloffset=+1]

=== Summary

include::helloWorld/helloWorld_5.adoc[leveloffset=+1]

== Wicket as page layout manager

include::layout.adoc[]

=== Header, footer, left menu, content, etc...

include::layout/layout_1.adoc[leveloffset=+1]

=== Here comes the inheritance!

include::layout/layout_2.adoc[leveloffset=+1]

=== Divide et impera!

include::layout/layout_3.adoc[leveloffset=+1]

=== Markup inheritance with the wicket:extend tag

include::layout/layout_4.adoc[leveloffset=+1]

=== Summary

include::layout/layout_5.adoc[leveloffset=+1]

== Keeping control over HTML

include::keepControl.adoc[]

=== Hiding or disabling a component

include::keepControl/keepControl_1.adoc[leveloffset=+1]

=== Modifing tag attributes

include::keepControl/keepControl_2.adoc[leveloffset=+1]

=== Generating tag attribute 'id'

include::keepControl/keepControl_3.adoc[leveloffset=+1]

=== Creating in-line panels with WebMarkupContainer

include::keepControl/keepControl_4.adoc[leveloffset=+1]

=== Working with markup fragments

include::keepControl/keepControl_5.adoc[leveloffset=+1]

=== Adding header contents to the final page

include::keepControl/keepControl_6.adoc[leveloffset=+1]

=== Using stub markup in our pages/panels

include::keepControl/keepControl_7.adoc[leveloffset=+1]

=== How to render component body only

include::keepControl/keepControl_8.adoc[leveloffset=+1]

=== Hiding decorating elements with the wicket:enclosure tag

include::keepControl/keepControl_9.adoc[leveloffset=+1]

=== Surrounding existing markup with Border

include::keepControl/keepControl_10.adoc[leveloffset=+1]

=== Summary

include::keepControl/keepControl_11.adoc[leveloffset=+1]

== Components lifecycle

include::componentLifecycle.adoc[]

=== Lifecycle stages of a component

include::componentLifecycle/componentLifecycle_1.adoc[leveloffset=+1]

=== Hook methods for component lifecycle

include::componentLifecycle/componentLifecycle_2.adoc[leveloffset=+1]

=== Initialization stage

include::componentLifecycle/componentLifecycle_3.adoc[leveloffset=+1]

=== Rendering stage

include::componentLifecycle/componentLifecycle_4.adoc[leveloffset=+1]

=== Removed stage

include::componentLifecycle/componentLifecycle_5.adoc[leveloffset=+1]

=== Detached stage

include::componentLifecycle/componentLifecycle_6.adoc[leveloffset=+1]

=== Summary

include::componentLifecycle/componentLifecycle_7.adoc[leveloffset=+1]

== Page versioning and caching

include::versioningCaching.adoc[]

=== Stateful pages vs stateless

include::versioningCaching/versioningCaching_1.adoc[leveloffset=+1]

=== Stateful pages

include::versioningCaching/versioningCaching_2.adoc[leveloffset=+1]

=== Stateless pages

include::versioningCaching/versioningCaching_3.adoc[leveloffset=+1]

=== Summary

include::versioningCaching/versioningCaching_4.adoc[leveloffset=+1]

== Under the hood of the request processing

include::requestProcessing.adoc[]

=== Class Application and request processing

include::requestProcessing/requestProcessing_1.adoc[leveloffset=+1]

=== Request and Response classes

include::requestProcessing/requestProcessing_2.adoc[leveloffset=+1]

=== The “director” of request processing - RequestCycle

include::requestProcessing/requestProcessing_3.adoc[leveloffset=+1]

=== Session Class

include::requestProcessing/requestProcessing_4.adoc[leveloffset=+1]

=== Exception handling

include::requestProcessing/requestProcessing_5.adoc[leveloffset=+1]

=== Summary

include::requestProcessing/requestProcessing_6.adoc[leveloffset=+1]

== Wicket Links and URL generation

include::urls.adoc[]

=== PageParameters

include::urls/urls_1.adoc[leveloffset=+1]

=== Bookmarkable links

include::urls/urls_2.adoc[leveloffset=+1]

=== Automatically creating bookmarkable links with tag wicket:link

include::urls/urls_3.adoc[leveloffset=+1]

=== External links

include::urls/urls_4.adoc[leveloffset=+1]

=== Stateless links

include::urls/urls_5.adoc[leveloffset=+1]

=== Generating structured and clear URLs

include::urls/urls_6.adoc[leveloffset=+1]

=== Summary

include::urls/urls_7.adoc[leveloffset=+1]

== Wicket models and forms

include::modelsforms.adoc[]

=== What is a model?

include::modelsforms/modelsforms_1.adoc[leveloffset=+1]

=== IModel and Lambda

include::modelsforms/modelsforms_2.adoc[leveloffset=+1]

=== Models and JavaBeans

include::modelsforms/modelsforms_3.adoc[leveloffset=+1]

=== Wicket forms

include::modelsforms/modelsforms_4.adoc[leveloffset=+1]

=== Component DropDownChoice

include::modelsforms/modelsforms_5.adoc[leveloffset=+1]

=== Model chaining

include::modelsforms/modelsforms_6.adoc[leveloffset=+1]

=== Detachable models

include::modelsforms/modelsforms_7.adoc[leveloffset=+1]

=== Using more than one model in a component

include::modelsforms/modelsforms_8.adoc[leveloffset=+1]

=== Use models!

include::modelsforms/modelsforms_9.adoc[leveloffset=+1]

=== Summary

include::modelsforms/modelsforms_10.adoc[leveloffset=+1]

== Wicket forms in detail

include::forms2.adoc[]

=== Default form processing

include::forms2/forms2_1.adoc[leveloffset=+1]

=== Form validation and feedback messages

include::forms2/forms2_2.adoc[leveloffset=+1]

=== Input value conversion

include::forms2/forms2_3.adoc[leveloffset=+1]

=== Validation with JSR 303

include::forms2/forms2_4.adoc[leveloffset=+1]

=== Submit form with an IFormSubmittingComponent

include::forms2/forms2_5.adoc[leveloffset=+1]

=== Nested forms

include::forms2/forms2_6.adoc[leveloffset=+1]

=== Multi-line text input

include::forms2/forms2_7.adoc[leveloffset=+1]

=== File upload

include::forms2/forms2_8.adoc[leveloffset=+1]

=== Creating complex form components with FormComponentPanel

include::forms2/forms2_9.adoc[leveloffset=+1]

=== Stateless form

include::forms2/forms2_10.adoc[leveloffset=+1]

=== Working with radio buttons and checkboxes

include::forms2/forms2_11.adoc[leveloffset=+1]

=== Selecting multiple values with ListMultipleChoices and Palette

include::forms2/forms2_12.adoc[leveloffset=+1]

=== Summary

include::forms2/forms2_13.adoc[leveloffset=+1]

== Displaying multiple items with repeaters

include::repeaters.adoc[]

=== The RepeatingView Component

include::repeaters/repeaters_1.adoc[leveloffset=+1]

=== The ListView Component

include::repeaters/repeaters_2.adoc[leveloffset=+1]

=== The RefreshingView Component

include::repeaters/repeaters_3.adoc[leveloffset=+1]

=== Pageable repeaters

include::repeaters/repeaters_4.adoc[leveloffset=+1]

=== Summary

include::repeaters/repeaters_5.adoc[leveloffset=+1]

== Component queueing

include::componentQueueing.adoc[]

=== Markup hierarchy and code

include::componentQueueing/componentQueueing_1.adoc[leveloffset=+1]

=== Improved auto components

include::componentQueueing/componentQueueing_2.adoc[leveloffset=+1]

=== When are components dequeued?

include::componentQueueing/componentQueueing_3.adoc[leveloffset=+1]

=== Restrictions of queueing

include::componentQueueing/componentQueueing_4.adoc[leveloffset=+1]

=== Summary

include::componentQueueing/componentQueueing_5.adoc[leveloffset=+1]

== Internationalization with Wicket

include::i18n.adoc[]

=== Localization

include::i18n/i18n_1.adoc[leveloffset=+1]

=== Localization in Wicket

include::i18n/i18n_2.adoc[leveloffset=+1]

=== Bundles lookup algorithm

include::i18n/i18n_3.adoc[leveloffset=+1]

=== Localization of component's choices

include::i18n/i18n_4.adoc[leveloffset=+1]

=== Internationalization and Models

include::i18n/i18n_5.adoc[leveloffset=+1]

=== Summary

include::i18n/i18n_6.adoc[leveloffset=+1]

== Resource management with Wicket

include::resources.adoc[]

=== Static vs dynamic resources

include::resources/resources_1.adoc[leveloffset=+1]

=== Resource references

include::resources/resources_2.adoc[leveloffset=+1]

=== Package resources

include::resources/resources_3.adoc[leveloffset=+1]

=== Adding resources to page header section

include::resources/resources_4.adoc[leveloffset=+1]

=== Context-relative resources

include::resources/resources_5.adoc[leveloffset=+1]

=== Resource dependencies

include::resources/resources_6.adoc[leveloffset=+1]

=== Aggregate multiple resources with resource bundles

include::resources/resources_7.adoc[leveloffset=+1]

=== Put JavaScript inside page body

include::resources/resources_8.adoc[leveloffset=+1]

=== Header contributors positioning

include::resources/resources_9.adoc[leveloffset=+1]

=== Custom resources

include::resources/resources_10.adoc[leveloffset=+1]

=== Mounting resources

include::resources/resources_11.adoc[leveloffset=+1]

=== Lambda support

include::resources/resources_12.adoc[leveloffset=+1]

=== Shared resources

include::resources/resources_13.adoc[leveloffset=+1]

=== Customizing resource loading

include::resources/resources_14.adoc[leveloffset=+1]

=== CssHeaderItem and JavaScriptHeaderItem compression

include::resources/resources_15.adoc[leveloffset=+1]

=== NIO resources

include::resources/resources_16.adoc[leveloffset=+1]

=== Resources derived through models

include::resources/resources_17.adoc[leveloffset=+1]

=== Summary

include::resources/resources_18.adoc[leveloffset=+1]

== An example of integration with JavaScript

include::jsintegration.adoc[]

=== What we want to do...

include::jsintegration/jsintegration_1.adoc[leveloffset=+1]

=== ...and how we will do it

include::jsintegration/jsintegration_2.adoc[leveloffset=+1]

=== Summary

include::jsintegration/jsintegration_3.adoc[leveloffset=+1]

== Wicket advanced topics

include::advanced.adoc[]

=== Enriching components with behaviors

include::advanced/advanced_1.adoc[leveloffset=+1]

=== Generating callback URLs with IRequestListener

include::advanced/advanced_2.adoc[leveloffset=+1]

=== Wicket events infrastructure

include::advanced/advanced_3.adoc[leveloffset=+1]

=== Initializers

include::advanced/advanced_4.adoc[leveloffset=+1]

=== Using JMX with Wicket

include::advanced/advanced_5.adoc[leveloffset=+1]

=== Generating HTML markup from code

include::advanced/advanced_6.adoc[leveloffset=+1]

=== Summary

include::advanced/advanced_7.adoc[leveloffset=+1]

== Working with AJAX

include::ajax.adoc[]

=== How to use AJAX components and behaviors

include::ajax/ajax_1.adoc[leveloffset=+1]

=== Build-in AJAX components

include::ajax/ajax_2.adoc[leveloffset=+1]

=== Built-in AJAX behaviors

include::ajax/ajax_3.adoc[leveloffset=+1]

=== Using an activity indicator

include::ajax/ajax_4.adoc[leveloffset=+1]

=== AJAX request attributes and call listeners

include::ajax/ajax_5.adoc[leveloffset=+1]

=== Creating custom AJAX call listener

include::ajax/ajax_6.adoc[leveloffset=+1]

=== Stateless AJAX components/behaviors

include::ajax/ajax_7.adoc[leveloffset=+1]

=== Lambda support for components

include::ajax/ajax_8.adoc[leveloffset=+1]

=== Lambda support for behaviors

include::ajax/ajax_9.adoc[leveloffset=+1]

=== Summary

include::ajax/ajax_10.adoc[leveloffset=+1]

== Integration with enterprise containers

include::jee.adoc[]

=== Integrating Wicket with EJB

include::jee/jee_1.adoc[leveloffset=+1]

=== Integrating Wicket with Spring

include::jee/jee_2.adoc[leveloffset=+1]

=== JSR-330 annotations

include::jee/jee_3.adoc[leveloffset=+1]

=== Summary

include::jee/jee_4.adoc[leveloffset=+1]

== Native WebSockets

include::nativewebsockets.adoc[]

=== How does it work ?

include::nativewebsockets/nativewebsockets_1.adoc[leveloffset=+1]

=== How to use

include::nativewebsockets/nativewebsockets_2.adoc[leveloffset=+1]

=== Client-side APIs

include::nativewebsockets/nativewebsockets_3.adoc[leveloffset=+1]

=== Testing

include::nativewebsockets/nativewebsockets_4.adoc[leveloffset=+1]

=== FAQ

include::nativewebsockets/nativewebsockets_5.adoc[leveloffset=+1]

== Security with Wicket

include::security.adoc[]

=== Authentication

include::security/security_1.adoc[leveloffset=+1]

=== Authorizations

include::security/security_2.adoc[leveloffset=+1]

=== Using HTTPS protocol

include::security/security_3.adoc[leveloffset=+1]

=== URLs encryption in detail

include::security/security_4.adoc[leveloffset=+1]

=== CSRF protection

include::security/security_4_1.adoc[leveloffset=+1]

=== Package Resource Guard

include::security/security_5.adoc[leveloffset=+1]

=== External Security Checks

include::security/security_6.adoc[leveloffset=+1]

=== Summary

include::security/security_7.adoc[leveloffset=+1]

== Test Driven Development with Wicket

include::testing.adoc[]

=== Utility class WicketTester

include::testing/testing_1.adoc[leveloffset=+1]

=== Testing Wicket forms

include::testing/testing_2.adoc[leveloffset=+1]

=== Testing markup with TagTester

include::testing/testing_3.adoc[leveloffset=+1]

=== Summary

include::testing/testing_4.adoc[leveloffset=+1]

== Test Driven Development with Wicket and Spring

include::testingspring.adoc[]

=== Configuration of the runtime environment

include::testingspring/testingspring_1.adoc[leveloffset=+1]

=== Configuration of the JUnit based integration test environment

include::testingspring/testingspring_2.adoc[leveloffset=+1]

=== Summary

include::testingspring/testingspring_3.adoc[leveloffset=+1]

== Wicket Best Practices

include::bestpractices.adoc[]

=== Encapsulate components correctly

include::bestpractices/bestpractices_1.adoc[leveloffset=+1]

=== Put models and page data in fields

include::bestpractices/bestpractices_2.adoc[leveloffset=+1]

=== Correct naming for Wicket IDs

include::bestpractices/bestpractices_3.adoc[leveloffset=+1]

=== Avoid changes at the component tree

include::bestpractices/bestpractices_4.adoc[leveloffset=+1]

=== Implement visibilities of components correctly

include::bestpractices/bestpractices_5.adoc[leveloffset=+1]

=== Always use models

include::bestpractices/bestpractices_6.adoc[leveloffset=+1]

=== Do not unwrap models within the constructor hierarchy

include::bestpractices/bestpractices_7.adoc[leveloffset=+1]

=== Pass models extended components

include::bestpractices/bestpractices_8.adoc[leveloffset=+1]

=== Validators must not change any data or models

include::bestpractices/bestpractices_9.adoc[leveloffset=+1]

=== Do not pass components to constructors

include::bestpractices/bestpractices_10.adoc[leveloffset=+1]

=== Use the Wicket session only for global data

include::bestpractices/bestpractices_11.adoc[leveloffset=+1]

=== Do not use factories for components

include::bestpractices/bestpractices_12.adoc[leveloffset=+1]

=== Every page and component must be tested

include::bestpractices/bestpractices_13.adoc[leveloffset=+1]

=== Avoid interactions with other servlet filters

include::bestpractices/bestpractices_14.adoc[leveloffset=+1]

=== Cut small classes and methods

include::bestpractices/bestpractices_15.adoc[leveloffset=+1]

=== The argument "Bad documentation"

include::bestpractices/bestpractices_16.adoc[leveloffset=+1]

=== Summary

include::bestpractices/bestpractices_17.adoc[leveloffset=+1]

== Wicket Internals

include::internals.adoc[]

=== Page storing

include::internals/pagestoring.adoc[leveloffset=+1]

=== Markup parsing and Autocomponents

include::internals/autocomponents.adoc[leveloffset=+1]

== Wicket HTTP/2 Support (Experimental)

include::http2push.adoc[]

=== Example Usage

include::http2push/http2push_1.adoc[leveloffset=+3]

=== Create server specific http/2 push support

include::http2push/http2push_2.adoc[leveloffset=+3]

== Wicket Metrics Monitoring (Experimental)

include::monitoring.adoc[]

=== Example setup

include::monitoring/monitoring_1.adoc[leveloffset=+1]

=== Visualization with Graphite

include::monitoring/monitoring_2.adoc[leveloffset=+1]

=== Measured data

include::monitoring/monitoring_3.adoc[leveloffset=+1]

=== Write own measurements

include::monitoring/monitoring_4.adoc[leveloffset=+1]

[appendix]
== Working with Maven

include::maven.adoc[]

=== Switching Wicket to DEPLOYMENT mode

include::maven/maven_1.adoc[leveloffset=+1]

=== Creating a Wicket project from scratch and importing it into our favourite IDE

include::maven/maven_2.adoc[leveloffset=+1]

[appendix]
== Project WicketStuff

include::wicketstuff.adoc[]

=== What is project WicketStuff

include::wicketstuff/wicketstuff_1.adoc[leveloffset=+1]

=== Module tinymce

include::wicketstuff/wicketstuff_2.adoc[leveloffset=+1]

=== Module wicketstuff-gmap3

include::wicketstuff/wicketstuff_3.adoc[leveloffset=+1]

=== Module wicketstuff-googlecharts

include::wicketstuff/wicketstuff_4.adoc[leveloffset=+1]

=== Module wicketstuff-inmethod-grid

include::wicketstuff/wicketstuff_5.adoc[leveloffset=+1]

=== Module wicketstuff-rest-annotations

include::wicketstuff/wicketstuff_6.adoc[leveloffset=+1]

=== Module wicketstuff-lambda-components

include::wicketstuff/wicketstuff_7.adoc[leveloffset=+1]

[appendix]
== Lost In Redirection With Apache Wicket

include::redirects.adoc[]

[appendix]
== Contributing to this guide

include::contributing.adoc[]

