: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 `hidden` element indicates that the property should be hidden in certain contexts.
Most commonly, this is to hide properties in tables (parented, standalone, or both).

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

* there is no equivalent for a  parameter (though parameters can be hidden dynamically using a `hide...()` supporting method)

Because some of the `hidden` variants relate to tables, this view model has a collection of child objects with those child objects annotated to show the relevant options.
There is also an action that returns this same set of child objects as a standalone list.

[NOTE]
====
It is also specify to hide properties using `@PropertyLayout`.
This is to allow the distinction between a property that is hidden as a deep domain concept, compared to a property that is hidden in some circumstances for cosmetic UI reasons.

In the user interface, the effect is the same.
====

== Annotated

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

* for properties, using `@Property#hidden()`:
+
[source,java,indent=0]
----
include::PropertyHiddenVm.java[tags=annotation]
----
<.> explicitly indicate that the property should be visible in all contexts.

Note that there is no equivalent for `@Parameter`.

== Variants

The table below lists the properties of this object, and the context (if any) in which it should be visible.

NOTE: there are other variants, the child object has all possible variants.

.Hidden Variants
[cols="^1m,2m,2a",options=header,frame="all"]
|===
^| Where
^| This object
^| Notes

| NOWHERE
| propertyHiddenNowhereUsingAnnotation
propertyHiddenNowhereUsingLayout
propertyUsingMetaAnnotationButOverridden
| Visible at all times

| EVERYWHERE
| propertyHiddenEverywhere
propertyUsingMetaAnnotation
| Should not be visible at all.

| ANYWHERE
| propertyHiddenAnywhere
| Should not be visible at all +
(synonym for EVERYWHERE)

|===

The source for the `propertyHiddenNowhereUsingAnnotation` property is quoted above; but the other two properties are:

* Everywhere:
+
[source,java,indent=0]
----
include::PropertyHiddenVm.java[tags=variants-everywhere]
----

* Anywhere:
+
[source,java,indent=0]
----
include::PropertyHiddenVm.java[tags=variants-anywhere]
----

Neither of these properties should be visible in the UI.


== Meta-annotated

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

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

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

Neither of these properties should be visible in the UI.

=== Meta-annotated Overridden

The meta-annotation can itself be overridden:

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


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

In both cases, even though the meta-annotation indicates that the property should be hidden everywhere, the override indicates that they should be hidden nowhere.
Both properties should therefore be visible in the UI.

== Children

The `children` collection illustrates the visibility of the child objects' properties when viewed in a collection:

* the `propertyHiddenObjectForms` property is visible as a column in the collection, but won't be visible in the object's page itself

* the `propertyHiddenStandalone` property similarly is visible here, but won't be visible in the standalone list returned by the "returns children" action

* the `propertyHiddenNowhere` property similar is visible here, and will also be visible on the object's page.

The child object has a number of other properties, each using a different `hidden` variant; click through to inspect.
