: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 `renderDay` element applies to date fields, and indicates that the date rendered should be one day before the day actually held in the property.

The typical use case for this is when two date properties together model an interval, namely a "startDate" and an "endDate".

* If these are both inclusive, ie "[startDate, endDate]", then there will be a day "missing" between adjacent intervals.
+
For example, ['Mon 1 Jan', 'Sun 7 Jan'], then ['Mon 8 Jan', 'Sun 14 Jan'], and so on.

* If instead the end date is exclusive, ie "[startDate, endDate)", then adjacent intervals can use the same date for both the end of one interval and the start of the next.
+
For example,  ['Mon 1 Jan', 'Mon 8 Jan'), then ['Mon 8 Jan', 'Mon 15 Jan')`.

This UI hint therefore allows the domain object to use an exclusive end date, thus simplifying business logic, but to be rendered the day before, as if with an inclusive end date.

The element applies to both properties and parameters:

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

The element is supported only for properties and parameters representing dates/times.

// TODO: java.time datatypes not yet supported.

TIP: You can inspect the "raw" data of the domain object, using the "download as XML" action.

== Annotated

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

* for properties, using `@PropertyLayout#renderDay()`:
+
[source,java,indent=0]
----
include::PropertyLayoutRenderDayVm.java[tags=render-as-day-before]
----
<.> explicitly specifies that the property should be rendered as the day before.

* for parameters, using `@ParameterLayout#renderDay()`:
+
[source,java,indent=0]
----
include::PropertyLayoutRenderDayVm_updateEndDateWithParameterLayout.java[tags=annotation]
----
<.> explicitly specifies that the parameter should be rendered as the day before.

== Layout File

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

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

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

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::PropertyLayoutRenderDayVm_mixinEndDateWithPropertyLayout.java[tags=class]
----
<.> explicitly specifies that the contributed property should be rendered as the day before

== Meta-annotated

The `renderDay` element can also be specified using a custom meta-annotation:

* the meta-annotation is defined as:
+
[source,java]
----
include::RenderDayMetaAnnotationEndDateExclusive.java[tags=class]
----
<.> annotated for a property or 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::PropertyLayoutRenderDayVm.java[tags=meta-annotation]
----
<.> hint is inherited from the meta-annotation

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

* or can be applied to mixin:
+
[source,java,indent=0]
----
include::PropertyLayoutRenderDayVm_mixinEndDateWithMetaAnnotation.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::PropertyLayoutRenderDayVm.java[tags=meta-annotation-overridden]
----
<.> hint from meta-annotation (deliberately incorrectly annotated) ...
<.> \... is overridden by the `@PropertyLayout` annotation

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


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

