It's possible to have the cartridge render tables for you from certain parameters modeled in UML. These tables use the displaytag tag-library behind the scenes.
In order to have these tables rendered for you you will need to model a
page variable
that maps onto a descendant of
java.util.Collection
(for example datatype::Collection
) or use
an array of a custom type.
Using arrays is interesting when you are using dates in columns and you want to specify a custom format, in this case you'll just need to add a tagged value to the corresponding attribute of the array's type. This feature elegantly integrates with the use of value objects and POJO entities such as found in Hibernate.
Do not specify type java.util.Collection
directly, but use
datatype::Collection
instead. When specifying an array you must not use an array
of datatypes, but define your own class instead, add attributes to it
and model another class representing the array by adding the array suffix to its name, eg.
[]
(see the
online store
for an example).
Next you will simply need to model one or more tagged values onto that parameter. (If you choose to specify more than one property per value you can also separate them using commas, nevertheless, it is recommended to specify a value per property)
@andromda.presentation.view.table.columns=property1,property2,...,propertyN
Just make sure that each property listed has corresponding accessor methods for each element in the collection parameter. This requirement cannot be checked during development so failing to conform to it will result in a runtime error.
It's very common that users want to click on a row in the table and continue to the next page, possibly showing the item in more detail. It's possible to have this feature generated by associating one of the table columns to one of the events exiting that same page.
First of all you will need to model an event with one or more parameters (if you are not sure how to do that then re-read this previous section ), make sure this event transition is going out of the page containing the table page-variable.
Second, you will need to make sure the event will be rendered as an hyperlink and not as a regular
form post, you can do that by using the @andromda.presentation.web.action.type=hyperlink
tagged value on the transition itself.
Finally link this event to the table page-variable and specify the column in which the hyperlink is
to be rendered, this is particularly important since there
might be more than a single table from which to choose. In order to achieve this we will be using
the @andromda.presentation.web.action.tablelink=myTable.myColumn
tagged value on the transition
(replace myTable
with the name of your table, and notice how to dot separates both
fields).
If you don't specify a column name then the hyperlink will be rendered in its own column, the link will show the name of your event, rather than the cell value.
Not only hyperlinks can be modeled this way, also events that work on individual rows. This is
very similar to the modeling of hyperlink events, except that here the tagged value should not be
set to hyperlink
, but to form
, like this:
@andromda.presentation.web.action.type=form
(which is the default value
if it has not been specified, so you don't actually need to set it).
Please note that it is not possible to use a hyperlink when submitting a row. It would be possible
only when none of the row values are updateable, but in order to not overly complicate the usage
of the bpm4struts cartridge by adding more/complex modeling constraints we prefer to simply
restrict sending a row's value using the @andromda.presentation.web.action.type=form
tagged
value.
Model an event going out of the page showing the table, add one or more parameters to this event. Every one of these parameters will now be rendered in a widget, and next to each row there will be a button to apply this action on it. Clicking the button will invoke a JavaScript function that will sumbit a form to the target action; browsers not supporting JavaScript or having JavaScript disabled will not be able to use this functionality.
Don't forget to add the tagged value, but it's not needed to specify any column this time:
@andromda.presentation.web.action.tablelink=myTable
No need to specify a column name in this
tagged value as these buttons will always be put in their own column.
Any widget is allowed, but if you still prefer to have plain text rendered instead of a widget
then simply use the plaintext
field type, like this:
@andromda.presentation.web.view.field.type=plaintext
If there are many events linked to the same table, and the same parameter is repeated across different events, then the hyperlink events with take priority, meaning you will never see any input widget for those parameters in an hyperlink event.
It's possible to have an image instead of an hyperlink or button, for this you'll have to
use the @andromda.presentation.web.action.type=image
tagged value on the event transition.
An entry in the resource bundle will be generated for the image, and the value will be resolved
against the current contextPath (much like the struts tags taking a page
attribute).
This has the advantage that the image can be i18n'ed, allowing you to display a different image per language or locale.
By default the image will be missing from the generated application, you will have to add it manually to your source directory and have it copied into the war bundle. You can use the copy-over feature to achieve this.
In addition to the submittal of a specific row it is also possible to select a couple of rows and submit them, mind you, this mechanism works a little different than one might expect.
This feature is only able to submit one single value per row, it is not possible to submit all column values for all selected rows.
In order to achieve this we use the table link and action type tagged values as before,
only this time the value is of the action type is table
, like this:
@andromda.presentation.web.action.tablelink=myTable @andromda.presentation.web.action.type=table
Let's list the things to do in order to successfully make use of this feature:
@andromda.presentation.web.action.tablelink
tagged value on
the action transition@andromda.presentation.web.action.type=table
tagged value on
the action transitionIn summary: this will result in the cartridge having generated code that will place a checkbox in front of each row, the checkbox carries the value of the table column with the same name as the event parameter modeled on the transition. Each such action will have a button and there's also a button to select or deselect all rows. When a checkbox is selected its corresponding value will be sent to the server when one of the action buttons is clicked.
One very special type of widget, which is a little more complicated to understand at first, is
the multibox
widget. Basically it allows you to render checkboxes whose
checked
statuses need to be controlled by another property.
Let's say you want to render a checkbox for each row, but the value behind is not of a
boolean
type but a String
; in that case you can setup a page-variable
which holds an array
or a Collection
of String
instances,
when a value for a specific row matches at least one of the elements the checkbox will be checked.
The available
column of the table in the example image below has the following
tagged values:
@andromda.presentation.web.view.field.tablelink=itemList @andromda.presentation.web.view.field.type=multibox @andromda.struts.view.field.multibox=availableItems
In this example the availableItems
page-variable is used to match the
available
property against.
This example is taken from the
Online Store
sample.
It is showing two hyperlink events, on the id
and publisher
columns
respectively, and one form event that will submit the id
, edition
and
available
fields (see the
UML model
, opens in MagicDraw only).
In the id
column you can see an hyperlink for each row. This has been achieved by
modeling the following things:
id
@andromda.presentation.web.action.tablelink
tag to the event,
the value should be the name of the table separated from the column name using a dot, ie.
itemList.id
. Not specifying the column name will make put this link in
a separate column on the right.
@andromda.presentation.web.action.type=hyperlink
tag to the event,
this denotes this action to be rendered as an hyperlink pointing to the target
Struts action.
@andromda.presentation.web.view.field.type=link
tagged
value to the 'id' event trigger parameter. Unless you do this the
field will be rendered using the default widget which will be a text-input field.
This feature is interesting when you want to see the details of a specific item in the list.
Equivalent to the id
hyperlink, except that this time we add two parameters to this
event: id
and publisher
.
Make sure to have the hyperlink point to the publisher
column, like this:
@andromda.presentation.web.action.tablelink=itemList.publisher
.
This feature is interesting when you want to see information on a related property, in this case the homepage of the company or person that has published this item.
All these elements make up a specific event, which has been modeled like this:
buy
edition
is a 'select' and
available
is a 'multibox'
@andromda.presentation.web.action.tablelink
tag to the event, the value should
be the name of the table
If you wish to include the title
parameter but you don't want to have it rendered
as an input field, then simply use the @andromda.presentation.web.view.field.type=plaintext
tagged value on that parameter.
Next up is the Other Content section.