http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/i18n/i18n_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_2.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_2.gdoc new file mode 100644 index 0000000..df6c66a --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_2.gdoc @@ -0,0 +1,148 @@ + + +A component can get the current locale in use calling its method getLocale(). By default this method will be recursively called on component's parent containers until one of them returns a valid locale. If no one of them returns a locale, this method will get the one associated with the current user session. This locale is automatically generated by Wicket in accordance with the language settings of the browser. + +Developers can change the locale of the current session with Session's method setLocale (Locale locale): + +{code} +Session.get().setLocale(locale) +{code} + +h3. Style and variation parameters for bundles + +In addition to locale's informations, Wicket supports two further parameters to identify a resource bundle: style and variation. Parameter style is a string value and is defined at session-level. To set/get the style for the current session we can use the corresponding setter and getter of class Session: + +{code} +Session.get().setStyle("myStyle"); +Session.get().getStyle(); +{code} + +If set, style's value contributes to the final full name of the bundle and it is placed between the base name and the locale's informations: + +{code} +<base name>[_style][_<language code>[_<COUNTRY_CODE>[_<variant code>]]] +{code} + +Wicket gives the priority to candidate names containing the style information (if available). The other parameter we can use for localization is variation. Just like style also variation is a string value, but it is defined at component-level. The value of variation is returned by Component's method getVariation(). By default this method returns the variation of the parent component or a null value if a component hasn't a parent (i.e. it's a page). If we want to customize this parameter we must overwrite method getVariation and make it return the desired value. + +Variation's value contributes to the final full name of the bundle and is placed before style parameter: + +{code} +<base name>[_variation][_style][_<language code>[_<COUNTRY_CODE>[_<variant code>]]] +{code} + + +h3. Using UTF-8 for resource bundles + +Java uses the standard character set "ISO 8859-11":http://en.wikipedia.org/wiki/ISO/IEC_8859-1 to encode text files like properties files. Unfortunately ISO 8859-1 does not support most of the extra-European languages like Chinese or Japanese. The only way to use properties files with such languages is to use escaped "Unicode":http://en.wikipedia.org/wiki/List_of_Unicode_characters characters, but this leads to not human-readable files. For example if we wanted to write the word 'website' in simplified Chinese (the ideograms are ç½ç«) we should write the Unicode characters @\u7F51\u7AD9@. +For this reason ISO 8859-11 is being replaced with another Unicode-compliant character encoding called UTF-8. Text files created with this encoding can contain Unicode symbols in plain format. +Wicket provides a useful convention to use properties file encoded with UTF-8. We just have to add prefix @.utf8.@ to file extension (i.e. @.utf8.properties@). + +{note} +If you want to use UTF-8 with your text files, make sure that your editor/IDE is actually using this character encoding. Some OS like Windows use a different encoding by default. +{note} + +h3. Using XML files as resource bundles + +Starting from version 1.5, Java introduced the support for XML files as resource bundles. XML files are generally encoded with character sets UTF-8 or UTF-16 which support every symbol of the Unicode standard. In order to be a valid resource bundle the XML file must conform to the DTD available at "http://www.oracle.com/webfolder/technetwork/jsc/dtd/properties.dtd":http://www.oracle.com/webfolder/technetwork/jsc/dtd/properties.dtd . + +Here is an example of XML resource bundle taken from project LocalizedGreetings (file WicketApplication_zh.properties.xml) containing the translation in simplified Chinese of the greeting message âWelcome to the website!â: + +{code:xml} +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE properties SYSTEM "http://www.oracle.com/webfolder/technetwork/jsc/dtd/properties.dtd";> +<properties> + <entry key="greetingMessage">欢è¿å 临æ¬ç½ç«ï¼</entry> +</properties> +{code} + +To use XML bundles in Wicket we don't need to put in place any additional configuration. The only rule we have to respect with these files is to use properties.xml as extension while their base name follows the same rules seen so far for bundle names. + +h3. Reading bundles from code + +Class Component makes reading bundles very easy with method getString(String key). This method searches for a resource with the given key looking into the resource bundles visited by the lookup algorithm illustrated in paragraph 12.4. For example if we have a greeting message with key greetingMessage in our application's resource bundle, we can read it from our component code with this instruction: + +{code} +getString("greetingMessage"); +{code} + +h3. Localization of bundles in Wicket + +In chapter 10 we have used as resource bundle the properties file placed next to our application class. This file is the default resource bundle for the entire application and it is used by the lookup algorithm if it doesn't find any better match for a given component and locale. If we want to provide localized versions of this file we must simply follow the rules of Java i18n and put our translated resources into another properties file with a name corresponding to the desired locale. For example project LocalizedGreetings comes with the default application's properties file ( WicketApplication.properties) containing a greeting message: + +{code} +greetingMessage=Welcome to the site! +{code} + +Along with this file we can also find a bundle for German (WicketApplication_de.properties) and another one in XML format for simplified Chinese (WicketApplication_zh.properties.xml). The example project consists of a single page (HomePage.java) displaying the greeting message. The current locale can be changed with a drop-down list and the possible options are English (the default one), German and simplified Chinese: + +!locale-german.png! + +The label displaying the greeting message has a custom read-only model which returns the message with method getString. The initialization code for this label is this: + +{code} +AbstractReadOnlyModel<String> model = new AbstractReadOnlyModel<String>() { + @Override + public String getObject() { + return getString("greetingMessage"); + } +}; + +add(new Label("greetingMessage", model)); +{code} + +Class @org.apache.wicket.model.AbstractReadOnlyModel@ is a convenience class for implementing read-only models. In this project we have implemented a custom read-only model for illustrative purposes only because Wicket already provides built-in models for the same task. We will see them in paragraph 12.6. + +The rest of the code of the home page builds the stateless form and the drop-down menu used to change the locale. + +{code} +List<Locale> locales = Arrays.asList(Locale.ENGLISH, Locale.CHINESE, Locale.GERMAN); +final DropDownChoice<Locale> changeLocale = + new DropDownChoice<Locale>("changeLocale", new Model<Locale>(), locales); + +StatelessForm form = new StatelessForm("form"){ + @Override + protected void onSubmit() { + Session.get().setLocale(changeLocale.getModelObject()); + } +}; + +setStatelessHint(true); +add(form.add(changeLocale)) +{code} + + +h3. Localization of markup files + +Although resource bundles exist to extract local-dependent elements from our code and from UI components, in Wicket we can decide to provide different markup files for different locale settings. Just like standard markup files, by default localized markup files must be placed next to component's class and their file name must contain the locale's informations. In the following picture, CustomPanel comes with a standard (or default) markup file and with another one localized for German: + +!comp-with-markup-german.png! + +When the current locale corresponds to German country (language code de), markup file CustomPanel_de.html will be used in place of the default one. + +h3. Reading bundles with tag <wicket:message> + +String resources can be also retrieved directly from markup code using tag <wicket:message>. The key of the desired resource is specified with attribute key: + +{code:xml} +<wicket:message key="greetingMessage">message goes here</wicket:message> +{code} + +By default the resource value is not escaped for HTML entities. To do that use the @escape@ attribute: + +{code:xml} +<wicket:message key="greetingMessage" escape="true">message goes here</wicket:message> +{code} + + +@wicket:message@ can be adopted also to localize the attributes of a tag. The name of the attribute and the resource key are expressed as a colon-separated value. In the following markup the content of attribute @value@ will be replaced with the localized resource having 'key4value' as key: + +{code:html} +<input type="submit" value="Preview value" wicket:message="value:key4value"/> +{code} + +If we want to specify multiple attributes at once, we can separate them with a comma: + +{code:html} +<input type="submit" value="Preview value" wicket:message="value:key4value, title:key4title"/> +{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/i18n/i18n_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_3.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_3.gdoc new file mode 100644 index 0000000..75e870e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_3.gdoc @@ -0,0 +1,100 @@ + + +As we hinted at the beginning of this chapter, by default Wicket provides a very flexible algorithm to locate the resource bundles available for a given component. In this paragraph we will learn how this default lookup algorithm works and which options it offers to manage our bundle files. + +h3. Localizing pages and panels + +Similarly to application class, also component classes can have their own bundle files having as base name the class name of the related component and placed in the same package. So for example if class CustomPanel is a custom panel we created, we can provide it with a default bundle file called CustomPanel.properties containing the textual resources used by this panel. This rule applies to page classes as well: + +!page-and-panel-bundle.png! + +One fundamental thing to keep in mind when we work with these kinds of bundles is that the lookup algorithm gives priority to the bundles of the containers of the component that is requesting a localized resource. The more a container is higher in the hierarchy, the bigger is its priority over the other components. This mechanism was made to allow containers to overwrite resources used by children components. As a consequence the values inside the resource bundle of a page will have the priority over the other values with the same key defined in the bundles of children components. + +To better grasp this concept let's consider the component hierarchy depicted in the following picture: + +!custom-panel-bundle.png! + +If CustomPanel tries to retrieve the string resource having 'message' as key, it will get the value 'Wellcome!' and not the one defined inside its own bundle file. + +The default message-lookup algorithm is not limited to component hierarchy but it also includes the class hierarchy of every component visited in the search strategy described so far. This makes bundle files inheritable, just like markup files. When the hierarchy of a container component is explored, any ancestor has the priority over children components. Consider for example the hierarchy in the following picture: + +!custom-panel-bundle2.png! + +Similarly to the previous example, the bundle owned by CustomPanel is overwritten by the bundle of page class BasePage (which has been inherited by CustomPage). + +h3. Component-specific resources + +In order to make a resource specific for a given child component, we can prefix the message key with the id of the desired component. Consider for example the following code and bundle of a generic page: + +Page code: + +{code} +add(new Label("label",new ResourceModel("labelValue"))); +add(new Label("anotherLabel",new ResourceModel("labelValue"))); +{code} + +Page bundle: + +{code} +labelValue=Default value +anotherLabel.labelValue=Value for anotherLabel +{code} + +Label with id anotherLabel will display the value 'Value for anotherLabel' while label label will display 'Default value'. In a similar fashion, parent containers can specify a resource for a nested child component prepending also its relative path (the path is dot-separated): + +Page code: + +{code} +Form form = new Form("form"); +form.add(new Label("anotherLabel",new ResourceModel("labelValue"))); +add(form); +{code} + +Page bundle: + +{code} +labelValue=Default value +anotherLabel.labelValue=Value for anotherLabel +form.anotherLabel.labelValue=Value for anotherLabel inside form +{code} + +With the code and the bundle above, the label inside the form will display the value 'Value for anotherLabel inside form'. + +h3. Package bundles + +If no one of the previous steps can find a resource for the given key, the algorithm will look for package bundles. These bundles have @wicket-package@ as base name and they can be placed in one of the package of our application: + +!package-bundles.png! + +Packages are traversed starting from the one containing the component requesting for a resource and going up to the root package. + +h3. Bundles for feedback messages + +The algorithm described so far applies to feedback messages as well. In case of validation errors, the component that has caused the error will be considered as the component which the string resource is relative to. Furthermore, just like application class and components, validators can have their own bundles placed next to their class and having as base name their class name. This allows us to distribute validators along with the messages they use to report errors: + +!validator-with-bundle.png! + +Validator's resource bundles have the lowest priority in the lookup algorithm. They can be overwritten by resource bundles of components, packages and application class. + +h3. Extending the default lookup algorithm + +Wicket implements the default lookup algorithm using the strategy pattern1. The concrete strategies are abstracted with the interface @org.apache.wicket.resource.loader.IStringResourceLoader@. By default Wicket uses the following implementations of @IStringResourceLoader@ (sorted by execution order): + +# *ComponentStringResourceLoader:* implements most of the default algorithm. It searches for a given resource across bundles from the container hierarchy, from class hierarchy and from the given component. +# *PackageStringResourceLoader:* searches into package bundles. +# *ClassStringResourceLoader:* searches into bundles of a given class. By default the target class is the application class. +# *ValidatorStringResourceLoader:* searches for resources into validator's bundles. A list of validators is provided by the form component that failed validation. +# *InitializerStringResourceLoader:* this resource allows internationalization to interact with the initialization mechanism of the framework that will be illustrated in paragraph 15.4. + +Developer can customize lookup algorithm removing default resource loaders or adding custom implementations to the list of the resource loaders in use. This task can be accomplished using method getStringResourceLoaders of setting interface @org.apache.wicket.settings.IResourceSettings@: + +{code} +@Override +public void init() +{ + super.init(); + //retrieve IResourceSettings and then the list of resource loaders + List<IStringResourceLoader> resourceLoaders = getResourceSettings(). + getStringResourceLoaders(); + //customize the list... +{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/i18n/i18n_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_4.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_4.gdoc new file mode 100644 index 0000000..8372272 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_4.gdoc @@ -0,0 +1,67 @@ + + +Components that inherit from @AbstractChoice@ (such as @DropDownChoice@, @CheckBoxMultipleChoice@ and @RadioChoice@) must override method @localizeDisplayValues@ and make it return true to localize the values displayed for their choices. By default this method return false so values are displayed as they are. Once localization is activated we can use display values as key for our localized string resources. In project LocalizedChoicesExample we have a drop-down list that displays four colors (green, red, blue, and yellow) which are localized in three languages (English, German and Italian). The current locale can be changed with another drop-down menu (in a similar fashion to project @LocalizedGreetings@). The code of the home page and the relative bundles are the following: + +Java code: + +{code} +public HomePage(final PageParameters parameters) { + super(parameters); + + List<Locale> locales = Arrays.asList(Locale.ENGLISH, Locale.ITALIAN, Locale.GERMAN); + List<String> colors = Arrays.asList("green", "red", "blue", "yellow"); + + final DropDownChoice<Locale> changeLocale = new DropDownChoice<Locale>("changeLocale", + new Model<Locale>(), locales); + + StatelessForm form = new StatelessForm("form"){ + @Override + protected void onSubmit() { + Session.get().setLocale(changeLocale.getModelObject()); + } + }; + + DropDownChoice<String> selectColor = new DropDownChoice<String>("selectColor", new + Model<String>(), colors){ + @Override + protected boolean localizeDisplayValues() { + return true; + } + }; + + form.add(selectColor); + add(form.add(changeLocale)); + } +{code} + +Default bundle (English): + +{code} +selectColor.null=Select a color +green=Green +red=Red +blue=Blue +yellow=Yellow +{code} + +German bundle: + +{code} +selectColor.null=Wahlen sie eine farbe +green=Grun +red=Rot +blue=Blau +yellow=Gelb +{code} + +Italian bundle: + +{code} +selectColor.null=Scegli un colore +green=Verde +red=Rosso +blue=Blu +yellow=Giallo +{code} + +Along with the localized versions of colors names, in the bundles above we can also find a custom value for the placeholder text (âChose one â) used for null value. The resource key for this resource is 'null' or '<component id>.null' if we want to make it component-specific. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/i18n/i18n_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_5.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_5.gdoc new file mode 100644 index 0000000..aff8c2c --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_5.gdoc @@ -0,0 +1,93 @@ + + +Internationalization is another good chance to taste the power of models. Wicket provides two built-in models to better integrate our components with string resources: they are ResourceModel and StringResourceModel. + +h3. ResourceModel + +Model @org.apache.wicket.model.ResourceModel@ acts just like the read-only model we have implemented in paragraph 12.3.4. It simply retrieves a string resource corresponding to a given key: + +{code} +//build a ResourceModel for key 'greetingMessage' +new ResourceModel("greetingMessage"); +{code} + +We can also specify a default value to use if the requested resource is not found: + +{code} +//build a ResourceModel with a default value +new ResourceModel("notExistingResource", "Resource not found."); +{code} + +h3. StringResourceModel + +Model @org.apache.wicket.model.StringResourceModel@ allows to work with complex and dynamic string resources containing parameters and property expressions. The basic constructor of this model takes in input a resource key and another model. This further model can be used by both the key and the related resource to specify dynamic values with property expressions. For example let's say that we are working on an e-commerce site which has a page where users can see an overview of their orders. To handle the state of user's orders we will use the following bean and enum (the code is from project StringResourceModelExample): + +Bean: + +{code} +public class Order implements Serializable { + + private Date orderDate; + private ORDER_STATUS status; + + public Order(Date orderDate, ORDER_STATUS status) { + super(); + this.orderDate = orderDate; + this.status = status; + } + //Getters and setters for private fields +} +{code} + +Enum: + +{code} +public enum ORDER_STATUS { + + PAYMENT_ACCEPTED(0), + IN_PROGRESS(1), + SHIPPING(2), + DELIVERED(3); + + private int code; + //Getters and setters for private fields +} +{code} + +Now what we want to do in this page is to print a simple label which displays the status of an order and the date on which the order has been submitted. All the informations about the order will be passed to a StringResourceModel with a model containing the bean Order. The bundle in use contains the following key/value pairs: + +{code} +orderStatus.0=Your payment submitted on ${orderDate} has been accepted. +orderStatus.1=Your order submitted on ${orderDate} is in progress. +orderStatus.2=Your order submitted on ${orderDate} has been shipped. +orderStatus.3=Your order submitted on ${orderDate} has been delivered. +{code} + +The values above contain a property expression (${orderDate}) that will be evaluated on the data object of the model. The same technique can be applied to the resource key in order to load the right resource according to the state of the order: + +{code} +Order order = new Order(new Date(), ORDER_STATUS.IN_PROGRESS); +add(new Label("orderStatus", new StringResourceModel("orderStatus.${status.code}", Model.of(order)))); +{code} + +As we can see in the code above also the key contains a property expression (${status.code}) which makes its value dynamic. In this way the state of an object (an Order in our example) can determinate which resource will be loaded by StringResourceModel. If we don't use properties expressions we can provide a null value as model and in this case StringResourceModel will behave exactly as a ResourceModel. StringResourceModel supports also the same parameter substitution used by standard class java.text.MessageFormat. Parameters can be generic objects but if we use a model as parameter, StringResourceModel will use the data object inside it as actual value (it will call getObject on the model). Parameters are passed to constructor as a vararg argument. Here is an example of usage of parameter substitution: + +Java code: + +{code} +PropertyModel propertyModel = new PropertyModel<Order>(order, "orderDate"); +//build a string model with two parameters: a property model and an integer value +StringResourceModel srm = new StringResourceModel("orderStatus.delay", null, propertyModel, 3); +{code} + +Bundle: + +{code} +orderStatus.delay=Your order submitted on ${0} has been delayed by {1} days. +{code} + +One further parameter we can specify when we build a StringResourceModel is the component that must be used by the lookup algorithm. Normally this parameter is not relevant, but if we need to use a particular bundle owned by a component not considered by the algorithm, we can specify this component as second parameter. If we pass all possible parameters to StringResourceModel's constructor we obtain something like this: + +{code} +new StringResourceModel("myKey", myComponent, myModel, param1, param2, param3,...); +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/i18n/i18n_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_6.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_6.gdoc new file mode 100644 index 0000000..0c9050f --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_6.gdoc @@ -0,0 +1,3 @@ + + +Internationalization is a mandatory step if we want to take our applications (and our business!) abroad. Choosing the right strategy to manage our localized resources is fundamental to avoid to make a mess of them. In this chapter we have explored the built-in support for localization provided by Wicket, and we have learnt which solutions it offers to manage resource bundles. In the final part of the chapter we have seen how to localize the options displayed by a component (such as DropDownChoice or RadioChoice) and we also introduced two new models specifically designed to localize our components without introducing in their code any detail about internationalization. http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/internals.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/internals.gdoc b/wicket-user-guide/src/docs/guide/internals.gdoc new file mode 100644 index 0000000..e69de29 http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/internals/pagestoring.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/internals/pagestoring.gdoc b/wicket-user-guide/src/docs/guide/internals/pagestoring.gdoc new file mode 100644 index 0000000..2def2fe --- /dev/null +++ b/wicket-user-guide/src/docs/guide/internals/pagestoring.gdoc @@ -0,0 +1,74 @@ +During request handling, Wicket manages page instances through interface @org.apache.wicket.request.handler.IPageProvider@. This interface creates a new page instance or loads a previously serialized page instance if we provide the corrisponding page id. @IPageProvider@ delegates page creation and retrieval to interface @org.apache.wicket.request.mapper.IPageSource@. +When page class is provided @IPageSource@ delegates page creation to interface @org.apache.wicket.IPageFactory@, while when page id is provided it uses interface @org.apache.wicket.page.IPageManager@ to load the previously serialized page. + +The following workflow diagram summarizes the mechanism seen so far: + +!page-storage.png! + +h3. IPageManager + +@org.apache.wicket.page.IPageManager@'s task is to manage which pages have been used in a request and store their last state in the backing stores, namely @IPageStore@. +The default implementation @org.apache.wicket.page.PageStoreManager@ collects all stateful pages which have been used in the request cycle (more than one page can be used in a single request if for example @setResponsePage()@ or @RestartResponseException@ is used). +At the end of the request all collected page instances are being stored in the first level cache - http session. They are stored in http session attribute named @"wicket:persistentPageManagerData-APPLICATION_NAME"@ and passed to the underlying @IPageStore@. +When the next http request comes @IPageProvider@ will ask for page with specific id and @PageStoreManager@ will look first in the http session and if no match is found then it will delegate to the IPageStore. At the end of the second request the http session based cache is being overwritten completely with the newly used page instances. + +To setup another @IPageManager@ implementation use @org.apache.wicket.Application.setPageManagerProvider(IPageManagerProvider)@. +The custom @IPageManager@ implementation may or may not use @IPageStore/IDataStore@. + +h3. IPageStore + +@org.apache.wicket.pageStore.IPageStore@'s role is to mediate the storing and loading of pages done by the underlying @IDataStore@. The default implementation @org.apache.wicket.pageStore.DefaultPageStore@ pre-processes the pages before passing them to @IDataStore#storeData(String, int, byte[])@ and to post-processes them after @IDataStore#getData(String, int)@. The processing consists of transforming the page instance to @org.apache.wicket.pageStore.DefaultPageStore.SerializedPage@. This is a struct of: + +{code} +{ + sessionId: String, + pageId : int, + data : byte[] +} +{code} + +i.e. this is the serialized page instance (data) plus additional information needed to be able to easily find it later (sessionId, pageId). + +When a @SerializedPage@ has to be stored @DefaultPageStore@ stores it in a application scoped cache ({sessionId, pageId} -> SerializedPage) and additionally gives it to the underlying @IDataStore#storeData(sessionId, pageId, data)@. The application scoped cache is used as second level cache. Getting a page from it is slower than the http session based cache in @PageStoreManager@ because the page has to be deserialized, but is faster than the underlying @IDataStore@ which stores the page bytes in some persistent store. + +The size of the application scoped cache is configurable via @org.apache.wicket.settings.IStoreSettings.setInmemoryCacheSize(int)@. + +h3. IDataStore + +@org.apache.wicket.pageStore.IDataStore@ is used to persist Wicket pages (as bytes) to a persistent store like e.g. files or databases. The default implementation is @org.apache.wicket.pageStore.DiskDataStore@ which as its name says stores the pages in files. The location of the folder where the files are stored is configurable via @org.apache.wicket.settings.IStoreSettings.setFileStoreFolder(File)@, by default the web container's work folder is used (ServletContext attribute 'javax.servlet.context.tempdir'). In this folder a sub-folder is created named @'applicationName-filestore'@. +This folder contains a sub-folder for each active http session. This session folder contains a single file named 'data' which contains the bytes for the pages. The size of this 'data' file is configurable via @org.apache.wicket.settings.IStoreSettings.setMaxSizePerSession(Bytes)@. When this size is exceeded the newly stored files overwrite the oldest ones. + +h3. AsynchronousDataStore + +By default Wicket wraps @DiskDataStore@ with @org.apache.wicket.pageStore.AsynchronousDataStore@. The role of @AsynchronousDataStore@ is to detach the http worker thread from waiting for the write of the page bytes to the disk. +To disable it use: @org.apache.wicket.settings.IStoreSettings.setAsynchronous(false)@. AsynchronousDataStore can delay the storage of pages' bytes for at most @org.apache.wicket.settings.IStoreSettings.setAsynchronousQueueCapacity(int)@ pages. If this capacity is exceeded then the page's bytes are written synchronously to the backing @IDataStore@. + +h3. DebugDiskDataStore + +Wicket provides an extension of @DiskDataStore@ that can be used to browse the content of the 'data' files created by @DiskDataStore@. This debug enabled @DiskDataStore@ is automatically setup when wicket-devutils.jar is in the classpath. +The debug information can be seen at http://host:port/context/wicket/internal/debug/diskDataStore + +h3. HttpSessionDataStore + +In some environments like Google AppEngine it is not allowed to write to the file system and thus @DiskDataStore@ cannot be used. In this case @org.apache.wicket.pageStore.memory.HttpSessionDataStore@ can be used as replacement. This implementation of @IDataStore@ is not persistent and puts all the data in the http session. +Wicket comes with 2 default eviction strategies to keep the size of the http session reasonable: + +* *org.apache.wicket.pageStore.memory.PageNumberEvictionStrategy* - specifies how many pages can be hold +* *org.apache.wicket.pageStore.memory.MemorySizeEvictionStrategy* - specifies the maximum amount of memory for pages per http session. + +To configure it: +{code} +MyApp#init() +{ + super.init(); + + setPageManagerProvider(new DefaultPageManagerProvider() + { + protected IDataStore newDataStore() + { + return new HttpSessionDataStore(pageManagerContext, new PageNumberEvictionStrategy(20)); + } + } +} +{code} + http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/introduction.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/introduction.gdoc b/wicket-user-guide/src/docs/guide/introduction.gdoc new file mode 100644 index 0000000..28badd5 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/introduction.gdoc @@ -0,0 +1,24 @@ +Wicket has been around since 2004 and it has been an Apache project since 2007. During these years it has proved to be a solid and valuable solution for building enterprise web applications. + +Wicket core developers have done a wonderful job with this framework and they continue to improve it release after release. +However Wicket never provided a freely available documentation and even if you can find on Internet many live examples and many technical articles on it (most of them at "Wicket Library":http://www.wicket-library.com/ and at "Wicket in Action":http://wicketinaction.com ), the lack of an organized and freely available documentation has always been a sore point for this framework. + +That's quite an issue because many other popular frameworks (like Spring, Hibernate or Struts) offer a vast and very good documentation which substantially contributed to their success. + +This document is not intended to be a complete reference for Wicket but it simply aims to be a straightforward introduction to the framework that should significantly reduce its learning curve. What you will find here reflects my experience with Wicket and it's strictly focused on the framework. +The various Wicket-related topics are gradually introduced using pragmatic examples of code that you can find in "the according repository on Github.":https://github.com/bitstorm/Wicket-tutorial-examples + +However remember that Wicket is a vast and powerful tool, so you should feel confident with the topics exposed in this document before starting to code your real applications! + +For those who need further documentation on Wicket, there are "many good books":http://wicket.apache.org/learn/books/ available for this framework. + +Hope you'll find this guide helpful. Have fun with Wicket! + +*Andrea Del Bene, adelb...@apache.org* + +*PS*: this guide is based on Wicket 6. However if you are using an older version you should find this guide useful as well, but it's likely that the code and the snippets won't work with your version. + +*PPS*: although I've tried to do my best working on this tutorial, this document is a work in progress and may contain errors and/or omissions. That's why any feedback of any kind is REALLY appreciated! + +Project started by "!comsysto-logo.png!":http://comsysto.com/ + http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jee.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee.gdoc b/wicket-user-guide/src/docs/guide/jee.gdoc new file mode 100644 index 0000000..97ace94 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jee.gdoc @@ -0,0 +1,11 @@ +Writing a web application is not just about producing a good layout and a bunch of âcoolâ pages. We must also integrate our presentation code with enterprise resources like data sources, message queues, business objects, etc... + +The first decade of 2000s has seen the rising of new frameworks (like "Spring":http://spring.io/ ) and new specifications (like "EJB 3.1":http://en.wikipedia.org/wiki/Enterprise_JavaBeans ) aimed to simplify the management of enterprise resources and (among other things) their integration with presentation code. + +All these new technologies are based on the concepts of container and dependency injection. Container is the environment where our enterprise resources are created and configured while "dependency injection":http://en.wikipedia.org/wiki/Dependency_Injection is a pattern implemented by containers to inject into an object the resources it depends on. + +Wicket can be easily integrated with enterprise containers using component instantiation listeners. These entities are instances of interface @org.apache.wicket.application.IComponentInstantiationListener@ and can be registered during application's initialization. IComponentInstantiationListener defines callback method onInstantiation(Component component) which can be used to provide custom instantiation logic for Wicket components. + +Wicket distribution and project "WicketStuff":https://github.com/wicketstuff already provide a set of built-in listeners to integrate our applications with EJB 3.1 compliant containers (like JBoss Seam) or with some of the most popular enterprise frameworks like "Guice":http://code.google.com/p/google-guice/ or Spring. + +In this chapter we will see two basic examples of injecting a container-defined object into a page using first an implementation of the EJB 3.1 specifications (project "OpenEJB":http://openejb.apache.org/ ) and then using Spring. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc new file mode 100644 index 0000000..042b8b2 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc @@ -0,0 +1,51 @@ + + +WicketStuff provides a module called wicketstuff-javaee-inject that contains component instantiation listener @JavaEEComponentInjector@. If we register this listener in our application we can use standard EJB annotations to inject dependencies into our Wicket components. + +To register a component instantiation listener in Wicket we must use @Application@'s method @getComponentInstantiationListeners@ which returns a typed collection of @IComponentInstantiationListeners@. + +The following initialization code is taken from project @EjbInjectionExample@: + +{code} +public class WicketApplication extends WebApplication +{ + //Constructor... + + @Override + public void init() + { + super.init(); + getComponentInstantiationListeners().add(new JavaEEComponentInjector(this)); + } +} +{code} + +In this example the object that we want to inject is a simple class containing a greeting message: + +{code} +@ManagedBean +public class EnterpriseMessage { + public String message = "Welcome to the EJB world!"; +} +{code} + +Please note that we have used annotation ManagedBean to decorate our object. Now to inject it into the home page we must add a field of type EnterpriseMessage and annotate it with annotation @EJB: + +{code} +public class HomePage extends WebPage { + + @EJB + private EnterpriseMessage enterpriseMessage; + //getter and setter for enterpriseMessage... + + public HomePage(final PageParameters parameters) { + super(parameters); + + add(new Label("message", enterpriseMessage.message)); + } +} +{code} + +That is all. We can point the browser to the home page of the project and see the greeting message injected into the page: + +!EjbInjectionExample.png! \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc new file mode 100644 index 0000000..5e006ca --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc @@ -0,0 +1,60 @@ + + +If we need to inject dependencies with Spring we can use listener @org.apache.wicket.spring.injection.annot.SpringComponentInjector@ provided by module wicket-spring. + +For the sake of simplicity in the example project @SpringInjectionExample@ we have used Spring class @AnnotationConfigApplicationContext@ to avoid any XML file and create a Spring context directly from code: + +{code} +public class WicketApplication extends WebApplication +{ + //Constructor... + + @Override + public void init() + { + super.init(); + + AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); + //Scan package for annotated beans + ctx.scan("org.wicketTutorial.ejbBean"); + ctx.refresh(); + + getComponentInstantiationListeners().add(new SpringComponentInjector(this, ctx)); + } +} +{code} + +As we can see in the code above, the constructor of @SpringComponentInjector@ takes in input also an instance of Spring context. + +The injected object is the same used in the previous project @EjbInjectionExample@, it differs only for the greeting message: + +{code} +@ManagedBean +public class EnterpriseMessage { + public String message = "Welcome to the Spring world!"; +} +{code} + +In the home page of the project the object is injected using Wicket annotation @SpringBean: + +{code} +public class HomePage extends WebPage { + @SpringBean + private EnterpriseMessage enterpriseMessage; + //getter and setter for enterpriseMessage... + + public HomePage(final PageParameters parameters) { + super(parameters); + + add(new Label("message", enterpriseMessage.message)); + } +} +{code} + +By default @SpringBean@ searches into Spring context for a bean having the same type of the annotated field. If we want we can specify also the name of the bean to use as injected object and we can declare if the dependency is required or not. By default dependencies are required and if they can not be resolved to a compatible bean, Wicket will throw an @IllegalStateException@: + +{code} + //set the dependency as not required, i.e the field can be left null + @SpringBean(name="anotherName", required=false) + private EnterpriseMessage enterpriseMessage; +{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc new file mode 100644 index 0000000..38e56da --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc @@ -0,0 +1,9 @@ + + +Spring (and Guice) users can use standard "JSR-330":http://jcp.org/en/jsr/detail?id=330 annotations to wire their dependencies. This will make their code more interoperable with other containers that support this standard: + +{code} + //inject a bean specifying its name with JSR-330 annotations + @Inject @Named("anotherName") + private EnterpriseMessage enterpriseMessage; +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc new file mode 100644 index 0000000..b7c9c45 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc @@ -0,0 +1,5 @@ + + +In this chapter we have seen how to integrate Wicket applications with Spring and with an EJB container. Module wicket-examples contains also an example of integration with Guice (see application class @org.apache.wicket.examples.guice.GuiceApplication@). + + http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jsintegration.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration.gdoc b/wicket-user-guide/src/docs/guide/jsintegration.gdoc new file mode 100644 index 0000000..e34ed0e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jsintegration.gdoc @@ -0,0 +1 @@ +It's time to put into practice what we have learnt so far in this guide. To do this we will build a custom date component consisting of a text field to edit a date value and a fancy calendar icon to open a JavaScript datepicker. This chapter will also illustrate an example of integration of Wicket with a JavaScript library like "JQuery":http://jquery.com/ and its child project "JQuery UI":http://jqueryui.com/ . \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc new file mode 100644 index 0000000..936ea92 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc @@ -0,0 +1,23 @@ + + +For end-users a datepicker is one of the most appreciated widget. It allows to simply edit a date value with the help of a user-friendly pop-up calendar. That's why nearly all UI frameworks provide a version of this widget. + +Popular JavaScript libraries like YUI and JQuery come with a ready-to-use datepicker to enrich the user experience of our web applications. Wicket already provides a component which integrates a text field with a calendar widget from YUI library, but there is no built-in component that uses a datepicker based on JQuery library. + +As both JQuery and its child project JQueryUI have gained a huge popularity in the last years, it's quite interesting to see how to integrate them in Wicket building a custom component. In this chapter we will create a custom datepicker based on the corresponding widget from JQueryUI project: + +!datepicker-screenshot.png! + +{warning} +On Internet you can find different libraries that already offer a strong integration between Wicket and JQuery. The goal of this chapter is to see how to integrate Wicket with a JavaScript framework building a simple homemade datepicker which is not intended to provide every feature of the original JavaScript widget. +{warning} + +h3. What features we want to implement + +Before starting to write code, we must clearly define what features we want to implement for our component. The new component should: + +* *Be self-contained*: we must be able to distribute it and use it in other projects without requiring any kind of additional configuration. +* *Have a customizable date format*: developer must be able to decide the date format used to display date value and to parse user input. +* *Be localizable*: the pop-up calendar must be localizable in order to support different languages. + +That's what we'd like to have with our custom datepicker. In the rest of the chapter we will see how to implement the features listed above and which resources must be packaged with our component. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc new file mode 100644 index 0000000..7b32ede --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc @@ -0,0 +1,137 @@ + + +Our new component will extend the a built-in text field @org.apache.wicket.extensions.markup.html.form.DateTextField@ which already uses a java.util.Date as model object and already performs conversion and validation for input values. Since the component must be self-contained, we must ensure that the JavaScript libraries it relies on (JQuery and JQuery UI) will be always available. + +Starting from version 6.0 Wicket has adopted JQuery as backing JavaScript library so we can use the version bundled with Wicket for our custom datepicker. + +To make JQuery UI available we should instead go to its official site, download the required artifacts and use them as package resources of our component. + +h3. Component package resources + +JQuery UI needs the following static resources in order to work properly: + +* *jquery-ui.min.js*: the minified version of the library. +* *jquery-ui.css*: the CSS containing the style used by JQuery UI widgets. +* *jquery-ui-i18n.min.js*: the minified JavaScript containing the built-in support for localization. +* *Folder 'images'*: the folder containing picture files used by JQuery UI widgets. + +In the following picture we can see these package resources with our component class (named JQueryDateField): + +!datepicker-package-resources.png! + +Along with the four static resources listed above, we can find also file calendar.jpg, which is the calendar icon used to open the pop up calendar, and file JQDatePicker.js which contains the following custom JavaScript code that binds our component to a JQuery UI datepicker: + +{code:javascript} +function initJQDatepicker(inputId, countryIsoCode, dateFormat, calendarIcon) { + var localizedArray = $.datepicker.regional[countryIsoCode]; + localizedArray['buttonImage'] = calendarIcon; + localizedArray['dateFormat'] = dateFormat; + initCalendar(localizedArray); + $("#" + inputId).datepicker(localizedArray); +}; + +function initCalendar(localizedArray){ + localizedArray['changeMonth']= true; + localizedArray['changeYear']= true; + localizedArray['showOn'] = 'button'; + localizedArray['buttonImageOnly'] = true; +}; +{code} + +Function initJQDatepicker takes in input the following parameters: + +* *inputId*: the id of the HTML text field corresponding to our custom component instance. +* *countryIsoCode*: a two-letter low-case ISO language code. It can contain also the two-letter upper-case ISO country code separated with a minus sign (for example en-GB) +* *dateFormat*: the date format to use for parsing and displaying date values. +* *calendarIcon*: the relative URL of the icon used as calendar icon. + +As we will see in the next paragraphs, its up to our component to generate this parameters and invoke the initJQDatepicker function. + +Function initCalendar is a simple utility function that sets the initialization array for datepicker widget. For more details on JQuery UI datepicker usage see the documentation at http://jqueryui.com/ datepicker. + +h3. Initialization code + +The initialization code for our component is contained inside its method onInitialize and is the following: + +{code} +@Override +protected void onInitialize() { + super.onInitialize(); + setOutputMarkupId(true); + + datePattern = new ResourceModel("jqueryDateField.shortDatePattern", "mm/dd/yy") + .getObject(); + countryIsoCode = new ResourceModel("jqueryDateField.countryIsoCode", "en-GB") + .getObject(); + + PackageResourceReference resourceReference = + new PackageResourceReference(getClass(), "calendar.jpg"); + + urlForIcon = urlFor(resourceReference, new PageParameters()); + dateConverter = new PatternDateConverter(datePattern, false); +} + +@Override +public <Date> IConverter<Date> getConverter(Class<Date> type) { + return (IConverter<Date>) dateConverter; +} +{code} + +The first thing to do inside onInitialize is to ensure that our component will have a markup id for its related text field. This is done invoking setOutputMarkupId(true). + +Next, JQueryDateField tries to retrieve the date format and the ISO language code that must be used as initialization parameters. This is done using class @ResourceModel@ which searches for a given resource in the available bundles. If no value is found for date format or for ISO language code, default values will be used ('mm/dd/yy' and 'en-GB'). + +To generate the relative URL for calendar icon, we load it as package resource reference and then we use @Component@'s method urlFor to get the URL value (we have seen this method in paragraph 7.3.2). + +The last configuration instruction executed inside onInitialize is the instantiation of the custom converter used by our component. This converter is an instance of the built-in class @org.apache.wicket.datetime.PatternDateConvert@ and must use the previously retrieved date format to perform conversion operations. Now to tell our component to use this converter we must return it overriding @FormComponent@'s method @getConverter@. + +h3. Header contributor code + +The rest of the code of our custom component is inside method @renderHeader@, which is responsible for adding to page header the bundled JQuery library, the three files from JQuery UI distribution, the custom file JQDatePicker.js and the invocation of function @initJQDatepicker@: + +{code} +@Override +public void renderHead(IHeaderResponse response) { + super.renderHead(response); + + //if component is disabled we don't have to load the JQueryUI datepicker + if(!isEnabledInHierarchy()) + return; + //add bundled JQuery + IJavaScriptLibrarySettings javaScriptSettings = + getApplication().getJavaScriptLibrarySettings(); + response.render(JavaScriptHeaderItem. + forReference(javaScriptSettings.getJQueryReference())); + //add package resources + response.render(JavaScriptHeaderItem. + forReference(new PackageResourceReference(getClass(), "jquery-ui.min.js"))); + response.render(JavaScriptHeaderItem. + forReference(new PackageResourceReference(getClass(), "jquery-ui-i18n.min.js"))); + response.render(CssHeaderItem. + forReference(new PackageResourceReference(getClass(), "jquery-ui.css"))); + //add custom file JQDatePicker.js. Reference JQDatePickerRef is a static field + response.render(JavaScriptHeaderItem.forReference(JQDatePickerRef)); + + //add the init script for datepicker + String jqueryDateFormat = datePattern.replace("yyyy", "yy").toLowerCase(); + String initScript = ";initJQDatepicker('" + getMarkupId() + "', '" + countryIsoCode + + "', '" + jqueryDateFormat + "', " + "'" + urlForIcon +"');"; + response.render(OnLoadHeaderItem.forScript(initScript)); +} +{code} + +If component is disabled the calendar icon must be hidden and no datepicker must be displayed. That's why @renderHeader@ is skipped if component is not enabled. + +To get a reference to the bundled JQuery library we used the JavaScript setting interface @IJavaScriptLibrarySettings@ and its method @getJQueryReference@. + +In the last part of @renderHeader@ we build the string to invoke function @initJQDatepicker@ using the values obtained inside onInitialize. Unfortunately the date format used by JQuery UI is different from the one adopted in Java so we have to convert it before building the JavaScript code. This init script is rendered into header section using a @OnLoadHeaderItem@ to ensure that it will be executed after all the other scripts have been loaded. + +{note} +If we add more than one instance of our custom component to a single page, static resources are rendered to the header section just once. Wicket automatically checks if a static resource is already referenced by a page and if so, it will not render it again. + +This does not apply to the init script which is dynamically generated and is rendered for every instance of the component. +{note} + +{warning} +Our datepicker is not ready yet to be used with AJAX. In chapter 16 we will see how to modify it to make it AJAX-compatible. +{warning} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc new file mode 100644 index 0000000..f1ba1d3 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc @@ -0,0 +1,6 @@ + + +In this brief chapter we have seen how custom components can be integrated with [DHTML|http://en.wikipedia.org/wiki/Dynamic_HTML] technologies. To do so we have used most of what we have learnt in this guide. Now we are able to build complex components with a rich user experience. However this is not enough yet to develop "Web 2.0":http://en.wikipedia.org/wiki/Web_2.0 applications. We still have to cover a fundamental technology like AJAX and some other Wicket-related topics that will help us building our application in more modular and efficient way. + + + http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl.gdoc b/wicket-user-guide/src/docs/guide/keepControl.gdoc new file mode 100644 index 0000000..657341e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl.gdoc @@ -0,0 +1,3 @@ +Many Wicket newbies are initially scared by its approach to web development because they have the impression that the component-oriented nature of the framework prevents them from having direct control over the generated markup. This is due to the fact that many developers come from other server-side technologies like JSP where we physically implement the logic that controls how the final HTML is generated. + +This chapter will prevent you from having any initial misleading feeling about Wicket showing you how to control and manipulate the generated HTML with the built-in tools shipped with the framework. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc new file mode 100644 index 0000000..cbf7bf8 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc @@ -0,0 +1,7 @@ +At the end of the previous chapter we have seen how to hide a component calling its method @setVisible@. In a similar fashion, we can also decide to disable a component using method @setEnabled@. When a component is disabled all the links inside it will be in turn disabled (they will be rendered as @<span>@) and it can not fire JavaScript events. + +Class @Component@ provides two getter methods to determinate if a component is visible or enabled: @isVisible@ and @isEnabled@. + +Even if nothing prevents us from overriding these two methods to implement a custom logic to determinate the state of a component, we should keep in mind that methods @isVisible@ and @isEnabled@ are called multiple times before a component is fully rendered. Hence, if we place non-trivial code inside these two methods, we can sensibly deteriorate the responsiveness of our pages. + +As we will see in the next chapter, class @Component@ provides method @onConfigure@ which is more suited to contain code that contributes to determinate component states because it is called just once during rendering phase. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc new file mode 100644 index 0000000..525f11c --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc @@ -0,0 +1,92 @@ +Component @org.apache.wicket.markup.html.border.Border@ is a special purpose container created to enclose its tag body with its related markup. Just like panels and pages, borders also have their own markup file which is defined following the same rules seen for panels and pages. In this file @<wicket:border>@ tag is used to indicate which part of the content is to be considered as border markup: + +{code:html} +<?xml version="1.0" encoding="UTF-8"?> +<html xmlns="http://www.w3.org/1999/xhtml"; xmlns:wicket="http://wicket.apache.org";> +<head></head> +<body> + <!-- everything above <wicket:border> tag will be discarded...--> + <wicket:border> + <div> + foo<br /> + <wicket:body/><br /> + buz <br /> + + </div> + </wicket:border> + <!-- everything below </wicket:border> tag will be discarded...--> +</body> +</html> +{code} + +The @<wicket:body/>@ tag used in the example above is used to indicate where the body of the tag will be placed inside border markup. Now if we attached this border to the following tag + +{code:html} +<span wicket:id="myBorder"> + bar +</span> +{code} + +we would obtain the following resulting HTML: + +{code:html} +<span wicket:id="myBorder"> + <div> + foo<br /> + bar<br /> + buz <br /> + </div> +</span> +{code} + +@Border@ can also contain children components which can be placed either inside its markup file or inside its corresponding HTML tag. In the first case children must be added to the border component with method @addToBorder(Component...)@, while in the second case we must use the @add(Component...)@ method. + +The following example illustrates both use cases: + +Border class: + +{code} +public class MyBorder extends Border { + + public MyBorder(String id) { + super(id); + } + +} +{code} + +Border Markup: + +{code:html} +<?xml version="1.0" encoding="UTF-8"?> +<html xmlns="http://www.w3.org/1999/xhtml"; xmlns:wicket="http://wicket.apache.org";> +<head></head> +<body> + <wicket:border> + <div> + <div wicket:id="childMarkup"></div> + <wicket:body/><br /> + </div> + </wicket:border> +</body> +</html> +{code} + +Border tag: + +{code:html} +<div wicket:id="myBorder"> + <span wicket:id="childTag"></span> +</div> +{code} + +Initialization code for border: + +{code} +MyBorder myBorder = new MyBorder("myBorder"); + +myBorder.addToBorder(new Label("childMarkup", "Child inside markup.")); +myBorder.add(new Label("childTag", "Child inside tag.")); + +add(myBorder); +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc new file mode 100644 index 0000000..9e118ed --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc @@ -0,0 +1,6 @@ + + +In this chapter we have seen the tools provided by Wicket to gain complete control over the generated HTML. However we didn't see yet how we can repeat a portion of HTML with Wicket. With classic server-side technologies like PHP or JSP we use loops (like @while@ or @for@) inside our pages to achieve this result. +To perform this task Wicket provides a special-purpose family of components called repeaters and designed to repeat their markup body to display a set of items. + +But to fully understand how these components work, we must first learn more of Wicket's basics. That's why repeaters will be introduced later in [chapter 13|guide:repeaters]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc new file mode 100644 index 0000000..d69f720 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc @@ -0,0 +1,32 @@ +To modify tag attributes we can use class @org.apache.wicket.AttributeModifier@. This class extends @org.apache.wicket.behavior.Behavior@ and can be added to any component via the @Component@'s @add@ method. Class @Behavior@ is used to expand component functionalities and it can also modify component markup. We will see this class in detail later in [chapter 17.1|guide:advanced_1]. + +As first example of attribute manipulation let's consider a @Label@ component bound to the following markup: + +{code:html} +<span wicket:id="simpleLabel"></span> +{code} + +Suppose we want to add some style to label content making it red and bolded. We can add to the label an @AttributeModifier@ which creates the tag attribute @style@ with value @"color:red;font-weight:bold"@: + +{code} +label.add(new AttributeModifier("style", "color:red;font-weight:bold")); +{code} + +If attribute @style@ already exists in the original markup, it will be replaced with the value specified by @AttributeModifier@. If we don't want to overwrite the existing value of an attribute we can use subclass @AttributeAppender@ which will append its value to the existing one: + +{code} +label.add(new AttributeAppender("style", "color:red;font-weight:bold")); +{code} + +We can also create attribute modifiers using factory methods provided by class @AttributeModifier@ and it's also possible to prepend a given value to an existing attribute: + +{code} +//replaces existing value with the given one +label.add(AttributeModifier.replace("style", "color:red;font-weight:bold")); + +//appends the given value to the existing one +label.add(AttributeModifier.append("style", "color:red;font-weight:bold")); + +//prepends the given value to the existing one +label.add(AttributeModifier.prepend("style", "color:red;font-weight:bold")); +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc new file mode 100644 index 0000000..286453e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc @@ -0,0 +1 @@ +Tag attribute @id@ plays a crucial role in web development as it allows JavaScript to identify a DOM element. That's why class @Component@ provides two dedicated methods to set this attribute. With method @setOutputMarkupId(boolean output)@ we can decide if the @id@ attribute will be rendered or not in the final markup (by default is not rendered). The value of this attribute will be automatically generated by Wicket and it will be unique for the entire page. If we need to specify this value by hand, we can use method @setMarkupId(String id)@. The value of the id can be retrieved with method @getMarkupId()@. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc new file mode 100644 index 0000000..1e0965d --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc @@ -0,0 +1,26 @@ +Create custom panels is a great way to handle complex user interfaces. However, sometimes we may need to create a panel which is used only by a specific page and only for a specific task. + +In situations like these component @org.apache.wicket.markup.html.WebMarkupContainer@ is better suited than custom panels because it can be directly attached to a tag in the parent markup without needing a corresponding html file (hence it is less reusable). Let's consider for example the main page of a mail service where users can see a list of received mails. Suppose that this page shows a notification box where user can see if new messages have arrived. This box must be hidden if there are no messages to display and it would be nice if we could handle it as if it was a Wicket component. + +Suppose also that this information box is a @<div>@ tag like this inside the page: + +{code:html} +<div wicket:id="informationBox"> + //here's the body + You've got <span wicket:id="messagesNumber"></span> new messages. +</div> +{code} + +Under those conditions we can consider using a @WebMarkupContainer@ component rather than implementing a new panel. The code needed to handle the information box inside the page could be the following: + +{code} +//Page initialization code +WebMarkupContainer informationBox = new WebMarkupContainer ("informationBox"); +informationBox.add(new Label("messagesNumber", messagesNumber)); +add(informationBox); + +//If there are no new messages, hide informationBox +informationBox.setVisible(false); +{code} + +As you can see in the snippet above we can handle our information box from Java code as we do with any other Wicket component. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc new file mode 100644 index 0000000..8c99f31 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc @@ -0,0 +1,58 @@ +Another circumstance in which we may prefer to avoid the creation of custom panels is when we want to conditionally display in a page small fragments of markup. In this case if we decided to use panels, we would end up having a huge number of small panel classes with their related markup file. + +To better cope with situations like this, Wicket defines component @Fragment@ in package @org.apache.wicket.markup.html.panel@. Just like its parent component @WebMarkupContainer@, Fragment doesn't have its own markup file but it uses a markup fragment defined in the markup file of its parent container, which can be a page or a panel. The fragment must be delimited with tag @<wicket:fragment>@ and must be identified by a @wicket:id@ attribute. In addition to the component id, @Fragment@'s constructor takes as input also the id of the fragment and a reference to its container. + +In the following example we have defined a fragment in a page and we used it as content area: + +*Page markup:* + +{code:html} +<html> + ... +<body> +... + <div wicket:id="contentArea"></div> + <wicket:fragment wicket:id="fragmentId"> + <!-- Fragment markup goes here --> + </wicket:fragment> +</body> +</html> +{code} + +*Java code:* + +{code} +Fragment fragment = new Fragment ("contentArea", "fragmentId", this); +add(fragment); +{code} + +Fragments can be very helpful with complex pages or components. For example let's say that we have a page where users can register to our forum. This page should first display a form where user must insert his/her personal data (name, username, password, email and so on), then, once the user has submitted the form, the page should display a message like âYour registration is complete! Please check your mail to activate your user profile.â. + +Instead of displaying this message with a new component or in a new page, we can define two fragments: one for the initial form and one to display the confirmation message. The second fragment will replace the first one after the form has been submitted: + +*Page markup:* + +{code:html} +<html> +<body> + <div wicket:id="contentArea"></div> + <wicket:fragment wicket:id="formFrag"> + <!-- Form markup goes here --> + </wicket:fragment> + <wicket:fragment wicket:id="messageFrag"> + <!-- Message markup goes here --> + </wicket:fragment> +</body> +</html> +{code} + +*Java code:* + +{code} +Fragment fragment = new Fragment ("contentArea", "formFrag", this); +add(fragment); + +//form has been submitted +Fragment fragment = new Fragment ("contentArea", "messageFrag", this); +replace(fragment); +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc new file mode 100644 index 0000000..5b82ba9 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc @@ -0,0 +1,38 @@ +Panel's markup can also contain HTML tags which must go inside header section of the final page, like tags @<script>@ or @<style>@. To tell Wicket to put these tags inside page @<head>@, we must surround them with the @<wicket:head>@ tag. + +Considering the markup of a generic panel, we can use @<wicket:head>@ tag in this way: + +{code:html} +<wicket:head> + <script type="text/javascript"> + function myPanelFunction(){ + } + </script> + + <style> + .myPanelClass{ + font-weight: bold; + color: red; + } + </style> +</wicket:head> +<body> + <wicket:panel> + + </wicket:panel> +</body> +{code} + +Wicket will take care of placing the content of @<wicket:head>@ inside the @<head>@ tag of the final page. + +{note} +The @<wicket:head>@ tag can also be used with children pages/panels which extend parent markup using tag @<wicket:extend>@. +{note} + +{note} +The content of the @<wicket:head>@ tag is added to the header section once per component class. In other words, if we add multiple instances of the same panel to a page, the @<head>@ tag will be populated just once with the content of @<wicket:head>@. +{note} + +{warning} +The @<wicket:head>@ tag is ideal if we want to define small in-line blocks of CSS or JavaScript. However Wicket provides also a more sophisticated technique to let components contribute to header section with in-line blocks and resource files like CSS or JavaScript files. We will see this technique later in [chapter 15|guide:resources]. +{warning} http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc new file mode 100644 index 0000000..ac6d177 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc @@ -0,0 +1,14 @@ +Wicket's @<wicket:remove>@ tag can be very useful when our web designer needs to show us how a page or a panel should look like. The markup inside this tag will be stripped out in the final page, so it's the ideal place for web designers to put their stub markup: + +{code:html} +<html> +<head> + +</head> +<body> + <wicket:remove> + <!-- Stub markup goes here --> + </wicket:remove> +</body> +</html> +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc new file mode 100644 index 0000000..2d1f78d --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc @@ -0,0 +1,39 @@ +When we bind a component to its corresponding tag we can choose to get rid of this outer tag in the final markup. If we call method @setRenderBodyOnly(true)@ on a component Wicket will remove the surrounding tag. + +For example given the following markup and code: + +*HTML markup:* + +{code:html} +<html> +<head> + <title>Hello world page</title> +</head> +<body> +<div wicket:id="helloWorld">[helloWorld]</div> +</body> +</html> +{code} + +*Java code:* + +{code} +Label label = new Label("helloWorld", âHello World!â); +label.setRenderBodyOnly(true); +add(label); +{code} + +the output will be: + +{code:html} +<html> +<head> + <title>Hello world page</title> +</head> +<body> + Hello World! +</body> +</html> +{code} + +As you can see the @<div>@ tag used for component @Label@ is not present in the final markup. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc new file mode 100644 index 0000000..7b1aa7a --- /dev/null +++ b/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc @@ -0,0 +1,33 @@ +Our data are rarely displayed alone without a caption or other graphic elements that make clear the meaning of their value. For example: + +{code:html} +<label>Total amount: </label><span wicket:id="totalAmount"></span> +{code} + +Wicket comes with a nice utility tag called @<wicket:enclosure>@ that automatically hides those decorating elements if the related data value is not visible. All we have to do is to put the involved markup inside this tag. Applying @<wicket:enclosure>@ to the previous example we get the following markup: + +{code:html} +<wicket:enclosure> + <label>Total amount: </label><span wicket:id="totalAmount"></span> +</wicket:enclosure> +{code} + +Now if component @totalAmount@ is not visible, its description (@Total amount:@) will be automatically hidden. If we have more than a Wicket component inside @<wicket:enclosure>@ we can use @child@ attribute to specify which component will control the overall visibility: + +{code:html} +<wicket:enclosure child="totalAmount"> + <label>Total amount: </label><span wicket:id="totalAmount"></span><br/> + <label>Expected delivery date: </label><span wicket:id="delivDate"></span> +</wicket:enclosure> +{code} + +@child@ attribute supports also nested components with a colon-separated path: + +{code:html} +<wicket:enclosure child="totalAmountContainer:totalAmount"> + <div wicket:id="totalAmountContainer"> + <label>Total amount: </label><span wicket:id="totalAmount"></span> + </div> + <label>Expected delivery date: </label><span wicket:id="delivDate"></span> +</wicket:enclosure> +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/layout.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout.gdoc b/wicket-user-guide/src/docs/guide/layout.gdoc new file mode 100644 index 0000000..de0034a --- /dev/null +++ b/wicket-user-guide/src/docs/guide/layout.gdoc @@ -0,0 +1 @@ +Before going ahead with more advanced topics, we will see how to maintain a consistent layout across our site using Wicket and its component-oriented features. Probably this is not the most interesting use we can get out of Wicket, but it is surely the simplest one so it's the best way to get our hands dirty with some code. http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc new file mode 100644 index 0000000..1630a61 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc @@ -0,0 +1,28 @@ +There was a time in the 90s when Internet was just a buzzword and watching a plain HTML page being rendered by a browser was a new and amazing experience. In those days we used to organize our page layout using the @<frame>@ HTML tag. Over the years this tag has almost disappeared from our code and it survives only in few specific domains. For example is still being used by JavaDoc. + +With the adoption of server side technologies like JSP, ASP or PHP the tag @<frame>@ has been replaced by a template-based approach where we divide our page layout into some common areas that will be present in each page of our web application. Then, we manually insert these areas in every page including the appropriate markup fragments. + +In this chapter we will see how to use Wicket to build a site layout. The sample layout we will use is a typical page layout consisting of the following areas: + +* *a header* which could contain site title, some logos, a navigation bar, etc... +* *a left* menu with a bunch of links to different areas/functionalities of the site. +* *a footer* with generic informations like web master's email, the company address, etc... +* *a content* area which usually contains the functional part of the page. + +The following picture summarises the layout structure: + +!layout.png! + +Once we have chosen a page layout, our web designer can start building up the site theme. The result is a beautiful mock of our future web pages. Over this mock we can map the original layout areas: + +!layout-mock.png! + +Now in order to have a consistent layout across all the site, we must ensure that each page will include the layout areas seen above. With an old template-based approach we must manually put them inside every page. If we were using JSP we would probably end up using @include@ directive to add layout areas in our pages. We would have one @include@ for each of the areas (except for the content): + +!layout-include.png! + +{note} +For the sake of simplicity we can consider each included area as a static HTML fragment. +{note} + +Now let's see how we can handle the layout of our web application using Wicket. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc new file mode 100644 index 0000000..f4e839d --- /dev/null +++ b/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc @@ -0,0 +1,64 @@ +The need of ensuring a consistent layout across our pages unveiled a serious limit of the HTML: the inability to apply inheritance to web pages and their markup. Wouldn't be great if we could write our layout once in a page and then inherit it in the other pages of our application? +One of the goals of Wicket is to overcome this kind of limit. + +h3. Markup inheritance + +As we have seen in the previous chapter, Wicket pages are pure Java classes, so we can easily write a page which is a subclass of another parent page. But in Wicket inheritance is not limited to the classic object-oriented code inheritance. When a class subclasses a @WebPage@ it also inherits the HTML file of the parent class. This type of inheritance is called markup inheritance. +To better illustrate this concept let's consider the following example where we have a page class called @GenericSitePage@ with the corresponding HTML file GenericSitePage.html. Now let's create a specific page called @OrderCheckOutPage@ where users can check out their orders on our web site. This class extends @GenericSitePage@ but we don't provide it with any corresponding HTML file. +In this scenario @OrderCheckOutPage@ will use GenericSitePage.html as markup file: + +!markup-inheritance.png! + +Markup inheritance comes in handy for page layout management as it helps us avoid the burden of checking that each page conforms to the site layout. However to fully take advantage of markup inheritance we must first learn how to use another important component of the framework that supports this feature: the panel. + +{warning} +If no markup is found (nor directly assigned to the class, neither inherited from an ancestor) a @MarkupNotFoundException@ is thrown. +{warning} + +h3. Panel class + +Class @org.apache.wicket.markup.html.panel.Panel@ is a special component which lets us reuse GUI code and HTML markup across different pages and different web applications. It shares a common ancestor class with WebPage class, which is @org.apache.wicket.MarkupContainer@: + +!page-panel-hierarchy.png! + +_Illustration: Hierarchy of WebPage and Panel classes_ + +Subclasses of @MarkupContainer@ can contain children components that can be added with method @add(Component...)@ (seen in [chapter 3.3|guide:whyLearn_3]). @MarkupContainer@ implements a full set of methods to manage children components. The basic operations we can do on them are: + +* add one or more children components (with method @add@). +* remove a specific child component (with method @remove@). +* retrieve a specific child component with method @get(String)@. The string parameter is the id of the component or its relative path if the component is nested inside other @MarkupContainer@s. This path is a colon-separated string containing also the ids of the intermediate containers traversed to get to the child component. To illustrate an example of component path, let's consider the code of the following page: + +{code} +MyPanel myPanel = new MyPanel ("innerContainer"); +add(myPanel); +{code} + +Component @MyPanel@ is a custom panel containing only a label having @"name"@ as id. Under those conditions we could retrieve this label from the container page using the following path expression: + +{code} +Label name = (Label)get("innerContainer:name"); +{code} + +* replace a specific child component with a new component having the same id (with method @replace@). +* iterate thought children components with the iterator returned by method @iterator@ or using visitor pattern1 with methods @visitChildren@. + +Both @Panel@ and @WebPage@ have their own associated markup file which is used to render the corresponding component. If such file is not provided, Wicket will apply markup inheritance looking for a markup file through their ancestor classes. When a panel is attached to a container, the content of its markup file is inserted into its related tag. + +While panels and pages have much in common, there are some notable differences between these two components that we should keep in mind. The main difference between them is that pages can be rendered as standalone entities while panels must be placed inside a page to be rendered. Another important difference is the content of their markup file: for both @WebPage@ and @Panel@ this is a standard HTML file, but @Panel@ uses a special tag to indicate which part of the whole file will be considered as markup source. This tag is @<wicket:panel>@. A markup file for a panel will typically look like this: + +{code:html} +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +... +</head> +<body> + <wicket:panel> + <!-- Your markup goes here --> + </wicket:panel> +</body> +</html> +{code} + +The HTML outside tag @<wicket:panel>@ will be removed during rendering phase. The space outside this tag can be used by both web developers and web designers to place some mock HTML to show how the final panel should look like.
