THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Scrollbar |
|---|
...
In the previous chapters, we saw how Tapestry can handle simple links, even links that pass information in the URL. In this chapter, we'll see how Tapestry can do the same, and quite a bit more, for HTML forms.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
package com.example.tutorialtutorial1.entities; import com.example.tutorialtutorial1.data.Honorific; public class Address { public Honorific honorific; public String firstName; public String lastName; public String street1; public String street2; public String city; public String state; public String zip; public String email; public String phone; } |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
package com.example.tutorialtutorial1.data; public enum Honorific { MR, MRS, MISS, DR } |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<html t:type="layout" title="Create New Address"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<em>coming soon ...</em>
</html>
|
(Note: for Tapestry 5.4, make that tapestry_5_4.xsd instead.)
Next, And the corresponding class:
| Code Block | ||||
|---|---|---|---|---|
| ||||
package com.example.tutorialtutorial1.pages.address; public class CreateAddress { } |
So ... why is the class named "CreateAddress" and not simply "Create"? Actually, we could have named it "Create", and the application would still work, but the longer class name is equally valid. Tapestry noticed the redundancy in the class name (com.example.tutorialtutorial1.pages.address.CreateAddress) and just stripped out the redundant suffix. Tapestry also checks for redundant prefixes. In addition, the long name, "address/CreateAddress" would also work.
Eventually, your application will probably have more entities: perhaps you'll have a "user/Create" page and a "payment/Create" page and an "account/Create" page. You could have a bunch of different classes all named Create spread across a number of different packages. That's legal Java, but it isn't ideal. You may find yourself accidentally editing the Java code for creating an Account when your really want to be editing the code for creating a Payment.
Tapestry is encouraging you to use a more descriptive name: CreateAddress, not just Create, but it isn't making you pay the cost (in terms of longer, uglier URLs). The URL to access the page will still be http://localhost:8080/tutorial1/address/create.
And remember, regardless of the name that Tapestry assigns to your page, the template file is named like the Java class itself: CreateAddress.tml.
| Info |
|---|
Index pages work in folders as well. A class named com.example.tutorial.pages.address.AddressIndex would be given the name "address/Index". However, Tapestry has special rules for pages named "Index" and the rendered URL would be http://localhost:8080/tutorial1/address/. In other words, you can place Index pages in any folder and Tapestry will build a short URL for that page ... and you don't have to keep naming the classes Index (it's confusing to have many classes with the same name, even across multiple packages); instead, you can name each index page after the package that contains it. Tapestry users a smart convention to keep it all straight and generate short, to the point URLs. |
Using the BeanEditForm Component
Time to start putting together the logic for this form. Tapestry has a specific component for client-side Forms: the Form component, as well as components for form controls, such as Checkbox and TextField. We'll cover those in a bit more detail later .. instead, we're again going to let Tapestry do the heavy lifting for us, via the BeanEditForm component.
Add the following to the CreateAddress template (replacing the "coming soon ..." message):
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:beaneditform object="address"/>
|
And match that up with a property in the CreateAddress class:
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Property
private Address address;
|
Tapestry actually creates a bunch of aliases for you pages; any of these aliases are valid and can appear in URLs or in the page parameter of PageLink. You can see the list in the console:
| Code Block |
|---|
[INFO] TapestryModule.ComponentClassResolver Available pages (12):
(blank): com.example.tutorial1.pages.Index
ComponentLibraries: org.apache.tapestry5.corelib.pages.ComponentLibraries
Error404: com.example.tutorial1.pages.Error404
ExceptionReport: org.apache.tapestry5.corelib.pages.ExceptionReport
GameOver: com.example.tutorial1.pages.GameOver
Guess: com.example.tutorial1.pages.Guess
Index: com.example.tutorial1.pages.Index
PageCatalog: org.apache.tapestry5.corelib.pages.PageCatalog
PropertyDisplayBlocks: org.apache.tapestry5.corelib.pages.PropertyDisplayBlocks
PropertyEditBlocks: org.apache.tapestry5.corelib.pages.PropertyEditBlocks
ServiceStatus: org.apache.tapestry5.corelib.pages.ServiceStatus
T5Dashboard: org.apache.tapestry5.corelib.pages.T5Dashboard
address/Create: com.example.tutorial1.pages.address.CreateAddress
address/CreateAddress: com.example.tutorial1.pages.address.CreateAddress |
Tapestry users the shortest alias when constructing URLs.
Eventually, your application will probably have more entities: perhaps you'll have a "user/Create" page and a "payment/Create" page and an "account/Create" page. You could have a bunch of different classes all named Create spread across a number of different packages. That's legal Java, but it isn't ideal. You may find yourself accidentally editing the Java code for creating an Account when you really want to be editing the code for creating a Payment.
Tapestry is encouraging you to use a more descriptive name: CreateAddress, not just Create, but it isn't making you pay the cost (in terms of longer, uglier URLs). The URL to access the page will still be http://localhost:8080/tutorial1/address/create.
And remember, regardless of the name that Tapestry assigns to your page, the template file is named like the Java class itself: CreateAddress.tml.
| Info |
|---|
Index pages work in folders as well. A class named com.example.tutorial1.pages.address.AddressIndex would be given the name "address/Index". However, Tapestry has special rules for pages named "Index" and the rendered URL would be http://localhost:8080/tutorial1/address/. In other words, you can place Index pages in any folder and Tapestry will build a short URL for that page ... and you don't have to keep naming the classes Index (it's confusing to have many classes with the same name, even across multiple packages); instead, you can name each index page after the package that contains it. Tapestry users a smart convention to keep it all straight and generate short, to the point URLs. |
Using the BeanEditForm Component
Time to start putting together the logic for this form. Tapestry has a specific component for client-side Forms: the Form component, as well as components for form controls, such as Checkbox and TextField. We'll cover those in a bit more detail later .. instead, we're again going to let Tapestry do the heavy lifting for us, via the BeanEditForm component.
Add the following to the CreateAddress template (replacing the "coming soon ..." message):
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:beaneditform object="address"/>
|
And match that up with a property in the CreateAddress class:
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Property
private Address address;
|
When you refresh the page, you may see a warning like the following at the top of the page:
If you see that, it means you need to invent an HMAC passphrase for your app. Just edit your AppModule.java class (in your services package), adding a couple of lines to the contributeApplicationDefaults method like the following:
| Code Block |
|---|
// Set the HMAC pass phrase to secure object data serialized to client
configuration.add(SymbolConstants.HMAC_PASSPHRASE, ""); |
but, instead of an empty string, insert a long, random string of characters (like a very long and complex password, at least 30 characters) that you keep private.
After you do that, stop the app and restart it, and click on the Create new address link again, and you'll see something like thisWhen you refresh the page, you'll see the following:
Tapestry has done quite a bit of work here. It has created a form that includes a field for each property. Further, it has seen that the honorific property is an enumerated type, and presented that as a drop-down list.
...
The BeanEditForm must guess at the right order to present the fields; for public fields, they end up in alphabetical order
| Wiki Markup |
|---|
{footnote}For standard JavaBeans properties, the BeanEditForm default is in the order in which the getter methods are defined in the class (it uses line number information, if available).{footnote} |
.
. For standard JavaBeans properties, the BeanEditForm default is in the order in which the getter methods are defined in the class (it uses line number information, if available).
A better order for these fields is the order in which they are defined in the Address class:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:beaneditform object="address"
reorder="honorific,firstName,lastName,street1,street2,city,state,zip,email,phone" />
|
Customizing labels
...
Since this is a new file (and not a change to an existing file), you may have to restart Jetty to force Tapestry to pick up the change.
Create Address form with field labels corrected
We can also customize the options in the drop down list. All we have to do is add some more entries to the message catalog matching the enum names to the desired labels. Update CreateAddress.properties and add:
...
| Code Block | ||
|---|---|---|
| ||
<t:beaneditform submitlabel="Create Address" object="address"
reorder="honorific,firstName,lastName,street1,street2,city,state,zip,email,phone"/>
|
The default for the submitlabel parameter is "Create/Update", but here we're overriding that default to a specific value.
The final result shows the reformatting and relabelingrelabelling:
Create Address form with proper labels
Before continuing on to validation, a side note about message catalogs. Message catalogs are not just for re-labeling fields and options; we'll see in later chapters how message catalogs are used in the context of localization and internationalization.
...
| No Format |
|---|
submit-label=Create Address |
At In the end of the day, the exact same HTML is sent to the client, regardless of whether you include the label text directly in the template, or indirectly in the message catalog. In the long term, the latter approach will work better if you later chose to internationalize your application.
...
Before we worry about storing the Address object, we should make sure that the user provides reasonable values. For example, several of the fields should be required, and phone numbers and email address have specific formats.
The BeanEditForm checks for a Tapestry-specific annotation, @Validate, on the field, the getter method, or the setter method of each property.
Edit the Address entity, and update the lastName, firstName, street1, city, state and zip fields, adding a @Validate annotation to each:
| Code Block | ||
|---|---|---|
| ||
@Validate("required")
public String firstName;
|
What is that string, "required"? That's how you specify the desired validation. It is a series of names that identify what type of validation is desired. A number of validators are built in, such as "required", "minLength" and "maxLength". As elsewhere, Tapestry is case insensitive.
You can apply multiple validations, by separating the validator names with commas. Some validators can be configured (with an equals sign). Thus you might say "required,minLength=5" for a field that must be specified, and must be at least five characters long.
| Warning |
|---|
You can easily get confused when you make a change to an entity class, such as adding the @Validate annotatation, and not see the result in the browser. Only component classes, and (most) classes in the Tapestry services layer, are live-reloaded. Data and entity objects are not reloaded, so this is one area where you need to stop and restart Jetty to see the change. |
Restart the application, and refresh your browser, then hit the submit button.
Form with client side validations visible
This is a shot just after hitting the submit button; all the fields have been validated and pop-up error bubbles are displayed. This looks a bit cluttered, but all the bubbles, except for the one for the focus field (the field the user is actively typing into), will fade out after a moment. As you tab from field to field, Tapestry will validate your input and briefly display the error bubble. And all of this is taking place on the client side, without any communication with the application.
reasonable values. For example, several of the fields should be required, and phone numbers and email address have specific formats.
The BeanEditForm checks for a Tapestry-specific annotation, @Validate, on the field, the getter method, or the setter method of each property.
Edit the Address entity, and update the lastName, firstName, street1, city, state and zip fields, adding a @Validate annotation to each:
| Code Block | ||
|---|---|---|
| ||
@Validate("required")
public String firstName;
|
What is that string, "required"? That's how you specify the desired validation. It is a series of names that identify what type of validation is desired. A number of validators are built in, such as "required", "minLength" and "maxLength". As elsewhere, Tapestry is case insensitive.
You can apply multiple validations, by separating the validator names with commas. Some validators can be configured (with an equals sign). Thus you might say "required,minLength=5" for a field that must be specified, and must be at least five characters long.
| Warning |
|---|
You can easily get confused when you make a change to an entity class, such as adding the @Validate annotation, and not see the result in the browser. Only component classes, and (most) classes in the Tapestry services layer, are live-reloaded. Data and entity objects are not reloaded, so this is one area where you need to stop and restart Jetty to see the change. |
Restart the application, and refresh your browser, then hit the Create Address button.
This is a shot just after hitting the Create Address button; all the fields have been validated and errors displayed. Each field in error has been highlighted in red and had an error message addedEach field in error has been highlighted (it's a bit subtle) and marked with a red "X". Further, the label for each of the fields has also been highlighted in red, to even more clearly identify what's in error. The cursor has also been moved to the first field that's in error. And all of this is taking place on the client side, without any communication with the application.
Once all the errors are corrected, and the form does submit, all validations are performed on the server side as well (just in case the client has JavaScript disabled).
...
Let's give it a try; restart the application and enter an "abc" for the zip code.
Regexp validation
This is what you'll see after typing "abc" and tabbing out of the field, then tabbing back in. It's a little hard to capture all the animation effects in a still photo"abc" and clicking the Create Address button.
| Note |
|---|
Modern browsers will automatically validate a regexp field when the form is submitted, as shown above. Older browsers do not have that automatic support, but will still validate input, using the same decorations as for the required fields in the previous screenshot. |
In any case, that's the right validation behavior, but it's the wrong message. Your users are not going to know or care about regular expressions.
...
Refresh the page and submit again:
Regexp validation with corrected message
This trick isn't limited to just the regexp validator, it works equally well with any validator.
...
By now you are likely curious about what happens after the form submits successfully (without validation errors), so that's what we'll focus on next.
Next: Using Tapestry With Hibernate
...
...
| Scrollbar |
|---|
...