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


[#related-mixins-and-menus]
== Related Mixins and Menus

The service's functionality is exposed in the UI through a mixin (per object) and a menu action (for all objects):

* the xref:applib-classes:mixees-and-mixins.adoc#java-lang-object[Object] mixin provides the ability to download the XML layout for any domain object (entity or view model).

* the `LayoutServiceMenu` provides the ability to download all XML layouts as a single ZIP file (in any of the three styles).

The XML can then be copied into the codebase of the application, and annotations in the domain classes removed as desired.

=== Styles

Each of these actions take as a parameter an instance of xref:refguide:applib:index/services/layout/Style.adoc[Style].

The `CURRENT` style corresponds to the layout already loaded for the domain class, typically from an already persisted `layout.xml` file.
The other three styles allow the developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained elsewhere, typically from annotations in the metamodel.
The table below summarises the choices:

[cols="<.>,^.>,^.>",options="header"]
.Styles
|===

| Style
| xref:refguide:applib:index/annotation/ActionLayout.adoc#sequence[@ActionLayout#sequence], xref:refguide:applib:index/annotation/PropertyLayout.adoc#sequence[@PropertyLayout#sequence], xref:refguide:applib:index/annotation/CollectionLayout.adoc#sequence[@CollectionLayout#sequence]
| xref:refguide:applib:index/annotation/ActionLayout.adoc#fieldSetId[@ActionLayout#fieldSetId], xref:refguide:applib:index/annotation/PropertyLayout.adoc#fieldSetId[@PropertyLayout#fieldSetId]


|`COMPLETE`
|serialized as XML
|serialized as XML


// TODO: let's remove this, it's too difficult
//|`NORMALIZED`
//|serialized as XML
//|not in the XML


|`MINIMAL`
|not in the XML
|not in the XML

|===

As a developer, you therefore have a choice as to how you provide the metadata required for customised layouts:

* if you want all layout metadata to be read from the `.layout.xml` file, then download the "complete" version, and copy the file alongside the domain class.
+
You can then remove all `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.

//* if you want to use layout XML file to describe the grid (columns, tabs etc) and specify which object members are associated with those regions of the grid, then download the "normalized" version.
//+
//You should then  then remove the `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.

* if you want to use layout XML file ONLY to describe the grid, then download the "minimal" version.
+
The grid regions will be empty in this version, and the framework will use the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations to bind object members to those regions, and to specify their order within those regions.

// TODO: I realize that we don't have any way to associate collections with regions for the "minimal" version.






== See also

The functionality of `LayoutService` is surfaced in the user interface through a related xref:refguide:applib:index/services/layout/LayoutService.adoc#related-mixins-and-menus[mixin and menu action].
See also xref:refguide:applib:index/services/layout/Style.adoc[Style], which determines how much data is included in the downloaded XML.

The xref:refguide:applib:index/services/grid/GridService.adoc[GridService] is responsible for loading and normalizing layout XML for a domain class.
It in turn uses the xref:refguide:applib:index/services/grid/GridLoaderService.adoc[GridLoaderService] and  xref:refguide:applib:index/services/grid/GridSystemService.adoc[GridSystemService]
services.


