@PropertyLayout

Collects together all layout hints for a property of a domain object.

API

PropertyLayout.java
@interface PropertyLayout {
  String cssClass() default "";     (1)
  String describedAs() default "";     (2)
  Where hidden() default Where.NOT_SPECIFIED;     (3)
  LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;     (4)
  int multiLine() default -1;     (5)
  String named() default "";     (6)
  boolean namedEscaped() default true;     (7)
  Navigable navigable() default Navigable.NOT_SPECIFIED;     (8)
  PromptStyle promptStyle() default PromptStyle.NOT_SPECIFIED;     (9)
  RenderDay renderDay() default RenderDay.NOT_SPECIFIED;     (10)
  Repainting repainting() default Repainting.NOT_SPECIFIED;     (11)
  int typicalLength() default -1;     (12)
}
1 cssClass

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

2 describedAs

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

3 hidden

Indicates where in the UI the property should not be visible.

4 labelPosition

In forms, positioning of the label (left, top or none) relative to the property value.

5 multiLine

For string properties (and parameters), render as a text area over specified number of lines.

6 named

Name of this property (overriding the name derived from its name in code).

7 namedEscaped

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

8 navigable

Whether this property should be used to construct the navigable chain of breadcrumbs in the UI.

9 promptStyle

How the properties of this domain object are be edited, either PromptStyle#DIALOG dialog or PromptStyle#INLINE inline .

10 renderDay

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

11 repainting

Indicates that the value held by the property never changes over time, even when other properties of the object do change.

12 typicalLength

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

Members

cssClass

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

describedAs

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

hidden

Indicates where in the UI the property should not be visible.

labelPosition

In forms, positioning of the label (left, top or none) relative to the property value.

If not specified, the default depends upon the property value’s datatype (including whether the field is #multiLine() .

multiLine

For string properties (and parameters), render as a text area over specified number of lines.

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

named

Name of this property (overriding the name derived from its name in code).

A typical use case 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.

Whether this property should be used to construct the navigable chain of breadcrumbs in the UI.

Only one property can be annotated as such per domain class.

promptStyle

How the properties of this domain object are be edited, either PromptStyle#DIALOG dialog or PromptStyle#INLINE inline .

renderDay

For date properties (and parameters) 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 LocalDate getStartDate() { ... }

@PropertyLayout(renderDay=RenderDay.AS_DAY_BEFORE)
public LocalDate getEndDate() { ... }

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.

repainting

Indicates that the value held by the property never changes over time, even when other properties of the object do change.

Setting this attribute to RepaintPolicy.NO_REPAINT is used as a hint to the viewer to not repaint the property after an AJAX update of some other property/ies of the object have changed. This is primarily for performance, eg can improve the user experience when rendering PDFs/blobs.

Note that for this to work, the viewer will also ensure that none of the property’s parent component (such as a tab group panel) are re-rendered.

Design note: we considered implementing this an "immutable" flag on the Property annotation (because this flag is typically appropriate for immutable/unchanging properties of a domain object). However, we decided not to do that, on the basis that it might be interpreted as having a deeper impact within the framework than simply a hint for rendering.

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 {
    @PropertyLayout(
        cssClass="x-key",
        named="Description of this <i>item</i>",
        namedEscaped=false,
        describedAs="What needs to be done",
        labelPosition=LabelPosition.LEFT,
        typicalLength=80
    )
    public String getDescription() { /* ... */ }
    ...
}

As an alternative to using the @PropertyLayout annotation, a file-based layout can be used (and is generally to be preferred since it is more flexible/powerful).

The annotation is one of a handful (others including @Collection, @CollectionLayout and @Property) that can also be applied to the field, rather than the getter method. This is specifically so that boilerplate-busting tools such as Project Lombok can be used.

Usage Notes

As alternative to using the annotation, the dynamic file-based layout can generally be used instead.

Label Positioning

The labelPosition() element determines the positioning of labels for properties.

The positioning of labels is typically LEFT, but can be positioned to the TOP. The one exception is multiLine string properties, where the label defaults to TOP automatically (to provide as much real-estate for the multiline text field as possible).

For boolean properties 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:

import lombok.Getter;
import lombok.Setter;

public class ToDoItem {

    @PropertyLayout(
        labelPosition=LabelPosition.TOP
    )
    @Getter @Setter
    private String description;

    // ...
}

Default settings

If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it’d be rather frustrating to have to annotate every property.

Instead, a default can be specified using the isis.applib.annotation.property-layout.label-position configuration property:

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

or

application.properties
isis.applib.annotation.property-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.

Prompt Style

The promptStyle() element is used to specify whether, when editing a domain object property, the new value for the property is prompted by way of a dialog box, or is prompted using an inline panel (replacing the property on the page).

If the attribute is not set, then the value of the isis.viewer.wicket.prompt-style configuration property is used. If this is itself not set, then an inline prompt is used.

For example:

import lombok.Getter;
import lombok.Setter;

public class Customer {

    @PropertyLayout(
        promptStyle=PromptStyle.INLINE  (1)
    )
    @Getter @Setter
    private String notes;

    // ...
}
1 prompt for the new value for the property using an inline panel Note that the value INLINE_AS_IF_EDIT does not make sense for properties; if specified then it will be interpreted as just INLINE.

Text boxes

The multiLine() element specifies that the text field for a string property should span multiple lines. It is ignored for other property 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:

import lombok.Getter;
import lombok.Setter;

public class BugReport {

    @PropertyLayout(
        numberOfLines=10
    )
    @Getter @Setter
    private String stepsToReproduce;

    // ...
}

Here the stepsToReproduce property will be displayed in a text box of 10 rows.

The navigable() element allows to specify a domain object’s (or view’s) navigable parent, as utilized by the 'Where am I' feature.

For example, suppose:

@DomainObject
public class Company {
    // ...
}

then:

import lombok.Getter;
import lombok.Setter;

@DomainObject
public class Employee {

    @PropertyLayout(navigable=Navigable.PARENT)
    @Getter @Setter
    private Company myCompany;

    // ...
}

This points up to the Employee's parent Company.

For further details on using a navigable tree-structure, see Where am I in the user guide.

Descriptions

The describedAs() element is used to provide a short description of the property to the user.

In the Web UI (Wicket viewer) it is displayed as a 'tool tip'.

For example:

public class Customer {

    @PropertyLayout(
        describedAs = "The name that the customer has indicated " +
                      "that they wish to be addressed as " +
                      "(e.g. Johnny rather than Jonathan)")
    private String firstName;

    // ...
}

CSS Styling

The cssClass() element can be used to render additional CSS classes in the HTML (a wrapping <div>) that represents the property. Application-specific CSS can then be used to target and adjust the UI representation of that particular element.

For example:

import lombok.Getter;
import lombok.Setter;

public class ToDoItem {

    @PropertyLayout(cssClass="x-key")
    @Getter @Setter
    private LocalDate dueBy;

    // ...
}

Date intervals

The renderDay() element applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for properties 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:

import lombok.Getter;
import lombok.Setter;

public class Tenancy {

    @Getter @Setter
    private LocalDate startDate;

    @PropertyLayout(
        renderDay = RenderDay.AS_DAY_BEFORE
    )
    @Getter @Setter
    private LocalDate endDate;

    // ...
}

Smoother UI

The repainting() element is used to indicate that the value held by the property never changes over time, even when other properties of the object do change.

Setting this attribute to true is used as a hint to the viewer to not redraw the property after an AJAX update of some other property/ies of the object have changed. This is primarily for performance, eg can improve the user experience when rendering PDFs/blobs.

Note that for this to work, the viewer will also ensure that none of the property’s parent component (such as a tab group panel) are re-rendered.

Design note: we considered implementing this an "immutable" flag on the @Property annotation (because this flag is typically appropriate for immutable/unchanging properties of a domain object). However, we decided not to do that, on the basis that it might be interpreted as having a deeper impact within the framework than simply a hint for rendering.

For example:

import lombok.Getter;
import lombok.Setter;

public class Document {

    @PropertyLayout(
        repainting=Repainting.NO_REPAINT
    )
    @Getter @Setter
    private Blob blob;

    // ...
}

Names

The named() element explicitly specifies the property’s name, overriding the name that would normally be inferred from the Java source code.

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() to false.

For example:

import lombok.Getter;
import lombok.Setter;

public class ToDoItem {

    @PropertyLayout(
        named="Description of this <i>item</i>",
        namedEscaped=false
    )
    @Getter @Setter
    private String description;

    // ...
}

Alternatives

The framework also provides a separate, powerful mechanism for internationalization.

Hiding properties

The hidden() element attribute indicates where (in the UI) the property should be hidden from the user.

The acceptable values for the where parameter are:

  • Where.EVERYWHERE or Where.ANYWHERE

    The property should be hidden everywhere.

  • Where.ANYWHERE

    Synonym for everywhere.

  • Where.OBJECT_FORMS

    The property should be hidden when displayed within an object form.

  • Where.PARENTED_TABLES

    The property should be hidden when displayed as a column of a table within a parent object’s collection.

  • Where.STANDALONE_TABLES

    The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.

  • Where.ALL_TABLES

    The property should be hidden when displayed as a column of a table, either an object’s * collection or a standalone list. This combines PARENTED_TABLES and STANDALONE_TABLES.

  • Where.NOWHERE

    The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden.

The RestfulObjects viewer has only partial support for these Where enums.

Examples

For example:

import lombok.Getter;
import lombok.Setter;

public class Customer {

    @PropertyLayout(
        hidden=Where.ALL_TABLES
    )
    @Getter @Setter
    private int internalId;

    // ...
}

As one specific use case, if a property is annotated with @Title, then normally this should be hidden from all tables. Annotating with @Property(where=Where.NOWHERE) overrides this.

Alternatives

It is also possible to use @PropertyLayout#hidden to hide a property at the domain layer.

Typical (string) length

The typicalLength() element indicates the typical length of a string property. It is ignored for properties 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 property.

For example:

import lombok.Getter;
import lombok.Setter;

public class Customer {

    @javax.jdo.annotations.Column(length=30)
    @ParameterLayout(typicalLength=20)
    @Getter @Setter
    private String firstName;

    // ...
}
All that said, the Web UI (Wicket viewer) uses the maximum space available for all fields, so in effect ignores this element.