@ParameterLayout

Collects together all layout hints for action parameters in a single annotation.

API

ParameterLayout.java
@interface ParameterLayout {
  String cssClass() default "";     (1)
  String describedAs() default "";     (2)
  LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;     (3)
  String named() default "";     (4)
  boolean namedEscaped() default true;     (5)
  int multiLine() default -1;     (6)
  RenderDay renderDay() default RenderDay.NOT_SPECIFIED;     (7)
  int typicalLength() default -1;     (8)
}
1 cssClass

Indicates the css class that a parameter should have, to allow more targeted styling in application.css .

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 namedEscaped

A flag indicating whether the value of #named() should be HTML escaped or not.

6 multiLine

For string parameters (and properties), whether to render as a text area over multiple lines.

7 renderDay

For date parameters (and properties) only, instructs the viewer that the date should be rendered as one day prior to the actually stored date.

8 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 .

describedAs

Description of this property, eg to be rendered in a tooltip.

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.

namedEscaped

A flag indicating whether the value of #named() should be HTML escaped or not.

multiLine

For string parameters (and properties), whether to render as a text area over multiple lines.

If set to > 1, then #labelPosition() defaults to LabelPosition#TOP top .

renderDay

For date parameters (and properties) only, instructs the viewer that the date should be rendered as one day prior to the actually stored date.

This is intended to be used so that an exclusive end date of an interval can be rendered as 1 day before the actual value stored.

For example:

public void updateDates(
    @ParameterLayout(named="From") LocalDate startDate,
    @ParameterLayout(named="To"), renderDay=RenderDay.AS_DAY_BEFORE) LocalDate endDate) { ... }

Here, the interval of the [1-may-2013,1-jun-2013) would be rendered as the dates 1-may-2013 for the start date but using 31-may-2013 (the day before) for the end date. What is stored In the domain object, itself, however, the value stored is 1-jun-2013.

typicalLength

The typical entry length of a field, use to determine the optimum width for display

Note: the Wicket viewer does not use this information.

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 isis.applib.annotation.parameter-layout.label-position configuration property:

application.properties
isis.applib.annotation.parameter-layout.label-position=TOP

or

application.properties
isis.applib.annotation.parameter-layout.label-position=LEFT

If 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.

By default the name is HTML escaped. To allow HTML markup, set the related namedEscaped() attribute to false.

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.