You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2021/04/09 13:41:43 UTC

[isis] branch master updated: ISIS-2602: adoc fixes on @MemberOrder

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git


The following commit(s) were added to refs/heads/master by this push:
     new 464d854  ISIS-2602: adoc fixes on @MemberOrder
464d854 is described below

commit 464d854d17b9d59bddc47e9f38cd9a6effd5728b
Author: ahuber@apache.org <ah...@luna>
AuthorDate: Fri Apr 9 15:41:29 2021 +0200

    ISIS-2602: adoc fixes on @MemberOrder
---
 .../pages/index/annotation/ActionLayout.adoc       |  4 +-
 .../applib/pages/index/annotation/Title.adoc       |  2 +-
 .../hooks/ActionLayout_010-examples-and-usage.adoc |  4 +-
 .../hooks/ActionLayout_022-position.adoc           |  6 +--
 .../hooks/ActionLayout_026-bookmarking.adoc        |  5 ++-
 .../annotation/hooks/Action_021-associating.adoc   |  2 +-
 .../hooks/MemberOrder_010-examples-and-usage.adoc  | 50 ++++++++++++----------
 .../pages/index/layout/component/FieldSet.adoc     |  4 +-
 .../applib/pages/index/services/layout/Style.adoc  |  2 +-
 .../LayoutService_020-examples-and-usage.adoc      |  2 +
 .../modules/applib-ant/pages/about/other.adoc      | 14 +-----
 .../applib-methods/pages/ui-hints/layout.adoc      |  6 ++-
 .../modules/fun/pages/ui/menubars-layout.adoc      |  8 ++--
 .../modules/fun/pages/ui/object-layout.adoc        |  2 +
 14 files changed, 56 insertions(+), 55 deletions(-)

diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/ActionLayout.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/ActionLayout.adoc
index d247d4d..3fe90b6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/ActionLayout.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/ActionLayout.adoc
@@ -73,7 +73,7 @@ Name of this action (overriding the name derived from its name in code).
 <.> xref:#position[position]
 +
 --
-For actions that are associated with a property (using either _Action#associateWith()_ or _MemberOrder#name()_ , indicates the positioning of the action's button relative to the property.
+For actions that are associated with a property (using either _Action#associateWith()_ or _ActionLayout#fieldSetId()_ or _ActionLayout#fieldSetName()_ , indicates the positioning of the action's button relative to the property.
 --
 <.> xref:#promptStyle[promptStyle]
 +
@@ -153,7 +153,7 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
 [#position]
 === position
 
-For actions that are associated with a property (using either _Action#associateWith()_ or _MemberOrder#name()_ , indicates the positioning of the action's button relative to the property.
+For actions that are associated with a property (using either _Action#associateWith()_ or _ActionLayout#fieldSetId()_ or _ActionLayout#fieldSetName()_ , indicates the positioning of the action's button relative to the property.
 
 Ignored if the action has not been associated with a property.
 
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/Title.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/Title.adoc
index 157b9ec..5e9a271 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/Title.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/Title.adoc
@@ -3,7 +3,7 @@
 
 Used to indicate which property or properties make up the object title.
 
-If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
+If more than one property is used, the order can be specified (using the same Dewey-decimal notation). The string to use between the components can also be specified.
 
 == API
 
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
index 2c503e6..ed2d7dd 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
@@ -15,9 +15,9 @@ public class ToDoItems {
         cssClass="x-key",
         cssClassFa="fa-checkbox",
         describedAs="Mark the todo item as not complete after all",
-        hidden=Where.NOWHERE                        // <2>
+        hidden=Where.NOWHERE,                       // <2>
+        sequence = "1"
     )
-    @MemberOrder(sequence = "1")
     public List<ToDoItem> notYetComplete() {
         ...
     }
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
index f42e2c8..c4fbdfa 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
@@ -3,7 +3,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 [...]
 :page-partial:
 
-The xref:refguide:applib:index/annotation/ActionLayout.adoc#position[position()] element pertains only to actions that have been associated with properties using xref:refguide:applib:index/annotation/MemberOrder.adoc[@MemberOrder#named].
+The xref:refguide:applib:index/annotation/ActionLayout.adoc#position[position()] element pertains only to actions that have been associated with properties using xref:refguide:applib:index/annotation/Action.adoc#associateWith[@Action#associateWith()].
 For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
 
 The attribute can take one of four values: `BELOW`, `RIGHT`, `PANEL` or `PANEL_DROPDOWN`.
@@ -25,7 +25,7 @@ public class Customer {
     @Getter @Setter
     private String location;
 
-    @MemberOrder( named="cost" )                        // <.>
+    @Action( associateWith="cost" )                     // <.>
     @ActionLayout(
         named="Update",                                 // <.>
         position=Position.BELOW                         // <.>
@@ -34,7 +34,7 @@ public class Customer {
         // ...
     }
 
-    @MemberOrder( named="location" )
+    @Action( associateWith="location" )
     @ActionLayout(
         named="Update",
         position=Position.BELOW
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
index 780d8c5..02c8953 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
@@ -20,8 +20,9 @@ For example:
 ----
 public class ToDoItems {
     @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(bookmarking=BookmarkPolicy.AS_ROOT)
-    @MemberOrder(sequence = "1")
+    @ActionLayout(
+        bookmarking=BookmarkPolicy.AS_ROOT,
+        sequence = "1")
     public List<ToDoItem> notYetComplete() {
         ...
     }
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc
index d982217..d216583 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc
@@ -44,6 +44,6 @@ In the user interface associated actions are rendered close to the member to whi
 
 [NOTE]
 ====
-The same effect can be accomplished using `@MemberOrder` or with the `.layout.xml` file.
+The same effect can be accomplished using the `.layout.xml` file.
 ====
 
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/MemberOrder_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/MemberOrder_010-examples-and-usage.adoc
index c1260c5..4eaad0e 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/MemberOrder_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/MemberOrder_010-examples-and-usage.adoc
@@ -3,19 +3,23 @@
 :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:
 
-
-// TODO: v2: ISIS-2545: replace @MemberOrder#name() with @PropertyLayout#group().
-
-The interpretation of the xref:refguide:applib:index/annotation/MemberOrder.adoc#name[name()] element varies dependent on the type of object member it is annotated upon, but generally speaking it is used to associate members together.
-
-
-The xref:refguide:applib:index/annotation/MemberOrder.adoc#sequence[sequence()] element then orders those members that have been grouped together.
-
-
+Attributes `fieldSetId` and `fieldSetName` are used to associate members together. These are available for 
+xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout]
+and
+xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] 
+(but not for 
+xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout] 
+as collections don't support annotation based grouping).
+
+Dependent on the type of object member the `sequence` attribute orders those members that have been grouped together. It is available with 
+xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout], 
+xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] 
+and 
+xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout]
 
 === Properties
 
-For properties, the `name` attribute is used to group properties together, and `sequence` orders the properties within that group.
+For properties, the `fieldSetId` and/or `fieldSetName` attribute is used to group properties together, and `sequence` orders the properties within that group.
 It corresponds to a `<fieldset>` if using xref:userguide:fun:ui.adoc#object-layout[layout files].
 
 
@@ -28,34 +32,34 @@ import lombok.Setter;
 
 public class Customer {
 
-    @MemberOrder(name = "Personal Details", sequence = "1.0")
+    @PropertyLayout(fieldSetName = "Personal Details", sequence = "1.0")
     private String firstName;
 
-    @MemberOrder(name = "Personal Details", sequence = "2.0")
+    @PropertyLayout(fieldSetName = "Personal Details", sequence = "2.0")
     private String lastName;
 
-    @MemberOrder(name = "Address", sequence = "1.0")
+    @PropertyLayout(fieldSetName = "Address", sequence = "1.0")
     private String addressLine1;
 
-    @MemberOrder(name = "Address", sequence = "2.0")
+    @PropertyLayout(fieldSetName = "Address", sequence = "2.0")
     private String addressLine2;
 
-    @MemberOrder(name = "Address", sequence = "3.0")
+    @PropertyLayout(fieldSetName = "Address", sequence = "3.0")
     private String city;
 
-    @MemberOrder(name = "Address", sequence = "4.0")
+    @PropertyLayout(fieldSetName = "Address", sequence = "4.0")
     private String zipCode;
 
     // ...
 }
 ----
 
-TIP: It's possible to combine `@MemberOrder` with xref:userguide:fun:ui.adoc#object-layout[layout file].
-Use the layout file to define the positioning of the fieldsets, and use `@MemberOrder` to organise the properties within the fieldset.
+TIP: It's possible to combine `@PropertyLayout` with xref:userguide:fun:ui.adoc#object-layout[layout file].
+Use the layout file to define the positioning of the fieldsets, and use `@PropertyLayout` to organise the properties within the fieldset.
 
 === Actions
 
-For actions, the `name` attribute indicates the name of a property to associate the action with, and `sequence` orders all the actions associated with the same property or collection (on the panel of the property's fieldset, or collection's title bar).
+For actions, the `fieldSetId` and/or `fieldSetName` attribute indicates the name of a property to associate the action with, and `sequence` orders all the actions associated with the same property or collection (on the panel of the property's fieldset, or collection's title bar).
 
 
 For example:
@@ -67,12 +71,12 @@ import lombok.Setter;
 
 public class Customer {
 
-    @MemberOrder(name = "Personal Details")
+    @ActionLayout(fieldSetName = "Personal Details")
     public Customer updateName(String firstName, String lastName) {
         // ...
     }
 
-    @MemberOrder(name = "Address")
+    @ActionLayout(fieldSetName = "Address")
     public Customer changeAddress(String firstName, String lastName) {
         // ...
     }
@@ -81,12 +85,12 @@ public class Customer {
 }
 ----
 
-TIP: For actions, `@Member#name()` element and xref:refguide:applib:index/annotation/Action.adoc#associateWith[@Action#associateWith()] element have the same effect.
+TIP: For actions xref:refguide:applib:index/annotation/Action.adoc#associateWith[@Action#associateWith()] is an alternative that indicates, that the action should be rendered close to its associated peer.
 
 TIP: For actions associated with properties, the xref:refguide:applib:index/annotation/ActionLayout.adoc#position[@ActionLayout#position()] element indicates whether the action should be rendered beneath the property's field, or instead on the property's fieldset panel's header.
 
 
 === Collections
 
-The `name` attribute is ignored when annotated on collections.
+The `fieldSetId` and `fieldSetName` attributes have no counterpart within `@CollectionLayout`.
 
diff --git a/antora/components/refguide-index/modules/applib/pages/index/layout/component/FieldSet.adoc b/antora/components/refguide-index/modules/applib/pages/index/layout/component/FieldSet.adoc
index 8bd776e..1f35ab6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/layout/component/FieldSet.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/layout/component/FieldSet.adoc
@@ -49,7 +49,7 @@ Whether this fieldset should be used to hold any unreferenced properties (contri
 <.> xref:#getName__[getName()]
 +
 --
-Corresponds to the _MemberOrder#name()_ (when applied to properties).
+Corresponds to the _PropertyLayout#fieldSetName()_ (when applied to properties).
 --
 <.> xref:#getOwner__[getOwner()]
 +
@@ -86,7 +86,7 @@ Any grid layout must have precisely one fieldset that has this attribute set.
 [#getName__]
 === getName()
 
-Corresponds to the _MemberOrder#name()_ (when applied to properties).
+Corresponds to the _PropertyLayout#fieldSetName()_ (when applied to properties).
 
 [#getOwner__]
 === getOwner()
diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/layout/Style.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/layout/Style.adoc
index 581fa8f..6b38f94 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/services/layout/Style.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/services/layout/Style.adoc
@@ -1,7 +1,7 @@
 = Style _(enum)_
 :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 [...]
 
-Mode of operation when downloading a layout file (while prototyping).
+Mode of operation when downloading a layout file (while prototyping).TODO update for v2 - @MemberGroupLayout and @MemberOrder have been removed
 
 It affects the way the file's content is assembled. Once a layout file is in place, its layout data takes precedence over any conflicting layout data from annotations.
 
diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/layout/hooks/LayoutService_020-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/layout/hooks/LayoutService_020-examples-and-usage.adoc
index 02924fb..c140b48 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/services/layout/hooks/LayoutService_020-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/services/layout/hooks/LayoutService_020-examples-and-usage.adoc
@@ -21,6 +21,8 @@ The `CURRENT` style corresponds to the layout already loaded for the domain clas
 The other three styles allow the developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained elsewhere, typically from annotations in the metamodel.
 The table below summarises the choices:
 
+NOTE: TODO v2 - @MemberOrder was remove, Style has been changed as well (WIP)
+
 [cols="<.>,^.>,^.>",options="header"]
 .Styles
 |===
diff --git a/antora/components/refguide/modules/applib-ant/pages/about/other.adoc b/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
index 9ef342d..729e6ec 100644
--- a/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
+++ b/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
@@ -7,39 +7,27 @@
 These annotations are also commonly used, but relate _not_ to objects or object members but instead to other aspects of the Apache Isis metamodel.
 
 .Other Isis Annotations
-[cols="2,4a,1,1", options="header"]
+[cols="2,4a,1", options="header"]
 |===
 |Annotation
 |Purpose
 |Layer
-|xref:userguide:fun:ui.adoc#object-layout[File-based layout]?
 
 |xref:refguide:applib:index/annotation/Facets.adoc[@Facets]
 |Install arbitrary facets within the Apache Isis metamodel.
 |(any)
-|
 
 |xref:refguide:applib:index/annotation/HomePage.adoc[@HomePage]
 |Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
 |UI
-|
-
-|xref:refguide:applib:index/annotation/MemberOrder.adoc[@MemberOrder]
-|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
-|UI
-|Yes
-
 
 |xref:refguide:applib:index/annotation/MinLength.adoc[@MinLength]
 |Minimum number of characters required for an auto-complete search argument.
 |UI
-|
-
 
 |xref:refguide:applib:index/annotation/Programmatic.adoc[@Programmatic]
 |Ignore a public method, excluded from the Apache Isis metamodel.
 |Domain
-|
 
 |xref:refguide:applib:index/annotation/Title.adoc[@Title]
 |Indicates which of the object's properties should be used to build up a title for the object.
diff --git a/antora/components/refguide/modules/applib-methods/pages/ui-hints/layout.adoc b/antora/components/refguide/modules/applib-methods/pages/ui-hints/layout.adoc
index 8a89462..1aa904b 100644
--- a/antora/components/refguide/modules/applib-methods/pages/ui-hints/layout.adoc
+++ b/antora/components/refguide/modules/applib-methods/pages/ui-hints/layout.adoc
@@ -5,7 +5,11 @@
 
 
 Every object has a xref:userguide:fun:ui.adoc#object-layout[layout] .
-This may be specified using annotations such as xref:refguide:applib:index/annotation/MemberOrder.adoc[@MemberOrder], xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@DomainObjectLayout] and the like, but it much more commonly specified using an xref:userguide:fun:ui.adoc#object-layout [XML layout file].
+This may be specified using annotations such as 
+xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout], 
+xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout], 
+xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout], 
+xref:refguide:applib:index/annotation/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/antora/components/userguide/modules/fun/pages/ui/menubars-layout.adoc b/antora/components/userguide/modules/fun/pages/ui/menubars-layout.adoc
index 0127c94..055bb4d 100644
--- a/antora/components/userguide/modules/fun/pages/ui/menubars-layout.adoc
+++ b/antora/components/userguide/modules/fun/pages/ui/menubars-layout.adoc
@@ -61,15 +61,15 @@ image::application-menu/tertiary.png[width="300px"]
 
 
 
-In addition, the xref:refguide:applib:index/annotation/MemberOrder.adoc[@MemberOrder] annotation can be used to group and order domain service actions:
+In addition, the xref:refguide:applib:index/annotation/ActionLayout.adoc[@ActionLayout] annotation can be used to group and order domain service actions:
 
-* `@MemberOrder#name()` is used to define the name of the menu
+* `@ActionLayout#named()` 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.
+* `@ActionLayout#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.
+Thus, using `named()` it's possible to group menu items from actions that are from different domain services.
 
 There are some significant limitations, however:
 
diff --git a/antora/components/userguide/modules/fun/pages/ui/object-layout.adoc b/antora/components/userguide/modules/fun/pages/ui/object-layout.adoc
index 57ce2f7..78b9055 100644
--- a/antora/components/userguide/modules/fun/pages/ui/object-layout.adoc
+++ b/antora/components/userguide/modules/fun/pages/ui/object-layout.adoc
@@ -253,6 +253,8 @@ There is no way to specify these semantics in the `.layout.xml` file (action par
 
 === Layout file styles
 
+NOTE: TODO v2 - Style has been changed (WIP)
+
 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:index/services/layout/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.