You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by ad...@apache.org on 2013/12/14 22:13:12 UTC
svn commit: r1550971 [9/15] - in /wicket/common/site/trunk/_site/guide: ./
gapi/ gapi/DefaultPackage/ gapi/spring/ guide/ guide/pages/
guide/src/docs/guide/chapter14/ guide/src/docs/guide/chapter15/
guide/src/docs/guide/chapter16/ guide/src/docs/guide/...
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter13_1.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter13_1.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter13_1.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter13_1.html Sat Dec 14 21:13:09 2013
@@ -159,14 +159,14 @@ function addJsClass() {
<h2 id="chapter13_1">14.1 Localization</h2>
<p class="paragraph"/>As we have seen in chapter 10, the infrastructure of feedback messages is built on top of Java internationalization (i18n) support, so it should not be surprising that the same infrastructure is used also for localization purpose. However, while so far we have used only the <ApplicationClassName>.properties file to store our custom messages, in this chapter we will see that also pages, components, validators and even Java packages can have their own resource bundles. This allows us to split bundles into multiple files keeping them close to where they are used. But before diving into the details of internationalization with Wicket, it's worthwhile to quickly review how i18n works under Java, see what classes are involved and how they are integrated into Wicket.<p class="paragraph"/><blockquote class="note">
Providing a full description of Java support for i18n is clearly out of the scope of this document. If you need more informations about this topic you can find them in the JavaDocs and in the official <a href="http://docs.oracle.com/javase/tutorial/i18n/index.html" target="blank">i18n tutorial</a> .
-</blockquote><p class="paragraph"/><h3>Class Locale and ResourceBundle</h3><p class="paragraph"/>Class java.util.Locale represents a specific country or language of the world and is used in Java to retrieve other locale-dependent informations like numeric and date formats, the currency in use in a country and so on. Such kind of informations are accessed through special entities called resource bundles which are implemented by class java.util.ResourceBundle. Every resource bundle is identified by a full name which is built using four parameters: a base name (which is required), a language code, a country code and a variant (which are all optional). These three optional parameters are provided by an instance of Locale with its three corresponding getter methods: getLanguage(), getCountry() and getVariant(). Parameter language code is a lowercase ISO 639 2-letter code (like zh for Chinese, de for German and so on) while country code is an uppercase ISO 3166 2-letter code (like CN for
China, DE for Germany and so on). The final full name will have the following structure (NOTE: tokens inside squared brackets are optional):<p class="paragraph"/><div class="code"><pre><base name>[ <em class="italic"><language code>[</em> <COUNTRY_CODE>[_<variant code>]]]</pre></div><p class="paragraph"/>For example a bundle with MyBundle as base name and localized for Mandarin Chinese (language code zh, country code CH, variant cmn) will have MyBundle_zh_CH_cmn as full name. A base name can be a fully qualified class name, meaning that it can include a package name before the actual base name. The specified package will be the container of the given bundle. For example if we use org.foo.MyBundle as base name, the bundle named MyBundle will be searched inside package org.foo. The actual base name (MyBundle in our example) will be used to build the full name of the bundle following the same rules seen above.
-ResourceBundle is an abstract factory class, hence it exposes a number of factory methods named getBundle to load a concrete bundle. Without going into too much details we can say that a bundle corresponds to a file in the classpath. To find a file for a given bundle, getBundle needs first to generate an ordered list of candidate bundle names. These names are the set of all possible full names for a given bundle. For example if we have org.foo.MyBundle as base name and the current locale is the one seen before for Mandarin Chinese, the candidate names will be:
+</blockquote><p class="paragraph"/><h3>Class Locale and ResourceBundle</h3><p class="paragraph"/>Class java.util.Locale represents a specific country or language of the world and is used in Java to retrieve other locale-dependent informations like numeric and date formats, the currency in use in a country and so on. Such kind of informations are accessed through special entities called resource bundles which are implemented by class <code>java.util.ResourceBundle</code>. Every resource bundle is identified by a full name which is built using four parameters: a base name (which is required), a language code, a country code and a variant (which are all optional). These three optional parameters are provided by an instance of Locale with its three corresponding getter methods: getLanguage(), getCountry() and getVariant(). Parameter language code is a lowercase ISO 639 2-letter code (like zh for Chinese, de for German and so on) while country code is an uppercase ISO 3166 2-letter code
(like CN for China, DE for Germany and so on). The final full name will have the following structure (NOTE: tokens inside squared brackets are optional):<p class="paragraph"/><div class="code"><pre><base name>[ <em class="italic"><language code>[</em> <COUNTRY_CODE>[_<variant code>]]]</pre></div><p class="paragraph"/>For example a bundle with MyBundle as base name and localized for Mandarin Chinese (language code zh, country code CH, variant cmn) will have MyBundle_zh_CH_cmn as full name. A base name can be a fully qualified class name, meaning that it can include a package name before the actual base name. The specified package will be the container of the given bundle. For example if we use org.foo.MyBundle as base name, the bundle named MyBundle will be searched inside package org.foo. The actual base name (MyBundle in our example) will be used to build the full name of the bundle following the same rules seen above.
+<code>ResourceBundle</code> is an abstract factory class, hence it exposes a number of factory methods named getBundle to load a concrete bundle. Without going into too much details we can say that a bundle corresponds to a file in the classpath. To find a file for a given bundle, getBundle needs first to generate an ordered list of candidate bundle names. These names are the set of all possible full names for a given bundle. For example if we have org.foo.MyBundle as base name and the current locale is the one seen before for Mandarin Chinese, the candidate names will be:
<ol>
<li>org.foo.MyBundle_zh_CH_cmn</li>
<li>org.foo.MyBundle_zh_CH</li>
<li>org.foo.MyBundle_zh</li>
<li>org.foo.MyBundle</li>
-</ol><p class="paragraph"/>The list of these candidate names is generated starting from the most specific one and subtracting an optional parameter at each step. The last name of the list corresponds to the default resource bundle which is the most general name and is equal to the base name. Once that getBundle has generated the list of candidate names, it will iterate over them to find the first one for which is possible to load a class or a properties file. The class must be a subclass of ResourceBundle having as class name the full name used in the current iteration. If such a class is not found, getBundle will try to locate a properties file having a file name equals to the current full name (Java will automatically append extension .properties to the full name). For example given the resource bundle of the previous example, Java will search first for class org.foo.MyBundle_zh_CH_cmn and then for file MyBundle_zh_CH_cmn.properties inside package org.foo. If no file is found for
any of the candidate names, a MissingResourceException will be thrown. Bundles contains local-dependent string resources identified by a key that is unique in the given bundle. So once we have obtained a valid bundle we can access these objects with method getString (String key).<p class="paragraph"/>As we have seen before working with feedback messages, in Wicket most of the times we will work with properties files rather than with bundle classes. In chapter 10 we used a properties file having as base name the class name of the application class and without any information about the locale. This file is the default resource bundle for a Wicket application. In paragraph 12.4 we will explore the algorithm used in Wicket to locate the available bundles for a given component. Once we have learnt how to leverage this algorithm, we will be able to split our bundles into more files organized in a logical hierarchy.
+</ol><p class="paragraph"/>The list of these candidate names is generated starting from the most specific one and subtracting an optional parameter at each step. The last name of the list corresponds to the default resource bundle which is the most general name and is equal to the base name. Once that getBundle has generated the list of candidate names, it will iterate over them to find the first one for which is possible to load a class or a properties file. The class must be a subclass of <code>ResourceBundle</code> having as class name the full name used in the current iteration. If such a class is not found, getBundle will try to locate a properties file having a file name equals to the current full name (Java will automatically append extension .properties to the full name). For example given the resource bundle of the previous example, Java will search first for class org.foo.MyBundle_zh_CH_cmn and then for file MyBundle_zh_CH_cmn.properties inside package org.foo. If no file
is found for any of the candidate names, a MissingResourceException will be thrown. Bundles contains local-dependent string resources identified by a key that is unique in the given bundle. So once we have obtained a valid bundle we can access these objects with method getString (String key).<p class="paragraph"/>As we have seen before working with feedback messages, in Wicket most of the times we will work with properties files rather than with bundle classes. In chapter 10 we used a properties file having as base name the class name of the application class and without any information about the locale. This file is the default resource bundle for a Wicket application. In paragraph 12.4 we will explore the algorithm used in Wicket to locate the available bundles for a given component. Once we have learnt how to leverage this algorithm, we will be able to split our bundles into more files organized in a logical hierarchy.
<div style="clear:both;margin-top:15px;"></div>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter13_2.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter13_2.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter13_2.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter13_2.html Sat Dec 14 21:13:09 2013
@@ -167,7 +167,7 @@ Session.get().getStyle();</pre></div><p
<span class="java-keyword">public</span> <span class="java-object">String</span> getObject() {
<span class="java-keyword">return</span> getString(<span class="java-quote">"greetingMessage"</span>);
}
-};<p class="paragraph"/>add(<span class="java-keyword">new</span> Label(<span class="java-quote">"greetingMessage"</span>, model));</pre></div><p class="paragraph"/>Class org.apache.wicket.model.AbstractReadOnlyModel is a convenience class for implementing read-only models. In this project we have implemented a custom read-only model for illustrative purposes only because Wicket already provides built-in models for the same task. We will see them in paragraph 12.6.<p class="paragraph"/>The rest of the code of the home page builds the stateless form and the drop-down menu used to change the locale.<p class="paragraph"/><div class="code"><pre>List<Locale> locales = Arrays.asList(Locale.ENGLISH, Locale.CHINESE, Locale.GERMAN);
+};<p class="paragraph"/>add(<span class="java-keyword">new</span> Label(<span class="java-quote">"greetingMessage"</span>, model));</pre></div><p class="paragraph"/>Class <code>org.apache.wicket.model.AbstractReadOnlyModel</code> is a convenience class for implementing read-only models. In this project we have implemented a custom read-only model for illustrative purposes only because Wicket already provides built-in models for the same task. We will see them in paragraph 12.6.<p class="paragraph"/>The rest of the code of the home page builds the stateless form and the drop-down menu used to change the locale.<p class="paragraph"/><div class="code"><pre>List<Locale> locales = Arrays.asList(Locale.ENGLISH, Locale.CHINESE, Locale.GERMAN);
<span class="java-keyword">final</span> DropDownChoice<Locale> changeLocale =
<span class="java-keyword">new</span> DropDownChoice<Locale>(<span class="java-quote">"changeLocale"</span>, <span class="java-keyword">new</span> Model<Locale>(), locales);<p class="paragraph"/>StatelessForm form = <span class="java-keyword">new</span> StatelessForm(<span class="java-quote">"form"</span>){
@Override
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter13_3.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter13_3.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter13_3.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter13_3.html Sat Dec 14 21:13:09 2013
@@ -163,14 +163,14 @@ anotherLabel.labelValue=Value <span clas
form.add(<span class="java-keyword">new</span> Label(<span class="java-quote">"anotherLabel"</span>,<span class="java-keyword">new</span> ResourceModel(<span class="java-quote">"labelValue"</span>)));
add(form);</pre></div><p class="paragraph"/>Page bundle:<p class="paragraph"/><div class="code"><pre>labelValue=Default value
anotherLabel.labelValue=Value <span class="java-keyword">for</span> anotherLabel
-form.anotherLabel.labelValue=Value <span class="java-keyword">for</span> anotherLabel inside form</pre></div><p class="paragraph"/>With the code and the bundle above, the label inside the form will display the value 'Value for anotherLabel inside form'.<p class="paragraph"/><h3>Package bundles</h3><p class="paragraph"/>If no one of the previous steps can find a resource for the given key, the algorithm will look for package bundles. These bundles have package as base name and they can be placed in one of the package of our application:<p class="paragraph"/><img border="0" class="center" src="../img/package-bundles.png"></img><p class="paragraph"/>Packages are traversed starting from the one containing the component requesting for a resource and going up to the root package.<p class="paragraph"/><h3>Bundles for feedback messages</h3><p class="paragraph"/>The algorithm described so far applies to feedback messages as well. In case of validation errors, the component that has cause
d the error will be considered as the component which the string resource is relative to. Furthermore, just like application class and components, validators can have their own bundles placed next to their class and having as base name their class name. This allows us to distribute validators along with the messages they use to report errors:<p class="paragraph"/><img border="0" class="center" src="../img/validator-with-bundle.png"></img><p class="paragraph"/>Validator's resource bundles have the lowest priority in the lookup algorithm. They can be overwritten by resource bundles of components, packages and application class.<p class="paragraph"/><h3>Extending the default lookup algorithm</h3><p class="paragraph"/>Wicket implements the default lookup algorithm using the strategy pattern1. The concrete strategies are abstracted with the interface org.apache.wicket.resource.loader.IStringResource Loader. By default Wicket uses the following implementations of IStringResourceLoader (so
rted by execution order):
+form.anotherLabel.labelValue=Value <span class="java-keyword">for</span> anotherLabel inside form</pre></div><p class="paragraph"/>With the code and the bundle above, the label inside the form will display the value 'Value for anotherLabel inside form'.<p class="paragraph"/><h3>Package bundles</h3><p class="paragraph"/>If no one of the previous steps can find a resource for the given key, the algorithm will look for package bundles. These bundles have package as base name and they can be placed in one of the package of our application:<p class="paragraph"/><img border="0" class="center" src="../img/package-bundles.png"></img><p class="paragraph"/>Packages are traversed starting from the one containing the component requesting for a resource and going up to the root package.<p class="paragraph"/><h3>Bundles for feedback messages</h3><p class="paragraph"/>The algorithm described so far applies to feedback messages as well. In case of validation errors, the component that has cause
d the error will be considered as the component which the string resource is relative to. Furthermore, just like application class and components, validators can have their own bundles placed next to their class and having as base name their class name. This allows us to distribute validators along with the messages they use to report errors:<p class="paragraph"/><img border="0" class="center" src="../img/validator-with-bundle.png"></img><p class="paragraph"/>Validator's resource bundles have the lowest priority in the lookup algorithm. They can be overwritten by resource bundles of components, packages and application class.<p class="paragraph"/><h3>Extending the default lookup algorithm</h3><p class="paragraph"/>Wicket implements the default lookup algorithm using the strategy pattern1. The concrete strategies are abstracted with the interface <code>org.apache.wicket.resource.loader.IStringResourceLoader</code>. By default Wicket uses the following implementations of <code>IString
ResourceLoader</code> (sorted by execution order):
<ol>
<li><strong class="bold">ComponentStringResourceLoader:</strong> implements most of the default algorithm. It searches for a given resource across bundles from the container hierarchy, from class hierarchy and from the given component.</li>
<li><strong class="bold">PackageStringResourceLoader:</strong> searches into package bundles.</li>
<li><strong class="bold">ClassStringResourceLoader:</strong> searches into bundles of a given class. By default the target class is the application class.</li>
<li><strong class="bold">ValidatorStringResourceLoader:</strong> searches for resources into validator's bundles. A list of validators is provided by the form component that failed validation.</li>
<li><strong class="bold">InitializerStringResourceLoader:</strong> this resource allows internationalization to interact with the initialization mechanism of the framework that will be illustrated in paragraph 15.4.</li>
-</ol><p class="paragraph"/>Developer can customize lookup algorithm removing default resource loaders or adding custom implementations to the list of the resource loaders in use. This task can be accomplished using method getStringResourceLoaders of setting interface org.apache.wicket.settings.IResourceSettings:<p class="paragraph"/><div class="code"><pre>@Override
+</ol><p class="paragraph"/>Developer can customize lookup algorithm removing default resource loaders or adding custom implementations to the list of the resource loaders in use. This task can be accomplished using method getStringResourceLoaders of setting interface <code>org.apache.wicket.settings.IResourceSettings</code>:<p class="paragraph"/><div class="code"><pre>@Override
<span class="java-keyword">public</span> void init()
{
<span class="java-keyword">super</span>.init();
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter13_4.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter13_4.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter13_4.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter13_4.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter13_4">14.4 Localization of component's choices</h2>
-<p class="paragraph"/>Components that inherit from AbstractChoice (such as DropDownChoice, CheckBoxMultiple Choice and RadioChoice) must override method localizeDisplayValues and make it return true to localize the values displayed for their choices. By default this method return false so values are displayed as they are. Once localization is activated we can use display values as key for our localized string resources. In project LocalizedChoicesExample we have a drop-down list that displays four colors (green, red, blue, and yellow) which are localized in three languages (English, German and Italian). The current locale can be changed with another drop-down menu (in a similar fashion to project LocalizedGreetings). The code of the home page and the relative bundles are the following:<p class="paragraph"/>Java code:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> HomePage(<span class="java-keyword">final</span> PageParameters parameters)
{
+<p class="paragraph"/>Components that inherit from <code>AbstractChoice</code> (such as <code>DropDownChoice</code>, <code>CheckBoxMultipleChoice</code> and <code>RadioChoice</code>) must override method <code>localizeDisplayValues</code> and make it return true to localize the values displayed for their choices. By default this method return false so values are displayed as they are. Once localization is activated we can use display values as key for our localized string resources. In project LocalizedChoicesExample we have a drop-down list that displays four colors (green, red, blue, and yellow) which are localized in three languages (English, German and Italian). The current locale can be changed with another drop-down menu (in a similar fashion to project <code>LocalizedGreetings</code>). The code of the home page and the relative bundles are the following:<p class="paragraph"/>Java code:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> Ho
mePage(<span class="java-keyword">final</span> PageParameters parameters) {
<span class="java-keyword">super</span>(parameters);<p class="paragraph"/> List<Locale> locales = Arrays.asList(Locale.ENGLISH, Locale.ITALIAN, Locale.GERMAN);
List<<span class="java-object">String</span>> colors = Arrays.asList(<span class="java-quote">"green"</span>, <span class="java-quote">"red"</span>, <span class="java-quote">"blue"</span>, <span class="java-quote">"yellow"</span>);<p class="paragraph"/> <span class="java-keyword">final</span> DropDownChoice<Locale> changeLocale = <span class="java-keyword">new</span> DropDownChoice<Locale>(<span class="java-quote">"changeLocale"</span>,
<span class="java-keyword">new</span> Model<Locale>(), locales);<p class="paragraph"/> StatelessForm form = <span class="java-keyword">new</span> StatelessForm(<span class="java-quote">"form"</span>){
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter13_5.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter13_5.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter13_5.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter13_5.html Sat Dec 14 21:13:09 2013
@@ -157,9 +157,9 @@ function addJsClass() {
<h2 id="chapter13_5">14.5 Internationalization and Models</h2>
-<p class="paragraph"/>Internationalization is another good chance to taste the power of models. Wicket provides two built-in models to better integrate our components with string resources: they are ResourceModel and StringResourceModel.<p class="paragraph"/><h3>ResourceModel</h3><p class="paragraph"/>Model org.apache.wicket.model.ResourceModel acts just like the read-only model we have implemented in paragraph 12.3.4. It simply retrieves a string resource corresponding to a given key:<p class="paragraph"/><div class="code"><pre>//build a ResourceModel <span class="java-keyword">for</span> key 'greetingMessage'
+<p class="paragraph"/>Internationalization is another good chance to taste the power of models. Wicket provides two built-in models to better integrate our components with string resources: they are ResourceModel and StringResourceModel.<p class="paragraph"/><h3>ResourceModel</h3><p class="paragraph"/>Model <code>org.apache.wicket.model.ResourceModel</code> acts just like the read-only model we have implemented in paragraph 12.3.4. It simply retrieves a string resource corresponding to a given key:<p class="paragraph"/><div class="code"><pre>//build a ResourceModel <span class="java-keyword">for</span> key 'greetingMessage'
<span class="java-keyword">new</span> ResourceModel(<span class="java-quote">"greetingMessage"</span>);</pre></div><p class="paragraph"/>We can also specify a default value to use if the requested resource is not found:<p class="paragraph"/><div class="code"><pre>//build a ResourceModel with a <span class="java-keyword">default</span> value
-<span class="java-keyword">new</span> ResourceModel(<span class="java-quote">"notExistingResource"</span>, <span class="java-quote">"Resource not found."</span>);</pre></div><p class="paragraph"/><h3>StringResourceModel</h3><p class="paragraph"/>Model org.apache.wicket.model.StringResourceModel allows to work with complex and dynamic string resources containing parameters and property expressions. The basic constructor of this model takes in input a resource key and another model. This further model can be used by both the key and the related resource to specify dynamic values with property expressions. For example let's say that we are working on an e-commerce site which has a page where users can see an overview of their orders. To handle the state of user's orders we will use the following bean and enum (the code is from project StringResourceModelExample):<p class="paragraph"/>Bean:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</sp
an> class Order <span class="java-keyword">implements</span> Serializable {<p class="paragraph"/> <span class="java-keyword">private</span> Date orderDate;
+<span class="java-keyword">new</span> ResourceModel(<span class="java-quote">"notExistingResource"</span>, <span class="java-quote">"Resource not found."</span>);</pre></div><p class="paragraph"/><h3>StringResourceModel</h3><p class="paragraph"/>Model <code>org.apache.wicket.model.StringResourceModel</code> allows to work with complex and dynamic string resources containing parameters and property expressions. The basic constructor of this model takes in input a resource key and another model. This further model can be used by both the key and the related resource to specify dynamic values with property expressions. For example let's say that we are working on an e-commerce site which has a page where users can see an overview of their orders. To handle the state of user's orders we will use the following bean and enum (the code is from project StringResourceModelExample):<p class="paragraph"/>Bean:<p class="paragraph"/><div class="code"><pre><span class="java-keywor
d">public</span> class Order <span class="java-keyword">implements</span> Serializable {<p class="paragraph"/> <span class="java-keyword">private</span> Date orderDate;
<span class="java-keyword">private</span> ORDER_STATUS status;<p class="paragraph"/> <span class="java-keyword">public</span> Order(Date orderDate, ORDER_STATUS status) {
<span class="java-keyword">super</span>();
<span class="java-keyword">this</span>.orderDate = orderDate;
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_1.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_1.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_1.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_1.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_1">15.1 Static vs dynamic resources</h2>
-<p class="paragraph"/>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.<p class="paragraph"/>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.<p class="paragraph"/>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.<p class="paragraph"/>As we will see in paragraph 13.6, developers can build custom resour
ces extending base class org.apache.wicket.request.resource.AbstractResource.
+<p class="paragraph"/>In Wicket a resource is an entity that can interact with the current request and response and It must implement interface <code>org.apache.wicket.request.resource.IResource</code>. This interface defines just method respond(IResource.Attributes attributes) where the nested class IResource. Attributes provides access to request, response and page parameters objects.<p class="paragraph"/>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.<p class="paragraph"/>An example of dynamic resource is the built-in class CaptchaImageResource in package <code>org.apache.wicket.extensions.markup.html.captcha</code> which generates a captcha image each time is rendered.<p class="paragraph"/>As we will see in paragraph 13.6, develope
rs can build custom resources extending base class <code>org.apache.wicket.request.resource.AbstractResource</code>.
<div style="clear:both;margin-top:15px;"></div>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_2.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_2.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_2.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_2.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_2">15.2 Resource references</h2>
-<p class="paragraph"/>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.
+<p class="paragraph"/>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 <code>org.apache.wicket.request.resource.ResourceReference</code> 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.
<div style="clear:both;margin-top:15px;"></div>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_3.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_3.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_3.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_3.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_3">15.3 Package resources</h2>
-<p class="paragraph"/>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.<p class="paragraph"/>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.<p class="paragraph"/>These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot):<p class="paragraph"/><img border="0" class="center" src="../img
/package-resources.png"></img><p class="paragraph"/>With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies.<p class="paragraph"/>To load package resources Wicket provides class org.apache.wicket.request.resource. PackageResourceReference.<p class="paragraph"/>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).<p class="paragraph"/>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:<p class="paragraph"/><strong class="bold">HTML:</strong>
+<p class="paragraph"/>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.<p class="paragraph"/>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.<p class="paragraph"/>These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot):<p class="paragraph"/><img border="0" class="center" src="../img
/package-resources.png"></img><p class="paragraph"/>With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies.<p class="paragraph"/>To load package resources Wicket provides class <code>org.apache.wicket.request.resource.PackageResourceReference</code>.<p class="paragraph"/>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).<p class="paragraph"/>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 <code>org.apache.wicket.markup.html.image.Image</code>:<p class="paragraph"/><strong class="bold">HTML:</strong>
<div class="code"><pre><html>
<head>...</head>
<body>
@@ -172,7 +172,7 @@ function addJsClass() {
<span class="java-keyword">new</span> PackageResourceReference(getClass(), <span class="java-quote">"calendar.jpg"</span>);
add(<span class="java-keyword">new</span> Image(<span class="java-quote">"packageResPicture"</span>, resourceReference));
}
-}</pre></div><p class="paragraph"/>Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure:<p class="paragraph"/><code>&lt;path to application root>/wicket/resource/&lt;fully qualified classname>/&lt;resource file name> -&lt;ver-&lt;id>>.<file extension></code><p class="paragraph"/>In our example the URL for our picture file calendar.jpg is the following:<p class="paragraph"/><code>./wicket/resource/org.wicketTutorial.CustomPanel/ calendar-ver-1297887542000.jpg</code><p class="paragraph"/>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 paragraph 8.6.4.<p class="paragraph"/>The fourth segment is the fully qualified name of the cl
ass 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).<p class="paragraph"/>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.<p class="paragraph"/>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 s
o often when our application runs into production environment and when this appends the application is redeployed.<p class="paragraph"/><blockquote class="note">
+}</pre></div><p class="paragraph"/>Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure:<p class="paragraph"/><code><path to application root>/wicket/resource/<fully qualified classname>/<resource file name>-<ver-<id>>(.file extension)</code><p class="paragraph"/>In our example the URL for our picture file calendar.jpg is the following:<p class="paragraph"/><code>./wicket/resource/org.wicketTutorial.CustomPanel/calendar-ver-1297887542000.jpg</code><p class="paragraph"/>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 paragraph 8.6.4.<p class="paragraph"/>The fourth segment is the fully qualified name of the class used to locate t
he 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).<p class="paragraph"/>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.<p class="paragraph"/>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 app
lication runs into production environment and when this appends the application is redeployed.<p class="paragraph"/><blockquote class="note">
Package resources can be localized following the same rules seen for resource bundles and markup files:<p class="paragraph"/><img border="0" class="center" src="../img/package-resource-localization.png"></img><p class="paragraph"/>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.
</blockquote><p class="paragraph"/>
<h3>Using package resources with tag <wicket:link></h3><p class="paragraph"/>In paragraph 8.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:<p class="paragraph"/><div class="code"><pre><wicket:link>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_4.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_4.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_4.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_4.html Sat Dec 14 21:13:09 2013
@@ -157,15 +157,15 @@ function addJsClass() {
<h2 id="chapter14_4">15.4 Adding resources to page header section</h2>
-<p class="paragraph"/>Wicket comes with interface <code>org.apache.wicket.markup.html.IHeaderContributor</code> which allows components and behaviors (which will be introduced later in paragraph 15.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.<p class="paragraph"/>Header entries are instances of abstract class <code>org.apache.wicket.markup.head.HeaderItem</code>. 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:
+<p class="paragraph"/>Wicket comes with interface <code>org.apache.wicket.markup.html.IHeaderContributor</code> which allows components and behaviors (which will be introduced later in paragraph 15.1) to contribute to the header section of their page. The only method defined in this interface is <code>renderHead(IHeaderResponse response)</code> where <code>IHeaderResponse</code> is an interface which defines method <code>render(HeaderItem item)</code> to write static resources or free-form text into the header section of the page.<p class="paragraph"/>Header entries are instances of abstract class <code>org.apache.wicket.markup.head.HeaderItem</code>. Wicket provides a set of built-in implementations of this class suited for the most common types of resources. With the exception of <code>PriorityHeaderItem</code>, every implementation of <code>HeaderItem</code> is an abstract factory class:
<ul class="star">
<li><strong class="bold">CssHeaderItem:</strong> represents a CSS resource. Factory methods provided by this class are <code>forReference</code> which takes in input a resource reference, <code>forUrl</code> which creates an CSS item from a given URL and <code>forCSS</code> which takes in input an arbitrary CSS string and an optional id value to identify the resource.</li>
-<li><strong class="bold">JavaScriptHeaderItem:</strong> represents a JavaScript resource. Just like CssHeaderItem it provides factory methods <code>forReference</code> and <code>forUrl</code> along with method <code>forScript</code> which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method <code>forReference</code> also supports boolean parameter <code>defer</code> which renders the namesake attribute in the script tag (<code>defer</code> attribute indicates that our script must be execute only after the page has loaded).</li>
+<li><strong class="bold">JavaScriptHeaderItem:</strong> represents a JavaScript resource. Just like <code>CssHeaderItem</code> it provides factory methods <code>forReference</code> and <code>forUrl</code> along with method <code>forScript</code> which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method <code>forReference</code> also supports boolean parameter <code>defer</code> which renders the namesake attribute in the script tag (<code>defer</code> attribute indicates that our script must be execute only after the page has loaded).</li>
<li><strong class="bold">OnDomReadyHeaderItem:</strong> 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 <code>forScript</code> which takes in input an arbitrary string representing the script to execute.</li>
-<li><strong class="bold">OnEventHeaderItem:</strong> 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.</li>
-<li><strong class="bold">OnLoadHeaderItem:</strong> 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).</li>
+<li><strong class="bold">OnEventHeaderItem:</strong> 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 <code>forScript(String target, String event, CharSequence javaScript)</code>, 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.</li>
+<li><strong class="bold">OnLoadHeaderItem:</strong> the JavaScript code added with this class is executed after the whole page is loaded, external files included. The factory method is <code>forScript(CharSequence javaScript)</code>.</li>
<li><strong class="bold">PriorityHeaderItem:</strong> it wraps another header item and ensures that it will have the priority over the other items during rendering phase.</li>
-<li><strong class="bold">StringHeaderItem:</strong> with this class we can add an arbitrary text to the header section. Factory method is forString(CharSequence string).</li>
+<li><strong class="bold">StringHeaderItem:</strong> with this class we can add an arbitrary text to the header section. Factory method is <code>forString(CharSequence string)</code>.</li>
</ul><p class="paragraph"/>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.<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class MyComponent <span class="java-keyword">extends</span> Component{<p class="paragraph"/> @Override
<span class="java-keyword">public</span> void renderHead(IHeaderResponse response) {
PackageResourceReference cssFile =
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_5.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_5.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_5.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_5.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_5">15.5 Resource dependencies</h2>
-<p class="paragraph"/>Class ResourceReference allows to specify the resources it depends on overriding method getDependencies(). The method returns an iterator over the set of HeaderItems that must be rendered before the resource referenced by ResourceReference can be used. This can be really helpful when our resources are JavaScript or CSS libraries that in turn depend on other libraries.<p class="paragraph"/>For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page:<p class="paragraph"/><div class="code"><pre>Url jqueyuiUrl = Url.parse(<span class="java-quote">"https://ajax.googleapis.com/ajax/libs/jqueryui/"</span> +
+<p class="paragraph"/>Class <code>ResourceReference</code> allows to specify the resources it depends on overriding method <code>getDependencies()</code>. The method returns an iterator over the set of <code>HeaderItems</code> that must be rendered before the resource referenced by <code>ResourceReference</code> can be used. This can be really helpful when our resources are JavaScript or CSS libraries that in turn depend on other libraries.<p class="paragraph"/>For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page:<p class="paragraph"/><div class="code"><pre>Url jqueyuiUrl = Url.parse(<span class="java-quote">"https://ajax.googleapis.com/ajax/libs/jqueryui/"</span> +
<span class="java-quote">"1.10.2/jquery-ui.min.js"</span>);<p class="paragraph"/>UrlResourceReference jqueryuiRef = <span class="java-keyword">new</span> UrlResourceReference(jqueyuiUrl){
@Override
<span class="java-keyword">public</span> Iterable<? <span class="java-keyword">extends</span> HeaderItem> getDependencies() {
@@ -165,7 +165,7 @@ function addJsClass() {
ResourceReference jqueryRef = application.getJavaScriptLibrarySettings().
getJQueryReference();<p class="paragraph"/> <span class="java-keyword">return</span> Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef));
}
-};</pre></div><p class="paragraph"/>Please note that in the code above we have built a resource reference using a URL to the desired library instead of a package resource holding the physical file.<p class="paragraph"/>The same method getDependencies() is defined also for class HeaderItem.
+};</pre></div><p class="paragraph"/>Please note that in the code above we have built a resource reference using a URL to the desired library instead of a package resource holding the physical file.<p class="paragraph"/>The same method <code>getDependencies()</code> is defined also for class <code>HeaderItem</code>.
<div style="clear:both;margin-top:15px;"></div>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_6.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_6.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_6.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_6.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_6">15.6 Custom resources</h2>
-<p class="paragraph"/>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.<p class="paragraph"/>As hinted above in paragraph 13.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:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class RSSProducerResource <span class="java-keyword">extends</span> AbstractResource {<p class="paragraph"/> @Override
+<p class="paragraph"/>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.<p class="paragraph"/>As hinted above in paragraph 13.1, class <code>AbstractResource</code> can be used as base class to implement new resources. This class defines abstract method <code>newResourceResponse</code> which is invoked when the resource is requested. The following is the code of our RSS feeds generator:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class RSSProducerResource <span class="java-keyword">extends</span> AbstractResource {<p class="paragraph"/> @Override
<span class="java-keyword">protected</span> ResourceResponse newResourceResponse(Attributes attributes) {
ResourceResponse resourceResponse = <span class="java-keyword">new</span> ResourceResponse();
resourceResponse.setContentType(<span class="java-quote">"text/xml"</span>);
@@ -178,7 +178,7 @@ function addJsClass() {
});<p class="paragraph"/> <span class="java-keyword">return</span> resourceResponse;
}
// method getFeed()…
-}</pre></div><p class="paragraph"/>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.<p class="paragraph"/>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).<p class="paragraph"/>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:<p clas
s="paragraph"/><div class="code"><pre>add(<span class="java-keyword">new</span> ResourceLink(<span class="java-quote">"rssLink"</span>, <span class="java-keyword">new</span> RSSProducerResource()));</pre></div><p class="paragraph"/>In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL.
+}</pre></div><p class="paragraph"/>Method <code>newResourceResponse</code> returns an instance of <code>ResourceResponse</code> 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.<p class="paragraph"/>To specify the content that will be returned by our resource we must also provide an implementation of inner class <code>WriteCallback</code> 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 <code>getFeed()</code> is just an utility method that generates a sample RSS feed (which is an instance of interface <code>com.sun.syndication.feed.synd.SyndFeed</code>).<p class="paragraph"/>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 <code>ResourceLink</code>:<p class="paragraph"/><div class="code"><pre>add(<span class="java-keyword">new</span> ResourceLink(<span class="java-quote">"rssLink"</span>, <span class="java-keyword">new</span> RSSProducerResource()));</pre></div><p class="paragraph"/>In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL.
<div style="clear:both;margin-top:15px;"></div>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_7.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_7.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_7.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_7.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter14_7">15.7 Mounting resources</h2>
-<p class="paragraph"/>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 paragraph 8.6.1:<p class="paragraph"/><div class="code"><pre>@Override
+<p class="paragraph"/>Just like pages also resources can be mounted to a specific path. Class <code>WebApplication</code> provides method <code>mountResource</code> which is almost identical to <code>mountPage</code> seen in paragraph 8.6.1:<p class="paragraph"/><div class="code"><pre>@Override
<span class="java-keyword">public</span> void init() {
<span class="java-keyword">super</span>.init();
//resource mounted to path /foo/bar
@@ -168,7 +168,7 @@ function addJsClass() {
<span class="java-keyword">return</span> rssResource;
}};
mountResource(<span class="java-quote">"/foo/bar"</span>, resourceReference);
-}</pre></div><p class="paragraph"/>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.<p class="paragraph"/>Parameter placeholders are supported as well:<p class="paragraph"/><div class="code"><pre>@Override
+}</pre></div><p class="paragraph"/>With the configuration above (taken from project <code>CustomResourceMounting</code>) every request to /foo/bar will be served by the custom resource built in the previous paragraph.<p class="paragraph"/>Parameter placeholders are supported as well:<p class="paragraph"/><div class="code"><pre>@Override
<span class="java-keyword">public</span> void init() {
<span class="java-keyword">super</span>.init();
//resource mounted to path /foo with a required indexed parameter
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_8.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_8.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_8.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_8.html Sat Dec 14 21:13:09 2013
@@ -157,16 +157,16 @@ function addJsClass() {
<h2 id="chapter14_8">15.8 Shared resources</h2>
-<p class="paragraph"/>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:<p class="paragraph"/><div class="code"><pre>//init application's method
+<p class="paragraph"/>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 <code>SharedResourceReference</code>. The global registry can be accessed with <code>Application</code>'s method <code>getSharedResources</code>. In the following excerpt of code (taken again from project <code>CustomResourceMounting</code>) we register an instance of our custom RSS feeds producer as application-shared resource:<p class="paragraph"/><div class="code"><pre>//init application's method
@Override
<span class="java-keyword">public</span> void init(){
RSSProducerResource rssResource = <span class="java-keyword">new</span> RSSProducerResource();
// …
getSharedResources().add(<span class="java-quote">"globalRSSProducer"</span>, rssResource);
- }</pre></div><p class="paragraph"/>Now to use an application-shared resource we can simply retrieve it using class SharedResource Reference and providing the key previously used to register the resource:<p class="paragraph"/><div class="code"><pre>add(<span class="java-keyword">new</span> ResourceLink(<span class="java-quote">"globalRssLink"</span>, <span class="java-keyword">new</span> SharedResourceReference(<span class="java-quote">"globalRSSProducer"</span>)));</pre></div><p class="paragraph"/>The URL generated for application shared resources follows the same pattern seen for package resources:<p class="paragraph"/><code>./wicket/resource/org.apache.wicket.Application/globalRSSProducer</code><p class="paragraph"/>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 surprisin
g since global resources are visible at application level (i.e. the scope is the application).<p class="paragraph"/><blockquote class="note">
+ }</pre></div><p class="paragraph"/>Now to use an application-shared resource we can simply retrieve it using class <code>SharedResourceReference</code> and providing the key previously used to register the resource:<p class="paragraph"/><div class="code"><pre>add(<span class="java-keyword">new</span> ResourceLink(<span class="java-quote">"globalRssLink"</span>, <span class="java-keyword">new</span> SharedResourceReference(<span class="java-quote">"globalRSSProducer"</span>)));</pre></div><p class="paragraph"/>The URL generated for application shared resources follows the same pattern seen for package resources:<p class="paragraph"/><code>./wicket/resource/org.apache.wicket.Application/globalRSSProducer</code><p class="paragraph"/>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 <code>Application</code>. Thi
s should not be surprising since global resources are visible at application level (i.e. the scope is the application).<p class="paragraph"/><blockquote class="note">
Package resources are also application-shared resources but they don't need to be explicitly registered.
</blockquote><p class="paragraph"/><blockquote class="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.
+Remember that we can get the URL of a resource reference using method <code>urlFor(ResourceReference resourceRef, PageParameters params )</code> available with both class <code>RequestCycle</code> and class <code>Component</code>.
</blockquote>
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter14_9.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter14_9.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter14_9.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter14_9.html Sat Dec 14 21:13:09 2013
@@ -157,14 +157,14 @@ function addJsClass() {
<h2 id="chapter14_9">15.9 Customizing resource loading</h2>
-<p class="paragraph"/>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 interface IResourceSettings:<p class="paragraph"/><div class="code"><pre>//init application's method
+<p class="paragraph"/>Wicket loads application's resources delegating this task to a resource locator represented by interface <code>org.apache.wicket.core.util.resource.locator.IResourceStreamLocator</code>. To retrieve or modify the current resource locator we can use the getter and setter methods defined by setting interface <code>IResourceSettings</code>:<p class="paragraph"/><div class="code"><pre>//init application's method
@Override
<span class="java-keyword">public</span> void init(){
//get the resource locator
getResourceSettings().getResourceStreamLocator();
//set the resource locator
getResourceSettings().setResourceStreamLocator(myLocator);
- }</pre></div><p class="paragraph"/>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.<p class="paragraph"/>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.<p class="paragraph"/>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 IResourceFinde
r 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).<p class="paragraph"/>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:<p class="paragraph"/><img border="0" class="center" src="../img/package-structure-custom-folder.png"></img><p class="paragraph"/>As we can see in th
e 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:<p class="paragraph"/><div class="code"><pre>@Override
+ }</pre></div><p class="paragraph"/>The default locator used by Wicket is class <code>ResourceStreamLocator</code> which in turn tries to load a requested resource using a set of implementations of interface <code>IResourceFinder</code>. This interface defines method <code>find(Class class, String pathname)</code> which tries to resolve a resource corresponding to the given class and path.<p class="paragraph"/>The default implementation of <code>IResourceFinder</code> used by Wicket is <code>ClassPathResourceFinder</code> 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.<p class="paragraph"/>To customize resource loading we can add further resource finders to our application in order to extend the resource-lookup algorithm to different locations. Wick
et 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 <code>Path</code> and it's defined in package <code>org.apache.wicket.util.file</code>. 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 <code>Folder</code> (in package <code>org.apache.wicket.util.file</code>). The second implementation of interface <code>IResourceFinder</code> is class <code>WebApplicationPath</code> which looks into a folder placed inside webapp's root path (but not inside folder WEB-INF).<p class="paragraph"/>Project CustomFolder4MarkupExample uses <code>WebApplicationPath</code> 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 p
roject:<p class="paragraph"/><img border="0" class="center" src="../img/package-structure-custom-folder.png"></img><p class="paragraph"/>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:<p class="paragraph"/><div class="code"><pre>@Override
<span class="java-keyword">public</span> void init()
{
getResourceSettings().getResourceFinders().add(
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter15_2.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter15_2.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter15_2.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter15_2.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter15_2">16.2 ...and how we will do it</h2>
-<p class="paragraph"/>Our new component will extend the a built-in text field org.apache.wicket.extensions .markup.html.form.DateTextField which already uses a java.util.Date as model object and already performs conversion and validation for input values. Since the component must be self-contained, we must ensure that the JavaScript libraries it relies on (JQuery and JQuery UI) will be always available.<p class="paragraph"/>Starting from version 6.0 Wicket has adopted JQuery as backing JavaScript library so we can use the version bundled with Wicket for our custom datepicker.<p class="paragraph"/>To make JQuery UI available we should instead go to its official site, download the required artifacts and use them as package resources of our component.<p class="paragraph"/><h3>Component package resources</h3><p class="paragraph"/>JQuery UI needs the following static resources in order to work properly:
+<p class="paragraph"/>Our new component will extend the a built-in text field <code>org.apache.wicket.extensions.markup.html.form.DateTextField</code> which already uses a java.util.Date as model object and already performs conversion and validation for input values. Since the component must be self-contained, we must ensure that the JavaScript libraries it relies on (JQuery and JQuery UI) will be always available.<p class="paragraph"/>Starting from version 6.0 Wicket has adopted JQuery as backing JavaScript library so we can use the version bundled with Wicket for our custom datepicker.<p class="paragraph"/>To make JQuery UI available we should instead go to its official site, download the required artifacts and use them as package resources of our component.<p class="paragraph"/><h3>Component package resources</h3><p class="paragraph"/>JQuery UI needs the following static resources in order to work properly:
<ul class="star">
<li><strong class="bold">jquery-ui.min.js</strong>: the minified version of the library.</li>
<li><strong class="bold">jquery-ui.css</strong>: the CSS containing the style used by JQuery UI widgets.</li>
@@ -192,7 +192,7 @@ function addJsClass() {
}<p class="paragraph"/>@Override
<span class="java-keyword">public</span> <Date> IConverter<Date> getConverter(<span class="java-object">Class</span><Date> type) {
<span class="java-keyword">return</span> (IConverter<Date>) dateConverter;
-}</pre></div><p class="paragraph"/>The first thing to do inside onInitialize is to ensure that our component will have a markup id for its related text field. This is done invoking setOutputMarkupId(true).<p class="paragraph"/>Next, JQueryDateField tries to retrieve the date format and the ISO language code that must be used as initialization parameters. This is done using class ResourceModel which searches for a given resource in the available bundles. If no value is found for date format or for ISO language code, default values will be used ('mm/dd/yy' and 'en-GB').<p class="paragraph"/>To generate the relative URL for calendar icon, we load it as package resource reference and then we use Component's method urlFor to get the URL value (we have seen this method in paragraph 7.3.2).<p class="paragraph"/>The last configuration instruction executed inside onInitialize is the instantiation of the custom converter used by our component. This converter is an instance of the built-i
n class org.apache.wicket.datetime.PatternDateConvert and must use the previously retrieved date format to perform conversion operations. Now to tell our component to use this converter we must return it overriding FormComponent's method getConverter.<p class="paragraph"/><h3>Header contributor code</h3><p class="paragraph"/>The rest of the code of our custom component is inside method renderHeader, which is responsible for adding to page header the bundled JQuery library, the three files from JQuery UI distribution, the custom file JQDatePicker.js and the invocation of function initJQDatepicker:<p class="paragraph"/><div class="code"><pre>@Override
+}</pre></div><p class="paragraph"/>The first thing to do inside onInitialize is to ensure that our component will have a markup id for its related text field. This is done invoking setOutputMarkupId(true).<p class="paragraph"/>Next, JQueryDateField tries to retrieve the date format and the ISO language code that must be used as initialization parameters. This is done using class <code>ResourceModel</code> which searches for a given resource in the available bundles. If no value is found for date format or for ISO language code, default values will be used ('mm/dd/yy' and 'en-GB').<p class="paragraph"/>To generate the relative URL for calendar icon, we load it as package resource reference and then we use <code>Component</code>'s method urlFor to get the URL value (we have seen this method in paragraph 7.3.2).<p class="paragraph"/>The last configuration instruction executed inside onInitialize is the instantiation of the custom converter used by our component. This converter is
an instance of the built-in class <code>org.apache.wicket.datetime.PatternDateConvert</code> and must use the previously retrieved date format to perform conversion operations. Now to tell our component to use this converter we must return it overriding <code>FormComponent</code>'s method <code>getConverter</code>.<p class="paragraph"/><h3>Header contributor code</h3><p class="paragraph"/>The rest of the code of our custom component is inside method <code>renderHeader</code>, which is responsible for adding to page header the bundled JQuery library, the three files from JQuery UI distribution, the custom file JQDatePicker.js and the invocation of function <code>initJQDatepicker</code>:<p class="paragraph"/><div class="code"><pre>@Override
<span class="java-keyword">public</span> void renderHead(IHeaderResponse response) {
<span class="java-keyword">super</span>.renderHead(response);<p class="paragraph"/> //<span class="java-keyword">if</span> component is disabled we don't have to load the JQueryUI datepicker
<span class="java-keyword">if</span>(!isEnabledInHierarchy())
@@ -215,7 +215,7 @@ function addJsClass() {
<span class="java-object">String</span> initScript = <span class="java-quote">";initJQDatepicker('"</span> + getMarkupId() + <span class="java-quote">"', '"</span> + countryIsoCode +
<span class="java-quote">"', '"</span> + jqueryDateFormat + <span class="java-quote">"', "</span> + <span class="java-quote">"'"</span> + urlForIcon +<span class="java-quote">"');"</span>;
response.render(OnLoadHeaderItem.forScript(initScript));
-}</pre></div><p class="paragraph"/>If component is disabled the calendar icon must be hidden and no datepicker must be displayed. That's why renderHeader is skipped if component is not enabled.<p class="paragraph"/>To get a reference to the bundled JQuery library we used the JavaScript setting interface IJavaScriptLibrarySettings and its method getJQueryReference.<p class="paragraph"/>In the last part of renderHeader we build the string to invoke function initJQDatepicker using the values obtained inside onInitialize. Unfortunately the date format used by JQuery UI is different from the one adopted in Java so we have to convert it before building the JavaScript code. This init script is rendered into header section using a OnLoadHeaderItem to ensure that it will be executed after all the other scripts have been loaded.<p class="paragraph"/><blockquote class="note">
+}</pre></div><p class="paragraph"/>If component is disabled the calendar icon must be hidden and no datepicker must be displayed. That's why renderHeader is skipped if component is not enabled.<p class="paragraph"/>To get a reference to the bundled JQuery library we used the JavaScript setting interface <code>IJavaScriptLibrarySettings</code> and its method <code>getJQueryReference</code>.<p class="paragraph"/>In the last part of renderHeader we build the string to invoke function initJQDatepicker using the values obtained inside onInitialize. Unfortunately the date format used by JQuery UI is different from the one adopted in Java so we have to convert it before building the JavaScript code. This init script is rendered into header section using a <code>OnLoadHeaderItem</code> to ensure that it will be executed after all the other scripts have been loaded.<p class="paragraph"/><blockquote class="note">
If we add more than one instance of our custom component to a single page, static resources are rendered to the header section just once. Wicket automatically checks if a static resource is already referenced by a page and if so, it will not render it again.<p class="paragraph"/>This does not apply to the init script which is dynamically generated and is rendered for every instance of the component.
</blockquote><p class="paragraph"/><blockquote class="warning">
Our datepicker is not ready yet to be used with AJAX. In chapter 16 we will see how to modify it to make it AJAX-compatible.
Modified: wicket/common/site/trunk/_site/guide/guide/pages/chapter16_1.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/pages/chapter16_1.html?rev=1550971&r1=1550970&r2=1550971&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/pages/chapter16_1.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/pages/chapter16_1.html Sat Dec 14 21:13:09 2013
@@ -157,7 +157,7 @@ function addJsClass() {
<h2 id="chapter16_1">17.1 Enriching components with behaviors</h2>
-<p class="paragraph"/>With class org.apache.wicket.behavior.Behavior Wicket provides a very flexible mechanism to share common features across different components and to enrich existing components with further functionalities. As the class name suggests, Behavior adds a generic behavior to a component modifying its markup and/or contributing to the header section of the page (Behavior implements the interface IHeaderContributor).<p class="paragraph"/>One or more behaviors can be added to a component with Component's method add(Behavior...), while to remove a behavior we must use method remove(Behavior).<p class="paragraph"/>Here is a partial list of methods defined inside class Behavior along with a brief description of what they do:
+<p class="paragraph"/>With class <code>org.apache.wicket.behavior.Behavior</code> Wicket provides a very flexible mechanism to share common features across different components and to enrich existing components with further functionalities. As the class name suggests, <code>Behavior</code> adds a generic behavior to a component modifying its markup and/or contributing to the header section of the page (<code>Behavior</code> implements the interface <code>IHeaderContributor</code>).<p class="paragraph"/>One or more behaviors can be added to a component with <code>Component</code>'s method <code>add(Behavior...)</code>, while to remove a behavior we must use method <code>remove(Behavior)</code>.<p class="paragraph"/>Here is a partial list of methods defined inside class <code>Behavior</code> along with a brief description of what they do:
<ul class="star">
<li><strong class="bold">beforeRender(Component component)</strong>: called when a component is about to be rendered.</li>
<li><strong class="bold">afterRender(Component component)</strong>: called after a component has been rendered.</li>
@@ -180,7 +180,7 @@ function addJsClass() {
}
response.write(asteriskHtml);
}
-}</pre></div><p class="paragraph"/>Since method beforeRender is called before the coupled component is rendered, we can use it to prepend custom markup to component tag. This can be done writing our markup directly to the current Response object, as we did in the example above.<p class="paragraph"/>Please note that we could achieve the same result overriding component method onBeforeRender. However using a behavior we can easily reuse our custom code with any other kind of component without modifying its source code. As general best practice we should always consider to implement a new functionality using a behavior if it can be shared among different kinds of component.<p class="paragraph"/>Behaviors play also a strategic role in the built-in AJAX support provided by Wicket, as we will see in the next chapter.
+}</pre></div><p class="paragraph"/>Since method <code>beforeRender</code> is called before the coupled component is rendered, we can use it to prepend custom markup to component tag. This can be done writing our markup directly to the current Response object, as we did in the example above.<p class="paragraph"/>Please note that we could achieve the same result overriding component method <code>onBeforeRender</code>. However using a behavior we can easily reuse our custom code with any other kind of component without modifying its source code. As general best practice we should always consider to implement a new functionality using a behavior if it can be shared among different kinds of component.<p class="paragraph"/>Behaviors play also a strategic role in the built-in AJAX support provided by Wicket, as we will see in the next chapter.