Modified: wicket/common/site/trunk/_site/guide/guide/resources.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/resources.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/resources.html (original) +++ wicket/common/site/trunk/_site/guide/guide/resources.html Thu Feb 12 18:54:52 2015 @@ -174,31 +174,34 @@ function addJsClass() { <div class="toc-item" style="margin-left:0px"><a href="#resources_4"><strong>15.4</strong><span>Adding resources to page header section</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_5"><strong>15.5</strong><span>Resource dependencies</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_5"><strong>15.5</strong><span>Context-relative resources</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_6"><strong>15.6</strong><span>Aggregate multiple resources with resource bundles</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_6"><strong>15.6</strong><span>Resource dependencies</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_7"><strong>15.7</strong><span>Put JavaScript inside page body</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_7"><strong>15.7</strong><span>Aggregate multiple resources with resource bundles</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_8"><strong>15.8</strong><span>Header contributors positioning</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_8"><strong>15.8</strong><span>Put JavaScript inside page body</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_9"><strong>15.9</strong><span>Custom resources</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_9"><strong>15.9</strong><span>Header contributors positioning</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_10"><strong>15.10</strong><span>Mounting resources</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_10"><strong>15.10</strong><span>Custom resources</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_11"><strong>15.11</strong><span>Shared resources</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_11"><strong>15.11</strong><span>Mounting resources</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_12"><strong>15.12</strong><span>Customizing resource loading</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_12"><strong>15.12</strong><span>Shared resources</span></a> </div> - <div class="toc-item" style="margin-left:0px"><a href="#resources_13"><strong>15.13</strong><span>Summary</span></a> + <div class="toc-item" style="margin-left:0px"><a href="#resources_13"><strong>15.13</strong><span>Customizing resource loading</span></a> + </div> + + <div class="toc-item" style="margin-left:0px"><a href="#resources_14"><strong>15.14</strong><span>Summary</span></a> </div> </div> @@ -264,7 +267,16 @@ Package resources can be localized follo -<h2 id="resources_5">15.5 Resource dependencies</h2> +<h2 id="resources_5">15.5 Context-relative resources</h2> +In web applications, it's quite common to have one or more root context folders containing css/js files. These resources are normally referenced with an absolute path inside link/script tags:<p class="paragraph"/><div class="code"><pre><script src=<span class="java-quote">"/misc/js/jscript.js"</span>></script> +<link type=<span class="java-quote">"text/css"</span> rel=<span class="java-quote">"stylesheet"</span> href=<span class="java-quote">"/misc/css/themes/style.css"</span> /></pre></div><p class="paragraph"/>To handle this kind of resources from code we can use resource reference class <code>org.apache.wicket.request.resource.ContextRelativeResourceReference</code>. To build a new instance of this class we must specify the root context path of the resource we want to use:<p class="paragraph"/><div class="code"><pre>ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>);</pre></div><p class="paragraph"/>By default when our application runs in DEPLOYMENT mode <code>ContextRelativeResourceReference</code> will automatically load the minified version of the specified resource using 'min' as postfix. In the example above it will load '/misc/js/jscrip t.min.js'. We can force <code>ContextRelativeResourceReference</code> to always use the not-minified resource passing an additional flag to class constructor:<p class="paragraph"/><div class="code"><pre>//it will always use '/misc/js/jscript.js' +ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>, <span class="java-keyword">false</span>);</pre></div><p class="paragraph"/>The minified postfix can be customized with an optional string parameter:<p class="paragraph"/><div class="code"><pre>//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode +ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>, <span class="java-quote">"minified"</span>);</pre></div><p class="paragraph"/><code>ContextRelativeResourceReference</code> is usually used with the header item classes we have seen before in this chapter to create entries for the page header section.<p class="paragraph"/><h3>Picture files</h3><p class="paragraph"/>For picture files Wicket provides a specific component with class <code>org.apache.wicket.markup.html.image.ContextImage</code> which is meant to be used with tag <img><p class="paragraph"/><div class="code"><pre>//build the component specifying its id and picture's context path +ContextImage image = <span class="java-keyword">new</span> ContextImage(<span class="java-quote">"myPicture"</span>, <span class="java-quote">"/misc/imgs/mypic.png"</span>);</pre></div> + + + +<h2 id="resources_6">15.6 Resource dependencies</h2> <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 @@ -276,7 +288,7 @@ Package resources can be localized follo };</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>. -<h2 id="resources_6">15.6 Aggregate multiple resources with resource bundles</h2> +<h2 id="resources_7">15.7 Aggregate multiple resources with resource bundles</h2> One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class <code>org.apache.wicket.ResourceBundles</code> to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it:<p class="paragraph"/><div class="code"><pre>@Override <span class="java-keyword">public</span> void init() { <span class="java-keyword">super</span>.init();<p class="paragraph"/> getResourceBundles().addJavaScriptBundle(WicketApplication.class, @@ -291,7 +303,7 @@ A specific resource reference can not be -<h2 id="resources_7">15.7 Put JavaScript inside page body</h2> +<h2 id="resources_8">15.8 Put JavaScript inside page body</h2> Some web developers prefer to put their <script> tags at the end of page body instead of inside the <head> tags:<p class="paragraph"/><div class="code"><pre><html><p class="paragraph"/><head> //no <script> tag here… </head><p class="paragraph"/><body> @@ -333,7 +345,7 @@ The following code is taken from the App }</pre></div><p class="paragraph"/>Looking at the code above you can note that our page adds two script to the header section: the first is an instance of <code>JavaScriptHeaderItem</code> and will be rendered in the <code>HeaderResponseContainer</code> while the second will follow the usual behavior and will be rendered inside <head> tag.<p class="paragraph"/><p class="paragraph"/> -<h2 id="resources_8">15.8 Header contributors positioning</h2> +<h2 id="resources_9">15.9 Header contributors positioning</h2> Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag <code><wicket:header-items/></code>:<p class="paragraph"/><div class="code"><pre><head> <meta chartset=<span class="java-quote">"UTF-8"</span>/> <wicket:header-items/> @@ -342,7 +354,7 @@ Starting from version 6.15.0 we can spec -<h2 id="resources_9">15.9 Custom resources</h2> +<h2 id="resources_10">15.10 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 <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(); @@ -367,7 +379,7 @@ Starting from version 6.15.0 we can spec }</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. -<h2 id="resources_10">15.10 Mounting resources</h2> +<h2 id="resources_11">15.11 Mounting resources</h2> <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(); @@ -393,7 +405,7 @@ Starting from version 6.15.0 we can spec }</pre></div> -<h2 id="resources_11">15.11 Shared resources</h2> +<h2 id="resources_12">15.12 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 <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(){ @@ -407,7 +419,7 @@ Remember that we can get the URL of a re </blockquote> -<h2 id="resources_12">15.12 Customizing resource loading</h2> +<h2 id="resources_13">15.13 Customizing resource loading</h2> <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(){ @@ -425,7 +437,7 @@ By default, if resource files can not be </blockquote> -<h2 id="resources_13">15.13 Summary</h2> +<h2 id="resources_14">15.14 Summary</h2> 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.<p class="paragraph"/>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.<p class="paragraph"/>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. @@ -456,7 +468,7 @@ In this chapter we have learnt how to ma <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div>
Modified: wicket/common/site/trunk/_site/guide/guide/security.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/security.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/security.html (original) +++ wicket/common/site/trunk/_site/guide/guide/security.html Thu Feb 12 18:54:52 2015 @@ -497,7 +497,7 @@ implementation of <code>ICryptFactory</c <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/single.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/single.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/single.html (original) +++ wicket/common/site/trunk/_site/guide/guide/single.html Thu Feb 12 18:54:52 2015 @@ -320,23 +320,25 @@ function addJsClass(el) { <div class="toc-item" style="margin-left:10px"><a href="#resources_4"><strong>15.4</strong><span>Adding resources to page header section</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_5"><strong>15.5</strong><span>Resource dependencies</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_5"><strong>15.5</strong><span>Context-relative resources</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_6"><strong>15.6</strong><span>Aggregate multiple resources with resource bundles</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_6"><strong>15.6</strong><span>Resource dependencies</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_7"><strong>15.7</strong><span>Put JavaScript inside page body</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_7"><strong>15.7</strong><span>Aggregate multiple resources with resource bundles</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_8"><strong>15.8</strong><span>Header contributors positioning</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_8"><strong>15.8</strong><span>Put JavaScript inside page body</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_9"><strong>15.9</strong><span>Custom resources</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_9"><strong>15.9</strong><span>Header contributors positioning</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_10"><strong>15.10</strong><span>Mounting resources</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_10"><strong>15.10</strong><span>Custom resources</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_11"><strong>15.11</strong><span>Shared resources</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_11"><strong>15.11</strong><span>Mounting resources</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_12"><strong>15.12</strong><span>Customizing resource loading</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_12"><strong>15.12</strong><span>Shared resources</span></a></div> - <div class="toc-item" style="margin-left:10px"><a href="#resources_13"><strong>15.13</strong><span>Summary</span></a></div> + <div class="toc-item" style="margin-left:10px"><a href="#resources_13"><strong>15.13</strong><span>Customizing resource loading</span></a></div> + + <div class="toc-item" style="margin-left:10px"><a href="#resources_14"><strong>15.14</strong><span>Summary</span></a></div> <div class="toc-item" style="margin-left:0px"><a href="#jsintegration"><strong>16</strong><span>An example of integration with JavaScript</span></a></div> @@ -2630,7 +2632,16 @@ Package resources can be localized follo -<h2 id="resources_5">15.5 Resource dependencies</h2> +<h2 id="resources_5">15.5 Context-relative resources</h2> +In web applications, it's quite common to have one or more root context folders containing css/js files. These resources are normally referenced with an absolute path inside link/script tags:<p class="paragraph"/><div class="code"><pre><script src=<span class="java-quote">"/misc/js/jscript.js"</span>></script> +<link type=<span class="java-quote">"text/css"</span> rel=<span class="java-quote">"stylesheet"</span> href=<span class="java-quote">"/misc/css/themes/style.css"</span> /></pre></div><p class="paragraph"/>To handle this kind of resources from code we can use resource reference class <code>org.apache.wicket.request.resource.ContextRelativeResourceReference</code>. To build a new instance of this class we must specify the root context path of the resource we want to use:<p class="paragraph"/><div class="code"><pre>ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>);</pre></div><p class="paragraph"/>By default when our application runs in DEPLOYMENT mode <code>ContextRelativeResourceReference</code> will automatically load the minified version of the specified resource using 'min' as postfix. In the example above it will load '/misc/js/jscrip t.min.js'. We can force <code>ContextRelativeResourceReference</code> to always use the not-minified resource passing an additional flag to class constructor:<p class="paragraph"/><div class="code"><pre>//it will always use '/misc/js/jscript.js' +ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>, <span class="java-keyword">false</span>);</pre></div><p class="paragraph"/>The minified postfix can be customized with an optional string parameter:<p class="paragraph"/><div class="code"><pre>//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode +ContextRelativeResourceReference resource = <span class="java-keyword">new</span> ContextRelativeResourceReference(<span class="java-quote">"/misc/js/jscript.js"</span>, <span class="java-quote">"minified"</span>);</pre></div><p class="paragraph"/><code>ContextRelativeResourceReference</code> is usually used with the header item classes we have seen before in this chapter to create entries for the page header section.<p class="paragraph"/><h3>Picture files</h3><p class="paragraph"/>For picture files Wicket provides a specific component with class <code>org.apache.wicket.markup.html.image.ContextImage</code> which is meant to be used with tag <img><p class="paragraph"/><div class="code"><pre>//build the component specifying its id and picture's context path +ContextImage image = <span class="java-keyword">new</span> ContextImage(<span class="java-quote">"myPicture"</span>, <span class="java-quote">"/misc/imgs/mypic.png"</span>);</pre></div> + + + +<h2 id="resources_6">15.6 Resource dependencies</h2> <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 @@ -2642,7 +2653,7 @@ Package resources can be localized follo };</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>. -<h2 id="resources_6">15.6 Aggregate multiple resources with resource bundles</h2> +<h2 id="resources_7">15.7 Aggregate multiple resources with resource bundles</h2> One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class <code>org.apache.wicket.ResourceBundles</code> to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it:<p class="paragraph"/><div class="code"><pre>@Override <span class="java-keyword">public</span> void init() { <span class="java-keyword">super</span>.init();<p class="paragraph"/> getResourceBundles().addJavaScriptBundle(WicketApplication.class, @@ -2657,7 +2668,7 @@ A specific resource reference can not be -<h2 id="resources_7">15.7 Put JavaScript inside page body</h2> +<h2 id="resources_8">15.8 Put JavaScript inside page body</h2> Some web developers prefer to put their <script> tags at the end of page body instead of inside the <head> tags:<p class="paragraph"/><div class="code"><pre><html><p class="paragraph"/><head> //no <script> tag here… </head><p class="paragraph"/><body> @@ -2699,7 +2710,7 @@ The following code is taken from the App }</pre></div><p class="paragraph"/>Looking at the code above you can note that our page adds two script to the header section: the first is an instance of <code>JavaScriptHeaderItem</code> and will be rendered in the <code>HeaderResponseContainer</code> while the second will follow the usual behavior and will be rendered inside <head> tag.<p class="paragraph"/><p class="paragraph"/> -<h2 id="resources_8">15.8 Header contributors positioning</h2> +<h2 id="resources_9">15.9 Header contributors positioning</h2> Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag <code><wicket:header-items/></code>:<p class="paragraph"/><div class="code"><pre><head> <meta chartset=<span class="java-quote">"UTF-8"</span>/> <wicket:header-items/> @@ -2708,7 +2719,7 @@ Starting from version 6.15.0 we can spec -<h2 id="resources_9">15.9 Custom resources</h2> +<h2 id="resources_10">15.10 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 <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(); @@ -2733,7 +2744,7 @@ Starting from version 6.15.0 we can spec }</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. -<h2 id="resources_10">15.10 Mounting resources</h2> +<h2 id="resources_11">15.11 Mounting resources</h2> <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(); @@ -2759,7 +2770,7 @@ Starting from version 6.15.0 we can spec }</pre></div> -<h2 id="resources_11">15.11 Shared resources</h2> +<h2 id="resources_12">15.12 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 <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(){ @@ -2773,7 +2784,7 @@ Remember that we can get the URL of a re </blockquote> -<h2 id="resources_12">15.12 Customizing resource loading</h2> +<h2 id="resources_13">15.13 Customizing resource loading</h2> <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(){ @@ -2791,7 +2802,7 @@ By default, if resource files can not be </blockquote> -<h2 id="resources_13">15.13 Summary</h2> +<h2 id="resources_14">15.14 Summary</h2> 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.<p class="paragraph"/>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.<p class="paragraph"/>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. @@ -4855,7 +4866,7 @@ and attach it to a ticket in Apache Wick <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_10.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_10.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_10.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_10.gdoc Thu Feb 12 18:54:52 2015 @@ -1,37 +1,48 @@ -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: +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 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: {code} -@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); +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()... } {code} -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. +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@). -Parameter placeholders are supported as well: +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@: {code} -@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); -} -{code} \ No newline at end of file +add(new ResourceLink("rssLink", new RSSProducerResource())); +{code} + +In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL. \ No newline at end of file Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_11.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_11.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_11.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_11.gdoc Thu Feb 12 18:54:52 2015 @@ -1,33 +1,37 @@ -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: +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: {code} - //init application's method - @Override - public void init(){ - RSSProducerResource rssResource = new RSSProducerResource(); - // ... - getSharedResources().add("globalRSSProducer", rssResource); - } +@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); +} {code} -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: +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. -{code} -add(new ResourceLink("globalRssLink", new SharedResourceReference("globalRSSProducer"))); -{code} - -The URL generated for application shared resources follows the same pattern seen for package resources: - -@./wicket/resource/org.apache.wicket.Application/globalRSSProducer@ +Parameter placeholders are supported as well: -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} - -{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@. -{note} \ No newline at end of file +{code} +@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); +} +{code} \ No newline at end of file Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_12.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_12.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_12.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_12.gdoc Thu Feb 12 18:54:52 2015 @@ -1,45 +1,33 @@ -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@: +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: {code} //init application's method @Override - public void init(){ - //get the resource locator - getResourceSettings().getResourceStreamLocator(); - //set the resource locator - getResourceSettings().setResourceStreamLocator(myLocator); + public void init(){ + RSSProducerResource rssResource = new RSSProducerResource(); + // ... + getSharedResources().add("globalRSSProducer", rssResource); } {code} -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: - -!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: +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: {code} -@Override -public void init() -{ - getResourceSettings().getResourceFinders().add( - new WebApplicationPath(getServletContext(), "markupFolder")); -} +add(new ResourceLink("globalRssLink", new SharedResourceReference("globalRSSProducer"))); {code} -Method getResourceFinders() defined by setting interface IResourceSettings 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(). +The URL generated for application shared resources follows the same pattern seen for package resources: -{note} -By default, if resource files can not be found inside application classpath, Wicket will search for them inside âresourcesâ folder. You may have noted this folder in the previous picture. It is placed next to the folder âjavaâ containing our source files: +@./wicket/resource/org.apache.wicket.Application/globalRSSProducer@ -!package-structure-resource-folder.png! +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). -This folder can be used to store resource files without writing any configuration code. +{note} +Package resources are also application-shared resources but they don't need to be explicitly registered. +{note} + +{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@. {note} \ No newline at end of file Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_13.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_13.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_13.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_13.gdoc Thu Feb 12 18:54:52 2015 @@ -1,5 +1,45 @@ -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. +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@: + +{code} + //init application's method + @Override + public void init(){ + //get the resource locator + getResourceSettings().getResourceStreamLocator(); + //set the resource locator + getResourceSettings().setResourceStreamLocator(myLocator); + } +{code} + +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: + +!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: + +{code} +@Override +public void init() +{ + getResourceSettings().getResourceFinders().add( + new WebApplicationPath(getServletContext(), "markupFolder")); +} +{code} + +Method getResourceFinders() defined by setting interface IResourceSettings 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 âresourcesâ folder. You may have noted this folder in the previous picture. It is placed next to the folder âjavaâ containing our source files: + +!package-structure-resource-folder.png! + +This folder can be used to store resource files without writing any configuration code. +{note} \ No newline at end of file Added: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_14.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_14.gdoc?rev=1659361&view=auto ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_14.gdoc (added) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_14.gdoc Thu Feb 12 18:54:52 2015 @@ -0,0 +1,5 @@ +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. Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_5.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_5.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_5.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_5.gdoc Thu Feb 12 18:54:52 2015 @@ -1,25 +1,37 @@ +In web applications, it's quite common to have one or more root context folders containing css/js files. These resources are normally referenced with an absolute path inside link/script tags: +{code:html} +<script src="/misc/js/jscript.js"></script> +<link type="text/css" rel="stylesheet" href="/misc/css/themes/style.css" /> +{code} + +To handle this kind of resources from code we can use resource reference class @org.apache.wicket.request.resource.ContextRelativeResourceReference@. To build a new instance of this class we must specify the root context path of the resource we want to use: + +{code} +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js"); +{code} + +By default when our application runs in DEPLOYMENT mode @ContextRelativeResourceReference@ will automatically load the minified version of the specified resource using 'min' as postfix. In the example above it will load '/misc/js/jscript.min.js'. We can force @ContextRelativeResourceReference@ to always use the not-minified resource passing an additional flag to class constructor: -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. +{code} +//it will always use '/misc/js/jscript.js' +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", false); +{code} -For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page: +The minified postfix can be customized with an optional string parameter: {code} -Url jqueyuiUrl = Url.parse("https://ajax.googleapis.com/ajax/libs/jqueryui/"; + - "1.10.2/jquery-ui.min.js"); - -UrlResourceReference jqueryuiRef = new UrlResourceReference(jqueyuiUrl){ - @Override - public Iterable<? extends HeaderItem> getDependencies() { - Application application = Application.get(); - ResourceReference jqueryRef = application.getJavaScriptLibrarySettings(). - getJQueryReference(); - - return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef)); - } -}; +//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", "minified"); {code} -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. +@ContextRelativeResourceReference@ is usually used with the header item classes we have seen before in this chapter to create entries for the page header section. + +h3. Picture files -The same method @getDependencies()@ is defined also for class @HeaderItem@. \ No newline at end of file +For picture files Wicket provides a specific component with class @org.apache.wicket.markup.html.image.ContextImage@ which is meant to be used with tag <img> + +{code} +//build the component specifying its id and picture's context path +ContextImage image = new ContextImage("myPicture", "/misc/imgs/mypic.png"); +{code} Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_6.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_6.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_6.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_6.gdoc Thu Feb 12 18:54:52 2015 @@ -1,25 +1,25 @@ -One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class @org.apache.wicket.ResourceBundles@ to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it: + + +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. + +For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page: {code} -@Override -public void init() { - super.init(); - - getResourceBundles().addJavaScriptBundle(WicketApplication.class, - "jqueryUiJs", - jqueryJsReference, - jqueryUiJsReference); - - getResourceBundles().addCssBundle(WicketApplication.class, - "jqueryUiCss", - jqueryCssReference, - jqueryUiCssReference); - -} +Url jqueyuiUrl = Url.parse("https://ajax.googleapis.com/ajax/libs/jqueryui/"; + + "1.10.2/jquery-ui.min.js"); + +UrlResourceReference jqueryuiRef = new UrlResourceReference(jqueyuiUrl){ + @Override + public Iterable<? extends HeaderItem> getDependencies() { + Application application = Application.get(); + ResourceReference jqueryRef = application.getJavaScriptLibrarySettings(). + getJQueryReference(); + + return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef)); + } +}; {code} -To declare a new resource bundle we need to provide a _scope_ class (@WicketApplication.class@ in our example) and an unique name. Now, when one of the resources included in the bundle is requested, the entire bundle is rendered instead. +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. -{note} -A specific resource reference can not be shared among different resource bundles (i.e. it can be part of only one bundle). -{note} +The same method @getDependencies()@ is defined also for class @HeaderItem@. \ No newline at end of file Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_7.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_7.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_7.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_7.gdoc Thu Feb 12 18:54:52 2015 @@ -1,103 +1,25 @@ -Some web developers prefer to put their <script> tags at the end of page body instead of inside the <head> tags: +One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class @org.apache.wicket.ResourceBundles@ to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it: -{code:html} - -<html> - -<head> -//no <script> tag here... -</head> - -<body> -... -<script> -//one or more <script> tags at the end of the body -</script> -</body> -</html> - -{code} - - -In Wicket we can achieve this result providing a custom @IHeaderResponseDecorator@ to a our application and using Wicket tag <wicket:container/> to indicate where we want to render our scripts inside the page. Interface @IHeaderResponseDecorator@ defines method @IHeaderResponse decorate(IHeaderResponse response)@ which allows to decorate or add funtionalities to Wicket @IHeaderResponse@. Our custom @IHeaderResponseDecorator@ can be registered in the application with method @setHeaderResponseDecorator@. Anytime Wicket creates an instance of @IHeaderResponse@, it will call the registered @IHeaderResponseDecorator@ to decorate the header response. - -In the example project @ScriptInsideBody@ we can find a custom @IHeaderResponseDecorator@ that renders CSS into the usual <head> tag and put JavaScricpt header items into a specific container (tag <wicket:container/>) -Wicket already comes with class @JavaScriptFilteredIntoFooterHeaderResponse@ which wraps a @IHeaderResponse@ and renders in a given container all the instances of @JavaScriptHeaderItem@. -The following code is taken from the Application class of the project: - -{code} - - //... - @Override - public void init() - { - setHeaderResponseDecorator(new JavaScriptToBucketResponseDecorator("footer-container")); - } - - /** - * Decorates an original IHeaderResponse and renders all javascript items - * (JavaScriptHeaderItem), to a specific container in the page. - */ - static class JavaScriptToBucketResponseDecorator implements IHeaderResponseDecorator - { - - private String bucketName; - - public JavaScriptToBucketResponseDecorator(String bucketName) { - this.bucketName = bucketName; - } - - @Override - public IHeaderResponse decorate(IHeaderResponse response) { - return new JavaScriptFilteredIntoFooterHeaderResponse(response, bucketName); - } - - } -{code} - -As you can see in the code above the "bucket" that will contain JavaScript tags is called @"footer-container"@. To make a use of it the developer have to add a special component called @HeaderResponseContainer@ in his page: - -{code} -add(new HeaderResponseContainer("someId", "filterName")); {code} - -Please note that @HeaderResponseContainer@'s needs also a name for the corresponding header response's filter. The markup of our page will look like this: - -{code:html} - -<html> - -<header> -//no <script> tag here... -</header> - -<body> -<!-- here we will have our JavaScript tags --> -<wicket:container wicket:id="someId"/> -</body> -</html> - -{code} - -The code of the home page is the following: - -{code} - public HomePage(final PageParameters parameters) { - super(parameters); - - add(new HeaderResponseContainer("footer-container", "footer-container")); - } - - @Override - public void renderHead(IHeaderResponse response) { - response.render(JavaScriptHeaderItem.forReference(new PackageResourceReference(getClass(), - "javasciptLibrary.js"))); - - response.render(OnEventHeaderItem.forScript("'logo'", "click", "alert('Clicked me!')")); - } -{code} - -Looking at the code above you can note that our page adds two script to the header section: the first is an instance of @JavaScriptHeaderItem@ and will be rendered in the @HeaderResponseContainer@ while the second will follow the usual behavior and will be rendered inside <head> tag. - - - +@Override +public void init() { + super.init(); + + getResourceBundles().addJavaScriptBundle(WicketApplication.class, + "jqueryUiJs", + jqueryJsReference, + jqueryUiJsReference); + + getResourceBundles().addCssBundle(WicketApplication.class, + "jqueryUiCss", + jqueryCssReference, + jqueryUiCssReference); + +} +{code} + +To declare a new resource bundle we need to provide a _scope_ class (@WicketApplication.class@ in our example) and an unique name. Now, when one of the resources included in the bundle is requested, the entire bundle is rendered instead. + +{note} +A specific resource reference can not be shared among different resource bundles (i.e. it can be part of only one bundle). +{note} Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_8.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_8.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_8.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_8.gdoc Thu Feb 12 18:54:52 2015 @@ -1,15 +1,103 @@ -Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag @<wicket:header-items/>@: +Some web developers prefer to put their <script> tags at the end of page body instead of inside the <head> tags: {code:html} + +<html> + <head> - <meta chartset="UTF-8"/> - <wicket:header-items/> - <script src="my-monkey-patch-of-wicket-ajax.js"></script> +//no <script> tag here... </head> + +<body> +... +<script> +//one or more <script> tags at the end of the body +</script> +</body> +</html> + +{code} + + +In Wicket we can achieve this result providing a custom @IHeaderResponseDecorator@ to a our application and using Wicket tag <wicket:container/> to indicate where we want to render our scripts inside the page. Interface @IHeaderResponseDecorator@ defines method @IHeaderResponse decorate(IHeaderResponse response)@ which allows to decorate or add funtionalities to Wicket @IHeaderResponse@. Our custom @IHeaderResponseDecorator@ can be registered in the application with method @setHeaderResponseDecorator@. Anytime Wicket creates an instance of @IHeaderResponse@, it will call the registered @IHeaderResponseDecorator@ to decorate the header response. + +In the example project @ScriptInsideBody@ we can find a custom @IHeaderResponseDecorator@ that renders CSS into the usual <head> tag and put JavaScricpt header items into a specific container (tag <wicket:container/>) +Wicket already comes with class @JavaScriptFilteredIntoFooterHeaderResponse@ which wraps a @IHeaderResponse@ and renders in a given container all the instances of @JavaScriptHeaderItem@. +The following code is taken from the Application class of the project: + +{code} + + //... + @Override + public void init() + { + setHeaderResponseDecorator(new JavaScriptToBucketResponseDecorator("footer-container")); + } + + /** + * Decorates an original IHeaderResponse and renders all javascript items + * (JavaScriptHeaderItem), to a specific container in the page. + */ + static class JavaScriptToBucketResponseDecorator implements IHeaderResponseDecorator + { + + private String bucketName; + + public JavaScriptToBucketResponseDecorator(String bucketName) { + this.bucketName = bucketName; + } + + @Override + public IHeaderResponse decorate(IHeaderResponse response) { + return new JavaScriptFilteredIntoFooterHeaderResponse(response, bucketName); + } + + } +{code} + +As you can see in the code above the "bucket" that will contain JavaScript tags is called @"footer-container"@. To make a use of it the developer have to add a special component called @HeaderResponseContainer@ in his page: + {code} +add(new HeaderResponseContainer("someId", "filterName")); +{code} + +Please note that @HeaderResponseContainer@'s needs also a name for the corresponding header response's filter. The markup of our page will look like this: + +{code:html} + +<html> + +<header> +//no <script> tag here... +</header> + +<body> +<!-- here we will have our JavaScript tags --> +<wicket:container wicket:id="someId"/> +</body> +</html> + +{code} + +The code of the home page is the following: + +{code} + public HomePage(final PageParameters parameters) { + super(parameters); + + add(new HeaderResponseContainer("footer-container", "footer-container")); + } + + @Override + public void renderHead(IHeaderResponse response) { + response.render(JavaScriptHeaderItem.forReference(new PackageResourceReference(getClass(), + "javasciptLibrary.js"))); + + response.render(OnEventHeaderItem.forScript("'logo'", "click", "alert('Clicked me!')")); + } +{code} + +Looking at the code above you can note that our page adds two script to the header section: the first is an instance of @JavaScriptHeaderItem@ and will be rendered in the @HeaderResponseContainer@ while the second will follow the usual behavior and will be rendered inside <head> tag. -With the code above all header contributions done by using IHeaderResponse in your Java code or the special @<wicket:head>@ tag will be put between the <meta> and <script> elements, i.e. in the place of @<wicket:header-items/>@. -This way you can make sure that some header item is always before or after the header items managed by Wicket. -@<wicket:header-items/>@ can be used only in the page's <head> element and there could be at most one instance of it. Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_9.gdoc URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_9.gdoc?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_9.gdoc (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/resources/resources_9.gdoc Thu Feb 12 18:54:52 2015 @@ -1,48 +1,15 @@ +Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag @<wicket:header-items/>@: - -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 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: - -{code} -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()... -} +{code:html} +<head> + <meta chartset="UTF-8"/> + <wicket:header-items/> + <script src="my-monkey-patch-of-wicket-ajax.js"></script> +</head> {code} -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. +With the code above all header contributions done by using IHeaderResponse in your Java code or the special @<wicket:head>@ tag will be put between the <meta> and <script> elements, i.e. in the place of @<wicket:header-items/>@. -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@: - -{code} -add(new ResourceLink("rssLink", new RSSProducerResource())); -{code} +This way you can make sure that some header item is always before or after the header items managed by Wicket. -In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL. \ No newline at end of file +@<wicket:header-items/>@ can be used only in the page's <head> element and there could be at most one instance of it. Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/toc.yml URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/toc.yml?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/toc.yml (original) +++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/toc.yml Thu Feb 12 18:54:52 2015 @@ -113,15 +113,16 @@ resources: resources_2: Resource references resources_3: Package resources resources_4: Adding resources to page header section - resources_5: Resource dependencies - resources_6: Aggregate multiple resources with resource bundles - resources_7: Put JavaScript inside page body - resources_8: Header contributors positioning - resources_9: Custom resources - resources_10: Mounting resources - resources_11: Shared resources - resources_12: Customizing resource loading - resources_13: Summary + resources_5: Context-relative resources + resources_6: Resource dependencies + resources_7: Aggregate multiple resources with resource bundles + resources_8: Put JavaScript inside page body + resources_9: Header contributors positioning + resources_10: Custom resources + resources_11: Mounting resources + resources_12: Shared resources + resources_13: Customizing resource loading + resources_14: Summary jsintegration: title: An example of integration with JavaScript jsintegration_1: What we want to do... Modified: wicket/common/site/trunk/_site/guide/guide/testing.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/testing.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/testing.html (original) +++ wicket/common/site/trunk/_site/guide/guide/testing.html Thu Feb 12 18:54:52 2015 @@ -430,7 +430,7 @@ formTester.submit(<span class="java- <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/testingspring.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/testingspring.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/testingspring.html (original) +++ wicket/common/site/trunk/_site/guide/guide/testingspring.html Thu Feb 12 18:54:52 2015 @@ -324,7 +324,7 @@ Since the development of many web applic <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/urls.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/urls.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/urls.html (original) +++ wicket/common/site/trunk/_site/guide/guide/urls.html Thu Feb 12 18:54:52 2015 @@ -372,7 +372,7 @@ By default <code>CryptoMapper</code> enc <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/versioningCaching.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/versioningCaching.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/versioningCaching.html (original) +++ wicket/common/site/trunk/_site/guide/guide/versioningCaching.html Thu Feb 12 18:54:52 2015 @@ -293,7 +293,7 @@ Page '<page class>' is not state <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/whyLearn.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/whyLearn.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/whyLearn.html (original) +++ wicket/common/site/trunk/_site/guide/guide/whyLearn.html Thu Feb 12 18:54:52 2015 @@ -247,7 +247,7 @@ Wicket is not the only component oriente <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div> Modified: wicket/common/site/trunk/_site/guide/guide/wicketstuff.html URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/wicketstuff.html?rev=1659361&r1=1659360&r2=1659361&view=diff ============================================================================== --- wicket/common/site/trunk/_site/guide/guide/wicketstuff.html (original) +++ wicket/common/site/trunk/_site/guide/guide/wicketstuff.html Thu Feb 12 18:54:52 2015 @@ -333,7 +333,7 @@ A short introduction to this module can <div id="footer"> Copyright © 2013-2014 â <a href="http://www.apache.org/"; target="_blank">The Apache Software Foundation</a> - â <b style="color:#E8590A !important;">(Generated on: 2015-02-03)</b> + â <b style="color:#E8590A !important;">(Generated on: 2015-02-12)</b> </div>
