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

The `labelPosition` element indicates where the label for a property to be rendered: typically to the left or the top, or sometimes none:

* for properties, the element can be specified using either the `@PropertyLayout` annotation, or a meta-annotation, or using the `Xxx.layout.xml` layout file.

* for parameters, the element can be specified using either the `@ParameterLayout` annotation, or a meta-annotation.

Some data types also support the label being rendered to the right (support for this is shown on each of the demo pages for each of the data types).



== Annotated

The `labelPosition` element can be specified explicitly using an annotation:

* for properties, using `@PropertyLayout#labelPosition()`:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=annotation]
----
<.> explicitly specifies the label position for the property

* for parameters, using `@ParameterLayout#labelPosition()`:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateWithParameterLayout.java[tags=annotation]
----
<.> explicitly specifies the label position for the parameter

== Layout File

For properties (not parameters), the CSS class element can be specified using the `Xxx.layout.xml` file:

* property definition:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=layout-file]
----
<.> `labelPosition` hint is _not_ present.

* layout file snippet:
+
[source,xml,indent=0,tabsize=4]
----
<cpt:property id="propertyUsingLayout" labelPosition="TOP"/>
----

One advantage of the layout file over the annotation is that the layout file is dynamic: it can be modified and the changes reloaded in a running application.

TIP: It is sometimes necessary to invoke the `Rebuild Metamodel` action to see this take effect.

== Contributed

The `@PropertyLayout` can also be applied at the class-level to mixin properties:.

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_mixinProperty.java[tags=class]
----
<.> explicitly specifies the label position for the contributed property

== Meta-annotated

The label position element can also be specified using a custom meta-annotation:

* the meta-annotation is defined as:
+
[source,java]
----
include::LabelPositionTopMetaAnnotation.java[tags=class]
----
<.> annotated for a property ...
<.> \... and for a parameter.
<.> annotation can be applied to a property (either its getter or the field directly)
<.> annotation can be applied to a parameter
<.> annotation can be applied to a type (ie, meta-meta annotations recursively)

* and can be applied to a property:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=meta-annotated]
----
<.> hint is inherited from the meta-annotation

* or can be applied to a parameter:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateWithMetaAnnotation.java[tags=meta-annotation]
----
<.> hint is inherited from the meta-annotation

* or can be applied to mixin:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_mixinPropertyWithMetaAnnotation.java[tags=class]
----
<.> hint is inherited from the meta-annotation

=== Meta-annotated Overridden

The meta-annotation can itself be overridden:

* in a property:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=meta-annotated-overridden]
----
<.> hint from meta-annotation ...
<.> \... is overridden by the `@PropertyLayout` annotation

* or a parameter:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateWithMetaAnnotationOverridden.java[tags=meta-annotation-overridden]
----
<.> hint from meta-annotation ...
<.> \... is overridden by the `@ParameterLayout` annotation


* or a mixin:
+
[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_mixinPropertyWithMetaAnnotationOverridden.java[tags=meta-annotation-overridden]
----
<.> hint from meta-annotation ...
<.> \... is overridden by the `@PropertyLayout` annotation


== Variants

As mentioned earlier, the label can be positioned to the left, top, none, right or left unspecified.

=== Left

For a property:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-left]
----

And for a parameter:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateVariantLeft.java[tags=annotation]
----

=== Top

For a property:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-top]
----

And for a parameter:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateVariantTop.java[tags=annotation]
----

=== Right

Most data types do not support the right label position, and instead render to the top.

For a string property:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-right]
----

However, the boolean type _does_ support labels position to the right:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-right-boolean]
----


=== None

All data types allow the label position to be omitted, although this can create a confusing user interface.

For a string property:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-none]
----

One place where "NONE" is used however is with multiline descriptions:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-none-multiline]
----

TIP: the description text you are reading right now is in fact a contributed `AsciiDoc` property with no label.

=== Not Specified

It's also possible to omit specifying the label position, either implicitly or explicitly.
In this case a default position will be used:

For a property:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm.java[tags=variants-not-specified]
----

And for a parameter:

[source,java,indent=0]
----
include::PropertyLayoutLabelPositionVm_updateVariantNotSpecified.java[tags=annotation]
----

The default position itself can be configured globally, in the `application.yml` or `application.properties` configuration file.
This is done using:

* `causeway.applib.annotation.property-layout.label-position` configuration property for properties, and
* `causeway.applib.annotation.parameter-layout.label-position` configuration property for parameters.

