http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_11.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_11.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_11.gdoc new file mode 100644 index 0000000..664b54c --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_11.gdoc @@ -0,0 +1,187 @@ + + +In this paragraph we will see which components can be used to handle HTML radio buttons and checkboxes. Both these input elements are usually grouped together to display a list of possible choices: + +!choice-form-screenshot.png! + +A check box can be used as single component to set a boolean property. For this purpose Wicket provides the @org.apache.wicket.markup.html.form.CheckBox@ component which must be attached to <input type="checkbox".../> tag. In the next example (project SingleCheckBox) we will consider a form similar to the one used in paragraph 9.5 to edit a Person object, but with an additional checkbox to let the user decide if she wants to subscribe to our mailing list or not. The form uses the following bean as backing object: + +{code} +public class RegistrationInfo implements Serializable { + + private String name; + private String surname; + private String address; + private String email; + private boolean subscribeList; + + /*Getters and setters*/ +} +{code} + +The markup and the code for this example are the following: + +*HTML:* + +{code:html} +<form wicket:id="form"> + <div style="display: table;"> + <div style="display: table-row;"> + <div style="display: table-cell;">Name: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="name"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Surname: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="surname"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Address: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="address"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Email: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="email"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Subscribe list:</div> + <div style="display: table-cell;"> + <input type="checkbox" wicket:id="subscribeList"/> + </div> + </div> + </div> + <input type="submit" value="Save"/> +</form> +{code} + +*Java code:* + +{code} +public HomePage(final PageParameters parameters) { + RegistrationInfo registrtionInfo = new RegistrationInfo(); + registrtionInfo.setSubscribeList(true); + + Form form = new Form("form", + new CompoundPropertyModel<RegistrationInfo>(registrtionInfo)); + + form.add(new TextField("name")); + form.add(new TextField("surname")); + form.add(new TextField("address")); + form.add(new TextField("email")); + form.add(new CheckBox("subscribeList")); + + add(form); +} +{code} + +Please note that the checkbox will be initially selected because we have set to true the subscribe flag during the model object creation (with instruction registrtionInfo.setSubscribeList(true)): + +!subscribe-checkbox-set.png! + +h3. Working with grouped checkboxes + +When we need to display a given number of options with checkboxes, we can use the @org.apache.wicket.markup.html.form.CheckBoxMultipleChoice@ component. For example, If our options are a list of strings, we can display them in this way: + +*HTML:* + +{code:html} +<div wicket:id="checkGroup"> + <input type="checkbox"/>It will be replaced by the actual checkboxes... +</div> +{code} + +*Java code:* + +{code} +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new + ArrayList<String>()), fruits)); +{code} + +*Screenshot:* + +!grouped-checkbox.png! + +This component can be attached to a <div> tag or to a <span> tag. No specific content is required for this tag as it will be populated with the actual checkboxes. Since this component allows multiple selection, its model object is a list. In the example above we have used model class @org.apache.wicket.model.util.ListModel@ which is specifically designed to wrap a List object. + +By default CheckBoxMultipleChoice inserts a <br/> tag as suffix after each option. We can configure both the suffix and the prefix used by the component with the setPrefix and setSuffix methods. + +When our options are more complex objects than simple strings, we can render them using an IChoiceRender, as we did for DropDownChoice in paragraph 9.4: + +*HTML:* + +{code:html} +<div wicket:id="checkGroup"> + <input type="checkbox"/>It will be replaced by actual checkboxes... +</div> +{code} + +*Java code:* + +{code} +Person john = new Person("John", "Smith"); +Person bob = new Person("Bob", "Smith"); +Person jill = new Person("Jill", "Smith"); +List<Person> theSmiths = Arrays.asList(john, bob, jill); +ChoiceRenderer render = new ChoiceRenderer("name"); + form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new ArrayList<String>()), + theSmiths, render)); +{code} + +*Screenshot:* + +!grouped-checkbox2.png! + +h3. How to implement a "Select all" checkbox + +A nice feature we can offer to users when we have a group of checkboxes is a âspecialâ checkbox which selects/unselects all the other options of the group: + +!select-all-checkbox.png! + +Wicket comes with a couple of utility components that make it easy to implement such a feature. They are CheckboxMultipleChoiceSelector and CheckBoxSelector classes, both inside package @org.apache.wicket.markup.html.form@. The difference between these two components is that the first works with an instance of CheckBoxMultipleChoice while the second takes in input a list of CheckBox objects: + +{code} +/* CheckboxMultipleChoiceSelector usage: */ + +CheckBoxMultipleChoice checkGroup; +//checkGroup initialization... +CheckboxMultipleChoiceSelector cbmcs = new CheckboxMultipleChoiceSelector("id", checkGroup); + +/* CheckBoxSelector usage: */ + +CheckBox checkBox1, checkBox2, checkBox3; +//checks initialization... +CheckBoxSelector cbmcs = new CheckBoxSelector("id", checkBox1, checkBox2, checkBox3); +{code} + +h3. Working with grouped radio buttons + +For groups of radio buttons we can use the @org.apache.wicket.markup.html.form.RadioChoice@ component which works in much the same way as CheckBoxMultipleChoice: + +*HTML:* + +{code:html} +<div wicket:id="radioGroup"> + <input type="radio"/>It will be replaced by actual radio buttons... +</div> +{code} + +*Java code:* + +{code} +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new RadioChoice("radioGroup", Model.of(""), fruits)); +{code} + +*Screenshot:* + +!grouped-radiobutton.png! + +Just like CheckBoxMultipleChoice, this component provides the setPrefix and setSuffix methods to configure the prefix and suffix for our options and it supports IChoiceRender as well. In addition, RadioChoice provides the wantOnSelectionChangedNotifications() method to notify the web server when the selected option changes (this is the same method seen for DropDownChoice in paragraph 9.4). \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_12.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_12.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_12.gdoc new file mode 100644 index 0000000..058b8b9 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_12.gdoc @@ -0,0 +1,106 @@ + + +Checkboxes work well when we have a small amount of options to display, but they quickly become chaotic as the number of options increases. To overcome this limit we can use the <select> tag switching it to multiple-choice mode with attribute multiple="multiple": + +!list-multiple-choices.png! + +Now the user can select multiple options by holding down Ctrl key (or Command key for Mac) and selecting them. + +To work with multiple choice list Wicket provides the @org.apache.wicket.markup.html.form.ListMultipleChoice@ component: + +*HTML:* + +{code:html} +<select wicket:id="fruits"> + <option>choice 1</option> + <option>choice 2</option> +</select> +{code} + +*Java code:* + +{code} +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new ListMultipleChoice("fruits", new ListModel<String>(new ArrayList<String>()), fruits)); +{code} + +*Screenshot:* + +!list-multiple-choices2.png! + +This component must be bound to a <select> tag but the attribute multiple="multiple" is not required as it will automatically be added by the component. + +The number of visible rows can be set with the setMaxRows(int maxRows) method. + +h3. Component Palette + +While multiple choice list solves the problem of handling a big number of multiple choices, it is not much intuitive for end users. That's why desktop GUIs have introduced a more complex component which can be generally referred to as multi select transfer component (it doesn't have an actual official name): + +!multi-select-transfer-component.png! + +This kind of component is composed by two multiple-choice lists, one on the left displaying the available options and the other one on the right displaying the selected options. User can move options from a list to another by double clicking on them or using the buttons placed between the two list. + +Built-in @org.apache.wicket.extensions.markup.html.form.palette.Palette@ component provides an out-of-the-box implementation of a multi select transfer component. It works in a similar way to ListMultipleChoice: + +*HTML:* + +{code:html} +<div wicket:id="palette"> + Select will be replaced by the actual content... + <select multiple="multiple"> + <option>option1</option> + <option>option2</option> + <option>option3</option> +</div> +{code} + +*Java code:* + +{code} +Person john = new Person("John", "Smith"); +Person bob = new Person("Bob", "Smith"); +Person jill = new Person("Jill", "Smith"); +Person andrea = new Person("Andrea", "Smith"); + +List<Person> theSmiths = Arrays.asList(john, bob, jill, andrea); +ChoiceRenderer render = new ChoiceRenderer("name"); + +form.add(new Palette("palette", Model.of(new ArrayList<String>()), new ListModel<String> (theSmiths), render, 5, true)); +{code} + +*Screenshot:* + +!multi-select-transfer-component-wicket.png! + +The last two parameters of the Palette's constructor (an integer value and a boolean value) are, respectively, the number of visible rows for the two lists and a flag to choose if we want to display the two optional buttons which move selected options up and down. The descriptions of the two lists (âAvailableâ and âSelectedâ) can be customized providing two resources with keys palette.available and palette.selected. + +The markup of this component uses a number of CSS classes which can be extended/overriden to customize the style of the component. We can find these classes and see which tags they decorate in the default markup file of the component: + +{code:html} +<table cellspacing="0" cellpadding="2" class="palette"> +<tr> + <td class="header headerAvailable"><span wicket:id="availableHeader">[available header]</span></td> + <td> </td> + <td class="header headerSelected"><span wicket:id="selectedHeader">[selected header]</span> + </td> +</tr> +<tr> + <td class="pane choices"> + <select wicket:id="choices" class="choicesSelect">[choices]</select> + </td> + <td class="buttons"> + <button type="button" wicket:id="addButton" class="button add"><div/> + </button><br/> + <button type="button" wicket:id="removeButton" class="button remove"><div/> + </button><br/> + <button type="button" wicket:id="moveUpButton" class="button up"><div/> + </button><br/> + <button type="button" wicket:id="moveDownButton" class="button down"><div/> + </button><br/> + </td> + <td class="pane selection"> + <select class="selectionSelect" wicket:id="selection">[selection]</select> + </td> +</tr> +</table> +{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_13.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_13.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_13.gdoc new file mode 100644 index 0000000..c91e48e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_13.gdoc @@ -0,0 +1,6 @@ + +Forms are the standard solution to let users interact with our web applications. In this chapter we have seen the three steps involved with the form processing workflow in Wicket. We have started looking at form validation and feedback messages generation, then we have seen how Wicket converts input values into Java objects and vice versa. + +In the second part of the chapter we learnt how to build reusable form components and how to implement a stateless form. We have ended the chapter with an overview of the built-in form components needed to handle standard input form elements like checkboxes, radio buttons and multiple selections lists. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_2.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_2.gdoc new file mode 100644 index 0000000..2e9ea33 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_2.gdoc @@ -0,0 +1,285 @@ + + +A basic example of a validation rule is to make a field required. In paragraph 9.3.2 we have already seen how this can be done calling setRequired(true) on a field. However, to set a validation rule on a FormComponent we must add the corresponding validator to it. + +A validator is an implementation of the @org.apache.wicket.validation.IValidator@ interface and the @FormComponent@ has a version of method add which takes as input a reference of this interface. + +For example if we want to use a text field to insert an email address, we could use the built-in validator EmailAddressValidator to ensure that the inserted input will respect the email format "local-part@domain":http://en.wikipedia.org/wiki/Email_address : + +{code} +TextField email = new TextField("email"); +email.add(EmailAddressValidator.getInstance()); +{code} + +Wicket comes with a set of built-in validators that should suit most of our needs. We will see them in paragraph 10.2.3. + +h3. Feedback messages and localization + +Wicket generates a feedback message for each field that doesn't satisfy one of its validation rules. For example the message generated when a required field is left empty is the following + +@Field '<label>' is required.@ + +<label> is the value of the label model set on a FormComponent with method setLabel(IModel <String> model). If such model is not provided, component id will be used as the default value. + +The entire infrastructure of feedback messages is built on top of the Java internationalization (I18N) support and it uses "resource bundles":http://docs.oracle.com/javase/tutorial/i18n/resbundle/index.html to store messages. + +{note} +The topics of internationalization will be covered in chapter 12. For now we will give just few notions needed to understand the examples from this chapter. +{note} + +By default resource bundles are stored into properties files but we can easily configure other sources as described later in paragraph 12.4.5. + +Default feedback messages (like the one above for required fields) are stored in the file Application. properties placed inside Wicket the org.apache.wicket package. Opening this file we can find the key and the localized value of the message: + +@Required=Field '$\{label\}' is required.@ + +We can note the key (Required in our case) and the label parameter written in the "expression language":http://en.wikipedia.org/wiki/Expression_Language (${label}). Scrolling down this file we can also find the message used by the Email AddressValidator: + +@EmailAddressValidator=The value of '${label}' is not a valid email address.@ + +By default FormComponent provides 3 parameters for feedback message: input (the value that failed validation), label and name (this later is the id of the component). + +{warning} +Remember that component model is updated with the user input only if validation succeeds! As a consequence, we can't retrieve the wrong value inserted for a field from its model. Instead, we should use getValue() method of FormComponent class. (This method will be introduced in the example used in paragraph 10.2.5) +{warning} + +h3. Displaying feedback messages and filtering them + +To display feedback messages we must use component @org.apache.wicket.markup.html.panel.FeedbackPanel@. This component automatically reads all the feedback messages generated during form validation and displays them with an unordered list: + +{code:html} +<ul class="feedbackPanel"> + <li class="feedbackPanelERROR"> + <span class="feedbackPanelERROR">Field 'Username' is required.</span> + </li> +</ul> +{code} + +CSS classes "feedbackPanel" and "feedbackPanelERROR" can be used in order to customize the style of the message list: + +!feedback-panel-style.png! + +The component can be freely placed inside the page and we can set the maximum amount of displayed messages with the setMaxMessages() method. + +Error messages can be filtered using three built-in filters: + +* *ComponentFeedbackMessageFilter*: shows only messages coming from a specific component. +* *ContainerFeedbackMessageFilter*: shows only messages coming from a specific container or from any of its children components. +* *ErrorLevelFeedbackMessageFilter*: shows only messages with a level of severity equals or greater than a given lower bound. Class FeedbackMessage defines a set of static constants to express different levels of severity: DEBUG, ERROR, WARNING, INFO, SUCCESS, etc.... Levels of severity for feedback messages are discussed in paragraph 10.2.6. + +These filters are intended to be used when there are more than one feedback panel (or more than one form) in the same page. We can pass a filter to a feedback panel via its constructor or using the setFilter method. Custom filters can be created implementing the IFeedbackMessageFilter interface. An example of custom filter is illustrated later in this paragraph. + +h3. Built-in validators + +Wicket already provides a number of built-in validators ready to be used. The following table is a short reference where validators are listed along with a brief description of what they do. The default feedback message used by each of them is reported as well: + +h4. EmailAddressValidator + +Checks if input respects the format local-part\@domain. + +*Message:* + +@The value of '${label}' is not a valid email address.@ + +h4. UrlValidator + +Checks if input is a valid URL. We can specify in the constructor which protocols are allowed (http://, https://, and ftp://). + +*Message:* + +@The value of '${label}' is not a valid URL.@ + +h4. DateValidator + +Validator class that can be extended or used as a factory class to get date validators to check if a date is bigger than a lower bound (method minimum(Date min)), smaller than a upper bound (method maximum(Date max)) or inside a range (method range(Date min, Date max)). + +*Messages:* + +@The value of '${label}' is less than the minimum of ${minimum}.@ + +@The value of '${label}' is larger than the maximum of ${maximum}.@ + +@The value of '${label}' is not between ${minimum} and ${maximum}.@ + +h4. RangeValidator + +Validator class that can be extended or used as a factory class to get validators to check if a value is bigger than a given lower bound (method minimum(T min)), smaller than a upper bound (method maximum(T max)) or inside a range (method range(T min,T max)). + +The type of the value is a generic subtype of java.lang.Comparable and must implement Serializable interface. + +*Messages:* + +@The value of '${label}' must be at least ${minimum}.@ + +@The value of '${label}' must be at most ${maximum}.@ + +@The value of '${label}' must be between ${minimum} and ${maximum}.@ + +h4. StringValidator + +Validator class that can be extended or used as a factory class to get validators to check if the length of a string value is bigger then a given lower bound (method minimumLength (int min)), smaller then a given upper bound (method maximumLength (int max)) or within a given range (method lengthBetween(int min, int max)). + +To accept only string values consisting of exactly n characters, we must use method exactLength(int length). + +*Messages:* + +@The value of '${label}' is shorter than the minimum of ${minimum} characters.@ + +@The value of '${label}' is longer than the maximum of ${maximum} characters.@ + +@The value of '${label}' is not between ${minimum} and ${maximum} characters long.@ + +@The value of '${label}' is not exactly ${exact} characters long.@ + +h4. CreditCardValidator + +Checks if input is a valid credit card number. This validator supports some of the most popular credit cards (like âAmerican Express", "MasterCard", âVisaâ or âDiners Clubâ). + +*Message:* + +@The credit card number is invalid.@ + +h4. EqualPasswordInputValidator + +This validator checks if two password fields have the same value. + +*Message:* + +@${label0} and ${label1} must be equal.@ + +h3. Overriding standard feedback messages with custom bundles + +If we don't like the default validation feedback messages, we can override them providing custom properties files. In these files we can write our custom messages using the same keys of the messages we want to override. For example if we wanted to override the default message for invalid email addresses, our properties file would contain a line like this: + +@EmailAddressValidator=Man, your email address is not good!@ + +As we will see in the next chapter, Wicket searches for custom properties files in various positions inside the application's class path, but for now we will consider just the properties file placed next to our application class. The name of this file must be equal to the name of our application class: + +!custom-properties-file.png! + +The example project OverrideMailMessage overrides email validator's message with a new one which also reports the value that failed validation: + +@EmailAddressValidator=The value '${input}' inserted for field '${label}' is not a valid email address.@ + +!validation-error-message.png! + +h3. Creating custom validators + +If our web application requires a complex validation logic and built-in validators are not enough, we can implement our own custom validators. For example (project UsernameCustomValidator) suppose we are working on the registration page of our site where users can create their profile choosing their username. Our registration form should validate the new username checking if it was already chosen by another user. In a situation like this we may need to implement a custom validator that queries a specific data source to check if a username is already in use. + +For the sake of simplicity, the validator of our example will check the given username against a fixed list of three existing usernames. + +A custom validator must simply implement interface IValidator: + +{code} +public class UsernameValidator implements IValidator<String> { + List<String> existingUsernames = Arrays.asList("bigJack", "anonymous", "mrSmith"); + + public void validate(IValidatable<String> validatable) { + String chosenUserName = validatable.getValue(); + + if(existingUsernames.contains(chosenUserName)){ + ValidationError error = new ValidationError(this); + Random random = new Random(); + + error.setVariable("suggestedUserName", + validatable.getValue() + random.nextInt()); + validatable.error(error); + } + } +} +{code} + +The only method defined inside IValidator is validate(IValidatable<T> validatable) and is invoked during validation's step. Interface IValidatable represents the component being validated and it can be used to retrieve the component model (getModel()) or the value to validate (getValue()). + +The custom validation logic is all inside IValidator's method validate. When validation fails a validator must use IValidatable's method error(IValidationError error) to generate the appropriate feedback message. In the code above we used the ValidationError class as convenience implementation of the IValidationError interface which represents the validation error that must be displayed to the user. This class provides a constructor that uses the class name of the validator in input as key for the resource to use as feedback message (i.e. 'UsernameValidator' in the example). If we want to specify more then one key to use to locate the error message, we can use method addKey(String key) of ValidationError class. + +In our example when validation fails, we suggest a possible username concatenating the given input with a pseudo-random integer. This value is passed to the feedback message with a variable named suggestedUserName. The message is inside application's properties file: + +@UsernameValidator=The username '${input}' is already in use. Try with '${suggestedUserName}'@ + +To provide further variables to our feedback message we can use method setVariable(String name, Object value) of class ValidationError as we did in our example. + +The code of the home page of the project will be examined in the next paragraph after we have introduced the topic of flash messages. + +h3. Using flash messages + +So far we have considered just the error messages generated during validation step. However Wicket's Component class provides a set of methods to explicitly generate feedback messages called flash messages. These methods are: + +* debug(Serializable message) +* info(Serializable message) +* success(Serializable message) +* warn(Serializable message) +* error(Serializable message) +* fatal(Serializable message) + +Each of these methods corresponds to a level of severity for the message. The list above is sorted by increasing level of severity. + +In the example seen in the previous paragraph we have a form which uses success method to notify user when the inserted username is valid. Inside this form there are two FeedbackPanel components: one to display the error message produced by custom validator and the other one to display the success message. The code of the example page is the following: + +*HTML:* + +{code:html} +<body> + <form wicket:id="form"> + Username: <input type="text" wicket:id="username"/> + <br/> + <input type="submit"/> + </form> + <div style="color:green" wicket:id="succesMessage"> + </div> + <div style="color:red" wicket:id="feedbackMessage"> + </div> +</body> +{code} + +*Java code:* + +{code} +public class HomePage extends WebPage { + + public HomePage(final PageParameters parameters) { + Form form = new Form("form"){ + @Override + protected void onSubmit() { + super.onSubmit(); + success("Username is good!"); + } + }; + + TextField mail; + + form.add(mail = new TextField("username", Model.of(""))); + mail.add(new UsernameValidator()); + + add(new FeedbackPanel("feedbackMessage", + new ExactErrorLevelFilter(FeedbackMessage.ERROR))); + add(new FeedbackPanel("succesMessage", + new ExactErrorLevelFilter(FeedbackMessage.SUCCESS))); + + add(form); + } + + class ExactErrorLevelFilter implements IFeedbackMessageFilter{ + private int errorLevel; + + public ExactErrorLevelFilter(int errorLevel){ + this.errorLevel = errorLevel; + } + + public boolean accept(FeedbackMessage message) { + return message.getLevel() == errorLevel; + } + + } + //UsernameValidator definition + //... +} +{code} + +The two feedback panels must be filtered in order to display just the messages with a given level of severity (ERROR for validator message and SUCCESS for form's flash message). Unfortunately the built-in message filter ErrorLevelFeedbackMessageFilter is not suitable for this task because its filter condition does not check for an exact error level (the given level is used as lower bound value). As a consequence, we had to build a custom filter (inner class ExactErrorLevelFilter) to accept only the desired severity level (see method accept of interface IFeedbackMessageFilter). + +{note} +Since version 6.13.0 Wicket provides the additional filter class org.apache.wicket.feedback.ExactLevelFeedbackMessageFilter to accept only feedback messages of a certain error level. +{note} + http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_3.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_3.gdoc new file mode 100644 index 0000000..83b9add --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_3.gdoc @@ -0,0 +1,137 @@ + + +Working with Wicket we will rarely need to worry about conversion between input values (which are strings because the underlying HTTP protocol) and Java types because in most cases the default conversion mechanism will be smart enough to infer the type of the model object and perform the proper conversion. However, sometimes we may need to work under the hood of this mechanism to make it properly work or to perform custom conversions. That's why this paragraph will illustrate how to control input value conversion. + +The component that is responsible for converting input is the FormComponent itself with its convertInput() method. In order to convert its input a FormComponent must know the type of its model object. This parameter can be explicitly set with method setType(Class<?> type): + +{code} +//this field must receive an integer value +TextField integerField = new TextField("number", new Model()).setType(Integer.class)); +{code} + +If no type has been provided, FormComponent will try to ask its model for this information. The PropertyModel and CompoundPropertyModel models can use reflection to get the type of object model. By default, if FormComponent can not obtain the type of its model object in any way, it will consider it as a simple String. + +Once FormComponent has determined the type of model object, it can look up for a converter, which is the entity in charge of converting input to Java object and vice versa. Converters are instances of @org.apache.wicket.util.convert.IConverter@ interface and are registered by our application class on start up. + +To get a converter for a specific type we must call method getConverter(Class<C> type) on the interface IConverterLocator returned by Application's method getConverterLocator(): + +{code} +//retrieve converter for Boolean type +Application.get().getConverterLocator().getConverter(Boolean.class); +{code} + +{note} +Components which are subclasses of AbstractSingleSelectChoice don't follow the schema illustrated above to convert user input. + +These kinds of components (like DropDownChoice and RadioChoice1) use their choice render and their collection of possible choices to perform input conversion. +{note} + +h3. Creating custom application-scoped converters + +The default converter locator used by Wicket is @org.apache.wicket.ConverterLocator@. This class provides converters for the most common Java types. Here we can see the converters registered inside its constructor: + +{code} +public ConverterLocator() +{ + set(Boolean.TYPE, BooleanConverter.INSTANCE); + set(Boolean.class, BooleanConverter.INSTANCE); + set(Byte.TYPE, ByteConverter.INSTANCE); + set(Byte.class, ByteConverter.INSTANCE); + set(Character.TYPE, CharacterConverter.INSTANCE); + set(Character.class, CharacterConverter.INSTANCE); + set(Double.TYPE, DoubleConverter.INSTANCE); + set(Double.class, DoubleConverter.INSTANCE); + set(Float.TYPE, FloatConverter.INSTANCE); + set(Float.class, FloatConverter.INSTANCE); + set(Integer.TYPE, IntegerConverter.INSTANCE); + set(Integer.class, IntegerConverter.INSTANCE); + set(Long.TYPE, LongConverter.INSTANCE); + set(Long.class, LongConverter.INSTANCE); + set(Short.TYPE, ShortConverter.INSTANCE); + set(Short.class, ShortConverter.INSTANCE); + set(Date.class, new DateConverter()); + set(Calendar.class, new CalendarConverter()); + set(java.sql.Date.class, new SqlDateConverter()); + set(java.sql.Time.class, new SqlTimeConverter()); + set(java.sql.Timestamp.class, new SqlTimestampConverter()); + set(BigDecimal.class, new BigDecimalConverter()); +} +{code} + +If we want to add more converters to our application, we can override Application's method newConverterLocator which is used by application class to build its converter locator. + +To illustrate how to implement custom converters and use them in our application, we will build a form with two text field: one to input a regular expression pattern and another one to input a string value that will be split with the given pattern. + +The first text field will have an instance of class java.util.regex.Pattern as model object. The final page will look like this (the code of this example is from the CustomConverter project): + +!regex-form.png! + +The conversion between Pattern and String is quite straightforward. The code of our custom converter is the following: + +{code} +public class RegExpPatternConverter implements IConverter<Pattern> { + @Override + public Pattern convertToObject(String value, Locale locale) { + return Pattern.compile(value); + } + + @Override + public String convertToString(Pattern value, Locale locale) { + return value.toString(); + } +} +{code} + +Methods declared by interface IConverter take as input a Locale parameter in order to deal with locale-sensitive data and conversions. We will learn more about locales and internationalization in chapter 12. + +Once we have implemented our custom converter, we must override method newConverterLocator() inside our application class and tell it to add our new converter to the default set: + +{code} +@Override + protected IConverterLocator newConverterLocator() { + ConverterLocator defaultLocator = new ConverterLocator(); + + defaultLocator.set(Pattern.class, new RegExpPatternConverter()); + + return defaultLocator; + } +{code} + +Finally, in the home page of the project we build the form which displays (with a flash message) the tokens obtained splitting the string with the given pattern: + +{code} +public class HomePage extends WebPage { + private Pattern regExpPatter; + private String stringToSplit; + + public HomePage(final PageParameters parameters) { + TextField mail; + TextField stringToSplitTxt; + + Form form = new Form("form"){ + @Override + protected void onSubmit() { + super.onSubmit(); + String messageResult = "Tokens for the given string and pattern:<br/>"; + String[] tokens = regExpPatter.split(stringToSplit); + + for (String token : tokens) { + messageResult += "- " + token + "<br/>"; + } + success(messageResult); + } + }; + + form.setDefaultModel(new CompoundPropertyModel(this)); + form.add(mail = new TextField("regExpPatter")); + form.add(stringToSplitTxt = new TextField("stringToSplit")); + add(new FeedbackPanel("feedbackMessage").setEscapeModelStrings(false)); + + add(form); + } +} +{code} + +{note} +If the user input can not be converted to the target type, FormComponent will generate the default error message âThe value of '${label}' is not a valid ${type}.â. The bundle key for this message is IConverter. +{note} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_4.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_4.gdoc new file mode 100644 index 0000000..635d0eb --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_4.gdoc @@ -0,0 +1,82 @@ +Standard JSR 303 defines a set of annotations and APIs to validate our domain objects at field-level. Wicket has introduced an experimental support for this standard since version 6.4.0 and with version 6.14.0 it has became an official Wicket model (named @wicket-bean-validation@). +In this paragraph we will see the basic steps needed to use JSR 303 validation in our Wicket application. Code snippets are from example project @JSR303validation@. + +In the example application we have a form to insert the data for a new @Person@ bean and its relative @Address@. The code for class @Person@ is the following + +{code} +public class Person implements Serializable{ + + @NotNull + private String name; + + //regular expression to validate an email address + @Pattern(regexp = "^[_A-Za-z0-9-]+(.[_A-Za-z0-9-]+)*[A-Za-z0-9-]+(.[A-Za-z0-9-]+)*((.[A-Za-z]{2,}){1}$)") + private String email; + + @Range(min = 18, max = 150) + private int age; + + @Past @NotNull + private Date birthDay; + + @NotNull + private Address address; +} +{code} + +You can note the JSR 303 annotations used in the code above to declare validation constraints on class fields. Class @Address@ has the following code: + +{code} +public class Address implements Serializable { + + @NotNull + private String city; + + @NotNull + private String street; + + @Pattern(regexp = "\\d+", message = "{address.invalidZipCode}") + private String zipCode; +} +{code} + +You might have noted that in class @Address@ we have used annotation @Pattern using also attribute @message@ which contains the key of the bundle to use for validation message. Our custom bundle is contained inside @HomePage.properties@: + +{code} +address.invalidZipCode=The inserted zip code is not valid. +{code} + +To tell Wicket to use JSR 303, we must register bean validator on Application's startup: + +{code} +public class WicketApplication extends WebApplication { + @Override + public void init(){ + super.init(); + + new BeanValidationConfiguration().configure(this); + } +} +{code} + +The last step to harness JSR 303 annotations is to add validator @org.apache.wicket.bean.validation.PropertyValidator@ to our corresponding form components: + +{code} +public HomePage(final PageParameters parameters) { + super(parameters); + + setDefaultModel(new CompoundPropertyModel<Person>(new Person())); + + Form<Void> form = new Form<Void>("form"); + + form.add(new TextField("name").add(new PropertyValidator())); + form.add(new TextField("email").add(new PropertyValidator())); + form.add(new TextField("age").add(new PropertyValidator())); + //... +} +{code} + +Now we can run our application an see that JSR 303 annotations are fully effective: + +!jsr303-form-validation.png! + http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_5.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_5.gdoc new file mode 100644 index 0000000..46a2b0b --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_5.gdoc @@ -0,0 +1,124 @@ + + +Besides submitting forms with a standard HTML submit button, Wicket allows us to use special components which implement interface IFormSubmittingComponent. This entity is a subinterface of IFormSubmitter: + +!class-diag-IFormSubmittingComponent.png! + +At the beginning of this chapter we have seen that form processing is started by process method which takes as input an instance of IFormSubmitter. This parameter corresponds to the IFormSubmittingComponent clicked by a user to submit the form and it is null if we have used a standard HTML submit button (like we have done so far). + +A submitting component is added to a form just like any other child component using method add(Component...). + +A form can have any number of submitting components and we can specify which one among them is the default one by calling the Form's method setDefaultButton(IFormSubmittingComponent  component). The default submitter is the one that will be used when user presses 'Enter' key in a field of the form. In order to make the default button work, Wicket will add to our form a hidden <div> tag containing a text field and a submit button with some JavaScript code to trigger it: + +{code:html} +<div style="width:0px;height:0px;position:absolute;left:-100px;top:-100px;overflow:hidden"> + <input type="text" autocomplete="off"/> + <input type="submit" name="submit2" onclick=" var b=document...."/> +</div> +{code} + +Just like Wicket forms, interface IFormSubmitter defines methods onSubmit and onError. These two methods have the priority over the namesake methods of the form, meaning that when a form is submitted with an IFormSubmitter, the onSubmit of the submitter is called before the one of the form. Similarly, if validation errors occurs during the first step of form processing, submitter's method onError is called before the form's one. + +{note} +Starting with Wicket version 6.0 interface IFormSubmitter defines a further callback method called onAfterSubmit(). This method is called after form's method onSubmit() has been executed. +{note} + +h3. Components Button and SubmitLink + +Component @org.apache.wicket.markup.html.form.Button@ is a basic implementation of a form submitter. It can be used with either the <input> or <button> tags. The string model received as input by its constructor is used as button label and it will be the value of the markup attribute value. + +In the following snippet we have a form with two submit buttons bound to an <input> tag. One of them is set as default button and both have a string model for the label: + +*HTML:* + +{code:html} +<body> + <form wicket:id="form"> + Username: <input type="text" wicket:id="username"/> + <br/> + <input type="submit" wicket:id="submit1"/> + <input type="submit" wicket:id="submit2"/> + </form> +</body> +{code} + +*Java code:* + +{code} +public class HomePage extends WebPage { + + public HomePage(final PageParameters parameters) { + Form form = new Form("form"); + + form.add(new TextField("username", Model.of(""))); + form.add(new Button("submit1", Model.of("First submitter"))); + Button secondSubmitter; + form.add(secondSubmitter = new Button("submit2", Model.of("Second submitter"))); + + form.setDefaultButton(secondSubmitter); + add(form); + } +} +{code} + +*Generated markup:* + +{code:html} +<form wicket:id="form" id="form1" method="post" action="?0-1.IFormSubmitListener-form"> + <div> + ... + <!-- Code generated by Wicket to handle the default button --> + ... + </div> + Username: <input type="text" wicket:id="username" value="" name="username"/> + <br/> + <input type="submit" wicket:id="submit1" name="submit1" id="submit13" value="First submitter"/> + <input type="submit" wicket:id="submit2" name="submit2" id="submit22" value="Second submitter"/> +</form> +{code} + +Another component that can be used to submit a form is @org.apache.wicket.markup.html.form.SubmitLink@. This component uses JavaScript to submit the form. Like the name suggests, the component can be used with the <a> tag but it can be also bound to any other tag that supports the event handler onclick. When used with the <a> tag, the JavaScript code needed to submit the form will be placed inside href attribute while with other tags the script will go inside the event handler onclick. + +A notable difference between this component and Button is that SubmitLink can be placed outside the form it must submit. In this case we must specify the form to submit in its constructor: + +*HTML:* + +{code:html} +<html xmlns:wicket="http://wicket.apache.org";> +<head> + </head> + <body> + <form wicket:id="form"> + Password: <input type="password" wicket:id="password"/> + <br/> + </form> + <button wicket:id="externalSubmitter"> + Submit + </button> + </body> +</html> +{code} + +*Java code:* + +{code} +public class HomePage extends WebPage { + + public HomePage(final PageParameters parameters) { + Form form = new Form("form"); + + form.add(new PasswordTextField("password", Model.of(""))); + //specify the form to submit + add(new SubmitLink("externalSubmitter", form)); + add(form); + } +} +{code} + +h3. Disabling default form processing + +With an IFormSubmittingComponent we can choose to skip the default form submission process by setting the appropriate flag to false with the setDefaultFormProcessing method. When the default form processing is disabled only the submitter's onSubmit is called while form's validation and models updating are skipped. + +This can be useful if we want to implement a âCancelâ button on our form which redirects user to another page without validating his/her input. + +When we set this flag to false we can decide to manually invoke the form processing by calling the process(IFormSubmittingComponent) method. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_6.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_6.gdoc new file mode 100644 index 0000000..3fb1ab7 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_6.gdoc @@ -0,0 +1,22 @@ + + +As you might already known, HTLM doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form. + +This can be useful if we want to split a big form into smaller ones in order to reuse them and to better distribute responsibilities among different components. +Forms can be nested to an arbitrary level: + +{code:html} +<form wicket:id="outerForm"> + ... + <form wicket:id="innerForm"> + ... + <form wicket:id="veryInnerForm"> + ... + </form> + </form> +</form> +{code} + +When a form is submitted also its nested forms are submitted and they participate in the validation step. This means that if a nested form contains invalid input values, the outer form won't be submitted. On the contrary, nested forms can be singularly submitted without depending on the status of their outer form. + +To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_7.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_7.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_7.gdoc new file mode 100644 index 0000000..d293a4a --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_7.gdoc @@ -0,0 +1,17 @@ + + +HTML provides a multi-line text input control with <textarea> tag. The Wicket counterpart for this kind of control is @org.apache.wicket.markup.html.form.TextArea@ component: + +*HTML:* + +{code:html} +<textarea wicket:id="description" rows="5" cols="40"></textarea> +{code} + +*Java code:* + +{code} +form.add(new TextArea("description", Model.of(""))); +{code} + +Component TextArea is used just like any other single-line text field. To specify the size of the text area we can write attributes rows and cols directly in the markup file or we can create new attribute modifiers and add them to our TextArea component. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_8.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_8.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_8.gdoc new file mode 100644 index 0000000..42ff95d --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_8.gdoc @@ -0,0 +1,81 @@ + + +Wicket supports file uploading with the FileUploadField component which must be used with the <input> tag whose type attribute must be set to "file". In order to send a file on form submission we must enable multipart mode calling MultiPart(true)on our form. + +In the next example (project UploadSingleFile) we will see a form which allows users to upload a file into the temporary directory of the server (path /tmp on Unix/Linux systems): + +*HTML:* + +{code:html} +<html> + <head> + </head> + <body> + <h1>Upload your file here!</h1> + <form wicket:id="form"> + <input type="file" wicket:id="fileUploadField"/> + <input type="submit" value="Upload"/> + </form> + <div wicket:id="feedbackPanel"> + </div> + </body> +</html> +{code} + +*Java code:* + +{code} +public class HomePage extends WebPage { + private FileUploadField fileUploadField; + + public HomePage(final PageParameters parameters) { + fileUploadField = new FileUploadField("fileUploadField"); + + Form form = new Form("form"){ + @Override + protected void onSubmit() { + super.onSubmit(); + + FileUpload fileUpload = fileUploadField.getFileUpload(); + + try { + File file = new File(System.getProperty("java.io.tmpdir") + "/" + + fileUpload.getClientFileName()); + + fileUpload.writeTo(file); + } catch (IOException e) { + e.printStackTrace(); + } + } + }; + + form.setMultiPart(true); + //set a limit for uploaded file's size + form.setMaxSize(Bytes.kilobytes(100)); + form.add(fileUploadField); + add(new FeedbackPanel("feedbackPanel")); + add(form); + } +} +{code} + +The code that copies the uploaded file to the temporary directory is inside the onSubmit method of the Form class. The uploaded file is handled with an instance of class FileUpload returned by the getFileUpload() method of the FileUploadField class. This class provides a set of methods to perform some common tasks like getting the name of the uploaded file (getClientFileName()), coping the file into a directory (writeTo(destinationFile)), calculating file digest (getDigest (digestAlgorithm)) and so on. + +Form component can limit the size for uploaded files using its setMaxSize(size) method. In the example we have set this limit to 100 kb to prevent users from uploading files bigger than this size. + +{note} +The maximum size for uploaded files can also be set at application's level using the setDefaultMaximumUploadSize(Bytes maxSize) method of the IApplicationSettings interface: + +{code} +@Override +public void init() +{ + getApplicationSettings().setDefaultMaximumUploadSize(Bytes.kilobytes(100)); +} +{code} +{note} + +h3. Upload multiple files + +If we need to upload multiple files at once and our clients support HTML5, we can still use FileUploadField adding attribute "multiple" to its tag. If we can not rely on HTML5, we can use the MultiFileUploadField component which allows the user to upload an arbitrary number of files using a JavaScript-based solution. +An example showing how to use this component can be found in Wicket module wicket-examples in file MultiUploadPage.java. The live example is hosted at "http://www.wicket-library.com/wicket-examples-6.0.x/upload/multi":http://www.wicket-library.com/wicket-examples-6.0.x/upload/multi . \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/forms2/forms2_9.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_9.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_9.gdoc new file mode 100644 index 0000000..4331ef8 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/forms2/forms2_9.gdoc @@ -0,0 +1,122 @@ + + +In chapter 3.2.2 we have seen how to use class Panel to create custom components with their own markup and with an arbitrary number of children components. + +While it's perfectly legal to use Panel also to group form components, the resulting component won't be itself a form component and it won't participate in the form's submission workflow. + +This could be a strong limitation if the custom component needs to coordinate its children during sub-tasks like input conversion or model updating. That's why in Wicket we have the @org.apache.wicket.markup.html.form.FormComponentPanel@ component which combines the features of a Panel (it has its own markup file) and a FormComponent (it is a subclass of FormComponent). + +A typical scenario in which we may need to implement a custom FormComponentPanel is when our web application and its users work with different units of measurement for the same data. + +To illustrate this possible scenario, let's consider a form where a user can insert a temperature that will be recorded after being converted to Kelvin degrees (see the example project CustomForm ComponentPanel). + +The Kelvin scale is wildly adopted among the scientific community and it is one of the seven base units of the "International System of Units":http://en.wikipedia.org/wiki/International_System_of_Units , so it makes perfect sense to store temperatures expressed with this unit of measurement. + +However, in our everyday life we still use other temperature scales like Celsius or Fahrenheit, so it would be nice to have a component which internally works with Kelvin degrees and automatically applies conversion between Kelvin temperature scale and the one adopted by the user. + +In order to implement such a component, we can make a subclass of FormComponentPanel and leverage the convertInput and onBeforeRender methods: in the implementation of the convertInput method we will convert input value to Kelvin degrees while in the implementation of onBeforeRender method we will take care of converting the Kelvin value to the temperature scale adopted by the user. + +Our custom component will contain two children components: a text field to let user insert and edit a temperature value and a label to display the letter corresponding to user's temperature scale (F for Fahrenheit and C for Celsius). The resulting markup file is the following: + +{code:html} +<html> +<head> +</head> +<body> + <wicket:panel> + Registered temperature: <input size="3" maxlength="3" + wicket:id="registeredTemperature"/> + <label wicket:id="mesuramentUnit"></label> + </wicket:panel> +</body> +</html> +{code} + +As shown in the markup above FormComponentPanel uses the same <wicket:panel> tag used by Panel to define its markup. Now let's see the Java code of the new form component starting with the onInitialize() method: + +{code} +public class TemperatureDegreeField extends FormComponentPanel<Double> { + + private TextField<Double> userDegree; + + public TemperatureDegreeField(String id) { + super(id); + } + + public TemperatureDegreeField(String id, IModel<Double> model) { + super(id, model); + } + + @Override + protected void onInitialize() { + super.onInitialize(); + + AbstractReadOnlyModel<String> labelModel=new AbstractReadOnlyModel<String>(){ + @Override + public String getObject() { + if(getLocale().equals(Locale.US)) + return "°F"; + return "°C"; + } + }; + + add(new Label("mesuramentUnit", labelModel)); + add(userDegree=new TextField<Double>("registeredTemperature", new + Model<Double>())); + userDegree.setType(Double.class); + } +{code} + +Inside the onInitialize method we have created a read-only model for the label that displays the letter corresponding to the user's temperature scale. To determinate which temperature scale is in use, we retrieve the Locale from the session by calling Component's getLocale() method (we will talk more about this method in chapter 12). Then, if locale is the one corresponding to the United States, the chosen scale will be Fahrenheit, otherwise it will be considered as Celsius. + +In the final part of onInitialize() we add the two components to our custom form component. You may have noticed that we have explicitly set the type of model object for the text field to double. This is necessary as the starting model object is a null reference and this prevents the component from automatically determining the type of its model object. + +Now we can look at the rest of the code containing the convertInput and onBeforeRender methods: + +{code} +// continued example + @Override + protected void convertInput() { + Double userDegreeVal = userDegree.getConvertedInput(); + Double kelvinDegree; + + if(getLocale().equals(Locale.US)){ + kelvinDegree = userDegreeVal + 459.67; + BigDecimal bdKelvin = new BigDecimal(kelvinDegree); + BigDecimal fraction = new BigDecimal(5).divide(new BigDecimal(9)); + + kelvinDegree = bdKelvin.multiply(fraction).doubleValue(); + }else{ + kelvinDegree = userDegreeVal + 273.15; + } + + setConvertedInput(kelvinDegree); + } + + @Override + protected void onBeforeRender() { + super.onBeforeRender(); + + Double kelvinDegree = (Double) getDefaultModelObject(); + Double userDegreeVal = null; + + if(kelvinDegree == null) return; + + if(getLocale().equals(Locale.US)){ + BigDecimal bdKelvin = new BigDecimal(kelvinDegree); + BigDecimal fraction = new BigDecimal(9).divide(new BigDecimal(5)); + + kelvinDegree = bdKelvin.multiply(fraction).doubleValue(); + userDegreeVal = kelvinDegree - 459.67; + }else{ + userDegreeVal = kelvinDegree - 273.15; + } + + userDegree.setModelObject(userDegreeVal); + } +} +{code} + +Since our component does not directly receive the user input, convertInput() must read this value from the inner text field using FormComponent's getConvertedInput() method which returns the input value already converted to the type specified for the component (Double in our case). Once we have the user input we convert it to kelvin degrees and we use the resulting value to set the converted input for our custom component (using method setConvertedInput(T convertedInput)). + +Method onBeforeRender() is responsible for synchronizing the model of the inner textfield with the model of our custom component. To do this we retrieve the model object of the custom component with the getDefaultModelObject() method, then we convert it to the temperature scale adopted by the user and finally we use this value to set the model object of the text field. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld.gdoc b/wicket-user-guide/src/docs/guide/helloWorld.gdoc new file mode 100644 index 0000000..6dd56b5 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld.gdoc @@ -0,0 +1,6 @@ +Wicket allows us to design our web pages in terms of components and containers, just like AWT does with desktop windows. +Both frameworks share the same component-based architecture: in AWT we have a @Windows@ instance which represents the physical windows containing GUI components (like text fields, radio buttons, drawing areas, etc...), in Wicket we have a @WebPage@ instance which represents the physical web page containing HTML components (pictures, buttons, forms, etc... ) . + +!uml-component.png! + +In both frameworks we find a base class for GUI components called @Component@. Wicket pages can be composed (and usually are) by many components, just like AWT windows are composed by Swing/AWT components. Both frameworks promote the reuse of presentation code and GUI elements building custom components. Even if Wicket already comes with a rich set of ready-to-use components, building custom components is a common practice when working with this framework. We'll learn more about custom components in the next chapters. http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_1.gdoc b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_1.gdoc new file mode 100644 index 0000000..bff575e --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_1.gdoc @@ -0,0 +1,21 @@ +Wicket is available as a binary package on the main site "http://wicket.apache.org":http://wicket.apache.org . Inside this archive we can find the distribution jars of the framework. Each jar corresponds to a sub-module of the framework. The following table reports these modules along with a short description of their purpose and with the related dependencies: + +{table} + *Module'sname* | *Description* | *Dependencies* + wicket-core | Contains the main classes of the framework, like class @Component@ and @Application@. | wicket-request, wicket-util + wicket-request | This module contains the classes involved into web request processing. | wicket-util + wicket-util | Contains general-purpose utility classes for functional areas such as I/O, lang, string manipulation, security, etc... | None + wicket-datetime | Contains special purpose components designed to work with date and time. | wicket-core + wicket-bean-validation | Provides support for JSR 303 standard validation. | wicket-core + wicket-devutils | Contains utility classes and components to help developers with tasks such as debugging, class inspection and so on. | wicket-core, wicket-extensions +wicket-extensions | Contains a vast set of built-in components to build a rich UI for our web application (Ajax support is part of this module). | wicket-core +wicket-auth-roles | Provides support for role-based authorization. | wicket-core +wicket-ioc | This module provides common classes to support Inversion Of Control. It's used by both Spring and Guice integration module. | wicket-core +wicket-guice | This module provides integration with the dependency injection framework developed by Google. | wicket-core, wicket-ioc +wicket-spring | This module provides integration with Spring framework. | wicket-core, wicket-ioc +wicket-velocity | This module provides panels and utility class to integrate Wicket with Velocity template engine. | wicket-core +wicket-jmx| This module provides panels and utility class to integrate Wicket with Java Management Extensions. | wicket-core +wicket-objectsizeof-agent | Provides integration with Java agent libraries and instrumentation tools. | wicket-core +{table} + +Please note that the core module depends on the utility and request modules, hence it cannot be used without them. http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_2.gdoc b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_2.gdoc new file mode 100644 index 0000000..5f83802 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_2.gdoc @@ -0,0 +1,97 @@ +In this chapter we will see a classic Hello World! example implemented using a Wicket page with a built-in component called @Label@ (the code is from project the HelloWorldExample). Since this is the first example of the guide, before looking at Java code we will go through the common artifacts needed to build a Wicket application from scratch. + +{note} +All the example projects presented in this document have been generated using Maven and the utility page at "http://wicket.apache.org/start/quickstart.html":http://wicket.apache.org/start/quickstart.html . *Appendix A* contains the instructions needed to use these projects and build a quickstart application using Apache Maven. All the artifacts used in the next example (files web.xml, HomePage.class and HomePage.html) are automatically generated by Maven. +{note} + +h3. Wicket application structure + +A Wicket application is a standard Java EE web application, hence it is deployed through a web.xml file placed inside folder WEB-INF: + +!webinf.png! + +_Illustration : The standard directory structure of a Wicket application_ + +The content of web.xml declares a servlet filter (class @org.apache.wicket.Protocol.http.WicketFilter@) which dispatches web requests to our Wicket application: + +{code:xml} +<?xml version="1.0" encoding="UTF-8"?> +<web-app> + <display-name>Wicket Test</display-name> + <filter> + <filter-name>TestApplication</filter-name> + <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class> + <init-param> + <param-name>applicationClassName</param-name> + <param-value>org.wicketTutorial.WicketApplication</param-value> + </init-param> + </filter> + <filter-mapping> + <filter-name>TestApplication</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> +</web-app> +{code} + +Since this is a standard servlet filter we must map it to a specific set of URLs through the @<filter-mapping>@ tag). In the xml above we have mapped every URL to our Wicket filter. + +If we are using Servlet 3 or a later version, we can of course use a class in place of web.xml to configure our application. The following example uses annotation @WebFilter. + +{code} +@WebFilter(value = "/*", initParams = { @WebInitParam(name = "applicationClassName", value = "com.mycompany.WicketApplication"), + @WebInitParam(name="filterMappingUrlPattern", value="/*") }) +public class ProjectFilter extends WicketFilter { + +} +{code} + + + +{note} +Wicket can be started in two modes named respectively DEVELOPMENT and DEPLOYMENT. The first mode activates some extra features which help application development, like resources monitoring and reloading, full stack trace rendering of exceptions, an AJAX debugger window, etc... The DEPLOYMENT mode turns off all these features optimizing performances and resource consumption. In our example projects we will use the default mode which is DEVELOPMENT. [Chapter 24.1|guide:maven_1] contains the chapter âSwitching Wicket to DEPLOYMENT modeâ where we can find further details about these two modes as well as the possible ways we have to set the desired one. In any case, DO NOT deploy your applications in a production environment without switching to DEPLOYMENT mode! +{note} + +h3. The application class + +If we look back at web.xml we can see that we have provided the Wicket filter with a parameter called @applicationClassName@. This value must be the fully qualified class name of a subclass of @org.apache.wicket.Application@. This subclass represents our web application built upon Wicket and it's responsible for configuring it when the server is starting up. Most of the times our custom application class won't inherit directly from class @Application@, but rather from class @org.apache.wicket.protocol.http.WebApplication@ which provides a closer integration with servlet infrastructure. +Class @Application@ comes with a set of configuration methods that we can override to customize our application's settings. One of these methods is @getHomePage()@ that must be overridden as it is declared abstract: + +{code} +public abstract Class<? extends Page> getHomePage() +{code} + +As you may guess from its name, this method specifies which page to use as homepage for our application. +Another important method is @init()@: + +{code} +protected void init() +{code} + +This method is called when our application is loaded by the web server (Tomcat, Jetty, etc...) and is the ideal place to put our configuration code. The @Application@ class exposes its settings grouping them into interfaces (you can find them in package @org.apache.wicket.settings@). We can access these interfaces through getter methods that will be gradually introduced in the next chapters when we will cover the related settings. + +The current application's instance can be retrieved at any time calling static method @Application.get()@ in our code. We will give more details about this method in [chapter 9.3|guide:requestProcessing_3]. The content of the application class from project HelloWorldExample is the following: + +{code} +public class WicketApplication extends WebApplication +{ + @Override + public Class<? extends WebPage> getHomePage() + { + return HomePage.class; + } + + @Override + public void init() + { + super.init(); + // add your configuration here + } +} +{code} + +Since this is a very basic example of a Wicket application, we don't need to specify anything inside the @init@ method. The home page of the application is the @HomePage@ class. In the next paragraph we will see how this page is implemented and which conventions we have to follow to create a page in Wicket. + +{note} +Declaring a @WicketFilter@ inside web.xml descriptor is not the only way we have to kickstart our application. +If we prefer to use a servlet instead of a filter, we can use class @org.apache.wicket.protocol.http.WicketServlet@. See the JavaDoc for further details. +{note} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_3.gdoc b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_3.gdoc new file mode 100644 index 0000000..327aa27 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_3.gdoc @@ -0,0 +1,61 @@ + + +To complete our first Wicket application we must explore the home page class that is returned by the @Application@'s method @getHomePage()@ seen above. +In Wicket a web page is a subclass of @org.apache.wicket.WebPage@. This subclass must have a corresponding HTML file which will be used by the framework as template to generate its HTML markup. This file is a regular plain HTML file (its extension must be html). + +By default this HTML file must have the same name of the related page class and must be in the same package: + +!samepackage.png! + +_Illustration :Page class and its related HTML file_ + +If you don't like to put class and html side by side (let's say you want all your HTML files in a separated folder) you can use Wicket settings to specify where HTML files can be found. We will cover this topic later in [chapter 15.9|guide:resources_9]. + +The Java code for the @HomePage@ class is the following: + +{code} +package org.wicketTutorial; + +import org.apache.wicket.request.mapper.parameter.PageParameters; +import org.apache.wicket.markup.html.basic.Label; +import org.apache.wicket.markup.html.WebPage; + +public class HomePage extends WebPage { + public HomePage() { + add(new Label("helloMessage", "Hello WicketWorld!")); + } +} +{code} + +Apart from subclassing @WebPage@, @HomePage@ defines a constructor that adds a @Label@ component to itself. +Method @add(Component component)@ is inherited from ancestor class @org.apache.wicket.MarkupContainer@ and is used to add children components to a web page. We'll see more about @MarkupContainer@ later in [chapter 5.2|guide:layout_2]. +Class @org.apache.wicket.markup.html.basic.Label@ is the simplest component shipped with Wicket. It just inserts a string (the second argument of its constructor) inside the corresponding HTML tag. +Just like any other Wicket component, @Label@ needs a textual id (@'helloMessage'@ in our example) to be instantiated. At runtime Wicket will use this value to find the HTML tag we want to bind to the component. This tag must have a special attribute called @wicket:id@ and its value must be identical to the component id (comparison is case-sensitive!). + +Here is the HTML markup for @HomePage@ (file HomePage.html): + +{code:html} +<!DOCTYPE html> +<html> + <head> + <meta charset="utf-8" /> + <title>Apache Wicket HelloWorld</title> + </head> + <body> + + <div wicket:id="helloMessage"> + [Label's message goes here] + </div> + </body> +</html> +{code} + +We can see that the @wicket:id@ attribute is set according to the value of the component id. If we run this example we will see the text @Hello WicketWorld!@ Inside a @<div>@ tag. + +{note} +@Label@ replaces the original content of its tag (in our example @[Label's message goes here]@) with the string passed as value (@Hello WicketWorld!@ in our example). +{note} + +{warning} +If we specify a @wicket:id@ attribute for a tag without adding the corresponding component in our Java code, Wicket will throw a @ComponentNotFound@ Exception. On the contrary if we add a component in our Java code without specifying a corresponding @wicket:id@ attribute in our markup, Wicket will throw a @WicketRuntimeException@. +{warning} http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_4.gdoc b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_4.gdoc new file mode 100644 index 0000000..1eea3a1 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_4.gdoc @@ -0,0 +1,52 @@ +The basic form of interaction offered by web applications is to navigate through pages using links. In HTML a link is basically a pointer to another resource that most of the time is another page. Wicket implements links with component @org.apache.wicket.markup.html.link.Link@, but due to the component-oriented nature of the framework, this component is quite different from classic HTML links. +Following the analogy with GUI frameworks, we can consider Wicket link as a âclickâ event handler: its purpose is to perform some actions (on server side!) when the user clicks on it. + +That said, you shouldn't be surprised to find an abstract method called @onClick()@ inside the @Link@ class. In the following example we have a page with a @Link@ containing an empty implementation of @onClick@: + +{code} +public class HomePage extends WebPage { + public HomePage(){ + add(new Link("id"){ + @Override + public void onClick() { + //link code goes here + } + }); + } +} +{code} + +By default after @onClick@ has been executed, Wicket will send back to the current page to the client web browser. If we want to navigate to another page we must use method @setResponsePage@ of class @Component@: + +{code} +public class HomePage extends WebPage { + public HomePage(){ + add(new Link("id"){ + @Override + public void onClick() { + //we redirect browser to another page. + setResponsePage(AnotherPage.class); + } + }); + } +} +{code} + +In the example above we used a version of @setResponsePage@ which takes as input the class of the target page. In this way a new instance of @AnotherPage@ will be created each time we click on the link. The other version of @setResponsePage@ takes in input a page instance instead of a page class: + +{code} +@Override +public void onClick() { + //we redirect browser to another page. + AnotherPage anotherPage = new AnotherPage(); + setResponsePage(anotherPage); +} +{code} + +The difference between using the first version of @setResponsePage@ rather than the second one will be illustrated in [chapter 8|guide:versioningCaching], when we will introduce the topic of stateful and stateless pages. For now, we can consider them as equivalent. + +Wicket comes with a rich set of link components suited for every need (links to static URL, Ajax-enhanced links, links to a file to download, links to external pages and so on). We will see them in [chapter 10|guide:urls]. + +{note} +We can specify the content of a link (i.e. the text of the picture inside it) with its method @setBody@. This method takes in input a generic Wicket model, which will be the topic of [chapter 11|guide:modelsforms]. +{note} http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_5.gdoc b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_5.gdoc new file mode 100644 index 0000000..b9d541b --- /dev/null +++ b/wicket-user-guide/src/docs/guide/helloWorld/helloWorld_5.gdoc @@ -0,0 +1,3 @@ +In this chapter we have seen the basic elements that compose a Wicket application. We have started preparing the configuration artifacts needed for our applications. As promised in [chapter 2.4|guide:helloWorld_4], we needed to put in place just a minimal amount of XML with an application class and a home page. +Then we have continued our âfirst contactâ with Wicket learning how to build a simple page with a label component as child. This example page has shown us how Wicket maps components to HTML tags and how it uses both of them to generate the final HTML markup. +In the last paragraph we had a first taste of Wicket links and we have seen how they can be considered as a âclickâ event listener and how they can be used to navigate from a page to another. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/howToSource.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/howToSource.gdoc b/wicket-user-guide/src/docs/guide/howToSource.gdoc new file mode 100644 index 0000000..8d5db51 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/howToSource.gdoc @@ -0,0 +1,15 @@ +Most of the code you will find in this document is available as a "Git repository":https://github.com/bitstorm/Wicket-tutorial-examples and is licensed under the ASF 2.0. To get a local copy of the repository you can run the clone command from shell: + +{code} +git clone https://github.com/bitstorm/Wicket-tutorial-examples.git +{code} + +If you aren't used to Git, you can simply download the whole source as a zip archive: + +!gitRepo.png! + +The repository contains a multi-module Maven project. Every subproject is contained in the relative folder of the repository: + +!gitMavenPrj.png! + +When the example code is used in the document, you will find the name of the subproject it belongs to. If you don't have any experience with Maven, you can read Appendix A where you can learn the basic commands needed to work with the example projects and to import them into your favourite IDE (NetBeans, IDEA or Eclipse). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/i18n.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n.gdoc b/wicket-user-guide/src/docs/guide/i18n.gdoc new file mode 100644 index 0000000..410bea5 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n.gdoc @@ -0,0 +1 @@ +In chapter 10 we have seen how the topic of localization is involved in the generation of feedback messages and we had a first contact with resource bundles. In this chapter we will continue to explore the localization support provided by Wicket and we will learn how to build pages and components ready to be localized in different languages. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/i18n/i18n_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/i18n/i18n_1.gdoc b/wicket-user-guide/src/docs/guide/i18n/i18n_1.gdoc new file mode 100644 index 0000000..a50b446 --- /dev/null +++ b/wicket-user-guide/src/docs/guide/i18n/i18n_1.gdoc @@ -0,0 +1,27 @@ + + +As we have seen in chapter 10, the infrastructure of feedback messages is built on top of Java internationalization (i18n) support, so it should not be surprising that the same infrastructure is used also for localization purpose. However, while so far we have used only the <ApplicationClassName>.properties file to store our custom messages, in this chapter we will see that also pages, components, validators and even Java packages can have their own resource bundles. This allows us to split bundles into multiple files keeping them close to where they are used. But before diving into the details of internationalization with Wicket, it's worthwhile to quickly review how i18n works under Java, see what classes are involved and how they are integrated into Wicket. + +{note} +Providing a full description of Java support for i18n is clearly out of the scope of this document. If you need more informations about this topic you can find them in the JavaDocs and in the official "i18n tutorial":http://docs.oracle.com/javase/tutorial/i18n/index.html . +{note} + +h3. Class Locale and ResourceBundle + +Class java.util.Locale represents a specific country or language of the world and is used in Java to retrieve other locale-dependent informations like numeric and date formats, the currency in use in a country and so on. Such kind of informations are accessed through special entities called resource bundles which are implemented by class @java.util.ResourceBundle@. Every resource bundle is identified by a full name which is built using four parameters: a base name (which is required), a language code, a country code and a variant (which are all optional). These three optional parameters are provided by an instance of Locale with its three corresponding getter methods: getLanguage(), getCountry() and getVariant(). Parameter language code is a lowercase ISO 639 2-letter code (like zh for Chinese, de for German and so on) while country code is an uppercase ISO 3166 2-letter code (like CN for China, DE for Germany and so on). The final full name will have the following structure (NOTE: tokens inside squared brackets are optional): + +{code} +<base name>[_<language code>[_<COUNTRY_CODE>[_<variant code>]]] +{code} + +For example a bundle with MyBundle as base name and localized for Mandarin Chinese (language code zh, country code CH, variant cmn) will have MyBundle_zh_CH_cmn as full name. A base name can be a fully qualified class name, meaning that it can include a package name before the actual base name. The specified package will be the container of the given bundle. For example if we use org.foo.MyBundle as base name, the bundle named MyBundle will be searched inside package org.foo. The actual base name (MyBundle in our example) will be used to build the full name of the bundle following the same rules seen above. +@ResourceBundle@ is an abstract factory class, hence it exposes a number of factory methods named getBundle to load a concrete bundle. Without going into too much details we can say that a bundle corresponds to a file in the classpath. To find a file for a given bundle, getBundle needs first to generate an ordered list of candidate bundle names. These names are the set of all possible full names for a given bundle. For example if we have org.foo.MyBundle as base name and the current locale is the one seen before for Mandarin Chinese, the candidate names will be: + +# org.foo.MyBundle_zh_CH_cmn +# org.foo.MyBundle_zh_CH +# org.foo.MyBundle_zh +# org.foo.MyBundle + +The list of these candidate names is generated starting from the most specific one and subtracting an optional parameter at each step. The last name of the list corresponds to the default resource bundle which is the most general name and is equal to the base name. Once that getBundle has generated the list of candidate names, it will iterate over them to find the first one for which is possible to load a class or a properties file. The class must be a subclass of @ResourceBundle@ having as class name the full name used in the current iteration. If such a class is not found, getBundle will try to locate a properties file having a file name equals to the current full name (Java will automatically append extension .properties to the full name). For example given the resource bundle of the previous example, Java will search first for class org.foo.MyBundle_zh_CH_cmn and then for file MyBundle_zh_CH_cmn.properties inside package org.foo. If no file is found for any of the candidate name s, a MissingResourceException will be thrown. Bundles contains local-dependent string resources identified by a key that is unique in the given bundle. So once we have obtained a valid bundle we can access these objects with method getString (String key). + +As we have seen before working with feedback messages, in Wicket most of the times we will work with properties files rather than with bundle classes. In chapter 10 we used a properties file having as base name the class name of the application class and without any information about the locale. This file is the default resource bundle for a Wicket application. In paragraph 12.4 we will explore the algorithm used in Wicket to locate the available bundles for a given component. Once we have learnt how to leverage this algorithm, we will be able to split our bundles into more files organized in a logical hierarchy. \ No newline at end of file
