@ParameterLayout
Collects together all layout hints for action parameters in a single annotation.
API
@interface ParameterLayout {
String cssClass() default ""; (1)
String describedAs() default ""; (2)
LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED; (3)
String named() default ""; (4)
int multiLine() default -1; (5)
int typicalLength() default -1; (6)
}| 1 | cssClass
Indicates the css class that a parameter should have, to allow more targeted styling in |
| 2 | describedAs
Description of this property, eg to be rendered in a tooltip. |
| 3 | labelPosition
In forms, positioning of the label (left, top or none) relative to the parameter value. |
| 4 | named
Name of this action parameter. |
| 5 | multiLine
For string parameters (and properties), whether to render as a text area over multiple lines. |
| 6 | typicalLength
The typical entry length of a field, use to determine the optimum width for display |
Members
cssClass
Indicates the css class that a parameter should have, to allow more targeted styling in application.css .
labelPosition
In forms, positioning of the label (left, top or none) relative to the parameter value.
If not specified, the default depends upon the parameter value’s datatype (including whether the field is #multiLine() .
named
Name of this action parameter.
The name of an action parameters is available to the framework provided that the code is compiled using -parameters (for javac .
The only reason then to name the parameter is if the desired name is a reserved Java keyword, such as default or package.
Examples
For example:
public class ToDoItem {
public ToDoItem updateDescription(
@ParameterLayout(
cssClass="x-key",
describedAs="What needs to be done",
labelPosition=LabelPosition.LEFT,
named="Description of this <i>item</i>",
namedEscaped=false,
typicalLength=80)
final String description) {
setDescription(description);
return this;
}
...
}|
Note that there is (currently) no support for specifying UI hints for domain services through the dynamic .layout.xml file (only for properties, collections and actions are supported). |
Usage Notes
Label Positioning
The labelPosition() element determines the positioning of labels for parameters.
The positioning of labels is typically LEFT, but can be positioned to the TOP.
The one exception is multiLine() string parameters, where the label defaults to TOP automatically (to provide as much real-estate for the multiline text field as possible).
For boolean parameters a positioning of RIGHT is also allowed; this is ignored for all other types.
It is also possible to suppress the label altogether, using NONE.
For example:
public class Order {
public Order changeStatus(
OrderStatus newStatus,
@Nullable
@ParameterLayout(
labelPosition=LabelPosition.TOP
)
String reason) {
// ...
}
// ...
}Default settings
If you want a consistent look-n-feel throughout the app, eg all parameter labels to the top, then it’d be rather frustrating to have to annotate every parameter.
Instead, a default can be specified using the causeway.applib.annotation.parameter-layout.label-position configuration property:
causeway.applib.annotation.parameter-layout.label-position=TOPor
causeway.applib.annotation.parameter-layout.label-position=LEFTIf these are not present then the framework will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
Text boxes
The multiLine() element specifies that the text field for a string parameter should span multiple lines. It is ignored for other parameter types.
If set > 1 (as would normally be the case), then the default labelPosition defaults to TOP (rather than LEFT, as would normally be the case).
For example:
public class BugReport {
public BugReport updateStepsToReproduce(
@ParameterLayout(
numberOfLines=10
)
final String steps) {
// ...
}
// ...
}Descriptions
The describedAs() element is used to provide a short description of the action parameter to the user.
In the Web UI (Wicket viewer) it is displayed as a 'tool tip'.
For example:
public class Customer {
public Order placeOrder(
Product product,
@ParameterLayout(
describedAs = "The quantity of the product being ordered"
)
int quantity) {
// ...
}
// ...
}CSS Styling
The cssClass() element can be used to render additional CSS classes in the HTML (a wrapping <div>) that represents the action parameter.
Application-specific CSS can then be used to target and adjust the UI representation of that particular element.
For example:
public class ToDoItem {
public ToDoItem postpone(
@ParameterLayout(
cssClass="x-key"
)
LocalDate until ) {
// ...
}
// ...
}Date intervals
The renderDay() element applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for parameters of other types.
This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.
In such cases there would typically be startDate and endDate properties, eg for all of Q2. Storing this as a half-closed interval — eg [1-Apr-2015, 1-July-2015) — can substantially simplify internal algorithms; the endDate of one interval will correspond to the startDate of the next.
However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as 30-Jun-2015.
This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
For example:
public class Tenancy {
public void changeDates(
LocalDate startDate,
@ParameterLayout(
renderDay = RenderDay.AS_DAY_BEFORE
)
LocalDate endDate) {
// ...
}
// ...
}Names
The named() element explicitly specifies the action parameter’s name.
Normally this is not necessary; so long the program must be compiled using javac's -parameters flag, the framework can use the parameter name in the compiled class file.
|
We recommend that you only use this element when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes. |
The name is HTML escaped.
For example:
public class Customer {
public Order placeOrder(
final Product product,
@ParameterLayout(named="Package ?")
final boolean packageUp) {
Order order = Order.forCustomer(this)
.ofProduct(product)
.withPackage(packageUp);
return repository.persistAndFlush(order);
}
...
}i18n
The framework also provides a separate, powerful mechanism for internationalization.
Typical (string) length
The typicalLength() element indicates the typical length of a string parameter. It is ignored for parameters of other types.
The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter.
For example:
public class Customer {
public Customer updateName(
@Parameter(maxLength=30)
@ParameterLayout(
typicalLength=20
)
final String firstName,
@Parameter(maxLength=30)
@ParameterLayout(
typicalLength=20
)
final String lastName) {
// ...
}
// ...
}| All that said, the Web UI (Wicket viewer) uses the maximum space available for all fields, so in effect ignores this element. |