As you saw in the last chapter, the Roo web interface heavily relies on a number of fea
tures: Apache Tiles, tag libraries, and Spring’s localization process. Let’s take a closer look at some of these elements and see how you can configure them.
Before we begin, we need to lay out the rules behind some of the common field and component names. Later, we’ll discuss techniques for manipulating and hiding pregenerated form elements.
6.1.1 Element naming conventions
Recall that most elements require an id attribute to identify them. This id is generally created, for data-based operations, using the following scheme:
id_[java-packages].[entity-name][.[field-name]]
For example, your Course entity would generally have the following id:
id_com_rooinaction_coursemanager_course
For the Course field name, you’d have
id_com_rooinaction_coursemanager_course_name
These HTML id field naming conventions are manipulated by the custom tags to pull various other values. For example, to show an entity label:
label_com_rooinaction_coursemanager_course=Course
The label for a collection of those entities:
label_com_rooinaction_coursemanager_course=Course_plural=Courses
The label for a given field within a table:
label_com_rooinaction_coursemanager_course_name=Name
These values are generated by the scaffolding process. This is done within the custom tag files themselves, which are located in the WEB-INF/tags directory.
In the HTML form views, all field id values are reduced to _fieldname_id so that they are easily scripted. For example, _name_id is the HTMLid field representing the name column.
What if I’m building my own views?
If you want to benefit from Roo’s predefined localization structure, you need to follow these naming guidelines. Roo should automatically add labels for the component and fields for any entity you define, provided it’s a Roo-managed entity (@RooJpaEntity,
@RooJpaActiveRecord, etc).
You can also choose to bypass these conventions, and use the custom tag attributes such as label to define your text in-line. But these won’t be localized, so it’s up to you to decide whether you want to buck the conventions for more control, or learn them and benefit from them.
You can customize the contents of these generated views. To do so, you can modify the tag attributes for the various list and form views.
6.1.2 Scaffold’s magic z attribute
If you’re modifying scaffolded forms, rather than building your own, you’ll encounter the z attribute, which is assigned a generated unique ID. This seemingly random value tells Roo that the field is being managed by Roo itself. You don’t want to change this value unless you decide to manage a field yourself. The valid values for z are
A generated unique value, such as T5MViHc0PXnvBhkOlpd, meaning that this field is controlled by Roo.
user-managed, which obviously means that the field is being controlled by the user. Less obviously, it tells the Roo shell to ignore this field definition, and spe
cifically not to generate another definition for this generated, but customized, element.
HOW DO I RESET A FIELD BACK TO THE SCAFFOLDED VERSION? When you save your view, the scaffold fixes it up and replaces the element that was removed, along with any subelements.
Beyond the ID fields and z attribute, Roo has a number of settings in the tag libraries that make it easy to customize your web views. Above all, read through the tag libraries and learn their features.
With the conventions behind us, let’s see how to change the views to suit your needs.
6.1.3 Modifying list views
List views are composed of tags nested as shown in figure 6.1.
Roo automatically iterates through the rows in the collection, first outputting the column headers in a title row, and then listing all data in the collection. If paging is enabled, the content is paginated automatically.
In the list view, the tags you can customize include page:list, table:table, and table:column. Table 6.1 shows some customizations you can make. Keep in mind, you are limited in the scaffolding to showing the data returned by the controller, and may
159 Customizing Roo CRUD views
page:list table:table
table:column table:column table:column
util:pagination Figure 6.1 Nested tags in a
typical generated list view
have to set the z parameter to "user-managed" if you make any changes to the attri
butes so that Roo doesn’t overwrite the field values.
Table 6.1 Some key page:list tag attributes
Attribute Description Examples
label
labelPlural
items
The label to show representing the entity if no entries are found. This should be written as a sin
gular value.
Defaults to the locale key emitted, which is resolved from the localized
application.properties file.
The label to show instead of the name of the entity, to the right of the title prefix List All from messages.properties.
Defaults to the pluralized name of the entity.
The collection to be iterated through in the nested table. It’s listed here so that the outer tag can determine whether to show a table of results, or a message that there are no items available.
label="Course"
labelPlural="Courses"
items="${courses}"
But more important customizations occur at the table:table and table:column level. Let’s look at the customizations you can perform on your results table in table 6.2.
Table 6.2 table:table attributes
Attribute Description Examples
create update delete
Whether or not to show the icons for creating, updating‚ or deleting entries from the table.
Defaults to displaying all of these features.
create="false"
update="false"
delete="false"
Table 6.2 table:table attributes (continued)
Attribute Description Examples
data path
render
typeIdFieldName
The data collection to iterate through.
The URL path fragment to prepend to any requests to edit or remove data.
Whether to render the table at all. You may wish to replace the table with other form elements instead.
The field name for the primary key of the row—id is the default.
data="${courses}"
path="/courses"
render="false"
typeIdFieldName="course_id"
Finally, each field is emitted using the table:column tag. Table 6.3 shows table col
umn attributes.
Table 6.3 table:column customizations
Attribute Description Examples
label
maxLength
render
date calendar
dateTimePattern
The label to display. Unless overridden by this property, the label defaults to the localized label for the field name in application.properties.
Columns default to showing a maximum of 128 characters‚a so this is the first setting you’ll want to override if you want to trim the output.
Whether to render a column in the table output. You won’t want to render all 60 fields of your massive employee record, for example. Setting render="false"
for the ones you don’t want will omit them from the page.
Tells the tag whether the value is a stored java.util.Date, or a long that can be converted into a
java.util.Calendar.
For scaffolded date fields, this value will be automatically set.
The pattern to apply when formatting a field marked as a date or calendar. Scaf
folded controllers create these patterns and add them to the request. You may use your own pattern instead (see sec
tion 6.2.4).
label="Times"
maxLength="30"
render="false"
date="true"
dateTimePattern="mm/dd/yy"
a. This was changed in Roo 1.2. In earlier versions, users were only shown 10 characters of each field.
Customizing Roo CRUD views 161 You can customize any of the attributes in these fields, as long as you don’t change the generated id field value, or, in the case of the column definitions, modify the name of the properties they’re attached to. This way, Roo marks the customized elements as user-managed and leaves them alone.
WHAT IF I WANT TO REMOVE A FORM ELEMENT IN A SCAFFOLD? Just set render
="false" on the element and it won’t be rendered. Remember, if it’s a key HTML form field value, you may have to add it as a hidden HTML field manu
ally to carry it in the form.
Now let’s move on to form field views. What can you customize there?
6.1.4 Form view customizations
There are two generated forms—the create and update variants. They’re nearly identical to what you saw in the previous chapter. Figure 6.2 shows the tag nesting.
The form view tags also take a number of attributes. You can choose to replace a gener
ated form field with another type, or customize the way the form is rendered, simply by modify
ing the attributes or form field tag names.
Unlike the list view, form views are generally relatively flat. That’s because they’re editing a single entity.
Table 6.4 shows some attributes from the
form:create or form:update form:checkbox, or
form:datetime, or form:display, or
form:editor, or form:input, or form:select
...
Figure 6.2 Nesting of form and field tags
form:create and form:update tags.
Table 6.4 form:create and form:update customizations
Attribute Create? Update? Description Examples
label Y Y The label for the entity being created. Will be added to the localized version of the mes
sage Create new, as in Create new Course.
label
="Training Course"
render Y Y Whether to render the gener
ated form. By default only ren
ders if all parent dependencies are satisfied.
render
="false"
multipart Y Y If a file upload field is present (see field:file), you need to set this attribute to true.
Otherwise the file will not be uploaded.
multipart
="true"
There are other parameters, mostly used by the scaffolding system. But the key cus
tomizations take place in the form fields.
6.1.5 Common form field attributes
Table 6.5 has a list of fields that are common to many field types, and their relevant uses.
Table 6.5 Common form field attributes
Attribute Description Field Type(s)
label
labelCode
required
disabled
validationRegex validationMessage validationMesageCode
The label to use to identify the field on the screen. This version is not localized, and is useful during prototyping or for applications that don’t need localization.
As with label above, identifies the field on the screen. The label is interpolated using the localized properties files.
Whether the field is required to submit the form. If this value is set to true, and the field is skipped, the client-side JavaScript val
idators won’t allow the form to be submitted.
This is a form of client-side validation.
Whether the field can be edited. This may be useful if set based on user permissions using the Spring Security API or other data- based permission scheme.
The regular expression defining the validation to apply for this field and the message to return when invalid.
The messageCode variant looks up the mes
sage in the localized property stream, and the message variant takes a literal error message.
Don’t forget to apply this pattern and mes
sage to both the create and update forms if you’re going to allow both creation and update editing of the field.
Example:
validationRegex="[A-Z,a-z ]*$"
validationMessage="Invalid Name"
all
all
input, editor, textarea, datetime, select
input, editor, textarea, datetime, select
input, textarea, editor, datetime
Armed with these tables of information, you should be able to customize your views nicely. You can always drop in additional HTML elements where needed, and update your CSS styles as well. But what else can you do?