= @PropertyLayout
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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

== API

[source,java]
.PropertyLayout.java
----
@interface PropertyLayout {
  String cssClass() default "";     // <.>
  String describedAs() default "";     // <.>
  String fieldSetId() default "__infer";     // <.>
  String fieldSetName() default "__infer";     // <.>
  Where hidden() default Where.NOT_SPECIFIED;     // <.>
  LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;     // <.>
  int multiLine() default -1;     // <.>
  String named() default "";     // <.>
  Navigable navigable() default Navigable.NOT_SPECIFIED;     // <.>
  PromptStyle promptStyle() default PromptStyle.NOT_SPECIFIED;     // <.>
  Repainting repainting() default Repainting.NOT_SPECIFIED;     // <.>
  String sequence() default "";     // <.>
  int typicalLength() default -1;     // <.>
}
----

<.> xref:#cssClass[cssClass]
+
--
Indicates the css class that a property should have, to allow more targeted styling in `application.css` .
--
<.> xref:#describedAs[describedAs]
+
--
Description of this property, eg to be rendered in a tooltip.
--
<.> xref:#fieldSetId[fieldSetId]
+
--
Specifies the *id* of associated _FieldSet_ .XML layout is presentXML layout is absent
--
<.> xref:#fieldSetName[fieldSetName]
+
--
Specifies the *friendly-name* of associated _FieldSet_ .
--
<.> xref:#hidden[hidden]
+
--
Indicates where in the UI the property should _not_ be visible.
--
<.> xref:#labelPosition[labelPosition]
+
--
In forms, positioning of the label (left, top or none) relative to the property value.
--
<.> xref:#multiLine[multiLine]
+
--
For string properties (and parameters), render as a text area over specified number of lines.
--
<.> xref:#named[named]
+
--
Name of this property (overriding the name derived from its name in code).
--
<.> xref:#navigable[navigable]
+
--
Whether this property should be used to construct the navigable chain of breadcrumbs in the UI.
--
<.> xref:#promptStyle[promptStyle]
+
--
How the properties of this domain object are be edited, either _PromptStyle#DIALOG dialog_ or _PromptStyle#INLINE inline_ .
--
<.> xref:#repainting[repainting]
+
--
Indicates that the value held by the property never changes over time, even when other properties of the object do change.
--
<.> xref:#sequence[sequence]
+
--
The order of this member relative to other members in the same (layout) group, given in _Dewey-decimal_ notation.
--
<.> xref:#typicalLength[typicalLength]
+
--
The typical entry length of a field, use to determine the optimum width for display.
--

== Members

[#cssClass]
=== cssClass

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

[#describedAs]
=== describedAs

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

[#fieldSetId]
=== fieldSetId

Specifies the *id* of associated _FieldSet_ .XML layout is presentXML layout is absent

A _FieldSet_ is a layout component for property grouping, that can either be specified via a `Xxx.layout.xml` file (with `Xxx` the domain object name) or is inferred by the framework via annotations (aka the programming model). _FieldSet_ s are represented in-memory and requires a framework internal unique id per domain object type.

Following 2 scenarios have slightly different behavior:

When a XML layout is present, every _FieldSet_  *id* is either explicitly specified in the file or may be inferred from a non-empty *name* . If the *name* is empty "" or missing, then the *id* within the file is mandatory.

If this _Property_ is not already explicitly listed within the XML layout, we lookup the associated _FieldSet_ in the XML layout file first matching by *id* using _@PropertyLayout(fieldSetId=...)_ if any, then falling back to matching by (friendly) *name* using @PropertyLayout(fieldSetName=...)} if any.

We reify (in-memory) the associated _FieldSet_ using _@PropertyLayout(fieldSetId=...)_ (if present) as its *id* and using _@PropertyLayout(fieldSetId=...)_ as its (friendly) *name* . While if no *id* is provided an *id* is inferred from the (friendly) *name* , in which case the (friendly) *name* must not be empty. Whereas if no (friendly) *name* is provided a (friendly) *name* is inferred from the *id* , in which case the *id* must not be empty.

With _@PropertyLayout(sequence=...)_ the relative position within that _FieldSet_ can be specified.

[#fieldSetName]
=== fieldSetName

Specifies the *friendly-name* of associated _FieldSet_ .

Explicitly specifying an empty "" *friendly-name* will suppress the _FieldSet_ 's label from being rendered.

For a more in depth description see _PropertyLayout#fieldSetId()_ .

[#hidden]
=== hidden

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

[#labelPosition]
=== 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]
=== 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]
=== 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`.

[#navigable]
=== navigable

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]
=== promptStyle

How the properties of this domain object are be edited, either _PromptStyle#DIALOG dialog_ or _PromptStyle#INLINE inline_ .

[#repainting]
=== 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 xref:refguide:applib:index/annotation/Property.adoc[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.

[#sequence]
=== sequence

The order of this member relative to other members in the same (layout) group, given in _Dewey-decimal_ notation.

An alternative is to use the `Xxx.layout.xml` file, where `Xxx` is the domain object name.

[#typicalLength]
=== 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.

include::hooks/PropertyLayout_010-examples-and-usage.adoc[]

include::hooks/PropertyLayout_021_labelPosition.adoc[]

include::hooks/PropertyLayout_022_promptStyle.adoc[]

include::hooks/PropertyLayout_023_multiLine.adoc[]

include::hooks/PropertyLayout_024_navigable.adoc[]

include::hooks/PropertyLayout_025_describedAs.adoc[]

include::hooks/PropertyLayout_026_cssClass.adoc[]

include::hooks/PropertyLayout_027_renderDay.adoc[]

include::hooks/PropertyLayout_028_repainting.adoc[]

include::hooks/PropertyLayout_029_named.adoc[]

include::hooks/PropertyLayout_030_hidden.adoc[]

include::hooks/PropertyLayout_31_typicalLength.adoc[]
