http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc deleted file mode 100644 index b49c74a..0000000 --- a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc +++ /dev/null @@ -1,92 +0,0 @@ - - -Class @org.apache.wicket.request.cycle.RequestCycle@ is the entity in charge of serving a web request. Our application class creates a new @RequestCycle@ on every request with its method @createRequestCycle(request, response)@. - -Method @createRequestCycle@ is declared as final, so we can't override it to return a custom subclass of @RequestCycle@. Instead, we must build a request cycle provider implementing interface @org.apache.wicket.IRequestCycleProvider@, and then we must tell our application class to use it via the @setRequestCycleProvider@ method. - -The current running request cycle can be retrieved at any time by calling its static method @RequestCycle.get()@. Strictly speaking this method returns the request cycle associated with the current (or local) thread, which is the thread that is serving the current request. A similar @get()@ method is also implemented in classes @org.apache.wicket.Application@ (as we have seen in [paragraph 4.2.2|guide:helloWorld_2]) and @org.apache.wicket.Session@ in order to get the application and the session in use by the current thread. - -{note} -The implementation of the get method takes advantage of the standard class @java.lang.ThreadLocal@. See its JavaDoc for an introduction to local-thread variables. -{note} - -Class @org.apache.wicket.Component@ provides the @getRequestCycle()@ method which is a convenience method that internally invokes @RequestCycle.get()@: - -{code} -public final RequestCycle getRequestCycle() { - return RequestCycle.get(); -} -{code} - -h3. RequestCycle and request processing - -{note} -This paragraph will provide just the basic informations about what happens behind the scenes of request processing. When you work with Wicket it's unlikely to have a need for customizing this process, so we won't cover this topic in detail. -{note} - -In order to process a request, @RequestCycle@ delegates the task to another entity which implements interface @org.apache.wicket.request.IRequestHandler@. There are different implementations of this interface, each suited for a particular type of requested resource (a page to render, an AJAX request, an URL to an external page, etc.). - -To resolve the right handler for a given HTTP request, the @RequestCycle@ uses a set of objects implementing the @org.apache.wicket.request.IRequestMapper@ interface. The mapping interface defines the @getCompatibilityScore(Request request)@ method which returns a score indicating how compatible the request mapper is for the current request. @RequestCycle@ will choose the mapper with the highest score and it will call its @mapRequest(Request request)@ method to get the proper handler for the given request. Once @RequestCycle@ has resolved a request handler, it invokes its method @respond(IRequestCycle requestCycle)@ to start request processing. - -The following sequence diagram recaps how a request handler is resolved by the @RequestCycle@: - -!request-cycle-handler.png! - -Developers can create additional implementations of IRequestMapper and add them to their application via the mount(IRequestMapper mapper) method of the WebApplication class. In paragraph 10.6 we will see how Wicket uses this method to add built-in mappers for mounted pages. - -h3. Generating URL with the urlFor and mapUrlFor methods - -The RequestCycle is also responsible for generating the URL value (as CharSequence) for the following entities: - -* a page class, via the @urlFor(Class<C> pageClass, PageParameters parameters)@ method -* an IRequestHandler via the @urlFor(IRequestHandler handler)@ method -* a ResourceReference via the @urlFor(ResourceReference reference, PageParameters params)@ method (resource entities will be introduced in [chapter 19|guide:resources]). - -The overloaded @urlFor@ method from above also has a corresponding version that returns an instance of @org.apache.wicket.request.Url@ instead of a @CharSequence@. This version has the prefix 'map' in its name (i.e. it has @mapUrlFor@ as full name). - -h3. Method setResponsePage - -The @RequestCycle@ class contains the implementation of the @setResponsePage@ method we use to redirect a user to a specific page (see [paragraph 4.4|guide:helloWorld_4]). The namesake method of class @org.apache.wicket.Component@ is just a convenience method that internally invokes the actual implementation on current request cycle: - -{code} -public final void setResponsePage(final Page page) { - getRequestCycle().setResponsePage(page); -} -{code} - -h3. RequestCycle's hook methods and listeners - -The RequestCycle comes with some hook methods which can be overridden to perform custom actions when request handling reaches a specific stage. These methods are: -* *onBeginRequest():* called when the RequestCycle is about to start handling the request. -* *onEndRequest():* called when the RequestCycle has finished to handle the request -* *onDetach():* called after the request handling has completed and the RequestCycle is about to be detached from its thread. The default implementation of this method invokes detach() on the current session (the Session class will be shortly discussed in paragraph 9.4). - -Methods onBeforeRequest and onEndRequest can be used if we need to execute custom actions before and after business code is executed, such as opening a Hibernate/JPA session and closing it when code has terminated. - -A more flexible way to interact with the request processing is to use the listener interface @org.apache.wicket.request.cycle.IRequestCycleListener@. In addition to the three methods already seen for RequestCycle, this interface offers further hooks into request processing: -* *onBeginRequest(RequestCycle cycle):* (see the description above) -* *onEndRequest(RequestCycle cycle):* (see the description above) -* *onDetach(RequestCycle cycle):* (see the description above) -* *onRequestHandlerResolved(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been resolved. -* *onRequestHandlerScheduled(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been scheduled for execution. -* *onRequestHandlerExecuted(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been executed. -* *onException(RequestCycle cycle, Exception ex):* called when an exception has been thrown during request processing. -* *onExceptionRequestHandlerResolved(RequestCycle rc, IRequestHandler rh, Exception ex):* called when an IRequestHandler has been resolved and will be used to handle an exception. -* *onUrlMapped(RequestCycle cycle, IRequestHandler handler, Url url):* called when an URL has been generated for an IRequestHandler object. - -To use the request cycle listeners we must add them to our application which in turn will pass them to the new @RequestCycle@'s instances created with @createRequestCycle@ method: - -{code} -@Override -public void init() { - - super.init(); - - IRequestCycleListener myListener; - //listener initialization... - getRequestCycleListeners().add(myListener) -} -{code} - -The @getRequestCycleListeners@ method returns an instance of class @org.apache.wicket.request.cycle.RequestCycleListenerCollection@. This class is a sort of typed collection for @IRequestCycleListener@ and it also implements the "Composite pattern":http://en.wikipedia.org/wiki/Composite_pattern . -
http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc deleted file mode 100644 index 393e0ac..0000000 --- a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc +++ /dev/null @@ -1,154 +0,0 @@ - - -In Wicket we use class @org.apache.wicket.Session@ to handle session-relative informations such as client informations, session attributes, session-level cache (seen in paragraph 8.2), etc... - -In addition, we know from paragraph 8.1 that Wicket creates a user session to store versions of stateful pages. Similarly to what happens with RequestCycle, the new Session's instances are generated by the @Application@ class with the @newSession(Request request, Response response)@ method. This method is not declared as final, hence it can be overridden if we need to use a custom implementation of the Session class. - -By default if our custom application class is a subclass of WebApplication, method newSession will return an instance of class @org.apache.wicket.protocol.http.WebSession@. As we have mentioned talking about @RequestCycle@, also class Session provides a static @get()@ method which returns the session associated to the current thread. - -h3. Session and listeners - -Similar to the @RequestCycle@, class @org.apache.wicket.Session@ also offers support for listener entities. With Session these entities must implement the callback interface @org.apache.wicket.ISessionListener@ which exposes only the @onCreated(Session session)@ method. As you might guess from its name, this method is called when a new session is created. Session listeners must be added to our application using a typed collection, just like we have done before with request cycle listeners: - -{code} -@Override -public void init(){ - - super.init(); - - //listener initialization... - ISessionListener myListener; - //add a custom session listener - getSessionListeners().add(myListener) - -} -{code} - -h3. Handling session attributes - -The Session class handles session attributes in much the same way as the standard interface javax.servlet.http.HttpSession. The following methods are provided to create, read and remove session attributes: - -* *setAttribute(String name, Serializable value):* creates an attribute identified by the given name. If the session already contains an attribute with the same name, the new value will replace the existing one. The value must be a serializable object. -* *getAttribute(String name):* returns the value of the attribute identified by the given name, or null if the name does not correspond to any attribute. -* *removeAttribute(String name):* removes the attribute identified by the given name. - -By default class WebSession will use the underlying HTTP session to store attributes. Wicket will automatically add a prefix to the name of the attributes. This prefix is returned by the WebApplication's method getSessionAttributePrefix(). - -h3. Accessing to the HTTP session - -If for any reason we need to directly access to the underlying HttpSession object, we can retrieve it from the current request with the following code: - -{code} -HttpSession session = ((ServletWebRequest)RequestCycle.get() - .getRequest()).getContainerRequest().getSession(); -{code} - -Using the raw session object might be necessary if we have to set a session attribute with a particular name without the prefix added by Wicket. Let's say for example that we are working with Tomcat as web server. One of the administrative tools provided by Tomcat is a page listing all the active user sessions of a given web application: - -!tomcat-admin-sessions.png! - -Tomcat allows us to set the values that will be displayed in columns âGuessed localeâ and âGuessed User nameâ. One possible way to do this is to use session attributes named âLocaleâ and âuserNameâ but we can't create them via Wicket's Session class because they would not have exactly the name required by Tomcat. Instead, we must use the raw HttpSession and set our attributes on it: - -{code} -HttpSession session = ((ServletWebRequest)RequestCycle.get(). - getRequest()).getContainerRequest().getSession(); - -session.setAttribute("Locale", "ENGLISH"); -session.setAttribute("userName", "Mr BadGuy"); -{code} - -h3. Temporary and permanent sessions - -Wicket doesn't need to store data into user session as long as the user visits only stateless pages. Nonetheless, even under these conditions, a temporary session object is created to process each request but it is discarded at the end of the current request. To know if the current session is temporary, we can use the isTemporary() method: - -{code} -Session.get().isTemporary(); -{code} - -If a session is not temporary (i.e. it is permanent), it's identified by an unique id which can be read calling the getId() method. This value will be null if the session is temporary. - -Although Wicket is able to automatically recognize when it needs to replace a temporary session with a permanent one, sometimes we may need to manually control this process to make our initially temporary session permanent. - -To illustrate this possible scenario let's consider project BindSessionExample where we have a stateless home page which sets a session attribute inside its constructor and then it redirects the user to another page which displays with a label the session attribute previously created. The code of the two pages is as follows: - -Home page: -{code} -public class HomePage extends WebPage { - public HomePage(final PageParameters parameters) { - Session.get().setAttribute("username", "tommy"); - Session.get().bind(); - - setResponsePage(DisplaySessionParameter.class); - } -} -{code} - -Target page: - -{code} -public class DisplaySessionParameter extends WebPage { - - public DisplaySessionParameter() { - super(); - add(new Label("username", (String) Session.get().getAttribute("username"))); - } -} -{code} - -Again, we kept page logic very simple to not over-bloat the example with unnecessary code. In the snippet above we have also bolded Session's bind() method which converts temporary session into a permanent one. If the home page has not invoked this method, the session with its attribute would have been discarded at the end of the request and the page DisplaySessionParameter would have displayed an empty value in its label. - -h3. Discarding session data - -Once a user has finished using our web application, she must be able to log out and clean any session data. To be sure that a permanent session will be discarded at the end of the current request, class Session provides the invalidate() method. If we want to immediately invalidate a given session without waiting for the current request to complete, we can invoke the invalidateNow() method. - -{warning} -Remember that invalidateNow() will immediately remove any instance of components (and pages) from the session, meaning that once we have called this method we won't be able to work with them for the rest of the request process. -{warning} - -h3. Storing arbitrary objects with metadata - -JavaServer Pages Specification1 defines 4 scopes in which a page can create and access a variable. These scopes are: - -* *request:* variables declared in this scope can be seen only by pages processing the same request. The lifespan of these variables is (at most) equal to the one of the related request. They are discarded when the full response has been generated or when the request is forwarded somewhere else. -* *page:* variables declared in this scope can be seen only by the page that has created them. -* *session:* variables in session scope can be created and accessed by every page used in the same session where they are defined. -* *application:* this is the widest scope. Variables declared in this scope can be used by any page of a given web application. - -Although Wicket doesn't implement the JSP Specification (it is rather an alternative to it), it offers a feature called metadata which resembles scoped variables but is much more powerful. Metadata is quite similar to a Java Map in that it stores pairs of key-value objects where the key must be unique. In Wicket each of the following classes has its own metadata store: RequestCycle, Session, Application and Component. - -The key used for metadata is an instance of class @org.apache.wicket.MetaDataKey<T>@. To put an arbitrary object into metadata we must use the setMetaData method which takes two parameters as input: the key used to store the value and the value itself. If we are using metadata with classes Session or Component, data object must be serializable because Wicket serializes both session and component instances. This constraint is not applied to metadata of classes Application and RequestCycle which can contain a generic object. In any case, the type of data object must be compatible with the type parameter T specified by the key. - -To retrieve a previously inserted object we must use the @getMetaData(MetaDataKey<T> key)@ method. In the following example we set a @java.sql.Connection@ object in the application's metadata so it can be used by any page of the application: - -Application class code: -{code} -public static MetaDataApp extends WebApplication{ - //Do some stuff... - /** - * Metadata key definition - */ - public static MetaDataKey<Connection> connectionKey = new MetaDataKey<Connection> (){}; - - /** - * Application's initialization - */ - @Override - public void init(){ - - super.init(); - Connection connection; - //connection initialization... - setMetaData(connectionKey, connection); - //Do some other stuff.. - - } -} -{code} - -Code to get the object from the metadata: - -{code} -Connection connection = Application.get().getMetaData(MetaDataApp.connectionKey); -{code} - -Since MetaDataKey<T> class is declared as abstract, we must implement it with a subclass or with an anonymous class (like we did in the example above). http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc deleted file mode 100644 index 329a67d..0000000 --- a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc +++ /dev/null @@ -1,35 +0,0 @@ -Wicket uses a number of custom exceptions during the regular running of an application. We have already seen @PageExpiredException@ raised when a page version is expired. Other examples of such exceptions are @AuthorizationException@ and @RestartResponseException@. We will see them later in the next chapters. -All the other exceptions raised during rendering phase are handled by an implementation of @org.apache.wicket.request.IExceptionMapper@ which by default is class @org.apache.wicket.DefaultExceptionMapper@. If we are working in DEVELOPMENT mode this mapper will redirect us to a page that shows the exception stacktrace (page @ExceptionErrorPage@). On the contrary, if application is running in DEPLOYMENT mode @DefaultExceptionMapper@ will display an internal error page which by default is @org.apache.wicket.markup.html.pages.InternalErrorPage@. -To use a custom internal error page we can change application settings like this: - -{code} -getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class); -{code} - -We can also manually set if Wicket should display the exception with @ExceptionErrorPage@ or if we want to use the internal error page or if we don't want to display anything at all when an unexpected exception is thrown: - -{code} -//show default developer page -getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_EXCEPTION_PAGE ); -//show internal error page -getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_INTERNAL_ERROR_PAGE ); -//show no exception page when an unexpected exception is thrown -getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_NO_EXCEPTION_PAGE ); -{code} - -Developers can also decide to use a custom exception mapper instead of @DefaultExceptionMapper@. To do this we must override @Application@'s method @getExceptionMapperProvider@: - -{code} -@Override -public IProvider<IExceptionMapper> getExceptionMapperProvider() -{ - //... -} -{code} - -The method returns an instance of @org.apache.wicket.util.IProvider@ that should return our custom exception mapper. - -h3. Ajax requests - -To control the behavior in Ajax requests the application may use @org.apache.wicket.settings.ExceptionSettings# setAjaxErrorHandlingStrategy(ExceptionSettings.AjaxErrorStrategy)@. By default if an error occurs during the -processing of an Ajax request Wicket will render the configured error page. By configuring @org.apache.wicket.settings.ExceptionSettings. AjaxErrorStrategy#INVOKE_FAILURE_HANDLER@ as the default strategy the application will call the JavaScript @onFailure@ callback(s) instead. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc deleted file mode 100644 index 4d9e5c3..0000000 --- a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc +++ /dev/null @@ -1,5 +0,0 @@ - - -In this chapter we had a look at how Wicket internally handles a web request. Even if most of the time we won't need to customize this internal process, knowing how it works is essential to use the framework at 100%. - -Entities like Application and Session will come in handy again when we will tackle the topic of security in [chapter 23|guide:security]. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources.gdoc b/wicket-user-guide/src/docs/guide/resources.gdoc deleted file mode 100644 index ff01f7c..0000000 --- a/wicket-user-guide/src/docs/guide/resources.gdoc +++ /dev/null @@ -1,5 +0,0 @@ -One of the biggest challenge for a web framework is to offer an efficient and consistent mechanism to handle internal resources such as CSS/JavaScript files, picture files, pdf and so on. Resources can be static (like an icon used across the site) or dynamic (they can be generated on the fly) and they can be made available to users as a download or as a simple URL. - -In [paragraph 6.6|guide:keepControl_6] we have already seen how to add CSS and JavaScript contents to the header section of the page. In the first half of this chapter we will learn a more sophisticated technique that allows us to manage static resources directly from code and âpackâ them with our custom components. - -Then, in the second part of the chapter we will see how to implement custom resources to enrich our web application with more complex and dynamic functionalities. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc deleted file mode 100644 index 5847bb3..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc +++ /dev/null @@ -1,9 +0,0 @@ - - -In Wicket a resource is an entity that can interact with the current request and response and It must implement interface @org.apache.wicket.request.resource.IResource@. This interface defines just method respond(IResource.Attributes attributes) where the nested class IResource. Attributes provides access to request, response and page parameters objects. - -Resources can be static or dynamic. Static resources don't entail any computational effort to be generated and they generally correspond to a resource on the filesystem. On the contrary dynamic resources are generated on the fly when they are requested, following a specific logic coded inside them. - -An example of dynamic resource is the built-in class CaptchaImageResource in package @org.apache.wicket.extensions.markup.html.captcha@ which generates a captcha image each time is rendered. - -As we will see in [paragraph 16.10|guide:resources_10], developers can build custom resources extending base class @org.apache.wicket.request.resource.AbstractResource@. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc deleted file mode 100644 index a841416..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc +++ /dev/null @@ -1,48 +0,0 @@ - - -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 16.1|guide:resources_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} - -Method @newResourceResponse@ returns an instance of @ResourceResponse@ representing the response generated by the custom resource. Since RSS feeds are based on XML, in the code above we have set the type of the response to text/xml and the text encoding to utf-8. - -To specify the content that will be returned by our resource we must also provide an implementation of inner class @WriteCallback@ which is responsible for writing content data to response's output stream. In our project we used class SyndFeedOutput from Rome framework to write our feed to response. Method @getFeed()@ is just an utility method that generates a sample RSS feed (which is an instance of interface @com.sun.syndication.feed.synd.SyndFeed@). - -Now that we have our custom resource in place, we can use it in the home page of the project. The easiest way to make a resource available to users is to expose it with link component @ResourceLink@: - -{code} -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. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc deleted file mode 100644 index 9d62202..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc +++ /dev/null @@ -1,37 +0,0 @@ - - -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 10.6.1|guide:urls_6]: - -{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); -} -{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. - -Parameter placeholders are supported as well: - -{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} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc deleted file mode 100644 index 550dabe..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc +++ /dev/null @@ -1,33 +0,0 @@ - - -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(){ - RSSProducerResource rssResource = new RSSProducerResource(); - // ... - getSharedResources().add("globalRSSProducer", rssResource); - } -{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: - -{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@ - -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 http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc deleted file mode 100644 index ee12183..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc +++ /dev/null @@ -1,45 +0,0 @@ - - -Wicket loads application's resources delegating this task to a resource locator represented by interface @org.apache.wicket.core.util.resource.locator.IResourceStreamLocator@. To retrieve or modify the current resource locator we can use the getter and setter methods defined by setting class @ResourceSettings@: - -{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 class ResourceSettings returns the list of resource finders defined in our application. The constructor of WebApplicationPath takes in input also an instance of standard interface javax.servlet.ServletContext which can be retrieved with WebApplication's method getServletContext(). - -{note} -By default, if resource files can not be found inside application classpath, Wicket will search for them inside â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} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc deleted file mode 100644 index 946456a..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc +++ /dev/null @@ -1,69 +0,0 @@ - - -Introduced in Wicket 6.20.0 / Wicket 7.0.0 there is a default way to be used in which the output of all CssHeaderItems / JavaScriptHeaderItems is modified before they are cached and delivered to the client. You can add a so called Compressor by receiving the resource settings and invoke #setJavaScriptCompressor(...) / #setJavaScriptCompressor(...). If you want to add several Compressors use @org.apache.wicket.resource.CompositeCssCompressor@ or @org.apache.wicket.resource.CompositeJavaScriptCompressor@ - -*Java Code:* -{code} -... -Â Â Â public class WicketApplication extends WebApplication -Â Â Â { -Â Â Â Â Â Â @Override -Â Â Â Â Â Â public Class<? extends WebPage> getHomePage() -Â Â Â Â Â Â { -Â Â Â Â Â Â Â Â Â return HomePage.class; -Â Â Â Â Â Â } -Â Â Â -Â Â Â Â Â Â @Override -Â Â Â Â Â Â public void init() -Â Â Â Â Â Â { -Â Â Â Â Â Â Â Â Â super.init(); -Â Â Â Â Â Â Â Â Â getResourceSettings().setCssCompressor(new CssUrlReplacer()); -Â Â Â Â Â Â } -Â Â Â } -... -{code} - -In the previous example you see that a @org.apache.wicket.resource.CssUrlReplacer@ is added which does not compress the content, but replaces all urls in CSS files and applies a Wicket representation for them by automatically wrapping them into PackageResourceReferences. Here is an example where you can see what Wicket does with the url representation. - -HomePage (in package my/company/): -*Java Code:* -{code} -... -response.render(CssReferenceHeaderItem.forReference(new PackageResourceReference(HomePage.class, "res/css/mycss.css"))); -... -{code} - -mycss.css (in package my/company/res/css/): -*CSS:* -{code} -... -body{ -Â Â Â background-image:url('../images/some.png'); -} -... -{code} - -some.png (in package my/company/res/images/): -<blob> - -Output of mycss.css: -*CSS:* -{code} -... -body{ -Â Â Â background-image:url('../images/some-ver-1425904170000.png'); -} -... -{code} - -If you add a url which looks like this background-image:url('../images/some.png?embedBase64'); Wicket is going to embed the complete image as base64 string with its corresponding mime type into the css file. It looks like the following code block demonstrates. - -Output of mycss.css: -*CSS:* -{code} -... -body{ -Â Â Â background-image: url(data:image/png;base64,R0lGODlh1wATAX....); -} -... -{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc deleted file mode 100644 index 475473a..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc +++ /dev/null @@ -1,62 +0,0 @@ -The FileSystemResourceRenference comes along with the FileSystemResource, FileSystemResourceStreamReference and the FileSystemResourceStream. Those classes provide a simple way to handle resources with Java's NIO API in Wicket starting from JDK version 7.0. (Available since Wicket 7.2.0 / Wicket 8.0.0) - -Example: To include a resource which is zipped into a file and located in a specific folder in the file system you can simply write code like this: - -Java: -{code} -URI uri = URI.create("jar:file:///videosFolder/videos.zip!/folderInZip/Video.mp4"); -Path path = FileSystemResourceReference.getPath(uri); -FileSystemResourceReference ref = new FileSystemResourceReference("video",path); -Video video = new Video("video",ref); -add(vide); -{code} - -HTML: -{code} -<video wicket:id="video"/> -{code} - -Using FileSystemResourceReference mounted: - -Java: -{code} -mountResource("/filecontent/${name}", new FileSystemResourceReference("filesystem") -{ - private static final long serialVersionUID = 1L; - - @Override - public IResource getResource() - { - return new FileSystemResource() - { - private static final long serialVersionUID = 1L; - - protected ResourceResponse newResourceResponse(Attributes attributes) - { - try - { - String name = attributes.getParameters().get("name").toString(""); - URI uri = URI.create( - "jar:file:////folder/example.zip!/zipfolder/" + name); - return createResourceResponse( - FileSystemResourceReference.getPath(uri)); - } - catch (IOException | URISyntaxException e) - { - throw new WicketRuntimeException("Error while reading the file.", e); - } - }; - }; - } -}); -{code} - -FileSystemResourceReference.getPath(uri) uses a FileSystemPathService to setup a path the resource reference can work on. - -So if you write a custom file system you can easily handle every path by adding a *org.apache.wicket.resource.FileSystemPathService* text file into *META-INF/services* and put in your implementation. - -A reference implementation can be found in the java class org.apache.wicket.resource.FileSystemJarPathService. - -Further FileSystemProviders and the corresponding FileSystems can be implemented as described here: - -[http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html|http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_16.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_16.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_16.gdoc deleted file mode 100644 index 21b1419..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_16.gdoc +++ /dev/null @@ -1,20 +0,0 @@ -Another way to receive external image resources is to use the corresponding component with a model which contains the target URL. - -The ExternalImage and ExternalSource components which are available since Wicket 7.2.0 / Wicket 8.0.0 fulfill that task. - -The following example demonstrates the usage of a CompoundPropertyModel with the model object "ImageSrc". The model object, bound to surrounding component / page, contains an attribute named "url" which is read by the component: - -Java: -{code} -ImageSrc imageSrc = new ImageSrc(); -imageSrc.setUrl("http://www.google.de/test.jpg";); -setDefaultModel(new CompoundPropertyModel<>(imageSrc)); -add(new ExternalImage("url")); -{code} - -HTML: -{code} -<img wicket:id="url" /> -{code} - -The ExternalImage can also be constructed by passing in a Model (src) and Model of List (srcSet). For ExternalSource only the srcSet is available. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_17.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_17.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_17.gdoc deleted file mode 100644 index f522ac9..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_17.gdoc +++ /dev/null @@ -1,7 +0,0 @@ - - -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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc deleted file mode 100644 index 771d594..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc +++ /dev/null @@ -1,3 +0,0 @@ - - -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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc deleted file mode 100644 index cd5e8f6..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc +++ /dev/null @@ -1,170 +0,0 @@ - - -With HTML we use to include static resources in our pages using tags like <script>, <link> or <img>. This is what we have done so far writing our custom panels and pages. However, when we work with a component-oriented framework like Wicket, this classic approach becomes inadequate because it makes custom components hardly reusable. This happens when a component depends on a big number of resources. In such a case, if somebody wanted to use our custom component in his application, he would be forced to know which resources it depends on and make them available. - -To solve this problem Wicket allows us to place static resource files into component package (like we do with markup and properties files) and load them from component code. - -These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot): - -!package-resources.png! - -With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies. - -To load package resources Wicket provides class @org.apache.wicket.request.resource.PackageResourceReference@. - -To identify a package resource we need to specify a class inside the target package and the name of the desired resource (most of the times this will be a file name). - -In the following example taken from project ImageAsPackageRes, CustomPanel loads a picture file available as package resource and it displays it in a <img> tag using the built-in component @org.apache.wicket.markup.html.image.Image@: - -*HTML:* -{code:html} -<html> -<head>...</head> -<body> -<wicket:panel> - Package resource image: <img wicket:id="packageResPicture"/> -</wicket:panel> -</body> -</html> -{code} - -*Jave Code:* -{code} -public class CustomPanel extends Panel { - - public CustomPanel(String id) { - super(id); - PackageResourceReference resourceReference = - new PackageResourceReference(getClass(), "calendar.jpg"); - add(new Image("packageResPicture", resourceReference)); - } -} -{code} - -Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure: - -@<path to application root>/wicket/resource/<fully qualified classname>/<resource file name>-<ver-<id>>(.file extension)@ - -In our example the URL for our picture file calendar.jpg is the following: - -@./wicket/resource/org.wicketTutorial.CustomPanel/calendar-ver-1297887542000.jpg@ - -The first part of the URL is the relative path to the application root. In our example our page is already at the application's root so we have only a single-dotted segment. The next two segments, wicket and resource, are respectively the namespace and the identifier for resources seen in [paragraph 10.6.4|guide:urls_6]. - -The fourth segment is the fully qualified name of the class used to locate the resource and it is the scope of the package resource. In the last segment of the URL we can find the name of the resource (the file name). - -As you can see Wicket has automatically appended to the file name a version identifier (ver-1297887542000). When Wicket runs in DEVELOPMENT mode this identifier contains the timestamp in millisecond indicating the last time the resource file was modified. This can be useful when we are developing our application and resource files are frequently modified. Appending the timestamp to the original name we are sure that our browser will use always the last version of the file and not an old, out of date, cached version. - -When instead Wicket is running in DEPLOYMENT mode, the version identifier will contain the MD5 digest of the file instead of the timestamp. The digest is computed only the first time the resource is requested. This perfectly makes sense as static resources don't change so often when our application runs into production environment and when this appends the application is redeployed. - -{note} -Package resources can be localized following the same rules seen for resource bundles and markup files: - -!package-resource-localization.png! - -In the example illustrated in the picture above, if we try to retrieve package resource calendar.jpg when the current locale is set to French, the actual file returned will be calendar_fr.jpg. -{note} - -h3. Responsive images - multiple resource references use in one component - -Since Wicket 7.0.0 the build-in component @org.apache.wicket.markup.html.image.Image@ allows you to add several ResourceReferences via varargs and to provide sizes for each image so that the browser is able to pick the best image source. - -*HTML:* -{code:html} -... - Package resource image: <img wicket:id="packageResPicture"/> -... -{code} - -*Java Code:* -{code} -... - Image image = new Image("packageResPicture", - new PackageResourceReference(getClass(),"small.jpg"), - new PackageResourceReference(getClass(), "large.jpg"), - new PackageResourceReference(getClass(), "medium.jpg"), - new PackageResourceReference(getClass(), "small.jpg")); - image.setXValues("1024w", "640w", "320w"); - image.setSizes("(min-width: 36em) 33.3vw", "100vw"); - - this.add(image); -... -{code} - -The component @org.apache.wicket.markup.html.image.Picture@ is used to provide a fallback image @org.apache.wicket.markup.html.image.Image@ and several source components @org.apache.wicket.markup.html.image.Source@ which gives a developer the control as to when and if those images are presented to the user. - -*HTML:* -{code:html} -... - <picture wicket:id="picture"> - <source wicket:id="big" /> - <source wicket:id="small" /> - <img wicket:id="fallback" /> - </picture> -... -{code} - -*Java Code:* -{code} -... - Picture picture = new Picture("picture"); - - Source big = new Source("big", new PackageResourceReference(getClass(), "big.jpg"), new PackageResourceReference(getClass(), "big-hd.jpg"); - big.setXValues("1x","2x"); - big.setMedia("(min-width: 40em)"); - picture.add(big); - - Source small = new Source("small", new PackageResourceReference(getClass(), "small.jpg"), new PackageResourceReference(getClass(), "small-hd.jpg"); - small.setXValues("1x","2x"); - picture.add(small); - - Image image = new Image("fallback", new PackageResourceReference(getClass(), "fallback.jpg")); - picture.add(image); - - this.add(picture); -... -{code} - -h3. Inline Image - embedded resource reference content - -In some components like in the inline image resource references are going to be translated to other representations like base64 content. - -*Java Code:* -{code} -... - add(new InlineImage("inline", new PackageResourceReference(getClass(),"image2.gif"))); -... -{code} - - -h3. Media tags - resource references with content range support - -Since Wicket 7.0.0 the PackageResource and the PackageResourceReference support "Range" HTTP header for the request and "Content-Range" / "Accept-Range" HTTP headers for the response, which are used for videos / audio tags. The "Range" header allows the client to only request a specific byte range of the resource. The server provides the "Content-Range" and tells the client which bytes are going to be send. - -If you want the resource not to be load into memory apply readBuffered(false) - this way the stream is written directly to the response. (@org.apache.wicket.resource.ITextResourceCompressor@ will not be applied if readBuffered is set to false) - -*HTML:* -{code:html} -... - <video wicket:id="video" /> -... -{code} - -*Java Code:* -{code} -... - Video video = new Video("video", new PackageResourceReference(getClass(),"video.mp4").readBuffered(false)); -... -{code} - -h3. Using package resources with tag <wicket:link> - -In [paragraph 10.3|guide:urls_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: - -{code:html} -<wicket:link> - <img src="icon.png"/> -</wicket:link> -{code} - -In the example above Wicket will populate the attribute src with the URL corresponding to the package resource icon.png. <wicket:link> supports also tag <link> for CSS files and tag <script> for JavaScript files. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc deleted file mode 100644 index a051718..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc +++ /dev/null @@ -1,32 +0,0 @@ - - -Wicket comes with interface @org.apache.wicket.markup.html.IHeaderContributor@ which allows components and behaviors (which will be introduced later in [paragraph 18.1|guide:advanced_1]) to contribute to the header section of their page. The only method defined in this interface is @renderHead(IHeaderResponse response)@ where @IHeaderResponse@ is an interface which defines method @render(HeaderItem item)@ to write static resources or free-form text into the header section of the page. - -Header entries are instances of abstract class @org.apache.wicket.markup.head.HeaderItem@. Wicket provides a set of built-in implementations of this class suited for the most common types of resources. With the exception of @PriorityHeaderItem@, every implementation of @HeaderItem@ is an abstract factory class: - -* *CssHeaderItem:* represents a CSS resource. Factory methods provided by this class are @forReference@ which takes in input a resource reference, @forUrl@ which creates an CSS item from a given URL and @forCSS@ which takes in input an arbitrary CSS string and an optional id value to identify the resource. -* *JavaScriptHeaderItem:* represents a JavaScript resource. Just like @CssHeaderItem@ it provides factory methods @forReference@ and @forUrl@ along with method @forScript@ which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method @forReference@ also supports boolean parameter @defer@ which renders the namesake attribute in the script tag (@defer@ attribute indicates that our script must be execute only after the page has loaded). -* *OnDomReadyHeaderItem:* it adds JavaScript code that will be executed after the DOM has been built, but before external files (such as picture, CSS, etc...) have been loaded. The class provides a factory method @forScript@ which takes in input an arbitrary string representing the script to execute. -* *OnEventHeaderItem:* the JavaScript code added with this class is executed when a specific JavaScript event is triggered on a given DOM element. The factory method is @forScript(String target, String event, CharSequence javaScript)@, where target is the id of a DOM element (or the element itself), event is the event that must trigger our code and javaScript is the code to execute. -* *OnLoadHeaderItem:* the JavaScript code added with this class is executed after the whole page is loaded, external files included. The factory method is @forScript(CharSequence javaScript)@. -* *PriorityHeaderItem:* it wraps another header item and ensures that it will have the priority over the other items during rendering phase. -* *StringHeaderItem:* with this class we can add an arbitrary text to the header section. Factory method is @forString(CharSequence string)@. -* *MetaDataHeaderItem:* starting from version 6.17.0, Wicket provides this class to handle meta informations such as <meta> tags or [canonical link element|http://en.wikipedia.org/wiki/Canonical_link_element]. The available factory methods are @forLinkTag@ and @forMetaTag@ which can be used to create respectively a <link> tag or a <meta> one. We can add tag attribute to an existing instance of @MetaDataHeaderItem@ with method @addTagAttribute(String attributeName, Object attributeValue)@. See JavaDoc for further details on this class. -* *HtmlImportHeaderItem:* introduced in Wicket 6.19.0, provides a HTML5 functionality to include other wicket pages (other html files) into the current generated. Factory methods provided by this class are @forImportLinkTag@ which takes the page class or the url of the page / html to be included. - - -In the following example our custom component loads a CSS file as a package resource (placed in the same package) and it adds it to header section. - -{code} -public class MyComponent extends Component{ - - @Override - public void renderHead(IHeaderResponse response) { - PackageResourceReference cssFile = - new PackageResourceReference(this.getClass(), "style.css"); - CssHeaderItem cssItem = CssHeaderItem.forReference(cssFile); - - response.render(cssItem); - } -} -{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc deleted file mode 100644 index 256b108..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc +++ /dev/null @@ -1,37 +0,0 @@ -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: - -{code} -//it will always use '/misc/js/jscript.js' -ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", false); -{code} - -The minified postfix can be customized with an optional string parameter: - -{code} -//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode -ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", "minified"); -{code} - -@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 - -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} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc deleted file mode 100644 index 092c649..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc +++ /dev/null @@ -1,31 +0,0 @@ - - -Class @ResourceReference@ allows to specify the resources it depends on overriding method @getDependencies()@. The method returns a list of @HeaderItem@s 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} -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 List<HeaderItem> getDependencies() { - Application application = Application.get(); - ResourceReference jqueryRef = application.getJavaScriptLibrarySettings(). - getJQueryReference(); - - return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef)); - } -}; -{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. - -{note} -Wicket already provides base class @org.apache.wicket.resource.JQueryPluginResourceReference@ for those JavaScript resources that depend on JQuery. This class uses the JQuery version bundled with Wicket. -{note} - -{note} -The same method @getDependencies()@ is defined also for class @HeaderItem@. -{note} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc deleted file mode 100644 index c9da469..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc +++ /dev/null @@ -1,25 +0,0 @@ -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} -@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} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc deleted file mode 100644 index 7471cd8..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc +++ /dev/null @@ -1,103 +0,0 @@ -Some web developers prefer to put their <script> tags at the end of page body and not inside the <head> tags: - -{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 functionalities 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. - - - http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc deleted file mode 100644 index 3bcdb9b..0000000 --- a/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc +++ /dev/null @@ -1,15 +0,0 @@ -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/>@: - -{code:html} -<head> - <meta charset="UTF-8"/> - <wicket:header-items/> - <script src="my-monkey-patch-of-wicket-ajax.js"></script> -</head> -{code} - -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. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/security.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/security.gdoc b/wicket-user-guide/src/docs/guide/security.gdoc deleted file mode 100644 index 06a537d..0000000 --- a/wicket-user-guide/src/docs/guide/security.gdoc +++ /dev/null @@ -1,3 +0,0 @@ -Security is one of the most important non-functional requirements we must implement in our applications. This is particularly true for enterprise applications as they usually support multiple concurrent users, and therefore they need to have an access control policy. - -In this chapter we will explore the security infrastructure provided by Wicket and we will learn how to use it to implement authentication and authorizations in our web applications. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/security/security_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/security/security_1.gdoc b/wicket-user-guide/src/docs/guide/security/security_1.gdoc deleted file mode 100644 index 66b39d3..0000000 --- a/wicket-user-guide/src/docs/guide/security/security_1.gdoc +++ /dev/null @@ -1,162 +0,0 @@ - - -The first step in implementing a security policy is assigning a trusted identity to our users, which means that we must authenticate them. Web applications usually adopt a form-based authentication with a login form that asks user for a unique username and the relative password: - -!wikipedia-login-form.png! - -Wicket supports form-based authentication with session class @AuthenticatedWebSession@ and application class @AuthenticatedWebApplication@, both placed inside package @org.apache.wicket.authroles.authentication@. - -h3. AuthenticatedWebSession - -Class AuthenticatedWebSession comes with the following set of public methods to manage user authentication: - -* *authenticate(String username, String password)*: this is an abstract method that must be implemented by every subclass of @AuthenticatedWebSession@. It should contain the actual code that checks for user's identity. It returns a boolean value which is true if authentication has succeeded or false otherwise. -* *signIn(String username, String password)*: this method internally calls authenticate and set the flag signedIn to true if authentication succeeds. -* *isSignedIn()*:getter method for flag signedIn. -* *invalidate()*: sets the flag signedIn to false and invalidates session. -* *signOut()*: an alias of *invalidate()*. - -Another abstract method we must implement when we use @AuthenticatedWebSession@ is getRoles which is inherited from parent class @AbstractAuthenticatedWebSession@. This method can be ignored for now as it will be discussed later when we will talk about role-based authorization. - -h3. AuthenticatedWebApplication - -Class AuthenticatedWebApplication provides the following methods to support form-based authentication: - -* *getWebSessionClass()*: abstract method that returns the session class to use for this application. The returned class must be a subclass of @AbstractAuthenticatedWebSession@. -* *getSignInPageClass()*: abstract method that returns the page to use as sign in page when a user must be authenticated. -* *restartResponseAtSignInPage()*: forces the current response to restart at the sign in page. After we have used this method to redirect a user, we can make her/him return to the original page calling @Component@'s method @continueToOriginalDestination()@. - -The other methods implemented inside @AuthenticatedWebApplication@ will be introduced when we talk about authorization. - -h3. A basic example of authentication - -Project @BasicAuthenticationExample@ is a basic example of form-based authentication implemented with classes @AuthenticatedWebSession@ and @AuthenticatedWebApplication@. - -The homepage of the project contains only a link to page @AuthenticatedPage@ which can be accessed only if user is signed in. The code of @AuthenticatedPage@ is this following: - -{code} -public class AuthenticatedPage extends WebPage { - @Override - protected void onConfigure() { - super.onConfigure(); - AuthenticatedWebApplication app = (AuthenticatedWebApplication)Application.get(); - //if user is not signed in, redirect him to sign in page - if(!AuthenticatedWebSession.get().isSignedIn()) - app.restartResponseAtSignInPage(); - } - - @Override - protected void onInitialize() { - super.onInitialize(); - add(new BookmarkablePageLink("goToHomePage", getApplication().getHomePage())); - - add(new Link("logOut") { - - @Override - public void onClick() { - AuthenticatedWebSession.get().invalidate(); - setResponsePage(getApplication().getHomePage()); - } - }); - } -} -{code} - -Page @AuthenticatedPage@ checks inside onConfigure if user is signed in and if not, it redirects her/him to the sign in page with method @restartResponseAtSignInPage@. The page contains also a link to the homepage and another link that signs out user. - -The sign in page is implemented in class @SignInPage@ and contains the form used to authenticate users: - -{code} -public class SignInPage extends WebPage { - private String username; - private String password; - - @Override - protected void onInitialize() { - super.onInitialize(); - - StatelessForm form = new StatelessForm("form") { - @Override - protected void onSubmit() { - if(Strings.isEmpty(username)) - return; - - boolean authResult = AuthenticatedWebSession.get().signIn(username, password); - //if authentication succeeds redirect user to the requested page - if(authResult) - continueToOriginalDestination(); - } - }; - - form.setModel(new CompoundPropertyModel(this)); - - form.add(new TextField("username")); - form.add(new PasswordTextField("password")); - - add(form); - } -} -{code} - -The form is responsible for handling user authentication inside its method @onSubmit()@. The username and password are passed to @AuthenticatedWebSession@'s method @signIn(username, password)@ and if authentication succeeds, the user is redirected to the original page with method @continueToOriginalDestination@. - -The session class and the application class used in the project are reported here: - -*Session class:* - -{code} -public class BasicAuthenticationSession extends AuthenticatedWebSession { - - public BasicAuthenticationSession(Request request) { - super(request); - } - - @Override - public boolean authenticate(String username, String password) { - //user is authenticated if both username and password are equal to 'wicketer' - return username.equals(password) && username.equals("wicketer"); - } - - @Override - public Roles getRoles() { - return new Roles(); - } -} -{code} - -*Application class:* - -{code} -public class WicketApplication extends AuthenticatedWebApplication { - @Override - public Class<HomePage> getHomePage(){ - return HomePage.class; - } - - @Override - protected Class<? extends AbstractAuthenticatedWebSession> getWebSessionClass(){ - return BasicAuthenticationSession.class; - } - - @Override - protected Class<? extends WebPage> getSignInPageClass() { - return SignInPage.class; - } -} -{code} - -The authentication logic inside authenticate has been kept quite trivial in order to make the code as clean as possible. Please note also that session class must have a constructor that accepts an instance of class @Request@. - -h3. Redirecting user to an intermediate page - -Method @restartResponseAtSignInPage@ is an example of redirecting user to an intermediate page before allowing him to access to the requested page. This method internally throws exception @org.apache.wicket.RestartResponseAtInterceptPageException@ which saves the URL and the parameters of the requested page into session metadata and then redirects user to the page passed as constructor parameter (the sign in page). - -Component's method @redirectToInterceptPage(Page)@ works in much the same way as @restartResponseAtSignInPage@ but it allows us to specify which page to use as intermediate page: - -{code} - redirectToInterceptPage(intermediatePage); -{code} - -{note} -Since both @restartResponseAtSignInPage@ and @redirectToInterceptPage@ internally throw an exception, the code placed after them will not be executed. -{note}
![http://www.google.de/test.jpg"](https://www.google.de/test.jpg"){kind=link}