= @CollectionLayout
: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.

Layout hints for collections.

== API

[source,java]
.CollectionLayout.java
----
@interface CollectionLayout {
  String cssClass() default "";     // <.>
  String defaultView() default "";     // <.>
  String describedAs() default "";     // <.>
  Where hidden() default Where.NOT_SPECIFIED;     // <.>
  String named() default "";     // <.>
  String navigableSubtree() default "";     // <.>
  int paged() default -1;     // <.>
  String sequence() default "";     // <.>
  @SuppressWarnings("rawtypes")
Class<? extends Comparator> sortedBy() default Comparator.class;     // <.>
  Class<? extends TableDecorator> tableDecorator() default TableDecorator.Default.class;     // <.>
}
----

<.> xref:#cssClass[cssClass]
+
--
Indicates the css class that a collection should have, to allow more targeted styling in `application.css` .
--
<.> xref:#defaultView[defaultView]
+
--
Indicates which view is used by default to render the collection.
--
<.> xref:#describedAs[describedAs]
+
--
Description of this collection, eg to be rendered in a tooltip.
--
<.> xref:#hidden[hidden]
+
--
Indicates where in the UI the collection should _not_ not be visible.
--
<.> xref:#named[named]
+
--
Name of this collection (overriding the name derived from its name in code).
--
<.> xref:#navigableSubtree[navigableSubtree]
+
--
When set, identifies logical children, that are navigable via the UI.
--
<.> xref:#paged[paged]
+
--
The page size for instances of this class when rendered within a table.
--
<.> xref:#sequence[sequence]
+
--
The order of this member relative to other members in the same (layout) group, given in _Dewey-decimal_ notation.
--
<.> xref:#sortedBy[sortedBy]
+
--
Indicates that the elements in a ( _java.util.SortedSet_ ) collection should be sorted according to a different order than the natural sort order, as defined by the specified _java.util.Comparator_ .
--
<.> xref:#tableDecorator[tableDecorator]
+
--
Whether a parented collection when represented in a table form should additionally be "decorated" with client-side (javascript) enhancements, for example to enable paging and filtering.
--

== Members

[#cssClass]
=== cssClass

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

[#defaultView]
=== defaultView

Indicates which view is used by default to render the collection.

This is a simple string; every available implementation is required to use a different string.

The default is "table". Extensions provide also: "excel" (download as Excel spreadsheet), "calendar" and "map".

[#describedAs]
=== describedAs

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

[#hidden]
=== hidden

Indicates where in the UI the collection should _not_ not be visible.

[#named]
=== named

Name of this collection (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`.

[#navigableSubtree]
=== navigableSubtree

When set, identifies logical children, that are navigable via the UI.

The order of appearance of this tree branch in the UI relative to other branches of the same tree node, is given in _Dewey-decimal_ notation.

[#paged]
=== paged

The page size for instances of this class when rendered within a table.

If annotated on a collection, then the page size refers to parented collections (eg `Order#lineItems` ).

If annotated on a type, then the page size refers to standalone collections (eg as returned from a repository query).

[#sequence]
=== sequence

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

It specifically governs the slot-in order for the layout group that collects all unreferenced _Collections_ , unless overwritten via application scoped config option that enforced alphabetical order:_causeway.applib.annotation.collectionLayout.sequencePolicyIfUnreferenced_

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

[#sortedBy]
=== sortedBy

Indicates that the elements in a ( _java.util.SortedSet_ ) collection should be sorted according to a different order than the natural sort order, as defined by the specified _java.util.Comparator_ .

Whenever there is a collection of type _java.util.SortedSet_ , the domain entity referenced is expected to implement _Comparable_ , ie to have a natural ordering. In effect this means that all domain entities should provide a natural ordering.

However, in some circumstances the ordering of collection may be different to the entity's natural ordering. For example, the entity may represent an interval of time sorted by its _startDate_ ascending, but the collection may wish to sort by _startDate_ .

The purpose of this annotation is to provide a _java.util.Comparator_ such that the collection may be sorted in an order more suitable to the context.

[#tableDecorator]
=== tableDecorator

Whether a parented collection when represented in a table form should additionally be "decorated" with client-side (javascript) enhancements, for example to enable paging and filtering.

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

include::hooks/CollectionLayout_021-defaultView.adoc[]

include::hooks/CollectionLayout_022-paged.adoc[]

include::hooks/CollectionLayout_023-describedAs.adoc[]

include::hooks/CollectionLayout_024-sortedBy.adoc[]

include::hooks/CollectionLayout_025-cssClass.adoc[]

include::hooks/CollectionLayout_026-named.adoc[]

include::hooks/CollectionLayout_027-hidden.adoc[]
