You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2020/03/25 00:13:38 UTC
[isis] 01/02: ISIS-2062: menu and object layouts
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2062
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 37ae51f16923ffef2a0d82fd6faa5d8aa38a3b27
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 25 00:07:59 2020 +0000
ISIS-2062: menu and object layouts
in the user guide
---
.../pages/what-is-apache-isis/screencasts.adoc | 6 +-
.../partials/UNUSED/faster-turnaround-times.adoc | 2 +-
.../modules/btb/pages/hints-and-tips.adoc | 1 +
.../btb/pages/hints-and-tips/advanced-layouts.adoc | 69 +++++
api/adoc/userguide/modules/btb/pages/i18n.adoc | 2 +-
.../fun}/images/application-menu/dividers.png | Bin
.../fun}/images/application-menu/layout-menus.pdn | Bin
.../fun}/images/application-menu/layout-menus.png | Bin
.../fun/images/application-menu/tertiary.png | Bin 0 -> 15059 bytes
.../images/layout-dynamic-xml/ToDoAppDashboard.png | Bin
.../fun}/images/layout-dynamic-xml/ToDoItem.png | Bin
.../modules/fun}/images/layouts/customer-order.png | Bin
.../fun}/images/layouts/estatio-Invoice.png | Bin
.../modules/fun}/images/layouts/estatio-Lease.png | Bin
.../fun}/images/layouts/estatio-LeaseItem.png | Bin
.../fun}/images/layouts/todoapp-ToDoItem.png | Bin
.../modules/fun}/images/menubars/010-download.png | Bin
.../modules/fun}/images/menubars/020-download.png | Bin
.../fun}/images/reference-layout/4-0-8-0.png | Bin
.../fun}/images/reference-layout/4-4-4-12.png | Bin
.../fun}/images/reference-layout/6-6-0-12.png | Bin
.../reference-layout/isis-layout-show-facets.css | 0
.../fun}/images/reference-layout/isis-layout.css | 0
.../images/reference-layout/layout-4-0-8-0.html | 0
.../images/reference-layout/layout-4-4-4-12.html | 0
.../images/reference-layout/layout-6-6-0-12.html | 0
api/adoc/userguide/modules/fun/pages/ui.adoc | 28 +-
.../modules/fun/pages/ui/eager-rendering.adoc | 2 +-
.../fun/pages/ui/layout-annotation-based.adoc | 4 +-
.../modules/fun/pages/ui/layout-files.adoc | 13 -
.../modules/fun/pages/ui/menubars-layout.adoc | 166 ++++++++++++
.../modules/fun/pages/ui/object-layout.adoc | 294 ++++-----------------
.../fun/pages/ui/object-titles-and-icons.adoc | 26 +-
.../modules/fun/pages/ui}/table-columns.adoc | 0
.../modules/applib-ant/pages/Action/hidden.adoc | 2 +-
.../modules/applib-ant/pages/ActionLayout.adoc | 2 +-
.../applib-ant/pages/ActionLayout/bookmarking.adoc | 2 +-
.../applib-ant/pages/ActionLayout/cssClass.adoc | 2 +-
.../applib-ant/pages/ActionLayout/cssClassFa.adoc | 2 +-
.../applib-ant/pages/ActionLayout/describedAs.adoc | 2 +-
.../applib-ant/pages/ActionLayout/hidden.adoc | 2 +-
.../applib-ant/pages/ActionLayout/named.adoc | 2 +-
.../applib-ant/pages/ActionLayout/position.adoc | 2 +-
.../applib-ant/pages/ActionLayout/promptStyle.adoc | 2 +-
.../applib-ant/pages/ActionLayout/redirect.adoc | 2 +-
.../applib-ant/pages/Collection/hidden.adoc | 2 +-
.../modules/applib-ant/pages/CollectionLayout.adoc | 2 +-
.../pages/CollectionLayout/cssClass.adoc | 2 +-
.../pages/CollectionLayout/defaultView.adoc | 3 +-
.../pages/CollectionLayout/describedAs.adoc | 2 +-
.../applib-ant/pages/CollectionLayout/hidden.adoc | 2 +-
.../applib-ant/pages/CollectionLayout/named.adoc | 2 +-
.../applib-ant/pages/CollectionLayout/paged.adoc | 2 +-
.../pages/CollectionLayout/sortedBy.adoc | 2 +-
.../applib-ant/pages/DomainObjectLayout.adoc | 2 +-
.../applib-ant/pages/DomainService/nature.adoc | 1 +
.../applib-ant/pages/DomainServiceLayout.adoc | 2 +-
.../pages/DomainServiceLayout/menuBar.adoc | 1 +
.../adoc/modules/applib-ant/pages/HomePage.adoc | 2 +-
.../modules/applib-ant/pages/ParameterLayout.adoc | 2 +-
.../modules/applib-ant/pages/PropertyLayout.adoc | 2 +-
.../applib-ant/pages/PropertyLayout/cssClass.adoc | 2 +-
.../pages/PropertyLayout/describedAs.adoc | 2 +-
.../applib-ant/pages/PropertyLayout/hidden.adoc | 4 +-
.../pages/PropertyLayout/labelPosition.adoc | 2 +-
.../applib-ant/pages/PropertyLayout/multiLine.adoc | 2 +-
.../applib-ant/pages/PropertyLayout/named.adoc | 2 +-
.../pages/PropertyLayout/promptStyle.adoc | 2 +-
.../pages/PropertyLayout/renderedAsDayBefore.adoc | 2 +-
.../pages/PropertyLayout/typicalLength.adoc | 2 +-
.../adoc/modules/applib-ant/pages/about/jee.adoc | 2 +-
.../adoc/modules/applib-ant/pages/about/main.adoc | 4 +-
.../adoc/modules/applib-ant/pages/about/other.adoc | 2 +-
.../applib-cm/pages/classes/mixins/Object.adoc | 31 +--
.../applib-cm/pages/methods/reserved/layout.adoc | 2 +-
.../ROOT/images/application-menu/tertiary.png | Bin 11491 -> 0 bytes
.../pages/customisation/tweaking-css-classes.adoc | 2 +-
viewers/wicket/adoc/modules/ROOT/pages/layout.adoc | 17 --
.../adoc/modules/ROOT/pages/menubars-layout.adoc | 38 ---
.../pages/menubars-layout/annotation-based.adoc | 125 ---------
.../ROOT/pages/menubars-layout/file-based.adoc | 104 --------
.../adoc/modules/ROOT/partials/module-nav.adoc | 1 -
82 files changed, 389 insertions(+), 625 deletions(-)
diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
index 525fc39..343cedd 100644
--- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
+++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
@@ -69,7 +69,7 @@ Walking through the main classes that make up the SimpleApp: `SimpleObject` pers
|link:https://www.youtube.com/watch?v=KCJ1ZPPB3pA[004^] +
-Using the optional `Xxx.layout.xml` file to provide xref:vw:ROOT:layout.adoc#file-based[layout metadata] to dynamically render a domain object using the link:http://getbootstrap.com[Bootstrap 3] grid system.
+Using the optional `Xxx.layout.xml` file to provide xref:userguide:fun:ui.adoc#object-layout[layout metadata] to dynamically render a domain object using the link:http://getbootstrap.com[Bootstrap 3] grid system.
||x|||||||||
@@ -144,7 +144,7 @@ include::screencasts/playlists.adoc[]
|link:https://www.youtube.com/watch?v=dfRZeYqzMtI[012^] +
-Implementing business logic using a (no-arg) action, and associating with a property using either the xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`] annotations or using xref:vw:ROOT:layout.adoc#file-based[dynamic (XML) layouts].
+Implementing business logic using a (no-arg) action, and associating with a property using either the xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`] annotations or using xref:userguide:fun:ui.adoc#object-layout[dynamic (XML) layouts].
|x||||||||x||
@@ -198,7 +198,7 @@ Extending a xref:testing:fixtures:about.adoc[fixture script] to more easily demo
|link:https://www.youtube.com/watch?v=39Hpd7C4Kvo[018^] +
-Using xref:vw:ROOT:layout.adoc#file-based[dynamic (XML) layouts] to specify the page size for a domain object's collection.
+Using xref:userguide:fun:ui.adoc#object-layout[dynamic (XML) layouts] to specify the page size for a domain object's collection.
||||x|||||||
diff --git a/antora/components/setupguide/modules/intellij/partials/UNUSED/faster-turnaround-times.adoc b/antora/components/setupguide/modules/intellij/partials/UNUSED/faster-turnaround-times.adoc
index 19a5d81..756b21f 100644
--- a/antora/components/setupguide/modules/intellij/partials/UNUSED/faster-turnaround-times.adoc
+++ b/antora/components/setupguide/modules/intellij/partials/UNUSED/faster-turnaround-times.adoc
@@ -71,7 +71,7 @@ image::070-advanced/004-gradle-output.png[width="600px",link="{imagesdir}/070-ad
== Using Gradle for liveReload
Similarly, gradle can be run to reduce the turn-around time when tweaking the UI (defined by the
-xref:vw:ROOT:layout.adoc#file-based[`*.layout.xml`] file for each domain class), when the app is running.
+xref:userguide:fun:ui.adoc#object-layout[`*.layout.xml`] file for each domain class), when the app is running.
The framework will automatically notice any changes to `.layout.xml` files, but these are read from the classpath (the `target/classes` directory), not the source path.
With IntelliJ these can be copied over manually by invoking `Run > Reload Changed Classes`.
diff --git a/api/adoc/userguide/modules/btb/pages/hints-and-tips.adoc b/api/adoc/userguide/modules/btb/pages/hints-and-tips.adoc
index 85787f0..c9cbc2a 100644
--- a/api/adoc/userguide/modules/btb/pages/hints-and-tips.adoc
+++ b/api/adoc/userguide/modules/btb/pages/hints-and-tips.adoc
@@ -11,6 +11,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
include::hints-and-tips/are-you-sure.adoc[leveloffset=+1]
+include::hints-and-tips/advanced-layouts.adoc[leveloffset=+1]
include::hints-and-tips/replacing-default-service-implementations.adoc[leveloffset=+1]
include::hints-and-tips/vetoing-visibility.adoc[leveloffset=+1]
include::hints-and-tips/transactions-and-errors.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/btb/pages/hints-and-tips/advanced-layouts.adoc b/api/adoc/userguide/modules/btb/pages/hints-and-tips/advanced-layouts.adoc
new file mode 100644
index 0000000..130f1b3
--- /dev/null
+++ b/api/adoc/userguide/modules/btb/pages/hints-and-tips/advanced-layouts.adoc
@@ -0,0 +1,69 @@
+= Advanced Layouts
+
+: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 ag [...]
+:page-partial:
+
+
+This section describes a number of more features useful in more complex layouts.
+
+== Multiple references to a feature
+
+One feature worth being aware of is that it is possible to render a single feature more than once.
+
+It is also possible to reference object properties and actions more than once.
+This might be useful for a complex domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the most commonly used info), but also on detail tabs.
+
+== Custom CSS
+
+Custom CSS styles can be associated with specific regions of the layout:
+
+[source,xml]
+----
+<grid ...>
+ <row>
+ <col span="2" unreferencedActions="true">
+ <ns2:domainObject/>
+ <row>
+ <col span="12"
+ cssClass="custom-width-100"> <!--.-->
+ <ns2:action id="exportToWordDoc"/>
+ </col>
+ </row>
+ ...
+ </col>
+ <col span="5" unreferencedCollections="true"
+ cssClass="custom-padding-top-20"> <!--.-->
+ ...
+ </col>
+ <col span="5"
+ cssClass="custom-padding-top-20"> <!--.-->
+ ...
+ </col>
+ </row>
+</grid>
+----
+<1> Render the column with the `custom-width-100` CSS class.
+<2> Render the column with the `custom-padding-top-20` CSS class.
+<3> Ditto
+
+For example the `custom-width-100` style is used to "stretch" the button for the `exportToWordDoc` action in the left-most column.
+This is accomplished with the following CSS in `static/css/application.css`:
+
+[source,css]
+----
+.custom-width-100 ul,
+.custom-width-100 ul li,
+.custom-width-100 ul li a.btn {
+ width: 100%;
+}
+----
+
+Similarly, the middle and right columns are rendered using the `custom-padding-top-20` CSS class.
+This shifts them down from the top of the page slightly, using the following CSS:
+
+[source,css]
+----
+.custom-padding-top-20 {
+ padding-top: 20px;
+}
+----
diff --git a/api/adoc/userguide/modules/btb/pages/i18n.adoc b/api/adoc/userguide/modules/btb/pages/i18n.adoc
index 4a73b0e..b93c5e6 100644
--- a/api/adoc/userguide/modules/btb/pages/i18n.adoc
+++ b/api/adoc/userguide/modules/btb/pages/i18n.adoc
@@ -526,7 +526,7 @@ msgid "<i>Quantity</i>"
msgstr "<i>Quantité</i>"
----
-For this to work, the `namedEscaped` attribute must be specified using either the xref:vw:ROOT:layout.adoc#file-based[layout file], or using an annotation such as xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`] or xref:refguide:applib-ant:ParameterLayout.adoc[`@ParameterLayout`].
+For this to work, the `namedEscaped` attribute must be specified using either the xref:userguide:fun:ui.adoc#object-layout[layout file], or using an annotation such as xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`] or xref:refguide:applib-ant:ParameterLayout.adoc[`@ParameterLayout`].
For example:
diff --git a/viewers/wicket/adoc/modules/ROOT/images/application-menu/dividers.png b/api/adoc/userguide/modules/fun/images/application-menu/dividers.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/application-menu/dividers.png
rename to api/adoc/userguide/modules/fun/images/application-menu/dividers.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/application-menu/layout-menus.pdn b/api/adoc/userguide/modules/fun/images/application-menu/layout-menus.pdn
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/application-menu/layout-menus.pdn
rename to api/adoc/userguide/modules/fun/images/application-menu/layout-menus.pdn
diff --git a/viewers/wicket/adoc/modules/ROOT/images/application-menu/layout-menus.png b/api/adoc/userguide/modules/fun/images/application-menu/layout-menus.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/application-menu/layout-menus.png
rename to api/adoc/userguide/modules/fun/images/application-menu/layout-menus.png
diff --git a/api/adoc/userguide/modules/fun/images/application-menu/tertiary.png b/api/adoc/userguide/modules/fun/images/application-menu/tertiary.png
new file mode 100644
index 0000000..059992d
Binary files /dev/null and b/api/adoc/userguide/modules/fun/images/application-menu/tertiary.png differ
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layout-dynamic-xml/ToDoAppDashboard.png b/api/adoc/userguide/modules/fun/images/layout-dynamic-xml/ToDoAppDashboard.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layout-dynamic-xml/ToDoAppDashboard.png
rename to api/adoc/userguide/modules/fun/images/layout-dynamic-xml/ToDoAppDashboard.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layout-dynamic-xml/ToDoItem.png b/api/adoc/userguide/modules/fun/images/layout-dynamic-xml/ToDoItem.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layout-dynamic-xml/ToDoItem.png
rename to api/adoc/userguide/modules/fun/images/layout-dynamic-xml/ToDoItem.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layouts/customer-order.png b/api/adoc/userguide/modules/fun/images/layouts/customer-order.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layouts/customer-order.png
rename to api/adoc/userguide/modules/fun/images/layouts/customer-order.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-Invoice.png b/api/adoc/userguide/modules/fun/images/layouts/estatio-Invoice.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-Invoice.png
rename to api/adoc/userguide/modules/fun/images/layouts/estatio-Invoice.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-Lease.png b/api/adoc/userguide/modules/fun/images/layouts/estatio-Lease.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-Lease.png
rename to api/adoc/userguide/modules/fun/images/layouts/estatio-Lease.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-LeaseItem.png b/api/adoc/userguide/modules/fun/images/layouts/estatio-LeaseItem.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layouts/estatio-LeaseItem.png
rename to api/adoc/userguide/modules/fun/images/layouts/estatio-LeaseItem.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/layouts/todoapp-ToDoItem.png b/api/adoc/userguide/modules/fun/images/layouts/todoapp-ToDoItem.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/layouts/todoapp-ToDoItem.png
rename to api/adoc/userguide/modules/fun/images/layouts/todoapp-ToDoItem.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/menubars/010-download.png b/api/adoc/userguide/modules/fun/images/menubars/010-download.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/menubars/010-download.png
rename to api/adoc/userguide/modules/fun/images/menubars/010-download.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/menubars/020-download.png b/api/adoc/userguide/modules/fun/images/menubars/020-download.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/menubars/020-download.png
rename to api/adoc/userguide/modules/fun/images/menubars/020-download.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/4-0-8-0.png b/api/adoc/userguide/modules/fun/images/reference-layout/4-0-8-0.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/4-0-8-0.png
rename to api/adoc/userguide/modules/fun/images/reference-layout/4-0-8-0.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/4-4-4-12.png b/api/adoc/userguide/modules/fun/images/reference-layout/4-4-4-12.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/4-4-4-12.png
rename to api/adoc/userguide/modules/fun/images/reference-layout/4-4-4-12.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/6-6-0-12.png b/api/adoc/userguide/modules/fun/images/reference-layout/6-6-0-12.png
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/6-6-0-12.png
rename to api/adoc/userguide/modules/fun/images/reference-layout/6-6-0-12.png
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/isis-layout-show-facets.css b/api/adoc/userguide/modules/fun/images/reference-layout/isis-layout-show-facets.css
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/isis-layout-show-facets.css
rename to api/adoc/userguide/modules/fun/images/reference-layout/isis-layout-show-facets.css
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/isis-layout.css b/api/adoc/userguide/modules/fun/images/reference-layout/isis-layout.css
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/isis-layout.css
rename to api/adoc/userguide/modules/fun/images/reference-layout/isis-layout.css
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-4-0-8-0.html b/api/adoc/userguide/modules/fun/images/reference-layout/layout-4-0-8-0.html
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-4-0-8-0.html
rename to api/adoc/userguide/modules/fun/images/reference-layout/layout-4-0-8-0.html
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-4-4-4-12.html b/api/adoc/userguide/modules/fun/images/reference-layout/layout-4-4-4-12.html
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-4-4-4-12.html
rename to api/adoc/userguide/modules/fun/images/reference-layout/layout-4-4-4-12.html
diff --git a/viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-6-6-0-12.html b/api/adoc/userguide/modules/fun/images/reference-layout/layout-6-6-0-12.html
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/images/reference-layout/layout-6-6-0-12.html
rename to api/adoc/userguide/modules/fun/images/reference-layout/layout-6-6-0-12.html
diff --git a/api/adoc/userguide/modules/fun/pages/ui.adoc b/api/adoc/userguide/modules/fun/pages/ui.adoc
index fbdf0f0..f99d2b9 100644
--- a/api/adoc/userguide/modules/fun/pages/ui.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui.adoc
@@ -1,23 +1,39 @@
-= UI Hints
+[#ui-layout-hints]
+= UI Layout & Hints
: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 ag [...]
:page-partial:
+In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis infers as much information from the domain classes as possible.
+Nevertheless, some metadata relating solely to the UI is inevitably required.
+
The Apache Isis programming model includes several mechanisms to influence the way in which the domain objects are rendered in the UI.
+r
+* the layout of application menu items
+
+* layout files allow the positioning of the xref:object-members.adoc[object members] into columns and tabs.
-* xref:#layout-files[layout files] allow the positioning of the xref:object-members.adoc[object members] into columns and tabs.
+* UI hints provided by the domain object itself returning:
-* UI hints allow the xref:#object-title[title] -- so an end-user can distinguish one object from another -- and xref:#object-icon[icon], as well as CSS styling to be influenced.
-These can be set at the domain object level, and at member level also.
+** the title so the end-user can distinguish one object from another
+** an icon to indicate the type of object (and perhaps its state)
+** CSS styles for additional adhoc styling
+** an alternate layout, for example changed according to the roles of the end-user that is viewing it.
-* it's also possible for the domain object to select different xref:#switching-layouts[layouts], for example according to the end-user that is viewing it.
+* in collections, how to customise which properties appear
This chapter discusses these topics.
-include::ui/layout-files.adoc[leveloffset=+1]
+include::ui/menubars-layout.adoc[leveloffset=+1]
+
+include::ui/object-layout.adoc[leveloffset=+1]
+include::ui/layout-annotation-based.adoc[leveloffset=+1]
+
include::ui/object-titles-and-icons.adoc[leveloffset=+1]
include::ui/action-icons-and-css.adoc[leveloffset=+1]
include::ui/names-and-descriptions.adoc[leveloffset=+1]
include::ui/eager-rendering.adoc[leveloffset=+1]
+
+include::ui/table-columns.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/fun/pages/ui/eager-rendering.adoc b/api/adoc/userguide/modules/fun/pages/ui/eager-rendering.adoc
index 13f4809..3e6d3ec 100644
--- a/api/adoc/userguide/modules/fun/pages/ui/eager-rendering.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui/eager-rendering.adoc
@@ -9,7 +9,7 @@ For the more commonly used collections though, we'll probably want to show the t
image::programming-model/todoapp-Dashboard.png[width="800px",link="{imagesdir}/programming-model/todoapp-Dashboard.png"]
-For this we annotate the collection using xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`@CollectionLayout#defaultView`]; for example
+For this we annotate the collection using xref:refguide:applib-ant:CollectionLayout.adoc#defaultview[`@CollectionLayout#defaultView`]; for example
[source,java]
----
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/annotation-based.adoc b/api/adoc/userguide/modules/fun/pages/ui/layout-annotation-based.adoc
similarity index 98%
rename from viewers/wicket/adoc/modules/ROOT/pages/layout/annotation-based.adoc
rename to api/adoc/userguide/modules/fun/pages/ui/layout-annotation-based.adoc
index 60ad192..cb97250 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout/annotation-based.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui/layout-annotation-based.adoc
@@ -4,7 +4,7 @@
: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 ag [...]
-Metadata providing UI hints can be specified either using annotations, or using a xref:vw:ROOT:layout.adoc#file-based[`layout.xml`] file.
+Metadata providing UI hints can be specified either using annotations, or using a xref:userguide:fun:ui.adoc#object-layout[`layout.xml`] file.
In most cases you will probably want to use the file-based approach: changes to file layouts are picked up dynamically, and using a file also allows tabs and tab groups to be specified: this is not supported using annotations.
@@ -112,7 +112,7 @@ The property groups/fieldsets in this case are those that are inferred from the
[TIP]
====
-It is also possible to combine `@MemberOrder` with a xref:vw:ROOT:layout.adoc#file-based[file-based layout].
+It is also possible to combine `@MemberOrder` with a xref:userguide:fun:ui.adoc#object-layout[file-based layout].
The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions.
The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid.
diff --git a/api/adoc/userguide/modules/fun/pages/ui/layout-files.adoc b/api/adoc/userguide/modules/fun/pages/ui/layout-files.adoc
deleted file mode 100644
index 2a80dcb..0000000
--- a/api/adoc/userguide/modules/fun/pages/ui/layout-files.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[#layout-files]
-= Layout Files
-
-: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 ag [...]
-:page-partial:
-
-The most significant aspect of the UI is the layout of the object's members: its properties, collections and actions.
-These can be organized into columns, rows and tabs.
-
-This can be accomplished using either annotations or through a separate file-based layout.
-Since this is a large topic, it has its own xref:vw:ROOT:layout.adoc[layout chapter] in the Wicket viewer guide.
-
-WARNING: TODO: v2 - move this material here, since it applies to any viewer, not just the Wicket viewer.
diff --git a/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc b/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc
new file mode 100644
index 0000000..2e8ebcd
--- /dev/null
+++ b/api/adoc/userguide/modules/fun/pages/ui/menubars-layout.adoc
@@ -0,0 +1,166 @@
+[#menu-bars-layout]
+= Menu Bars Layout
+
+: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 ag [...]
+
+
+The actions of domain services (annotated using xref:refguide:applib-ant:DomainService.adoc#nature[`@DomainService#nature()`] with a nature of `VIEW`) are made available as menu items on menus.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.VIEW, // <.>
+ objectType = "simple.SimpleObjects"
+ )
+public class SimpleObjects {
+ // ...
+}
+----
+<.> Domain service with actions visible in the UI
+
+By default each domain service corresponds to a single menu on this menu bar, with its actions as the drop-down menu items.
+
+By annotating the domain service class and its actions, it's possible to have a little more control over the placement of the menu items; this is discussed xref:#annotation-based-menus[below].
+
+For more fine-grained control, though, the `menubars.layout.xml` file can be supplied, as discussed xref:#file-based-menus[after].
+This file is also read dynamically at runtime, so layouts can be changed during prototyping and the page reloaded to check.
+
+
+
+[[annotation-based-menus]]
+== Annotation-based
+
+If using annotations, services can be added to either the primary, secondary or tertiary menu bar, as shown in this screenshot shows:
+
+image::application-menu/layout-menus.png[width="800px",link="{imagesdir}/application-menu/layout-menus.png"]
+
+This is done using the xref:refguide:applib-ant:DomainServiceLayout.adoc#menubar[`@DomainServiceLayout#menuBar()`] annotation.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.VIEW, // <.>
+ objectType = "simple.SimpleObjects"
+ )
+@DomainServiceLayout(menuBar = DomainServiceLayout.MenuBar.PRIMARY) // <.>
+public class SimpleObjects {
+ // ...
+}
+----
+<.> Domain service with actions visible in the UI
+<.> Menu for the service added to the primary menu bar.
+
+The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right.
+This is intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
+
+image::application-menu/tertiary.png[width="300px",link="{imagesdir}/application-menu/tertiary.png"]
+
+
+
+In addition, the xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`] annotation can be used to group and order domain service actions:
+
+* `@MemberOrder#name()` is used to define the name of the menu
++
+in which the menu items of the domain service action will appear
+
+* `@MemberOrder#sequence()` is used to order menu items within that menu.
+
+Thus, using `name()` it's possible to group menu items from actions that are from different domain services.
+
+There are some significant limitations, however:
+
+* domain services are added to the menu bar alphabetically.
+This cannot be controlled using annotations.
+* there is no way to order or group menu items from multiple domain services that appear on the same menu.
+
+The annotation based approach is therefore useful during very early prototyping, but in real-world applications you should use xref:ui.adoc#file-based-menus[file based] menu layouts.
+
+
+[[file-based-menus]]
+== `menubars.layout.xml`
+
+Rather than use annotations to specify the location of menu items corresponding to the domain services' actions, the framework instead allow domain service actions to be arranged using the `menubars.layout.xml` file.
+
+This offers a number of benefits:
+
+* Probably most significantly, the layout can be updated without requiring a recompile of the code and redeploy of the app; fine-tuning the layout with your end users is easy to do
+
+* You'll probably find it easier to reason about menu bars layout when all the hints are collated together in a single place (rather than scattered across the domain service classes as annotations).
+
+There are some disadvantages to using file-based layouts:
+
+* file-based layouts are not typesafe: a typo will result in the metadata not being picked up for the element.
+
+* they also suffer from syntactic fragility: an invalid XML document could result in no metadata for the entire class.
+
+The `menubars.layout.xml` file is just the serialized form of a xref:refguide:applib-cm:classes/layout.adoc[`MenuBars`] layout class defined within Apache Isis' applib.
+These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that
+is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making it easy to author such layout files.
+
+
+
+For example, here's a fragment of that provided by the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<mb3:menuBars
+ xsi:schemaLocation="..."
+ xmlns:cpt="http://isis.apache.org/applib/layout/component"
+ xmlns:lnk="http://isis.apache.org/applib/layout/links"
+ xmlns:mb3="http://isis.apache.org/applib/layout/menubars/bootstrap3"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <mb3:primary>
+ <mb3:menu>
+ <mb3:named>Simple Objects</mb3:named>
+ <mb3:section>
+ <mb3:serviceAction objectType="simple.SimpleObjects" id="create">
+ <cpt:named>Create</cpt:named>
+ </mb3:serviceAction>
+ <mb3:serviceAction objectType="simple.SimpleObjects" id="findByName">
+ <cpt:named>Find By Name</cpt:named>
+ </mb3:serviceAction>
+ <mb3:serviceAction objectType="simple.SimpleObjects" id="listAll">
+ <cpt:named>List All</cpt:named>
+ </mb3:serviceAction>
+ </mb3:section>
+ </mb3:menu>
+ <mb3:menu unreferencedActions="true">
+ <mb3:named>Other</mb3:named>
+ </mb3:menu>
+ </mb3:primary>
+ <mb3:secondary>
+ <mb3:menu>
+ <mb3:named>Prototyping</mb3:named>
+ ...
+ </mb3:secondary>
+ <mb3:tertiary>
+ <mb3:menu>
+ ...
+ </mb3:menu>
+ </mb3:tertiary>
+</mb3:menuBars>
+----
+
+Note the "Other" menu, with `unreferencedActions` attribute set to `true`.
+For a layout file to be valid there must be exactly one `<menu>` with this attribute set.
+Any domain service actions that are not explicitly listed will be placed under this menu.
+
+
+The downloaded `menubars.layout.xml` file can be adjusted as necessary, creating new menus and menu sections.
+Once done, it can be saved and the project rebuilt in the IDE.
+If running in prototype mode, the file will be dynamically reloaded from the classpath.
+
+Once the application has bootstrapped with a layout file, downloading the "Default" layout (from the prototyping menu) in essence just returns this file.
+
+=== Downloading the layout file
+
+The current `menubars.layout.xml` can be downloaded from the xref:refguide:applib-svc:MenuBarsService.adoc[`MenuBarsService`] (exposed on the prototyping menu):
+
+image::menubars/010-download.png[width="300px",link="{imagesdir}/menubars/010-download.png"]
+
+If there are unknown/unreferenced actions in the "Other" menu (which you would like to place elsewhere), then these will be listed in the downloaded layout, so they can easily be moved elsewhere.
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc b/api/adoc/userguide/modules/fun/pages/ui/object-layout.adoc
similarity index 51%
rename from viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
rename to api/adoc/userguide/modules/fun/pages/ui/object-layout.adoc
index 8e3e885..7c9324f 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui/object-layout.adoc
@@ -1,11 +1,10 @@
-[[file-based]]
-= File-based Layouts
+[[object-layout]]
+= Object Layout
: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 ag [...]
-
-Metadata providing UI hints can be specified either xref:vw:ROOT:layout.adoc#annotation-based[using annotations], or using an `Xxx.layout.xml` file (where `Xxx` is the entity or view model object to be rendered).
+As with menubars, although the layout of objects can be specified using just annotations, in real-world applications you will almost certainly use a companion layout file, `Xxx.layout.xml` (where `Xxx` is the entity or view model to be rendered).
File-based layouts offer a number of benefits:
@@ -21,71 +20,34 @@ There are some downsides, though:
* file-based layouts are not typesafe: a typo will result in the metadata not being picked up for the element.
-* they suffer from syntactic fragility: an invalid XML document will result in no metadata for the entire class.
+* they suffer from syntactic fragility: an invalid XML document could result in no metadata for the entire class.
* there is no notion of inheritance, so a `.layout.xml` is required for all concrete classes and also for any abstract classes (if used as a collection type).
-In contrast, the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
The `Xxx.layout.xml` file is just the serialized form of a xref:refguide:applib-cm:classes/layout.adoc[`Grid`] layout class defined within Apache Isis' applib.
These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making iteasy to author such layout files.
-
-== Alternative Layouts
-
-A domain object may also have multiple layouts.
-For example, there may be the capability to switch into an "edit" mode, which perhaps hides some class members, shows others (perhaps mixins specific to data entry).
-Another reason might be to support different tenancies/user groups, where different business processes might require a slightly different UI representation.
-
-One way in which the domain object can specify an alternate layout is through its xref:refguide:applib-cm:methods.adoc#layout[`layout()`] method.
-If this returns a non-null value, say "edit", then this is used to locate an alternative layout, in the form `Xxx-edit.layout.xml`.
-
-
-== Search Algorithm (Library Support)
-
-For a given domain object `Xxx`, if it has specified a layout `yyy`, then the framework will search for a file `Xxx.yyy.layout.xml` on the classpath.
-
-If no layout has been specified (or if the specified layout cannot be found), then the framework searches for a file called `Xxx.layout.xml`.
-
-Finally, if this can't be found, then the framework will search for a file named `Xxx.layout.fallback.xml`.
-If present, this will be used instead.
-
-The "fallback" layout therefore allows libraries that provide domain objects (for example, the (non-ASF) link:https://platform.incode.org[Incode Platform] modules) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires.
-
-
-
-
== Grids vs Components
The layout file distinguishes between two types of element:
* those that define a grid structure, of: rows, columns, tab groups and tabs. +
-+
-The rows and columns are closely modelled on link:http://getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:vw:ROOT:about.adoc[Wicket viewer]).
++ The rows and columns are closely modelled on link:http://getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:vw:ROOT:about.adoc[Wicket viewer]).
* those that define common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
-More information about these classes can be found in xref:refguide:applib-cm:classes/layout.adoc[the reference guide]. More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].
-
-
-
-== Screencast
+More information about these classes can be found in xref:refguide:applib-cm:classes/layout.adoc[the reference guide].
+More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].
-This link:https://www.youtube.com/watch?v=MxewC5Pve5k[screencast] describes the feature.
+== By Example
-
-
-
-== Examples
-
-Probably the easiest way to understand dynamic XML layouts is by example.
-For this we'll use the `ToDoItem` from the http://github.com/apache/isis-app-todoapp[TodoApp]:
+Probably the easiest way to understand dynamic XML layouts is by example, in this case of a "todo item":
image::layout-dynamic-xml/ToDoItem.png[width="940px",link="{imagesdir}/layout-dynamic-xml/ToDoItem.png"]
-
=== Namespaces
-First things first; every `.layout.xml` file must properly declare the XSD namespaces and schemas.
+Every `.layout.xml` file must properly declare the XSD namespaces and schemas.
There are two: one for the grid classes, and one for the common component classes:
[source,xml]
@@ -103,9 +65,7 @@ There are two: one for the grid classes, and one for the common component classe
</bs3:grid>
----
-Most IDEs will automatically download the XSD schemas from the specified schema locations, thereby providing
-"intellisense" help as you edit the file.
-
+Most IDEs will automatically download the XSD schemas from the specified schema locations, thereby providing "intellisense" help as you edit the file.
=== Rows, full-width cols, and tabs
@@ -141,11 +101,8 @@ This corresponds to the following XML:
</bs3:row>
----
-
You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute.
-This topic is discussed in more detail xref:vw:ROOT:layout/file-based/adoc#unreferenced[below].
-
-
+This topic is discussed in more detail xref:#unreferenced-members[below].
=== Fieldsets
@@ -189,7 +146,8 @@ Notice how actions - such as `duplicate` and `delete` - can be associated with t
Thereafter the fieldset lists the properties in order.
Actions can be associated with properties too; here they are rendered underneath or to the right of the field.
-Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:vw:ROOT:layout/file-based.adoc#unreferenced[below].
+Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:#unreferenced-members[below].
+
[NOTE]
====
@@ -199,11 +157,10 @@ If omitted, then the title panel is suppressed, freeing more real estate.
Do be aware though that if there are any actions that have been placed on the fieldset's panel, then these _will *not* be displayed_.
====
-
-
=== Collections
-In the final row the collections are placed in tabs, simply one collection per tab. This corresponds to the following XML:
+In the final row the collections are placed in tabs, simply one collection per tab.
+This corresponds to the following XML:
[source,xml]
----
@@ -228,20 +185,19 @@ In the final row the collections are placed in tabs, simply one collection per t
As with properties, actions can be associated with collections; this indicates that they should be rendered in the collection's header.
-
-
+[#unreferenced-members]
== Unreferenced Members
As noted in the preceding discussion, several of the grid's regions have either an ``unreferencedActions``, ``unreferencedCollections`` or ``unreferencedProperties`` attribute.
The rules are:
-* `unreferencedActions` attribute can be specified either on a column or on a fieldset. +
+* `unreferencedActions` attribute can be specified either on a column or on a fieldset.
+
It would normally be typical to use the column holding the `<domainObject/>` icon/title, that is as shown in the example.
The unreferenced actions then appear as top-level actions for the domain object.
-* `unreferencedCollections` attribute can be specified either on a column or on a tabgroup. +
+* `unreferencedCollections` attribute can be specified either on a column or on a tabgroup.
+
If specified on a column, then that column will contain each of the unreferenced collections, stacked one on top of the other.
If specified on a tab group, then a separate tab will be created for each collection, with that tab containing only that single collection.
@@ -252,214 +208,66 @@ The purpose of these attributes is to indicate where in the layout any unreferen
Every grid _must_ nominate one region for each of these three member types, the reason being that to ensure that the layout can be used even if it is incomplete with respect to the object members inferred from the Java source code.
This might be because the developer forgot to update the layout, or it might be because of a new mixin (property, collection or action) contributed to many objects.
-
The framework ensures that in any given grid exactly one region is specified for each of the three `unreferenced...` attributes.
-If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged. The layout XML will then be ignored.
-
-
-
-== More advanced features
-
-This section decribes a number of more features useful in more complex layouts.
-
-
-=== Multiple references to a feature
-
-One feature worth being aware of is that it is possible to render a single feature more than once.
-
-For example, the dashboard home page for the http://github.com/apache/isis-app-todoapp[TodoApp] shows
-the "not yet complete" collection of todo items twice, once as a table and also as a calendar:
-
-image::layout-dynamic-xml/TodoAppDashboard.png[width="940px",link="{imagesdir}/layout-dynamic-xml/TodoAppDashboard.png"]
-
-
-This is accomplished using the following (slightly abbreviated) layout:
-
-[source,xml]
-----
-<grid ...>
- <row>
- <col span="2" unreferencedActions="true">
- ...
- </col>
- <col span="5" unreferencedCollections="true" cssClass="custom-padding-top-20">
- <ns2:collection id="notYetComplete" defaultView="calendar"/> <!--1-->
- </col>
- <col span="5" cssClass="custom-padding-top-20">
- <ns2:collection id="notYetComplete" defaultView="table" paged="5"/> <!--2-->
- <ns2:collection id="complete" defaultView="table"/>
- </col>
- <col span="0">
- <ns2:fieldSet name="General" id="general" unreferencedProperties="true"/>
- </col>
- </row>
-</grid>
-----
-<1> render the collection in "calendar" view
-<2> also render the collection in "table" view
-
-In the middle column the `notYetComplete` collection is rendered in "calendar" view, while in the right-most column it is rendered in "table" view.
-
-
-It is also possible to reference object properties and actions more than once.
-This might be useful for a complex domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the most commonly used info), but also on detail tabs.
+If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged.
+The layout XML will then be ignored.
+== Combining with Annotations
-=== Custom CSS
+Rather than specify every UI semantic in the layout file, you can optionally combine with a number of annotations.
+The idea is that the layout.xml is used primarily for the coarse-grained grid layout, with annotations used for the stuff that changes less often, such as associating actions with properties or collections, or the order of properties or actions within a fieldset.
-The TodoApp's dashboard (above) also shows how custom CSS styles can be associated with specific regions of the layout:
+The annotations most relevant here is xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`]:
-[source,xml]
-----
-<grid ...>
- <row>
- <col span="2" unreferencedActions="true">
- <ns2:domainObject/>
- <row>
- <col span="12" cssClass="custom-width-100"> <!--1-->
- <ns2:action id="exportToWordDoc"/>
- </col>
- </row>
- ...
- </col>
- <col span="5" unreferencedCollections="true" cssClass="custom-padding-top-20"> <!--2-->
- ...
- </col>
- <col span="5" cssClass="custom-padding-top-20"> <!--3-->
- ...
- </col>
- </row>
-</grid>
-----
-<1> Render the column with the `custom-width-100` CSS class.
-<2> Render the column with the `custom-padding-top-20` CSS class.
-<3> Ditto
+* for properties:
-For example the `custom-width-100` style is used to "stretch" the button for the `exportToWordDoc` action in the left-most column.
-This is accomplished with the following CSS in `application.css`:
+** `@MemberOrder#name()` can be used to identify associate a property with a fieldset.
++
+With this approach all of the fieldsets in the `layout.xml` file are left empty.
+The properties "slot into" the relevant field set to associate = "...", sequence = "...")`.
-[source,css]
-----
-.custom-width-100 ul,
-.custom-width-100 ul li,
-.custom-width-100 ul li a.btn {
- width: 100%;
-}
-----
+** `@MemberOrder#sequence()` specifies the order of properties within their fieldset
-Similarly, the middle and right columns are rendered using the `custom-padding-top-20` CSS class. This shifts them down
-from the top of the page slightly, using the following CSS:
+* for actions:
-[source,css]
-----
-.custom-padding-top-20 {
- padding-top: 20px;
-}
-----
+** `@MemberOrder#name()` is used to associate an action with a property.
++
+The `@Action#associateWith()` annotation can be used instead as a direct replacement that "reads" better.
+** `@MemberOrder#sequence()` specifies the order of actions (if there are multiple actions for a property)
++
+The `@Action#associateWithSequence()` annotation can be used as a direct replacement.
+There are a number of other "layout" annotations, specifically xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`], xref:refguide:applib-ant:CollectionLayout.adoc[`@CollectionLayout`] and xref:refguide:applib-ant:ActionLayout.adoc[`@ActionLayout`].
+All of the semantics in these layout annotations can also be specified in the `.layout.xml` files; which is used is a matter of taste.
+In addition, xref:refguide:applib-ant:ParameterLayout.adoc[`@ParameterLayout`] provides layout hints for action parameters.
+There is no way to specify these semantics in the `.layout.xml` file (action parameters are not enumerated in the file).
-== Migrating from earlier versions
+=== Layout file styles
-As noted earlier on, it is possible to download layout XML files using the xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models.
-Alternatively the layout XML for a single domain object can be downloaded using the xref:refguide:applib-cm:classes/mixins.adoc#Object[mixin action] (contributed to every domain object).
+If you want to make your usage of layout files consistent, then the framework can help because it allows the layout XML files to be downloaded using the xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`].
+This is exposed on the prototyping menu to allow you to download a ZIP file of layout XML files for all domain entities and view models.
-There are four "styles":
+When downloading the layout files, there are four "styles" available:
* current
* complete
* normalized
* minimal
-
Ignoring the "current" style (which merely downloads the currently cached layout), 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 from annotations in the metamodel.
-The table below summarises the choices:
-
-.Table caption
-[cols="<.>,^.>,^.>,^.>", options="header"]
-|===
-
-| Style
-|xref:refguide:applib-ant:MemberGroupLayout.adoc[`@MemberGroupLayout`]
-| xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`]
-| xref:refguide:applib-ant:ActionLayout.adoc[`@ActionLayout`], xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`], xref:refguide:applib-ant:CollectionLayout.adoc[`@CollectionLayout`]
-
-
-|`COMPLETE`
-|serialized as XML
-|serialized as XML
-|serialized as XML
-
-|`NORMALIZED`
-|serialized as XML
-|serialized as XML
-|not in the XML
-
-
-|`MINIMAL`
-|serialized as XML
-|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:
+As a developer, you can therefore select the layout file which maps to your preferred usage:
* 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 `@MemberGroupLayout`, `@MemberOrder`, `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.
+You can then remove all `@MemberOrder`, `@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 can then remove the `@MemberGroupLayout` and `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.
+You can then remove the `@MemberOrder` and `@Action#associateWith` 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 `@MemberOrder` annotation to bind object members to those regions.
-The only annotation that can be safely removed from the source code with this style is the `@MemberGroupLayout` annotation.
-
-
-Download either for a single domain object, or download all domain objects (entities and view models).
-
-
-== Domain Services
-
-For more information about layouts, see:
-
-* xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] (whose functionality is exposed on the prototyping menu as an action) and lso the a xref:refguide:applib-cm:classes/mixins.adoc#Object[mixin action]
-
-* xref:refguide:applib-svc:GridService.adoc[`GridService`] and its supporting services, xref:refguide:applib-svc:GridLoaderService.adoc[`GridLoaderService`] and xref:refguide:applib-svc:GridSystemService.adoc[`GridSystemService`]
-
-* xref:refguide:applib-cm:classes/layout.adoc[grid layout classes], defined in the Apache Isis applib
-
-
-
-
-== Required updates to the dom project's pom.xml
-
-Any `.layout.xml` files must be compiled and available in the classpath.
-Ensure the following is defined in the dom project's `pom.xml`:
-
-[source.xml]
-----
-<resources>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/resources</directory>
- </resource>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </resource>
-</resources>
-----
-
-If using an Apache Isis xref:docs:starters:helloworld.adoc[HelloWorld] xref:docs:starters:simpleapp.adoc[SimpleApp] starter app, then the POM is already correctly configured.
-
+The grid regions will be empty in this version, and the framework will use the `@MemberOrder` and `@Action#associateWith` annotations to bind object members to those regions.
+If you want to adjust the layout XML for a single domain object, then you can use the xref:refguide:applib-cm:classes/mixins.adoc#downloadlayoutxml[mixin action] (contributed to every domain object).
diff --git a/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc b/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc
index 49564b1..63e0c1a 100644
--- a/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui/object-titles-and-icons.adoc
@@ -176,7 +176,7 @@ If there is no requirement to customize the icon (the normal case), then the ico
For example, the icon for a class `org.mydomain.myapp.Customer` will be `org/mydomain/myapp/Customer.png` (if it exists).
Alternatively, a font-awesome icon can be used.
-This is specified using the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute or in the xref:vw:ROOT:layout.adoc#file-based[layout.xml] file.
+This is specified using the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file.
For example:
@@ -261,7 +261,7 @@ In conjunction with xref:vw:ROOT:customisation.adoc#tweaking-css-classes[customi
=== Declarative style
To render an object with a particular CSS, use
-xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[`@DomainObjectLayout#cssClass()`] or in the xref:vw:ROOT:layout.adoc#file-based[layout.xml] file.
+xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[`@DomainObjectLayout#cssClass()`] or in the xref:userguide:fun:ui.adoc#object-layout[layout.xml] file.
When the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`.
Or, when the domain object is rendered as a row in a collection, then the CSS class will appear in a `<div>` wrapped by the `<tr>` of the row.
@@ -291,7 +291,7 @@ If non-null value is returned then the CSS class will be rendered _in addition_
As for title and icon, the determination of which CSS class to render can be externalized into a UI event subscriber.
-In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attribute to specify.
+In the target object, we define an appropriate event type and use the xref:refguide:applib-ant:DomainObjectLayout.adoc#cssclassuievent[`@DomainObjectLayout#cssClassUiEvent()`] attribute to specify.
For example
@@ -334,3 +334,23 @@ public class OrderSubscriptions {
WARNING: TODO: v2
+A domain object may also have multiple layouts.
+For example, there may be the capability to switch into an "edit" mode, which perhaps hides some class members, shows others (perhaps mixins specific to data entry).
+Another reason might be to support different tenancies/user groups, where different business processes might require a slightly different UI representation.
+
+One way in which the domain object can specify an alternate layout is through its xref:refguide:applib-cm:methods.adoc#layout[`layout()`] method.
+If this returns a non-null value, say "edit", then this is used to locate an alternative layout, in the form `Xxx-edit.layout.xml`.
+
+
+=== Search Algorithm (Library Support)
+
+For a given domain object `Xxx`, if it has specified a layout `yyy`, then the framework will search for a file `Xxx.yyy.layout.xml` on the classpath.
+
+If no layout has been specified (or if the specified layout cannot be found), then the framework searches for a file called `Xxx.layout.xml`.
+
+Finally, if this can't be found, then the framework will search for a file named `Xxx.layout.fallback.xml`.
+If present, this will be used instead.
+
+The "fallback" layout therefore allows libraries that provide domain objects (for example, the (non-ASF) link:https://platform.incode.org[Incode Platform] modules) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires.
+
+
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/table-columns.adoc b/api/adoc/userguide/modules/fun/pages/ui/table-columns.adoc
similarity index 100%
rename from viewers/wicket/adoc/modules/ROOT/pages/layout/table-columns.adoc
rename to api/adoc/userguide/modules/fun/pages/ui/table-columns.adoc
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
index d32bae3..4922a02 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
@@ -11,7 +11,7 @@ Actions can be hidden at the domain-level, indicating that they are not visible
[TIP]
====
-It is also possible to use xref:refguide:applib-ant:ActionLayout.adoc#hidden[`@ActionLayout#hidden`] or xref:vw:ROOT:layout.adoc#file-based[file-based layouts] such that the action can be hidden at the view layer.
+It is also possible to use xref:refguide:applib-ant:ActionLayout.adoc#hidden[`@ActionLayout#hidden`] or xref:userguide:fun:ui.adoc#object-layout[file-based layouts] such that the action can be hidden at the view layer.
Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
index 6052895..600eeea 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
@@ -79,7 +79,7 @@ public class ToDoItems {
[TIP]
====
-As an alternative to using the `@ActionLayout` annotation, a xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@ActionLayout` annotation, a xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/bookmarking.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/bookmarking.adoc
index 6f9bcd2..b0f0f26 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/bookmarking.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/bookmarking.adoc
@@ -51,7 +51,7 @@ The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmar
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc
index a3cf257..f00f447 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClass.adoc
@@ -29,7 +29,7 @@ to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icon
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc
index bdb2a00..b803175 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/cssClassFa.adoc
@@ -32,7 +32,7 @@ There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is n
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
[NOTE]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/describedAs.adoc
index 75a85b4..8b2156d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/describedAs.adoc
@@ -23,7 +23,7 @@ public class Customer {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/hidden.adoc
index f1bc78a..9eb1547 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/hidden.adoc
@@ -47,7 +47,7 @@ For actions of domain services the visibility is dependent upon its xref:refguid
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/named.adoc
index 013c7a8..8798e26 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/named.adoc
@@ -29,7 +29,7 @@ public class Customer {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/position.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/position.adoc
index 96a192c..36dc16a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/position.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/position.adoc
@@ -68,6 +68,6 @@ If there are multiple actions associated with a single property then the positio
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
The fact that the layout is dynamic (does not require a rebuild/restart) is particularly useful in that the look-n-feel can be easily experimented with and adjusted.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/promptStyle.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/promptStyle.adoc
index cfd9f32..b32386e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/promptStyle.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/promptStyle.adoc
@@ -56,6 +56,6 @@ The net effect is that a property conceptually consisting of different parts (eg
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/redirect.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/redirect.adoc
index 6f4913a..60ac220 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/redirect.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout/redirect.adoc
@@ -56,6 +56,6 @@ If `switchToEditMode()` action is invoked, then the UI will attempt to render th
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
index 5b08668..5e0b442 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
@@ -9,7 +9,7 @@ Collections can be hidden at the domain-level, indicating that they are not visi
[TIP]
====
-It is also possible to use xref:refguide:applib-ant:CollectionLayout.adoc#hidden[`@CollectionLayout#hidden`] or using xref:vw:ROOT:layout.adoc#file-based[file-based layout] such that the collection can be hidden at the view layer.
+It is also possible to use xref:refguide:applib-ant:CollectionLayout.adoc#hidden[`@CollectionLayout#hidden`] or using xref:userguide:fun:ui.adoc#object-layout[file-based layout] such that the collection can be hidden at the view layer.
Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
index a573016..903f183 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
@@ -63,7 +63,7 @@ public class ToDoItem {
[TIP]
====
-As an alternative to using the `@CollectionLayout` annotation, a xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@CollectionLayout` annotation, a xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
[TIP]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
index af9eaea..bea4ad3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
@@ -25,7 +25,7 @@ public class ToDoItem {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
index 3ab8bd2..554886d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
@@ -1,3 +1,4 @@
+[#defaultview]
= `defaultView`
: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 ag [...]
@@ -34,5 +35,5 @@ This attribute takes precedence over any value for the xref:refguide:applib-ant:
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
index b47d7df..b623cad 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
@@ -26,5 +26,5 @@ public class ToDoItem {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
index 2052e24..1b19abc 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
@@ -51,7 +51,7 @@ The other values of the `Where` enum have no meaning for a collection.
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
index 68765cb..5b79869 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
@@ -37,7 +37,7 @@ public class ToDoItem {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
index 8462e90..c111e6c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
@@ -34,7 +34,7 @@ It is also possible to specify a global default for the page size of standalone
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
index 42c4426..2a61c1f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
@@ -46,4 +46,4 @@ Without this annotation, the order would have been inverted (because the natural
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
index ff78c5d..8b6953c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
@@ -71,7 +71,7 @@ public class ToDoItem {
[NOTE]
====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:vw:ROOT:layout.adoc#file-based[`.layout.xml`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:userguide:fun:ui.adoc#object-layout[`.layout.xml`] file (only for properties, collections and actions are supported).
====
== UI Events API
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
index 99d28dd..9e4dbbd 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
@@ -1,3 +1,4 @@
+[#nature]
= `nature`
: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 ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
index dd49afa..132da9e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
@@ -8,7 +8,7 @@ The `@DomainServiceLayout` annotation applies to domain services, collecting tog
[TIP]
====
-You will also find some additional material in the xref:vw:ROOT:layout.adoc#application-menu[object layout] chapter.
+You will also find some additional material in the xref:userguide:fun:ui.adoc#menu-bars-layout[user guide].
====
The annotation is:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout/menuBar.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout/menuBar.adoc
index 5867814..87a91c9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout/menuBar.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout/menuBar.adoc
@@ -1,3 +1,4 @@
+[#menubar]
= `menuBar`
: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 ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
index 620e408..3c80d62 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
@@ -46,7 +46,7 @@ public class TodoAppDashboard {
public Blob exportToWordDoc() { /* ... */ } // <1>
}
----
-<1> associated using xref:vw:ROOT:layout.adoc#file-based[file-based layout] with the `notYetComplete` collection.
+<1> associated using xref:userguide:fun:ui.adoc#object-layout[file-based layout] with the `notYetComplete` collection.
The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `TodoAppDashboard` through various domain services, as is the `downloadLayout` action.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
index aa35a39..e133587 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
@@ -80,7 +80,7 @@ public class ToDoItem {
[NOTE]
====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:vw:ROOT:layout.adoc#file-based[`.layout.xml`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:userguide:fun:ui.adoc#object-layout[`.layout.xml`] file (only for properties, collections and actions are supported).
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
index 3768870..47aea89 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
@@ -94,7 +94,7 @@ It is also possible to apply the annotation to actions of domain services that a
[TIP]
====
-As an alternative to using the `@PropertyLayout` annotation, a xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@PropertyLayout` annotation, a xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
index 6e40b4e..2c3b6a7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
@@ -22,7 +22,7 @@ public class ToDoItem {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
index 2b10016..384041e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
@@ -21,4 +21,4 @@ public class Customer {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
index f275248..8db97bb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
@@ -9,7 +9,7 @@ The `hidden` attribute indicates where (in the UI) the property should be hidden
[TIP]
====
-It is also possible to use xref:refguide:applib-ant:PropertyLayout.adoc#hidden[`@PropertyLayout#hidden`] or a xref:vw:ROOT:layout.adoc#file-based[file-based layout] such that the property can be hidden at the view layer.
+It is also possible to use xref:refguide:applib-ant:PropertyLayout.adoc#hidden[`@PropertyLayout#hidden`] or a xref:userguide:fun:ui.adoc#object-layout[file-based layout] such that the property can be hidden at the view layer.
Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
@@ -69,7 +69,7 @@ The xref:vro:ROOT:about.adoc[RestfulObjects viewer] has only partial support for
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
index bcb5bfc..64843da 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
@@ -83,7 +83,7 @@ If these are not present then Apache Isis will render according to internal defa
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
index ed139fc..c6eb6b9d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
@@ -30,5 +30,5 @@ If set > 1 (as would normally be the case), then the default xref:refguide:appli
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
index ae89139..7e28907 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
@@ -34,7 +34,7 @@ public class ToDoItem {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
index ca945f3..fc98a32 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
@@ -24,5 +24,5 @@ public class Customer {
<1> prompt for the new value for the property using an inline panel
Note that the value `INLINE_AS_IF_EDIT` does not make sense for properties; if specified then it will be interpreted as just `INLINE`.
-Alternatively, the `promptStyle()` can be specified using xref:vw:ROOT:layout.adoc#file-based[file-based layouts].
+Alternatively, the `promptStyle()` can be specified using xref:userguide:fun:ui.adoc#object-layout[file-based layouts].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc
index 7a2dcbb..e2a35db 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc
@@ -36,7 +36,7 @@ public class Tenancy {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
index e3301e1..cbb0d8c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
@@ -27,4 +27,4 @@ public class Customer {
== Alternatives
-As an alternative to using the annotation, the dynamic xref:vw:ROOT:layout.adoc#file-based[file-based layout] can be used instead.
+As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
index c3abd96..c283f2d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
@@ -15,7 +15,7 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Annotation
|Purpose
|Layer
-|xref:vw:ROOT:layout.adoc#file-based[File-based layout]?
+|xref:userguide:fun:ui.adoc#object-layout[File-based layout]?
|xref:refguide:applib-ant:Digits.adoc[`@javax.validation.` +
`constraints.` +
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/about/main.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/about/main.adoc
index bac418c..777f385 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/about/main.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/about/main.adoc
@@ -10,7 +10,7 @@ For each of these domain types and members there are two annotations. One cover
[TIP]
====
-Most UI semantics can also be specified using xref:vw:ROOT:layout.adoc#file-based[dynamic object layout].
+Most UI semantics can also be specified using xref:userguide:fun:ui.adoc#object-layout[dynamic object layout].
====
@@ -23,7 +23,7 @@ The table below summarizes these most commonly used annotations in Apache Isis.
|Annotation
|Purpose
|Layer
-|xref:vw:ROOT:layout.adoc#file-based[File-based layout]?
+|xref:userguide:fun:ui.adoc#object-layout[File-based layout]?
|xref:refguide:applib-ant:Action.adoc[`@Action`]
|Domain semantics for actions
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/about/other.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/about/other.adoc
index 5f9885d..2ec4b8d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/about/other.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/about/other.adoc
@@ -12,7 +12,7 @@ These annotations are also commonly used, but relate _not_ to objects or object
|Annotation
|Purpose
|Layer
-|xref:vw:ROOT:layout.adoc#file-based[File-based layout]?
+|xref:userguide:fun:ui.adoc#object-layout[File-based layout]?
|xref:refguide:applib-ant:Facets.adoc[`@Facets`]
|Install arbitrary facets within the Apache Isis metamodel.
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Object.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Object.adoc
index f537d60..a62baef 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Object.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Object.adoc
@@ -36,11 +36,14 @@ This mixin uses the xref:refguide:applib-svc:HintStore.adoc[`HintStore`] service
+[#downloadlayoutxml]
== `downloadLayoutXml()`
-The `Object_downloadLayoutXml` mixin provides an action to download the xref:vw:ROOT:layout.adoc#file-based[layout XML] for the current domain object.
+The `Object_downloadLayoutXml` mixin provides an action to download the xref:userguide:fun:ui.adoc#object-layout[layout XML] for the current domain object.
It has the following signature:
+
+
[source,java]
----
public Object downloadLayoutXml(
@@ -52,7 +55,7 @@ public Object downloadLayoutXml(
----
<1> either current, complete, normalized or minimal.
-See the documentation on xref:vw:ROOT:layout.adoc#file-based[layout XML] and also
+See the documentation on xref:userguide:fun:ui.adoc#object-layout[layout XML] and also
the xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] for more information on these styles
@@ -82,30 +85,6 @@ This mixin calls xref:refguide:applib-svc:MetamodelService.adoc[`MetaModelServic
-== `downloadLayoutXml()`
-
-The `Object_downloadLayoutXml` mixin provides an action to download the xref:vw:ROOT:layout.adoc#file-based[layout XML] for the current domain object.
-It has the following signature:
-
-[source,java]
-----
-public Object downloadLayoutXml(
- @ParameterLayout(named = "File name")
- final String fileName,
- final LayoutService.Style style) { // <1>
- ...
-}
-----
-<1> either current, complete, normalized or minimal.
-
-See the documentation on xref:vw:ROOT:layout.adoc#file-based[layout XML] and also
-the xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] for more information on these styles
-
-
-=== Related Services
-
-This mixin calls xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] to obtain the layout XML.
-
== `openRestApi()`
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc
index 75f7e57..cef15e8 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/reserved/layout.adoc
@@ -5,7 +5,7 @@
Every object has a xref:vw:ROOT:layout.adoc[layout] .
-This may be specified using annotations such as xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`], xref:refguide:applib-ant:DomainObjectLayout.adoc[`@DomainObjectLayout`] and the like, but it much more commonly specified using an xref:vw:ROOT:layout.adoc#file-based [XML layout file].
+This may be specified using annotations such as xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`], xref:refguide:applib-ant:DomainObjectLayout.adoc[`@DomainObjectLayout`] and the like, but it much more commonly specified using an xref:userguide:fun:ui.adoc#object-layout [XML layout file].
The `layout` method allows the domain object to specify an alternate layout to its usual layout.
diff --git a/viewers/wicket/adoc/modules/ROOT/images/application-menu/tertiary.png b/viewers/wicket/adoc/modules/ROOT/images/application-menu/tertiary.png
deleted file mode 100644
index f2d2281..0000000
Binary files a/viewers/wicket/adoc/modules/ROOT/images/application-menu/tertiary.png and /dev/null differ
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/customisation/tweaking-css-classes.adoc b/viewers/wicket/adoc/modules/ROOT/pages/customisation/tweaking-css-classes.adoc
index 043a903..5f1bced 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/customisation/tweaking-css-classes.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/customisation/tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
}
----
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:vw:ROOT:layout.adoc#file-based[layout file].
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:userguide:fun:ui.adoc#object-layout[layout file].
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout.adoc b/viewers/wicket/adoc/modules/ROOT/pages/layout.adoc
deleted file mode 100644
index bc31c7b..0000000
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= Layout
-
-: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 ag [...]
-
-
-In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis aims to infer as much information from the domain classes as possible.
-Nevertheless, some metadata relating solely to the UI is inevitably required.
-This chapter describes how this is done both for domain objects using either annotations or using an associated layout file.
-
-The chapter also describes how to customising which columns of associated objects appear in tables.
-The layout of application menu items is described in a xref:vw:ROOT:menubars-layout.adoc[separate chapter].
-
-
-
-include::layout/annotation-based.adoc[leveloffset=+1]
-include::layout/file-based.adoc[leveloffset=+1]
-include::layout/table-columns.adoc[leveloffset=+1]
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout.adoc b/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout.adoc
deleted file mode 100644
index 30048be..0000000
--- a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-= Menu Bars Layout
-
-: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 ag [...]
-
-
-
-The actions of domain services are made available as menu items on menus.
-By default each domain service corresponds to a single menu on this menu bar, with its actions as the drop-down menu items.
-This is rarely exactly what is required, however; it often makes sense to group menu items for similar domain services together.
-
-For example, the (non-ASF) link:https://platform.incode.org[Incode Platform^] modules provides services whose actions appear into two top-level menus:
-
-* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the SECONDARY menu bar
-
-* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
-
-
-The menus themselves can be placed either on a primary, secondary or tertiary menu bar, as shown in this screenshot (taken from http://github.com/estatio/estatio[Estatio], an open source estate management application built using Apache Isis):
-
-image::application-menu/layout-menus.png[width="800px",link="{imagesdir}/application-menu/layout-menus.png"]
-
-Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services.
-The Wicket viewer shows these as separate sections, with a divider between each:
-
-image::application-menu/dividers.png[width="400px",link="{imagesdir}/application-menu/dividers.png"]
-
-
-The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right.
-This is intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
-
-image::application-menu/tertiary.png[width="300px",link="{imagesdir}/application-menu/tertiary.png"]
-
-
-The Apache Isis framework provides two mechanisms to control the arrangement of domain service actions across menubars and menus, either using annotations or using a file-based layout.
-
-
-include::menubars-layout/annotation-based.adoc[leveloffset=+1]
-include::menubars-layout/file-based.adoc[leveloffset=+1]
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/annotation-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/annotation-based.adoc
deleted file mode 100644
index 967f57f..0000000
--- a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/annotation-based.adoc
+++ /dev/null
@@ -1,125 +0,0 @@
-[[annotation-based]]
-= Annotation-based Menu Bars
-
-: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 ag [...]
-
-
-
-The annotations-based approach for arranging the placement of menu items is achieved through the xref:refguide:applib-ant:MemberOrder.adoc[`@MemberOrder`] and xref:refguide:applib-ant:DomainServiceLayout.adoc[`@DomainServiceLayout`] annotations.
-
-== @DomainServiceLayout
-
-In the example from Estatio shown above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations` services.
-The `Properties` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.1"
-)
-public class Properties ... { /* ... */ }
-----
-
-while the `Units` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.2"
-)
-public class Units ... { /* ... */ }
-----
-
-and similarly `FixedAssetRegistrations` is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.3"
-)
-public class FixedAssetRegistrations ... { /* ... */ }
-----
-
-Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets" and PRIMARY.
-This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
-
-Meanwhile the value of `menuOrder` attribute is significant for two reasons:
-
-* for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
-
-* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar.
-
-To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets" because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for "Fixed Assets":
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Parties",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "20.1"
-)
-public class Parties ... { /* ... */ }
-----
-
-Note that only the `menuOrder` of the _first_ domain service is significant in placing the menus along the menu bar; thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
-
-
-
-== Ordering menu actions
-
-For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation.
-Thus, for the `Units` domain service, its actions are annotated:
-
-[source,java]
-----
-public class Units extends EstatioDomainService<Unit> {
-
- @MemberOrder(sequence = "1")
- public Unit newUnit( ... ) { /* ... */ }
-
- @MemberOrder(sequence = "2")
- public List<Unit> findUnits( ... ) { /* ... */ }
-
- @ActionLayout( prototype = true )
- @MemberOrder(sequence = "99")
- public List<Unit> allUnits() { /* ... */ }
- ...
-}
-----
-
-Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
-In the UI it is rendered in italics.
-
-
-
-== Tertiary Menu
-
-
-Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation, but be aware that the `@DomainServiceLayout#name` attribute will be ignored (there is only one effective menu).
-
-For example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
-
-[source,java]
-----
-@DomainServiceLayout(
- menuBar = DomainServiceLayout.MenuBar.TERTIARY,
- menuOrder = "10.1"
-)
-public class EstatioAdministrationService ... {
-
- @MemberOrder(sequence = "1")
- public void updateEpochDate( ... ) { /* ... */ }
-
- @MemberOrder(sequence = "2")
- public List<ApplicationSetting> listAllSettings() { /* ... */ }
- ...
-}
-----
-
-Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the viewer does _not_ place dividers between actions from different services on the tertiary menu.
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc
deleted file mode 100644
index 0368daf..0000000
--- a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc
+++ /dev/null
@@ -1,104 +0,0 @@
-[[file-based]]
-= File-based Menu Bars
-
-: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 ag [...]
-
-
-The domain service actions can be arranged across menu items using the `menubars.layout.xml` file.
-Not only is this easier to work with, it also can be reloaded dynamically (if in prototype mode), substantially reducing the edit compile run cycle.
-
-As for xref:vw:ROOT:layout.adoc#file-based[file-based object layouts], this offers a number of benefits:
-
-* Probably most significantly, the layout can be updated without requiring a recompile of the code and redeploy of the app; fine-tuning the layout with your end users is easy to do
-
-* Many developers also find it easier to rationalize about menu bars layout when all the hints are collated together in a single place (rather than scattered across the domain service classes as annotations).
-
-There are some disadvantages to using file-based layouts:
-
-* file-based layouts are not typesafe: a typo will result in the metadata not being picked up for the element.
-
-* they also suffer from syntactic fragility: an invalid XML document will result in no metadata for the entire class.
-
-The `menubars.layout.xml` file is just the serialized form of a xref:refguide:applib-cm:classes/layout.adoc[`MenuBars`] layout class defined within Apache Isis' applib.
-These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that
-is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making it easy to author such layout files.
-
-
-== Obtaining an initial layout
-
-An initial `menubars.layout.xml` - capturing any existing metadata either implicit or explicitly specified through annotations can be downloaded from the xref:refguide:applib-svc:MenuBarsService.adoc[`MenuBarsService`] (exposed on the prototyping menu):
-
-image::/menubars/010-download.png[width="300px",link="{imagesdir}/menubars/010-download.png"]
-
-
-This action allows either the "Default" or the "Fallback" layout to be downloaded.
-
-image::/menubars/020-download.png[width="400px",link="{imagesdir}/menubars/020-download.png"]
-
-The "Default" layout is that currently in use, while the "Fallback" layout is that provided only from the annotations.
-Initially these are identical.
-
-For example, here's a fragment of that provided by the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<mb3:menuBars
- xsi:schemaLocation="..."
- xmlns:cpt="http://isis.apache.org/applib/layout/component"
- xmlns:lnk="http://isis.apache.org/applib/layout/links"
- xmlns:mb3="http://isis.apache.org/applib/layout/menubars/bootstrap3"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <mb3:primary>
- <mb3:menu>
- <mb3:named>Simple Objects</mb3:named>
- <mb3:section>
- <mb3:serviceAction objectType="simple.SimpleObjectMenu" id="listAll">
- <cpt:named>List All</cpt:named>
- </mb3:serviceAction>
- <mb3:serviceAction objectType="simple.SimpleObjectMenu" id="findByName">
- <cpt:named>Find By Name</cpt:named>
- </mb3:serviceAction>
- <mb3:serviceAction objectType="simple.SimpleObjectMenu" id="create">
- <cpt:named>Create</cpt:named>
- </mb3:serviceAction>
- </mb3:section>
- </mb3:menu>
- <mb3:menu unreferencedActions="true">
- <mb3:named>Other</mb3:named>
- </mb3:menu>
- </mb3:primary>
- <mb3:secondary>
- <mb3:menu>
- <mb3:named>Prototyping</mb3:named>
- ...
- </mb3:secondary>
- <mb3:tertiary>
- <mb3:menu>
- ...
- </mb3:menu>
- </mb3:tertiary>
-</mb3:menuBars>
-----
-
-Note the "Other" menu, with `unreferencedActions` attribute set to `true`.
-For a layout file to be valid there must be exactly one `<menu>` with this attribute set.
-Any domain service actions that are not explicitly listed will be placed under this menu.
-
-
-== Adjusting the layout
-
-The downloaded `menubars.layout.xml` file can be adjusted as necessary, creating new menus and menu sections.
-Once done, it can be saved in the same package as the `AppManifest` used to bootstrap the application.
-Subsequently, the file is then parsed and used when the application is started.
-
-If running in prototype mode, the file will be dynamically reloaded from the classpath.
-
-Once the application has bootstrapped with a layout file, downloading the "Default" layout (from the prototyping menu) in essence just returns this file.
-
-[TIP]
-====
-If, when the application is run, unwanted service actions are shown in the "Other" menu (which you would like to place elsewhere), then download the "Default" layout again.
-The downloaded file will list out all these domain service actions, so that they can easily be moved elsewhere.
-====
-
diff --git a/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc b/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
index cfc75b2..8133c7b 100644
--- a/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
@@ -2,7 +2,6 @@
* xref:vw:ROOT:layout.adoc[Layout]
-* xref:vw:ROOT:menubars-layout.adoc[Menubars Layout]
* xref:vw:ROOT:configuration-properties.adoc[Configuration Properties]
* xref:vw:ROOT:features.adoc[End-user Features]
* xref:vw:ROOT:security.adoc[Security]