You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by da...@apache.org on 2016/11/23 22:44:39 UTC
[06/22] wicket git commit: Moved wicket-7.x docs to asciidoctor
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc
new file mode 100644
index 0000000..01b57b5
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc
@@ -0,0 +1,34 @@
+
+By adding a _(Base)WebSocketBehavior_ to your component(s) Wicket will contribute _wicket-websocket-jquery.js_ library which provides some helper functions to write your client side code. There is a default websocket connection per Wicket Page opened for you which you can use like:
+[source,java]
+----
+Wicket.WebSocket.send('{msg: "my message"}').
+----
+
+To close the default connection:
+[source,java]
+----
+Wicket.WebSocket.close()
+----
+
+Wicket.WebSocket is a simple wrapper around the native window.WebSocket API which is used to intercept the calls and to fire special JavaScript events (Wicket.Event PubSub).
+Once a page that contributes _(Base)WebSocketBehavior_ is rendered the client may react on messages pushed by the server by subscribing to the _'/websocket/message'_ event:
+
+[source,java]
+----
+Wicket.Event.subscribe("/websocket/message", function(jqEvent, message) {
+ var data = JSON.parse(message);
+ processData(data); // does something with the pushed message
+});
+----
+
+Here is a table of all events that the application can subscribe to:
+|===
+|Event name | Arguments | Description
+|/websocket/open | jqEvent | A WebSocket connection has been just opened
+|/websocket/message | jqEvent, message | A message has been received from the server
+|/websocket/closed | jqEvent | A WebSocket connection has been closed
+|/websocket/error | jqEvent | An error occurred in the communication. The connection will be closed
+|===
+
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc
new file mode 100644
index 0000000..db869d5
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc
@@ -0,0 +1,4 @@
+
+The module provides _org.apache.wicket.protocol.ws.util.tester.WebSocketTester_ which gives you the possibility to emulate sending and receiving messages without the need to run in a real web container, as WicketTester does this for HTTP requests.
+Check https://github.com/apache/wicket/blob/master/wicket-native-websocket/wicket-native-websocket-core/src/test/java/org/apache/wicket/protocol/ws/util/tester/WebSocketTesterBehaviorTest.java?source=c[WebSocketTesterBehaviorTest]
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc
new file mode 100644
index 0000000..73611d3
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc
@@ -0,0 +1,3 @@
+
+Wicket-Atmosphere experimental module provides integration with https://github.com/Atmosphere/atmosphere[Atmosphere]
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc
new file mode 100644
index 0000000..5a1396a
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc
@@ -0,0 +1,3 @@
+
+1. Request and session scoped beans do not work.
+The Web Socket communication is not processed by Servlet Filters and Listeners and thus the Dependency Injection libraries have no chance to export the request and session bean proxies.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/redirects.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/redirects.adoc b/wicket-user-guide/src/main/asciidoc/redirects.adoc
new file mode 100644
index 0000000..4691234
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/redirects.adoc
@@ -0,0 +1,79 @@
+
+Quite a few teams have already got stuck into the following problem when working with wicket forms in a clustered environment while having 2 (or more) tomcat server with enabled session replication running.
+
+In case of invalid data being submitted with a form instance for example, it seemed like according error messages wouldn\u2019t be presented when the same form page gets displayed again. Sometimes! And sometimes they would! One of those nightmares of rather deterministic programmer\u2019s life. This so called Lost In Redirection problem, even if it looks like a wicket bug at first, is rather a result of a default setting in wicket regarding the processing of form submissions in general. In order to prevent another wide known problem of double form submissions, Wicket uses a so called REDIRECT_TO_BUFFER strategy for dealing with rendering a page after web form\u2019s processing (_see RequestCycleSettings1.RenderStrategy).
+
+What does the default RenderStrategy actually do?
+
+Both logical parts of a single HTTP request, an action and a render part get processed within the same request, but instead of streaming the render result to the browser directly, the result is cached on the server first.
+
+image::../img/lost-in-redirection-mockup.png[]
+
+Wicket will create an according BufferedHttpServletResponse instance that will be used to cache the resulting HttpServletResponse within the WebApplication.
+
+image::../img/lost-in-redirection-mockup2.png[]
+
+After the buffered response is cached the HTTP status code of 302 get\u2019s provided back to the browser resulting in an additional GET request to the redirect URL (which Wicket sets to the URL of the Form itself). There is a special handling code for this case in the WicketFilter instance that then looks up a Map of buffered responses within the WebApplication accordingly. If an appropriate already cached response for the current request is found, it get\u2019s streamed back to the browser immediately. No additional form processing happens now. The following is a code snippet taken from WicketFilter:
+
+[source,java]
+----
+// Are we using REDIRECT_TO_BUFFER?
+if (webApplication.getRequestCycleSettings().getRenderStrategy() == RequestCycleSettings.REDIRECT_TO_BUFFER)
+{
+ // Try to see if there is a redirect stored
+ // try get an existing session
+ ISessionStore sessionStore = webApplication.getSessionStore();
+ String sessionId = sessionStore.getSessionId(request, false);
+ if (sessionId != null)
+ {
+ BufferedHttpServletResponse bufferedResponse = null;
+ String queryString = servletRequest.getQueryString();
+ // look for buffered response
+ if (!Strings.isEmpty(queryString))
+ {
+ bufferedResponse = webApplication.popBufferedResponse(sessionId,
+ queryString);
+ }
+ else
+ {
+ bufferedResponse = webApplication.popBufferedResponse(sessionId,
+ relativePath);
+ }
+ // if a buffered response was found
+ if (bufferedResponse != null)
+ {
+ bufferedResponse.writeTo(servletResponse);
+ // redirect responses are ignored for the request
+ // logger...
+ return true;
+ }
+ }
+}
+----
+
+So what happens in case you have 2 server running your application with session replication and load balancing turned on while using the default RenderStrategy described above?
+
+Since a Map of buffered responses is cached within a WebApplication instance that does not get replicated between the nodes obviously, a redirect request that is suppose to pick up the previously cached response (having possibly form violation messages inside) potentially get\u2019s directed to the second node in your cluster by the load balancer. The second node does not have any responses already prepared and cached for your user. The node therefore handles the request as a completely new request for the same form page and displays a fresh new form page instance to the user accordingly.
+
+image::../img/lost-in-redirection-mockup3.png[]
+
+Unfortunately, there is currently no ideal solution to the problem described above. The default RenderStrategy used by Apache Wicket simply does not work well in a fully clustered environment with load balancing and session replication turned on. One possibility is to change the default render strategy for your application to a so called ONE_PASS_RENDER RenderStrategy which is the more suitable option to use when you want to do sophisticated (non-sticky session) clustering. This is easily done in the init method of your own subclass of Wicket\u2019s WebApplication :
+
+[source,java]
+----
+@Override
+protected void init() {
+ getRequestCycleSettings().setRenderStrategy(
+ RequestCycleSettings.ONE_PASS_RENDER);
+}
+----
+
+ONE_PASS_RENDER RenderStrategy does not solve the double submit problem though! So this way you\u2019d only be trading one problem for another one actually.
+
+You could of course turn on the session stickiness between your load balancer (apache server) and your tomcat server additionally to the session replication which would be the preferred solution in my opinion.
+
+image::../img/lost-in-redirection-mockup4.png[]
+
+Session replication would still provide you with failover in case one of the tomcat server dies for whatever reason and sticky sessions would ensure that the Lost In Redirection problem does not occur any more.
+
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters.adoc b/wicket-user-guide/src/main/asciidoc/repeaters.adoc
new file mode 100644
index 0000000..06b593b
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters.adoc
@@ -0,0 +1,24 @@
+
+A common task for web applications is to display a set of items. The most typical scenario where we need such kind of visualization is when we have to display some kind of search result. With the old template-based technologies (like JSP) we used to accomplish this task using classic for or while loops:
+
+[source,html]
+----
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Insert title here</title>
+</head>
+<body>
+ <%
+ for(int i = 12; i<=32; i++) {
+ %>
+ <div>Hello! I'm index n�<%= %></div>
+ <%
+ }
+ %>
+</body>
+----
+
+To ease this task Wicket provides a number of special-purpose components called repeaters which are designed to use their related markup to display the items of a given set in a more natural and less chaotic way.
+
+In this chapter we will see some of the built-in repeaters that come with Wicket.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc
new file mode 100644
index 0000000..e367b87
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc
@@ -0,0 +1,35 @@
+
+
+
+Component _org.apache.wicket.markup.repeater.RepeatingView_ is a container which renders its children components using the tag it is bound to. It can contain an arbitrary number of children elements and we can obtain a new valid id for a new child calling its method newChildId(). This component is particularly suited when we have to repeat a simple markup fragment, for example when we want to display some items as a HTML list:
+
+*HTML:*
+[source,html]
+----
+<ul>
+ <li wicket:id="listItems"></li>
+</ul>
+----
+
+*Java Code:*
+[source,java]
+----
+RepeatingView listItems = new RepeatingView("listItems");
+
+listItems.add(new Label(listItems.newChildId(), "green"));
+listItems.add(new Label(listItems.newChildId(), "blue"));
+listItems.add(new Label(listItems.newChildId(), "red"));
+----
+
+*Generated markup:*
+[source,html]
+----
+<ul>
+ <li>green</li>
+ <li>blue</li>
+ <li>red</li>
+</ul>
+----
+
+As we can see in this example, each child component has been rendered using the parent markup as if it was its own.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
new file mode 100644
index 0000000..4108d41
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
@@ -0,0 +1,52 @@
+
+
+
+As its name suggests, component _org.apache.wicket.markup.html.list.ListView_ is designed to display a given list of objects which can be provided as a standard Java List or as a model containing the concrete List. ListView iterates over the list and creates a child component of type _org.apache.wicket.markup.html.list.ListItem_ for every encountered item.
+
+Unlike RepeatingView this component is intended to be used with complex markup fragments containing nested components.
+
+To generate its children, ListView calls its abstract method populateItem(ListItem<T> item) for each item in the list, so we must provide an implementation of this method to tell the component how to create its children components. In the following example we use a ListView to display a list of Person objects:
+
+*HTML:*
+[source,html]
+----
+...
+ <body>
+ <div id="bd" style="display: table;">
+ <div wicket:id="persons" style="display: table-row;">
+ <div style="display: table-cell;"><b>Full name: </b></div>
+ <div wicket:id="fullName" style="display: table-cell;"></div>
+ </div>
+ </div>
+ </body>
+...
+----
+
+*Java Code (Page Constructor):*
+[source,java]
+----
+public HomePage(final PageParameters parameters) {
+ List<Person> persons = Arrays.asList(new Person("John", "Smith"),
+ new Person("Dan", "Wong"));
+
+ add(new ListView<Person>("persons", persons) {
+ @Override
+ protected void populateItem(ListItem<Person> item) {
+ item.add(new Label("fullName", new PropertyModel(item.getModel(), "fullName")));
+ }
+ });
+}
+----
+
+*Screenshot of generated page:*
+
+image::../img/simple-listview-screenshot.png[]
+
+In this example we have displayed the full name of two Person's instances. The most interesting part of the code is the implementation of method populateItem where parameter item is the current child component created by ListView and its model contains the corresponding element of the list. Please note that inside populateItem we must add nested components to the _item_ object and not directly to the _ListView_.
+
+=== ListView and Form
+
+By default _ListView_ replaces its children components with new instances every time is rendered. Unfortunately this behavior is a problem if _ListView_ is inside a form and it contains form components. The problem is caused by the fact that children components are replaced by new ones before form is rendered, hence they can't keep their input value if validation fails and, furthermore, their feedback messages can not be displayed.
+
+To avoid this kind of problem we can force _ListView_ to reuse its children components using its method setReuseItems and passing true as parameter. If for any reason we need to refresh children components after we have invoked setReuseItems(true), we can use MarkupContainer's method _removeAll()_ to force _ListView_ to rebuild them.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc
new file mode 100644
index 0000000..60bc8d7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc
@@ -0,0 +1,54 @@
+
+
+
+Component _org.apache.wicket.markup.repeater.RefreshingView_ is a subclass of RepeatingView that comes with a customizable rendering strategy for its children components.
+
+RefreshingView defines abstract methods populateItem(Item) and getItemModels(). The first method is similar to the namesake method seen for ListView, but it takes in input an instance of class _org.apache.wicket.markup.repeater.Item_ which is a subclass of _ListItem_. RefreshingView is designed to display a collection of models containing the actual items. An iterator over these models is returned by the other abstract method getItemModels.
+
+The following code is a version of the previous example that uses _RefreshingView_ in place of _ListView_:
+
+*HTML:*
+[source,html]
+----
+...
+ <body>
+ <div id="bd" style="display: table;">
+ <div wicket:id="persons" style="display: table-row;">
+ <div style="display: table-cell;"><b>Full name: </b></div>
+ <div wicket:id="fullName" style="display: table-cell;"></div>
+ </div>
+ </div>
+ </body>
+...
+----
+
+*Java Code (Page Constructor):*
+[source,java]
+----
+public HomePage(final PageParameters parameters) {
+ //define the list of models to use
+ final List<IModel<Person>> persons = new ArrayList<IModel<Person>>();
+
+ persons.add(Model.of(new Person("John", "Smith")));
+ persons.add(Model.of(new Person("Dan", "Wong")));
+
+ add(new RefreshingView<Person>("persons") {
+ @Override
+ protected void populateItem(Item<Person> item) {
+ item.add(new Label("fullName", new PropertyModel(item.getModel(), "fullName")));
+ }
+
+ @Override
+ protected Iterator<IModel<Person>> getItemModels() {
+ return persons.iterator();
+ }
+ });
+}
+----
+
+=== Item reuse strategy
+
+Similar to _ListView_, the default behavior of the _RefreshingView_ is to replace its children with new instances every time is rendered. The strategy that decides if and how children components must be refreshed is returned by method _getItemReuseStrategy_. This strategy is an implementation of interface IItemReuseStrategy. The default implementation used by _RefreshingView_ is class _DefaultItemReuseStrategy_ but Wicket provides also strategy _ReuseIfModelsEqualStrategy_ which reuses an item if its model has been returned by the iterator obtained with method _getItemModels_.
+
+To set a custom strategy we must use method _setItemReuseStrategy_.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc
new file mode 100644
index 0000000..58d8358
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc
@@ -0,0 +1,117 @@
+
+
+
+Wicket offers a number of components that should be used when we have to display a big number of items (for example the results of a select SQL query).
+
+All these components implement interface _org.apache.wicket.markup.html.navigation.paging.IPageable_ and use interface _IDataProvider_ (placed in package _org.apache.wicket.markup.repeater.data_) as data source. This interface is designed to support data paging. We will see an example of data paging later in <<repeaters.adoc#_pageable_repeaters,paragraph 13.4.2>>.
+
+The methods defined by IDataProvider are the following:
+* iterator(long first, long count): returns an iterator over a subset of the entire dataset. The subset starts from the item at position first and includes all the next count items (i.e. it's the closed interval <<_first,first+count>>
+).
+* size(): gets the size of the entire dataset.
+* model(T object): this method is used to wrap an item returned by the iterator with a model. This can be necessary if, for example, we need to wrap items with a detachable model to prevent them from being serialized.
+
+Wicket already provides implementations of IDataProvider to work with a List as data source (ListDataProvider) and to support data sorting (SortableDataProvider).
+
+=== Component DataView
+
+Class _org.apache.wicket.markup.repeater.data.DataView_ is the simplest pageable repeater shipped with Wicket. DataView comes with abstract method populateItem(Item) that must be implemented to configure children components. In the following example we use a DataView to display a list of Person objects in a HTML table:
+
+*HTML:*
+[source,html]
+----
+<table>
+ <tr>
+ <th>Name</th><th>Surename</th><th>Address</th><th>Email</th>
+ </tr>
+ <tr wicket:id="rows">
+ <td wicket:id="dataRow"></td>
+ </tr>
+</table>
+----
+
+*Java Code:*
+[source,java]
+----
+//method loadPersons is defined elsewhere
+List<Person> persons = loadPersons();
+ListDataProvider<Person> listDataProvider = new ListDataProvider<Person>(persons);
+
+DataView<Person> dataView = new DataView<Person>("rows", listDataProvider) {
+
+ @Override
+ protected void populateItem(Item<Person> item) {
+ Person person = item.getModelObject();
+ RepeatingView repeatingView = new RepeatingView("dataRow");
+
+ repeatingView.add(new Label(repeatingView.newChildId(), person.getName()));
+ repeatingView.add(new Label(repeatingView.newChildId(), person.getSurename()));
+ repeatingView.add(new Label(repeatingView.newChildId(), person.getAddress()));
+ repeatingView.add(new Label(repeatingView.newChildId(), person.getEmail()));
+ item.add(repeatingView);
+ }
+};
+add(dataView);
+----
+
+Please note that in the code above we have used also a RepeatingView component to populate the rows of the table.
+
+In the next paragraph we will see a similar example that adds support for data paging.
+
+=== Data paging
+
+To enable data paging on a pageable repeater, we must first set the number of items to display per page with method setItemsPerPage(long items). Then, we must attach the repeater to panel PagingNavigator (placed in package _org.apache.wicket.markup.html.navigation.paging_) which is responsible for rendering a navigation bar containing the links illustrated in the following picture:
+
+image::../img/paging-navigator.png[]
+
+Project PageDataViewExample mixes a DataView component with a PagingNavigator to display the list of all countries of the world sorted by alphabetical order. Here is the initialization code of the project home page:
+
+*HTML:*
+[source,html]
+----
+<table>
+ <tr>
+ <th>ISO 3166-1</th><th>Name</th><th>Long name</th><th>Capital</th><th>Population</th>
+ </tr>
+ <tr wicket:id="rows">
+ <td wicket:id="dataRow"></td>
+ </tr>
+</table>
+----
+
+*Java Code:*
+[source,java]
+----
+public HomePage(final PageParameters parameters) {
+ super(parameters);
+ //method loadCountriesFromCsv is defined elsewhere in the class.
+ //It reads countries data from a csv file and returns each row as an array of Strings.
+ List<String[]> countries = loadCountriesFromCsv();
+ ListDataProvider<String[]> listDataProvider = new ListDataProvider<String[]>(countries);
+
+ DataView<String[]> dataView = new DataView<String[]>("rows", listDataProvider) {
+ @Override
+ protected void populateItem(Item<String[]> item) {
+ String[] countriesArr = item.getModelObject();
+ RepeatingView repeatingView = new RepeatingView("dataRow");
+
+ for (int i = 0; i < countriesArr.length; i++){
+ repeatingView.add(new Label(repeatingView.newChildId(), countriesArr[i]));
+ }
+ item.add(repeatingView);
+ }
+ };
+
+ dataView.setItemsPerPage(15);
+
+ add(dataView);
+ add(new PagingNavigator("pagingNavigator", dataView));
+}
+----
+
+The data of a single country (ISO code, name, long name, capital and population) are handled with an array of strings. The usage of PagingNavigator is quite straightforward as we need to simply pass the pageable repeater to its constructor.
+
+To explore the other pageable repeaters shipped with Wicket you can visit the page at {externalink:wicket.examples.url_repeater} where you can find live examples of these components.
+
+NOTE: Wicket provides also component PageableListView which is a sublcass of ListView that implements interface IPageable, hence it can be considered a pageable repeater even if it doesn't use interface IDataProvider as data source.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc
new file mode 100644
index 0000000..e15f04e
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc
@@ -0,0 +1,8 @@
+
+
+
+In this chapter we have explored the built-in set of components called repeaters which are designed to repeat their own markup in output to display a set of items. We have started with component _RepeatingView_ which can be used to repeat a simple markup fragment.
+
+Then, we have seen components _ListView_ and _RefreshingView_ which should be used when the markup to repeat contains nested components to populate.
+
+Finally, we have discussed those repeaters that support data paging and that are called pageable repeaters. We ended the chapter looking at an example where a pageable repeater is used with panel PagingNavigator to make its dataset navigable by the user.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc
new file mode 100644
index 0000000..64aaaab
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc
@@ -0,0 +1,5 @@
+
+Although Wicket was born to provide a reliable and comprehensive object oriented abstraction for web development, sometimes we might need to work directly with \u201craw\u201d web entities such as user session, web request, query parameters, and so on. For example this is necessary if we want to store an arbitrary parameter in the user session.
+
+Wicket provides wrapper classes that allow us to easily access to web entities without the burden of using the low-level APIs of Java Servlet Specification. However it will always be possible to access standard classes (like HttpSession, HttpServletRequest, etc...) that lay under our Wicket application.
+This chapter will introduce these wrapper classes and it will explain how Wicket uses them to handle the web requests initiated by the user's browser.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc
new file mode 100644
index 0000000..6cbf9da
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc
@@ -0,0 +1,6 @@
+
+
+
+Beside configuring and initializing our application, the Application class is responsible for creating the internal entities used by Wicket to process a request. These entities are instances of the following classes: RequestCycle, Request, Response and Session.
+
+The next paragraphs will illustrate each of these classes, explaining how they are involved into request processing.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc
new file mode 100644
index 0000000..24ec9e0
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc
@@ -0,0 +1,6 @@
+
+
+
+The _Request_ and _Response_ classes are located in package _org.apache.wicket.request_ and they provide an abstraction of the concrete request and response used by our web application.
+
+Both classes are declared as abstract but if our application class inherits from _WebApplication_ it will use their sub classes _ServletWebRequest_ and _ServletWebResponse_, both of them located inside the package _org.apache.wicket.protocol.http.servlet.ServletWebRequest_ and _ServletWebResponse_ wrap respectively a _HttpServletRequest_ and a _HttpServletResponse_ object. If we need to access to these low-level objects we can call _Request_'s method _getContainerRequest()_ and _Response_'s method _getContainerResponse()_.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc
new file mode 100644
index 0000000..1868ee7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc
@@ -0,0 +1,94 @@
+
+
+
+Class _org.apache.wicket.request.cycle.RequestCycle_ is the entity in charge of serving a web request. Our application class creates a new _RequestCycle_ on every request with its method _createRequestCycle(request, response)_.
+
+Method _createRequestCycle_ is declared as final, so we can't override it to return a custom subclass of _RequestCycle_. Instead, we must build a request cycle provider implementing interface _org.apache.wicket.IRequestCycleProvider_, and then we must tell our application class to use it via the _setRequestCycleProvider_ method.
+
+The current running request cycle can be retrieved at any time by calling its static method _RequestCycle.get()_. Strictly speaking this method returns the request cycle associated with the current (or local) thread, which is the thread that is serving the current request. A similar _get()_ method is also implemented in classes _org.apache.wicket.Application_ (as we have seen in <<helloWorld.adoc#_configuration_of_wicket_applications,paragraph 4.2.2>>) and _org.apache.wicket.Session_ in order to get the application and the session in use by the current thread.
+
+NOTE: The implementation of the get method takes advantage of the standard class _java.lang.ThreadLocal_. See its JavaDoc for an introduction to local-thread variables.
+
+Class _org.apache.wicket.Component_ provides the _getRequestCycle()_ method which is a convenience method that internally invokes _RequestCycle.get()_:
+
+[source,java]
+----
+public final RequestCycle getRequestCycle() {
+ return RequestCycle.get();
+}
+----
+
+=== RequestCycle and request processing
+
+NOTE: This paragraph will provide just the basic informations about what happens behind the scenes of request processing. When you work with Wicket it's unlikely to have a need for customizing this process, so we won't cover this topic in detail.
+
+In order to process a request, _RequestCycle_ delegates the task to another entity which implements interface _org.apache.wicket.request.IRequestHandler_. There are different implementations of this interface, each suited for a particular type of requested resource (a page to render, an AJAX request, an URL to an external page, etc.).
+
+To resolve the right handler for a given HTTP request, the _RequestCycle_ uses a set of objects implementing the _org.apache.wicket.request.IRequestMapper_ interface. The mapping interface defines the _getCompatibilityScore(Request request)_ method which returns a score indicating how compatible the request mapper is for the current request. _RequestCycle_ will choose the mapper with the highest score and it will call its _mapRequest(Request request)_ method to get the proper handler for the given request. Once _RequestCycle_ has resolved a request handler, it invokes its method _respond(IRequestCycle requestCycle)_ to start request processing.
+
+The following sequence diagram recaps how a request handler is resolved by the _RequestCycle_:
+
+image::../img/request-cycle-handler.png[]
+
+Developers can create additional implementations of IRequestMapper and add them to their application via the mount(IRequestMapper mapper) method of the WebApplication class. In paragraph 10.6 we will see how Wicket uses this method to add built-in mappers for mounted pages.
+
+=== Generating URL with the urlFor and mapUrlFor methods
+
+The RequestCycle is also responsible for generating the URL value (as CharSequence) for the following entities:
+
+* a page class, via the _urlFor(Class<C> pageClass, PageParameters parameters)_ method
+* an IRequestHandler via the _urlFor(IRequestHandler handler)_ method
+* a ResourceReference via the _urlFor(ResourceReference reference, PageParameters params)_ method (resource entities will be introduced in
+<<_resource_management_with_wicket,chapter 19>>).
+
+The overloaded _urlFor_ method from above also has a corresponding version that returns an instance of _org.apache.wicket.request.Url_ instead of a _CharSequence_. This version has the prefix 'map' in its name (i.e. it has _mapUrlFor_ as full name).
+
+=== Method setResponsePage
+
+The _RequestCycle_ class contains the implementation of the _setResponsePage_ method we use to redirect a user to a specific page (see <<helloWorld.adoc#_wicket_links,paragraph 4.4>>). The namesake method of class _org.apache.wicket.Component_ is just a convenience method that internally invokes the actual implementation on current request cycle:
+
+[source,java]
+----
+public final void setResponsePage(final Page page) {
+ getRequestCycle().setResponsePage(page);
+}
+----
+
+=== RequestCycle's hook methods and listeners
+
+The RequestCycle comes with some hook methods which can be overridden to perform custom actions when request handling reaches a specific stage. These methods are:
+* *onBeginRequest():* called when the RequestCycle is about to start handling the request.
+* *onEndRequest():* called when the RequestCycle has finished to handle the request
+* *onDetach():* called after the request handling has completed and the RequestCycle is about to be detached from its thread. The default implementation of this method invokes detach() on the current session (the Session class will be shortly discussed in paragraph 9.4).
+
+Methods onBeforeRequest and onEndRequest can be used if we need to execute custom actions before and after business code is executed, such as opening a Hibernate/JPA session and closing it when code has terminated.
+
+A more flexible way to interact with the request processing is to use the listener interface _org.apache.wicket.request.cycle.IRequestCycleListener_. In addition to the three methods already seen for RequestCycle, this interface offers further hooks into request processing:
+* *onBeginRequest(RequestCycle cycle):* (see the description above)
+* *onEndRequest(RequestCycle cycle):* (see the description above)
+* *onDetach(RequestCycle cycle):* (see the description above)
+* *onRequestHandlerResolved(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been resolved.
+* *onRequestHandlerScheduled(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been scheduled for execution.
+* *onRequestHandlerExecuted(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been executed.
+* *onException(RequestCycle cycle, Exception ex):* called when an exception has been thrown during request processing.
+* *onExceptionRequestHandlerResolved(RequestCycle rc, IRequestHandler rh, Exception ex):* called when an IRequestHandler has been resolved and will be used to handle an exception.
+* *onUrlMapped(RequestCycle cycle, IRequestHandler handler, Url url):* called when an URL has been generated for an IRequestHandler object.
+
+To use the request cycle listeners we must add them to our application which in turn will pass them to the new _RequestCycle_'s instances created with _createRequestCycle_ method:
+
+[source,java]
+----
+@Override
+public void init() {
+
+ super.init();
+
+ IRequestCycleListener myListener;
+ //listener initialization...
+ getRequestCycleListeners().add(myListener)
+}
+----
+
+The _getRequestCycleListeners_ method returns an instance of class _org.apache.wicket.request.cycle.RequestCycleListenerCollection_. This class is a sort of typed collection for _IRequestCycleListener_ and it also implements the http://en.wikipedia.org/wiki/Composite_pattern[Composite pattern] .
+
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc
new file mode 100644
index 0000000..3e30614
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc
@@ -0,0 +1,162 @@
+
+
+
+In Wicket we use class _org.apache.wicket.Session_ to handle session-relative informations such as client informations, session attributes, session-level cache (seen in paragraph 8.2), etc...
+
+In addition, we know from paragraph 8.1 that Wicket creates a user session to store versions of stateful pages. Similarly to what happens with RequestCycle, the new Session's instances are generated by the _Application_ class with the _newSession(Request request, Response response)_ method. This method is not declared as final, hence it can be overridden if we need to use a custom implementation of the Session class.
+
+By default if our custom application class is a subclass of WebApplication, method newSession will return an instance of class _org.apache.wicket.protocol.http.WebSession_. As we have mentioned talking about _RequestCycle_, also class Session provides a static _get()_ method which returns the session associated to the current thread.
+
+=== Session and listeners
+
+Similar to the _RequestCycle_, class _org.apache.wicket.Session_ also offers support for listener entities. With Session these entities must implement the callback interface _org.apache.wicket.ISessionListener_ which exposes only the _onCreated(Session session)_ method. As you might guess from its name, this method is called when a new session is created. Session listeners must be added to our application using a typed collection, just like we have done before with request cycle listeners:
+
+[source,java]
+----
+@Override
+public void init(){
+
+ super.init();
+
+ //listener initialization...
+ ISessionListener myListener;
+ //add a custom session listener
+ getSessionListeners().add(myListener)
+
+}
+----
+
+=== Handling session attributes
+
+The Session class handles session attributes in much the same way as the standard interface javax.servlet.http.HttpSession. The following methods are provided to create, read and remove session attributes:
+
+* *setAttribute(String name, Serializable value):* creates an attribute identified by the given name. If the session already contains an attribute with the same name, the new value will replace the existing one. The value must be a serializable object.
+* *getAttribute(String name):* returns the value of the attribute identified by the given name, or null if the name does not correspond to any attribute.
+* *removeAttribute(String name):* removes the attribute identified by the given name.
+
+By default class WebSession will use the underlying HTTP session to store attributes. Wicket will automatically add a prefix to the name of the attributes. This prefix is returned by the WebApplication's method getSessionAttributePrefix().
+
+=== Accessing to the HTTP session
+
+If for any reason we need to directly access to the underlying HttpSession object, we can retrieve it from the current request with the following code:
+
+[source,java]
+----
+HttpSession session = ((ServletWebRequest)RequestCycle.get()
+ .getRequest()).getContainerRequest().getSession();
+----
+
+Using the raw session object might be necessary if we have to set a session attribute with a particular name without the prefix added by Wicket. Let's say for example that we are working with Tomcat as web server. One of the administrative tools provided by Tomcat is a page listing all the active user sessions of a given web application:
+
+image::../img/tomcat-admin-sessions.png[]
+
+Tomcat allows us to set the values that will be displayed in columns \u201cGuessed locale\u201d and \u201cGuessed User name\u201d. One possible way to do this is to use session attributes named \u201cLocale\u201d and \u201cuserName\u201d but we can't create them via Wicket's Session class because they would not have exactly the name required by Tomcat. Instead, we must use the raw HttpSession and set our attributes on it:
+
+[source,java]
+----
+HttpSession session = ((ServletWebRequest)RequestCycle.get().
+ getRequest()).getContainerRequest().getSession();
+
+session.setAttribute("Locale", "ENGLISH");
+session.setAttribute("userName", "Mr BadGuy");
+----
+
+=== Temporary and permanent sessions
+
+Wicket doesn't need to store data into user session as long as the user visits only stateless pages. Nonetheless, even under these conditions, a temporary session object is created to process each request but it is discarded at the end of the current request. To know if the current session is temporary, we can use the isTemporary() method:
+
+[source,java]
+----
+Session.get().isTemporary();
+----
+
+If a session is not temporary (i.e. it is permanent), it's identified by an unique id which can be read calling the getId() method. This value will be null if the session is temporary.
+
+Although Wicket is able to automatically recognize when it needs to replace a temporary session with a permanent one, sometimes we may need to manually control this process to make our initially temporary session permanent.
+
+To illustrate this possible scenario let's consider project BindSessionExample where we have a stateless home page which sets a session attribute inside its constructor and then it redirects the user to another page which displays with a label the session attribute previously created. The code of the two pages is as follows:
+
+Home page:
+[source,java]
+----
+public class HomePage extends WebPage {
+ public HomePage(final PageParameters parameters) {
+ Session.get().setAttribute("username", "tommy");
+ Session.get().bind();
+
+ setResponsePage(DisplaySessionParameter.class);
+ }
+}
+----
+
+Target page:
+
+[source,java]
+----
+public class DisplaySessionParameter extends WebPage {
+
+ public DisplaySessionParameter() {
+ super();
+ add(new Label("username", (String) Session.get().getAttribute("username")));
+ }
+}
+----
+
+Again, we kept page logic very simple to not over-bloat the example with unnecessary code. In the snippet above we have also bolded Session's bind() method which converts temporary session into a permanent one. If the home page has not invoked this method, the session with its attribute would have been discarded at the end of the request and the page DisplaySessionParameter would have displayed an empty value in its label.
+
+=== Discarding session data
+
+Once a user has finished using our web application, she must be able to log out and clean any session data. To be sure that a permanent session will be discarded at the end of the current request, class Session provides the invalidate() method. If we want to immediately invalidate a given session without waiting for the current request to complete, we can invoke the invalidateNow() method.
+
+WARNING: Remember that invalidateNow() will immediately remove any instance of components (and pages) from the session, meaning that once we have called this method we won't be able to work with them for the rest of the request process.
+
+=== Storing arbitrary objects with metadata
+
+JavaServer Pages Specification1 defines 4 scopes in which a page can create and access a variable. These scopes are:
+
+* *request:* variables declared in this scope can be seen only by pages processing the same request. The lifespan of these variables is (at most) equal to the one of the related request. They are discarded when the full response has been generated or when the request is forwarded somewhere else.
+* *page:* variables declared in this scope can be seen only by the page that has created them.
+* *session:* variables in session scope can be created and accessed by every page used in the same session where they are defined.
+* *application:* this is the widest scope. Variables declared in this scope can be used by any page of a given web application.
+
+Although Wicket doesn't implement the JSP Specification (it is rather an alternative to it), it offers a feature called metadata which resembles scoped variables but is much more powerful. Metadata is quite similar to a Java Map in that it stores pairs of key-value objects where the key must be unique. In Wicket each of the following classes has its own metadata store: RequestCycle, Session, Application and Component.
+
+The key used for metadata is an instance of class _org.apache.wicket.MetaDataKey<T>_. To put an arbitrary object into metadata we must use the setMetaData method which takes two parameters as input: the key used to store the value and the value itself. If we are using metadata with classes Session or Component, data object must be serializable because Wicket serializes both session and component instances. This constraint is not applied to metadata of classes Application and RequestCycle which can contain a generic object. In any case, the type of data object must be compatible with the type parameter T specified by the key.
+
+To retrieve a previously inserted object we must use the _getMetaData(MetaDataKey<T> key)_ method. In the following example we set a _java.sql.Connection_ object in the application's metadata so it can be used by any page of the application:
+
+Application class code:
+[source,java]
+----
+public static MetaDataApp extends WebApplication{
+ //Do some stuff...
+ /**
+ * Metadata key definition
+ */
+ public static MetaDataKey<Connection> connectionKey = new MetaDataKey<Connection> (){};
+
+ /**
+ * Application's initialization
+ */
+ @Override
+ public void init(){
+
+ super.init();
+ Connection connection;
+ //connection initialization...
+ setMetaData(connectionKey, connection);
+ //Do some other stuff..
+
+ }
+}
+----
+
+Code to get the object from the metadata:
+
+[source,java]
+----
+Connection connection = Application.get().getMetaData(MetaDataApp.connectionKey);
+----
+
+Since MetaDataKey<T> class is declared as abstract, we must implement it with a subclass or with an anonymous class (like we did in the example above).
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc
new file mode 100644
index 0000000..30ef66a
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc
@@ -0,0 +1,40 @@
+
+Wicket uses a number of custom exceptions during the regular running of an application. We have already seen _PageExpiredException_ raised when a page version is expired. Other examples of such exceptions are _AuthorizationException_ and _RestartResponseException_. We will see them later in the next chapters.
+All the other exceptions raised during rendering phase are handled by an implementation of _org.apache.wicket.request.IExceptionMapper_ which by default is class _org.apache.wicket.DefaultExceptionMapper_. If we are working in DEVELOPMENT mode this mapper will redirect us to a page that shows the exception stacktrace (page _ExceptionErrorPage_). On the contrary, if application is running in DEPLOYMENT mode _DefaultExceptionMapper_ will display an internal error page which by default is _org.apache.wicket.markup.html.pages.InternalErrorPage_.
+To use a custom internal error page we can change application settings like this:
+
+[source,java]
+----
+getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class);
+----
+
+We can also manually set if Wicket should display the exception with _ExceptionErrorPage_ or if we want to use the internal error page or if we don't want to display anything at all when an unexpected exception is thrown:
+
+[source,java]
+----
+//show default developer page
+getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_EXCEPTION_PAGE );
+//show internal error page
+getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_INTERNAL_ERROR_PAGE );
+//show no exception page when an unexpected exception is thrown
+getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_NO_EXCEPTION_PAGE );
+----
+
+Developers can also decide to use a custom exception mapper instead of _DefaultExceptionMapper_. To do this we must override _Application_'s method _getExceptionMapperProvider_:
+
+[source,java]
+----
+@Override
+public IProvider<IExceptionMapper> getExceptionMapperProvider()
+{
+ //...
+}
+----
+
+The method returns an instance of _org.apache.wicket.util.IProvider_ that should return our custom exception mapper.
+
+=== Ajax requests
+
+To control the behavior in Ajax requests the application may use _org.apache.wicket.settings.ExceptionSettings1. setAjaxErrorHandlingStrategy(ExceptionSettings.AjaxErrorStrategy)_. By default if an error occurs during the
+processing of an Ajax request Wicket will render the configured error page. By configuring _org.apache.wicket.settings.ExceptionSettings. AjaxErrorStrategy2.INVOKE_FAILURE_HANDLER_ as the default strategy the application will call the JavaScript _onFailure_ callback(s) instead.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc
new file mode 100644
index 0000000..fd937e7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc
@@ -0,0 +1,8 @@
+
+
+
+In this chapter we had a look at how Wicket internally handles a web request. Even if most of the time we won't need to customize this internal process, knowing how it works is essential to use the framework at 100%.
+
+Entities like Application and Session will come in handy again when we will tackle the topic of security in
+<<_security_with_wicket,chapter 23>>.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources.adoc b/wicket-user-guide/src/main/asciidoc/resources.adoc
new file mode 100644
index 0000000..fbe7212
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources.adoc
@@ -0,0 +1,7 @@
+
+One of the biggest challenge for a web framework is to offer an efficient and consistent mechanism to handle internal resources such as CSS/JavaScript files, picture files, pdf and so on. Resources can be static (like an icon used across the site) or dynamic (they can be generated on the fly) and they can be made available to users as a download or as a simple URL.
+
+In <<keepControl.adoc#_adding_header_contents_to_the_final_page,paragraph 6.6>> we have already seen how to add CSS and JavaScript contents to the header section of the page. In the first half of this chapter we will learn a more sophisticated technique that allows us to manage static resources directly from code and \u201cpack\u201d them with our custom components.
+
+Then, in the second part of the chapter we will see how to implement custom resources to enrich our web application with more complex and dynamic functionalities.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc
new file mode 100644
index 0000000..92aa46e
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc
@@ -0,0 +1,11 @@
+
+
+
+In Wicket a resource is an entity that can interact with the current request and response and It must implement interface _org.apache.wicket.request.resource.IResource_. This interface defines just method respond(IResource.Attributes attributes) where the nested class IResource. Attributes provides access to request, response and page parameters objects.
+
+Resources can be static or dynamic. Static resources don't entail any computational effort to be generated and they generally correspond to a resource on the filesystem. On the contrary dynamic resources are generated on the fly when they are requested, following a specific logic coded inside them.
+
+An example of dynamic resource is the built-in class CaptchaImageResource in package _org.apache.wicket.extensions.markup.html.captcha_ which generates a captcha image each time is rendered.
+
+As we will see in [paragraph 16.10|guide:resources_10], developers can build custom resources extending base class _org.apache.wicket.request.resource.AbstractResource_.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc
new file mode 100644
index 0000000..0147138
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc
@@ -0,0 +1,52 @@
+
+
+
+In Wicket the best way to add dynamic functionalities to our application (such as csv export, a pdf generated on the fly, etc...) is implementing a custom resource. In this paragraph as example of custom resource we will build a basic RSS feeds generator which can be used to publish feeds on our site (project CustomResourceMounting). Instead of generating a RSS feed by hand we will use Rome framework and its utility classes.
+
+As hinted above in <<resources.adoc#_static_vs_dynamic_resources,paragraph 16.1>>, class _AbstractResource_ can be used as base class to implement new resources. This class defines abstract method _newResourceResponse_ which is invoked when the resource is requested. The following is the code of our RSS feeds generator:
+
+[source,java]
+----
+public class RSSProducerResource extends AbstractResource {
+
+ @Override
+ protected ResourceResponse newResourceResponse(Attributes attributes) {
+ ResourceResponse resourceResponse = new ResourceResponse();
+ resourceResponse.setContentType("text/xml");
+ resourceResponse.setTextEncoding("utf-8");
+
+ resourceResponse.setWriteCallback(new WriteCallback()
+ {
+ @Override
+ public void writeData(Attributes attributes) throws IOException
+ {
+ OutputStream outputStream = attributes.getResponse().getOutputStream();
+ Writer writer = new OutputStreamWriter(outputStream);
+ SyndFeedOutput output = new SyndFeedOutput();
+ try {
+ output.output(getFeed(), writer);
+ } catch (FeedException e) {
+ throw new WicketRuntimeException("Problems writing feed to response...");
+ }
+ }
+ });
+
+ return resourceResponse;
+ }
+ // method getFeed()...
+}
+----
+
+Method _newResourceResponse_ returns an instance of _ResourceResponse_ representing the response generated by the custom resource. Since RSS feeds are based on XML, in the code above we have set the type of the response to text/xml and the text encoding to utf-8.
+
+To specify the content that will be returned by our resource we must also provide an implementation of inner class _WriteCallback_ which is responsible for writing content data to response's output stream. In our project we used class SyndFeedOutput from Rome framework to write our feed to response. Method _getFeed()_ is just an utility method that generates a sample RSS feed (which is an instance of interface _com.sun.syndication.feed.synd.SyndFeed_).
+
+Now that we have our custom resource in place, we can use it in the home page of the project. The easiest way to make a resource available to users is to expose it with link component _ResourceLink_:
+
+[source,java]
+----
+add(new ResourceLink("rssLink", new RSSProducerResource()));
+----
+
+In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc
new file mode 100644
index 0000000..7ad43b7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc
@@ -0,0 +1,41 @@
+
+
+
+Just like pages also resources can be mounted to a specific path. Class _WebApplication_ provides method _mountResource_ which is almost identical to _mountPage_ seen in <<urls.adoc#_generating_structured_and_clear_urls,paragraph 10.6.1>>:
+
+[source,java]
+----
+@Override
+public void init() {
+ super.init();
+ //resource mounted to path /foo/bar
+ ResourceReference resourceReference = new ResourceReference("rssProducer"){
+ RSSReaderResource rssResource = new RSSReaderResource();
+ @Override
+ public IResource getResource() {
+ return rssResource;
+ }};
+ mountResource("/foo/bar", resourceReference);
+}
+----
+
+With the configuration above (taken from project _CustomResourceMounting_) every request to /foo/bar will be served by the custom resource built in the previous paragraph.
+
+Parameter placeholders are supported as well:
+
+[source,java]
+----
+@Override
+public void init() {
+ super.init();
+ //resource mounted to path /foo with a required indexed parameter
+ ResourceReference resourceReference = new ResourceReference("rssProducer"){
+ RSSReaderResource rssResource = new RSSReaderResource();
+ @Override
+ public IResource getResource() {
+ return rssResource;
+ }};
+ mountResource("/bar/${baz}", resourceReference);
+}
+----
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc
new file mode 100644
index 0000000..ac45594
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc
@@ -0,0 +1,33 @@
+
+
+
+Resources can be added to a global registry in order to share them at application-level. Shared resources are identified by an application-scoped key and they can be easily retrieved at a later time using reference class _SharedResourceReference_. The global registry can be accessed with _Application_'s method _getSharedResources_. In the following excerpt of code (taken again from project _CustomResourceMounting_) we register an instance of our custom RSS feeds producer as application-shared resource:
+
+[source,java]
+----
+ //init application's method
+ @Override
+ public void init(){
+ RSSProducerResource rssResource = new RSSProducerResource();
+ // ...
+ getSharedResources().add("globalRSSProducer", rssResource);
+ }
+----
+
+Now to use an application-shared resource we can simply retrieve it using class _SharedResourceReference_ and providing the key previously used to register the resource:
+
+[source,java]
+----
+add(new ResourceLink("globalRssLink", new SharedResourceReference("globalRSSProducer")));
+----
+
+The URL generated for application shared resources follows the same pattern seen for package resources:
+
+_./wicket/resource/org.apache.wicket.Application/globalRSSProducer_
+
+The last segment of the URL is the key of the resource while the previous segment contains the scope of the resource. For application-scoped resources the scope is always the fully qualified name of class _Application_. This should not be surprising since global resources are visible at application level (i.e. the scope is the application).
+
+NOTE: Package resources are also application-shared resources but they don't need to be explicitly registered.
+
+NOTE: Remember that we can get the URL of a resource reference using method _urlFor(ResourceReference resourceRef, PageParameters params )_ available with both class _RequestCycle_ and class _Component_.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc
new file mode 100644
index 0000000..13d5246
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc
@@ -0,0 +1,47 @@
+
+
+
+Wicket loads application's resources delegating this task to a resource locator represented by interface _org.apache.wicket.core.util.resource.locator.IResourceStreamLocator_. To retrieve or modify the current resource locator we can use the getter and setter methods defined by setting class _ResourceSettings_:
+
+[source,java]
+----
+ //init application's method
+ @Override
+ public void init(){
+ //get the resource locator
+ getResourceSettings().getResourceStreamLocator();
+ //set the resource locator
+ getResourceSettings().setResourceStreamLocator(myLocator);
+ }
+----
+
+The default locator used by Wicket is class _ResourceStreamLocator_ which in turn tries to load a requested resource using a set of implementations of interface _IResourceFinder_. This interface defines method _find(Class class, String pathname)_ which tries to resolve a resource corresponding to the given class and path.
+
+The default implementation of _IResourceFinder_ used by Wicket is _ClassPathResourceFinder_ which searches for resources into the application class path. This is the implementation we have used so far in our examples. However some developers may prefer storing markup files and other resources in a separate folder rather than placing them side by side with Java classes.
+
+To customize resource loading we can add further resource finders to our application in order to extend the resource-lookup algorithm to different locations. Wicket already comes with two other implementations of IResourceFinder designed to search for resources into a specific folder on the file system. The first is class _Path_ and it's defined in package _org.apache.wicket.util.file_. The constructor of this class takes in input an arbitrary folder that can be expressed as a string path or as an instance of Wicket utility class _Folder_ (in package _org.apache.wicket.util.file_). The second implementation of interface _IResourceFinder_ is class _WebApplicationPath_ which looks into a folder placed inside webapp's root path (but not inside folder WEB-INF).
+
+Project CustomFolder4MarkupExample uses _WebApplicationPath_ to load the markup file and the resource bundle for its home page from a custom folder. The folder is called markupFolder and it is placed in the root path of the webapp. The following picture illustrates the file structure of the project:
+
+image::../img/package-structure-custom-folder.png[]
+
+As we can see in the picture above, we must preserve the package structure also in the custom folder used as resource container. The code used inside application class to configure WebApplicationPath is the following:
+
+[source,java]
+----
+@Override
+public void init()
+{
+ getResourceSettings().getResourceFinders().add(
+ new WebApplicationPath(getServletContext(), "markupFolder"));
+}
+----
+
+Method getResourceFinders() defined by setting class ResourceSettings returns the list of resource finders defined in our application. The constructor of WebApplicationPath takes in input also an instance of standard interface javax.servlet.ServletContext which can be retrieved with WebApplication's method getServletContext().
+
+NOTE: By default, if resource files can not be found inside application classpath, Wicket will search for them inside \u201cresources\u201d folder. You may have noted this folder in the previous picture. It is placed next to the folder \u201cjava\u201d containing our source files:
+
+image::../img/package-structure-resource-folder.png[]
+
+This folder can be used to store resource files without writing any configuration code.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc
new file mode 100644
index 0000000..4b9c6c6
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc
@@ -0,0 +1,76 @@
+
+
+
+Introduced in Wicket 6.20.0 / Wicket 7.0.0 there is a default way to be used in which the output of all CssHeaderItems / JavaScriptHeaderItems is modified before they are cached and delivered to the client. You can add a so called Compressor by receiving the resource settings and invoke 1.setJavaScriptCompressor(...) / 1.setJavaScriptCompressor(...). If you want to add several Compressors use _org.apache.wicket.resource.CompositeCssCompressor_ or _org.apache.wicket.resource.CompositeJavaScriptCompressor_
+
+*Java Code:*
+[source,java]
+----
+...
+��� public class WicketApplication extends WebApplication
+�� �{
+�� ��� �@Override
+�� ��� �public Class<? extends WebPage> getHomePage()
+�� ��� �{
+�� ��� ��� �return HomePage.class;
+�� ��� �}
+�� �
+�� ��� �@Override
+�� ��� �public void init()
+�� ��� �{
+�� ��� ��� �super.init();
+�� ��� ��� �getResourceSettings().setCssCompressor(new CssUrlReplacer());
+�� ��� �}
+�� �}
+...
+----
+
+In the previous example you see that a _org.apache.wicket.resource.CssUrlReplacer_ is added which does not compress the content, but replaces all urls in CSS files and applies a Wicket representation for them by automatically wrapping them into PackageResourceReferences. Here is an example where you can see what Wicket does with the url representation.
+
+HomePage (in package my/company/):
+*Java Code:*
+[source,java]
+----
+...
+response.render(CssReferenceHeaderItem.forReference(new PackageResourceReference(HomePage.class, "res/css/mycss.css")));
+...
+----
+
+mycss.css (in package my/company/res/css/):
+*CSS:*
+[source,java]
+----
+...
+body{
+��� background-image:url('../images/some.png');
+}
+...
+----
+
+some.png (in package my/company/res/images/):
+<blob>
+
+Output of mycss.css:
+*CSS:*
+[source,java]
+----
+...
+body{
+��� background-image:url('../images/some-ver-1425904170000.png');
+}
+...
+----
+
+If you add a url which looks like this background-image:url('../images/some.png?embedBase64'); Wicket is going to embed the complete image as base64 string with its corresponding mime type into the css file. It looks like the following code block demonstrates.
+
+Output of mycss.css:
+*CSS:*
+[source,java]
+----
+...
+body{
+��� background-image: url(data:image/png;base64,R0lGODlh1wATAX....);
+}
+...
+----
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc
new file mode 100644
index 0000000..320890e
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc
@@ -0,0 +1,67 @@
+
+The FileSystemResourceRenference comes along with the FileSystemResource, FileSystemResourceStreamReference and the FileSystemResourceStream. Those classes provide a simple way to handle resources with Java's NIO API in Wicket starting from JDK version 7.0. (Available since Wicket 7.2.0 / Wicket 8.0.0)
+
+Example: To include a resource which is zipped into a file and located in a specific folder in the file system you can simply write code like this:
+
+Java:
+[source,java]
+----
+URI uri = URI.create("jar:file:///videosFolder/videos.zip!/folderInZip/Video.mp4");
+Path path = FileSystemResourceReference.getPath(uri);
+FileSystemResourceReference ref = new FileSystemResourceReference("video",path);
+Video video = new Video("video",ref);
+add(vide);
+----
+
+HTML:
+[source,java]
+----
+<video wicket:id="video"/>
+----
+
+Using FileSystemResourceReference mounted:
+
+Java:
+[source,java]
+----
+mountResource("/filecontent/${name}", new FileSystemResourceReference("filesystem")
+{
+ private static final long serialVersionUID = 1L;
+
+ @Override
+ public IResource getResource()
+ {
+ return new FileSystemResource()
+ {
+ private static final long serialVersionUID = 1L;
+
+ protected ResourceResponse newResourceResponse(Attributes attributes)
+ {
+ try
+ {
+ String name = attributes.getParameters().get("name").toString("");
+ URI uri = URI.create(
+ "jar:file:////folder/example.zip!/zipfolder/" + name);
+ return createResourceResponse(
+ FileSystemResourceReference.getPath(uri));
+ }
+ catch (IOException | URISyntaxException e)
+ {
+ throw new WicketRuntimeException("Error while reading the file.", e);
+ }
+ };
+ };
+ }
+});
+----
+
+FileSystemResourceReference.getPath(uri) uses a FileSystemPathService to setup a path the resource reference can work on.
+
+So if you write a custom file system you can easily handle every path by adding a *org.apache.wicket.resource.FileSystemPathService* text file into *META-INF/services* and put in your implementation.
+
+A reference implementation can be found in the java class org.apache.wicket.resource.FileSystemJarPathService.
+
+Further FileSystemProviders and the corresponding FileSystems can be implemented as described here:
+
+http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html[http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html]
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc
new file mode 100644
index 0000000..1fc8173
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc
@@ -0,0 +1,23 @@
+
+Another way to receive external image resources is to use the corresponding component with a model which contains the target URL.
+
+The ExternalImage and ExternalSource components which are available since Wicket 7.2.0 / Wicket 8.0.0 fulfill that task.
+
+The following example demonstrates the usage of a CompoundPropertyModel with the model object [ImageSrc] The model object, bound to surrounding component / page, contains an attribute named [url] which is read by the component:
+
+Java:
+[source,java]
+----
+ImageSrc imageSrc = new ImageSrc();
+imageSrc.setUrl("http://www.google.de/test.jpg");
+setDefaultModel(new CompoundPropertyModel<>(imageSrc));
+add(new ExternalImage("url"));
+----
+
+HTML:
+[source,java]
+----
+<img wicket:id="url" />
+----
+
+The ExternalImage can also be constructed by passing in a Model (src) and Model of List (srcSet). For ExternalSource only the srcSet is available.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc
new file mode 100644
index 0000000..72c0dc3
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc
@@ -0,0 +1,8 @@
+
+
+
+In this chapter we have learnt how to manage resources with the built-in mechanism provided by Wicket. With this mechanism we handle resources from Java code and Wicket will automatically take care of generating a valid URL for them. We have also seen how resources can be bundled as package resources with a component that depends on them to make it self-contained.
+
+Then, in the second part of the chapter, we have built a custom resource and we have learnt how to mount it to an arbitrary URL and how to make it globally available as shared resource.
+
+Finally, in the last part of the paragraph we took a peek at the mechanism provided by the framework to customize the locations where the resource-lookup algorithm searches for resources.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc
new file mode 100644
index 0000000..fd61770
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc
@@ -0,0 +1,4 @@
+
+
+
+Most of the times in Wicket we won't directly instantiate a resource but rather we will use a reference to it. Resource references are represented by abstract class _org.apache.wicket.request.resource.ResourceReference_ which returns a concrete resource with factory method getResource(). In this way we can lazy-initialize resources loading them only the first time they are requested.
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc
new file mode 100644
index 0000000..cc1b6ed
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc
@@ -0,0 +1,180 @@
+
+
+
+With HTML we use to include static resources in our pages using tags like <script>, <link> or <img>. This is what we have done so far writing our custom panels and pages. However, when we work with a component-oriented framework like Wicket, this classic approach becomes inadequate because it makes custom components hardly reusable. This happens when a component depends on a big number of resources. In such a case, if somebody wanted to use our custom component in his application, he would be forced to know which resources it depends on and make them available.
+
+To solve this problem Wicket allows us to place static resource files into component package (like we do with markup and properties files) and load them from component code.
+
+These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot):
+
+image::../img/package-resources.png[]
+
+With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies.
+
+To load package resources Wicket provides class _org.apache.wicket.request.resource.PackageResourceReference_.
+
+To identify a package resource we need to specify a class inside the target package and the name of the desired resource (most of the times this will be a file name).
+
+In the following example taken from project ImageAsPackageRes, CustomPanel loads a picture file available as package resource and it displays it in a <img> tag using the built-in component _org.apache.wicket.markup.html.image.Image_:
+
+*HTML:*
+[source,html]
+----
+<html>
+<head>...</head>
+<body>
+<wicket:panel>
+ Package resource image: <img wicket:id="packageResPicture"/>
+</wicket:panel>
+</body>
+</html>
+----
+
+*Jave Code:*
+[source,java]
+----
+public class CustomPanel extends Panel {
+
+ public CustomPanel(String id) {
+ super(id);
+ PackageResourceReference resourceReference =
+ new PackageResourceReference(getClass(), "calendar.jpg");
+ add(new Image("packageResPicture", resourceReference));
+ }
+}
+----
+
+Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure:
+
+_<path to application root>/wicket/resource/<fully qualified classname>/<resource file name>-<ver-<id>>(.file extension)_
+
+In our example the URL for our picture file calendar.jpg is the following:
+
+_./wicket/resource/org.wicketTutorial.CustomPanel/calendar-ver-1297887542000.jpg_
+
+The first part of the URL is the relative path to the application root. In our example our page is already at the application's root so we have only a single-dotted segment. The next two segments, wicket and resource, are respectively the namespace and the identifier for resources seen in <<urls.adoc#_generating_structured_and_clear_urls,paragraph 10.6.4>>.
+
+The fourth segment is the fully qualified name of the class used to locate the resource and it is the scope of the package resource. In the last segment of the URL we can find the name of the resource (the file name).
+
+As you can see Wicket has automatically appended to the file name a version identifier (ver-1297887542000). When Wicket runs in DEVELOPMENT mode this identifier contains the timestamp in millisecond indicating the last time the resource file was modified. This can be useful when we are developing our application and resource files are frequently modified. Appending the timestamp to the original name we are sure that our browser will use always the last version of the file and not an old, out of date, cached version.
+
+When instead Wicket is running in DEPLOYMENT mode, the version identifier will contain the MD5 digest of the file instead of the timestamp. The digest is computed only the first time the resource is requested. This perfectly makes sense as static resources don't change so often when our application runs into production environment and when this appends the application is redeployed.
+
+NOTE: Package resources can be localized following the same rules seen for resource bundles and markup files:
+
+image::../img/package-resource-localization.png[]
+
+In the example illustrated in the picture above, if we try to retrieve package resource calendar.jpg when the current locale is set to French, the actual file returned will be calendar_fr.jpg.
+
+=== Responsive images - multiple resource references use in one component
+
+Since Wicket 7.0.0 the build-in component _org.apache.wicket.markup.html.image.Image_ allows you to add several ResourceReferences via varargs and to provide sizes for each image so that the browser is able to pick the best image source.
+
+*HTML:*
+[source,html]
+----
+...
+ Package resource image: <img wicket:id="packageResPicture"/>
+...
+----
+
+*Java Code:*
+[source,java]
+----
+...
+ Image image = new Image("packageResPicture",
+ new PackageResourceReference(getClass(),"small.jpg"),
+ new PackageResourceReference(getClass(), "large.jpg"),
+ new PackageResourceReference(getClass(), "medium.jpg"),
+ new PackageResourceReference(getClass(), "small.jpg"));
+ image.setXValues("1024w", "640w", "320w");
+ image.setSizes("(min-width: 36em) 33.3vw", "100vw");
+
+ this.add(image);
+...
+----
+
+The component _org.apache.wicket.markup.html.image.Picture_ is used to provide a fallback image _org.apache.wicket.markup.html.image.Image_ and several source components _org.apache.wicket.markup.html.image.Source_ which gives a developer the control as to when and if those images are presented to the user.
+
+*HTML:*
+[source,html]
+----
+...
+ <picture wicket:id="picture">
+ <source wicket:id="big" />
+ <source wicket:id="small" />
+ <img wicket:id="fallback" />
+ </picture>
+...
+----
+
+*Java Code:*
+[source,java]
+----
+...
+ Picture picture = new Picture("picture");
+
+ Source big = new Source("big", new PackageResourceReference(getClass(), "big.jpg"), new PackageResourceReference(getClass(), "big-hd.jpg");
+ big.setXValues("1x","2x");
+ big.setMedia("(min-width: 40em)");
+ picture.add(big);
+
+ Source small = new Source("small", new PackageResourceReference(getClass(), "small.jpg"), new PackageResourceReference(getClass(), "small-hd.jpg");
+ small.setXValues("1x","2x");
+ picture.add(small);
+
+ Image image = new Image("fallback", new PackageResourceReference(getClass(), "fallback.jpg"));
+ picture.add(image);
+
+ this.add(picture);
+...
+----
+
+=== Inline Image - embedded resource reference content
+
+In some components like in the inline image resource references are going to be translated to other representations like base64 content.
+
+*Java Code:*
+[source,java]
+----
+...
+ add(new InlineImage("inline", new PackageResourceReference(getClass(),"image2.gif")));
+...
+----
+
+
+=== Media tags - resource references with content range support
+
+Since Wicket 7.0.0 the PackageResource and the PackageResourceReference support [Range] HTTP header for the request and [Content-Range] / [Accept-Range] HTTP headers for the response, which are used for videos / audio tags. The [Range] header allows the client to only request a specific byte range of the resource. The server provides the [Content-Range] and tells the client which bytes are going to be send.
+
+If you want the resource not to be load into memory apply readBuffered(false) - this way the stream is written directly to the response. (_org.apache.wicket.resource.ITextResourceCompressor_ will not be applied if readBuffered is set to false)
+
+*HTML:*
+[source,html]
+----
+...
+ <video wicket:id="video" />
+...
+----
+
+*Java Code:*
+[source,java]
+----
+...
+ Video video = new Video("video", new PackageResourceReference(getClass(),"video.mp4").readBuffered(false));
+...
+----
+
+=== Using package resources with tag <wicket:link>
+
+In <<urls.adoc#_automatically_creating_bookmarkable_links_with_tag_wicketlink,paragraph 10.3>> we have used tag <wicket:link> to automatically create links to bookmarkable pages. The same technique can be used also for package resources in order to use them directly from markup file. Let's assume for example that we have a picture file called icon.png placed in the same package of the current page. Under these conditions we can display the picture file using the following markup fragment:
+
+[source,html]
+----
+<wicket:link>
+ <img src="icon.png"/>
+</wicket:link>
+----
+
+In the example above Wicket will populate the attribute src with the URL corresponding to the package resource icon.png. <wicket:link> supports also tag <link> for CSS files and tag <script> for JavaScript files.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc
new file mode 100644
index 0000000..59ae47e
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc
@@ -0,0 +1,35 @@
+
+
+
+Wicket comes with interface _org.apache.wicket.markup.html.IHeaderContributor_ which allows components and behaviors (which will be introduced later in <<advanced.adoc#_enriching_components_with_behaviors,paragraph 18.1>>) to contribute to the header section of their page. The only method defined in this interface is _renderHead(IHeaderResponse response)_ where _IHeaderResponse_ is an interface which defines method _render(HeaderItem item)_ to write static resources or free-form text into the header section of the page.
+
+Header entries are instances of abstract class _org.apache.wicket.markup.head.HeaderItem_. Wicket provides a set of built-in implementations of this class suited for the most common types of resources. With the exception of _PriorityHeaderItem_, every implementation of _HeaderItem_ is an abstract factory class:
+
+* *CssHeaderItem:* represents a CSS resource. Factory methods provided by this class are _forReference_ which takes in input a resource reference, _forUrl_ which creates an CSS item from a given URL and _forCSS_ which takes in input an arbitrary CSS string and an optional id value to identify the resource.
+* *JavaScriptHeaderItem:* represents a JavaScript resource. Just like _CssHeaderItem_ it provides factory methods _forReference_ and _forUrl_ along with method _forScript_ which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method _forReference_ also supports boolean parameter _defer_ which renders the namesake attribute in the script tag (_defer_ attribute indicates that our script must be execute only after the page has loaded).
+* *OnDomReadyHeaderItem:* it adds JavaScript code that will be executed after the DOM has been built, but before external files (such as picture, CSS, etc...) have been loaded. The class provides a factory method _forScript_ which takes in input an arbitrary string representing the script to execute.
+* *OnEventHeaderItem:* the JavaScript code added with this class is executed when a specific JavaScript event is triggered on a given DOM element. The factory method is _forScript(String target, String event, CharSequence javaScript)_, where target is the id of a DOM element (or the element itself), event is the event that must trigger our code and javaScript is the code to execute.
+* *OnLoadHeaderItem:* the JavaScript code added with this class is executed after the whole page is loaded, external files included. The factory method is _forScript(CharSequence javaScript)_.
+* *PriorityHeaderItem:* it wraps another header item and ensures that it will have the priority over the other items during rendering phase.
+* *StringHeaderItem:* with this class we can add an arbitrary text to the header section. Factory method is _forString(CharSequence string)_.
+* *MetaDataHeaderItem:* starting from version 6.17.0, Wicket provides this class to handle meta informations such as <meta> tags or http://en.wikipedia.org/wiki/Canonical_link_element[canonical link element]
+* *HtmlImportHeaderItem:* introduced in Wicket 6.19.0, provides a HTML5 functionality to include other wicket pages (other html files) into the current generated. Factory methods provided by this class are _forImportLinkTag_ which takes the page class or the url of the page / html to be included.
+
+
+In the following example our custom component loads a CSS file as a package resource (placed in the same package) and it adds it to header section.
+
+[source,java]
+----
+public class MyComponent extends Component{
+
+ @Override
+ public void renderHead(IHeaderResponse response) {
+ PackageResourceReference cssFile =
+ new PackageResourceReference(this.getClass(), "style.css");
+ CssHeaderItem cssItem = CssHeaderItem.forReference(cssFile);
+
+ response.render(cssItem);
+ }
+}
+----
+