You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/06/20 06:34:39 UTC
[causeway] branch master updated (25ec83d0b0 -> b41f1073ee)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
from 25ec83d0b0 CAUSEWAY-3493: CI build script: disable build of demo docker images
new 667f1cd763 CAUSEWAY-3395 : updates to user guide (object members)
new b41f1073ee CAUSEWAY-3395 : reworks user guide, choices and defaults
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
...PropertyLayout-FieldSet-examples-and-usage.adoc | 4 +-
.../hooks/ActionLayout_010-examples-and-usage.adoc | 4 +-
.../CollectionLayout_010-examples-and-usage.adoc | 4 +-
.../annotation/hooks/Collection_022_hidden.adoc | 2 +-
.../DomainObjectLayout_010-examples-and-usage.adoc | 2 +-
.../hooks/HomePage_010-examples-and-usage.adoc | 2 +-
.../ParameterLayout_010-examples-and-usage.adoc | 2 +-
.../PropertyLayout_010-examples-and-usage.adoc | 4 +-
.../hooks/Object_downloadLayout_see-also.adoc | 2 +-
.../modules/applib-ant/partials/about/main.adoc | 4 +-
.../modules/applib-classes/pages/about.adoc | 2 +-
.../applib-methods/partials/ui-hints/layout.adoc | 2 +-
.../petclinic/pages/010-getting-started.adoc | 6 +-
.../userguide/modules/ROOT/pages/about.adoc | 4 +-
.../ROOT/pages/drop-downs-and-defaults.adoc | 9 +-
.../userguide/modules/ROOT/pages/modules.adoc | 2 +-
.../modules/ROOT/pages/object-members.adoc | 12 --
.../userguide/modules/ROOT/pages/overview.adoc | 8 +-
.../pages/properties-collections-actions.adoc} | 12 +-
.../modules/ROOT/pages/ui-layout-and-hints.adoc} | 23 +--
.../ROOT/partials/business-rules/usability.adoc | 2 +
.../ROOT/partials/business-rules/validity.adoc | 2 +-
.../ROOT/partials/business-rules/visibility.adoc | 2 +-
.../ROOT/partials/domain-entities/progmodel.adoc | 2 +-
.../ROOT/partials/domain-services/progmodel.adoc | 4 +-
.../alternative-programming-models.adoc} | 6 +-
.../drop-down-and-defaults/auto-complete.adoc | 61 ++++++
.../partials/drop-down-and-defaults/choices.adoc | 54 ++++++
.../partials/drop-down-and-defaults/defaults.adoc} | 30 +--
.../dependent-dropdowns.adoc} | 42 ++---
.../globally-defined-dropdowns.adoc | 66 +++++++
.../multi-select-dropdowns.adoc | 27 +++
.../partials/drop-down-and-defaults/progmodel.adoc | 209 ---------------------
.../modules/ROOT/partials/events/progmodel.adoc | 4 +-
.../modules/ROOT/partials/module-nav.adoc | 4 +-
.../_intro.adoc | 8 +-
.../actions.adoc | 4 +-
.../collections.adoc | 6 +-
.../progmodel.adoc | 0
.../properties.adoc | 6 +-
.../ROOT/partials/the-theory/metamodel.adoc | 2 +-
.../ui-layout-and-hints/_intro.adoc} | 19 +-
.../action-icons-and-css.adoc | 2 +-
.../menubars-layout.adoc | 2 +-
.../names-and-descriptions.adoc | 0
.../{ui => ui-layout-and-hints}/object-layout.adoc | 0
.../object-titles-and-icons.adoc | 6 +-
.../{ui => ui-layout-and-hints}/progmodel.adoc | 0
.../{ui => ui-layout-and-hints}/table-columns.adoc | 0
.../userguide/modules/ROOT/partials/ui/_intro.adoc | 6 -
.../btb/partials/programming-model/_intro.adoc | 2 +-
.../application-specific/application-css.adoc | 2 +-
.../adoc/modules/commandlog/pages/about.adoc | 2 +-
.../adoc/modules/executionlog/pages/about.adoc | 2 +-
.../ROOT/pages/customisation/custom-css.adoc | 2 +-
55 files changed, 333 insertions(+), 363 deletions(-)
delete mode 100644 antora/components/userguide/modules/ROOT/pages/object-members.adoc
copy antora/components/{docs/modules/support/pages/slack-channel.adoc => userguide/modules/ROOT/pages/properties-collections-actions.adoc} (68%)
copy antora/components/{refguide-index/modules/applib/pages/index/annotation/hooks/DomainServiceLayout_022-named.adoc => userguide/modules/ROOT/pages/ui-layout-and-hints.adoc} (58%)
copy antora/components/{refguide-index/modules/testing/pages/index/fixtures/applib/fixturescripts/hooks/FixtureScripts_020-configuration-properties.adoc => userguide/modules/ROOT/partials/drop-down-and-defaults/alternative-programming-models.adoc} (78%)
create mode 100644 antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/auto-complete.adoc
create mode 100644 antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/choices.adoc
copy antora/components/{refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-describedAs.adoc => userguide/modules/ROOT/partials/drop-down-and-defaults/defaults.adoc} (50%)
copy antora/components/{refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_024_navigable.adoc => userguide/modules/ROOT/partials/drop-down-and-defaults/dependent-dropdowns.adoc} (50%)
create mode 100644 antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/globally-defined-dropdowns.adoc
create mode 100644 antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/multi-select-dropdowns.adoc
delete mode 100644 antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
rename antora/components/userguide/modules/ROOT/partials/{object-members => properties-collections-actions}/_intro.adoc (93%)
rename antora/components/userguide/modules/ROOT/partials/{object-members => properties-collections-actions}/actions.adoc (97%)
rename antora/components/userguide/modules/ROOT/partials/{object-members => properties-collections-actions}/collections.adoc (94%)
rename antora/components/userguide/modules/ROOT/partials/{object-members => properties-collections-actions}/progmodel.adoc (100%)
rename antora/components/userguide/modules/ROOT/partials/{object-members => properties-collections-actions}/properties.adoc (97%)
rename antora/components/userguide/modules/ROOT/{pages/ui.adoc => partials/ui-layout-and-hints/_intro.adoc} (77%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/action-icons-and-css.adoc (98%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/menubars-layout.adoc (99%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/names-and-descriptions.adoc (100%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/object-layout.adoc (100%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/object-titles-and-icons.adoc (97%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/progmodel.adoc (100%)
rename antora/components/userguide/modules/ROOT/partials/{ui => ui-layout-and-hints}/table-columns.adoc (100%)
delete mode 100644 antora/components/userguide/modules/ROOT/partials/ui/_intro.adoc
[causeway] 02/02: CAUSEWAY-3395 : reworks user guide, choices and defaults
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit b41f1073eef1b3d34f6ddd7a780f7478f64f95b5
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Jun 20 07:34:31 2023 +0100
CAUSEWAY-3395 : reworks user guide, choices and defaults
---
.../ROOT/pages/drop-downs-and-defaults.adoc | 9 +-
.../ROOT/partials/business-rules/usability.adoc | 2 +
.../ROOT/partials/business-rules/validity.adoc | 2 +-
.../ROOT/partials/business-rules/visibility.adoc | 2 +-
.../ROOT/partials/domain-entities/progmodel.adoc | 2 +-
.../ROOT/partials/domain-services/progmodel.adoc | 2 +-
.../alternative-programming-models.adoc} | 7 +-
.../drop-down-and-defaults/auto-complete.adoc | 61 +++++
.../partials/drop-down-and-defaults/choices.adoc | 54 +++++
.../partials/drop-down-and-defaults/defaults.adoc | 35 +++
.../dependent-dropdowns.adoc | 32 +++
.../globally-defined-dropdowns.adoc | 66 +++++
.../multi-select-dropdowns.adoc | 27 +++
.../partials/drop-down-and-defaults/progmodel.adoc | 269 ---------------------
14 files changed, 292 insertions(+), 278 deletions(-)
diff --git a/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc b/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc
index 0046b46756..090febdad6 100644
--- a/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc
@@ -7,4 +7,11 @@
include::partial$drop-down-and-defaults/_intro.adoc[leveloffset=+1]
-include::partial$drop-down-and-defaults/progmodel.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/choices.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/defaults.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/auto-complete.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/globally-defined-dropdowns.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/multi-select-dropdowns.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/dependent-dropdowns.adoc[leveloffset=+1]
+include::partial$drop-down-and-defaults/alternative-programming-models.adoc[leveloffset=+1]
+
diff --git a/antora/components/userguide/modules/ROOT/partials/business-rules/usability.adoc b/antora/components/userguide/modules/ROOT/partials/business-rules/usability.adoc
index 8e4d377f4c..7c0dc7e693 100644
--- a/antora/components/userguide/modules/ROOT/partials/business-rules/usability.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/business-rules/usability.adoc
@@ -111,6 +111,8 @@ public String disable1Categorize( // <.>
A non-`null` return string is taken as the _reason_ why the action argument cannot be changed.
+// TODO: xref mixins for specifying supporting methods by name or using `Parameters`
+
== For more information
For more information, see xref:refguide:applib-methods:prefixes.adoc#disable[disable...()] section in the appropriate reference guide.
diff --git a/antora/components/userguide/modules/ROOT/partials/business-rules/validity.adoc b/antora/components/userguide/modules/ROOT/partials/business-rules/validity.adoc
index 17cae78b88..c15230ca55 100644
--- a/antora/components/userguide/modules/ROOT/partials/business-rules/validity.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/business-rules/validity.adoc
@@ -56,7 +56,7 @@ A non-`null` return string is taken as the _reason_ why the action arguments tak
The framework validates each argument separately; only if all are valid does it check all the arguments together.
-
+// TODO: xref mixins for specifying supporting methods by name or using `Parameters`
== For more information
diff --git a/antora/components/userguide/modules/ROOT/partials/business-rules/visibility.adoc b/antora/components/userguide/modules/ROOT/partials/business-rules/visibility.adoc
index 75c4c64e4d..f00ccaf6fd 100644
--- a/antora/components/userguide/modules/ROOT/partials/business-rules/visibility.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/business-rules/visibility.adoc
@@ -90,5 +90,5 @@ However, if they check the first boolean parameter (ie, to ship the `Order` to t
* xref:refguide:applib-methods:prefixes.adoc#hide[hide...()] method prefix
-
+// TODO: xref mixins for specifying supporting methods by name or using `Parameters`
diff --git a/antora/components/userguide/modules/ROOT/partials/domain-entities/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/domain-entities/progmodel.adoc
index 5a2eec9294..81855d1632 100644
--- a/antora/components/userguide/modules/ROOT/partials/domain-entities/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/domain-entities/progmodel.adoc
@@ -1,5 +1,5 @@
[[programming-model]]
-= Programming Model
+= @DomainObject
: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:
diff --git a/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
index 0ec314f9d5..bcf1c05261 100644
--- a/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
@@ -1,5 +1,5 @@
[[programming-model]]
-= Programming Model
+= @DomainService vs @Service/@Repository
: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:
diff --git a/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/alternative-programming-models.adoc
similarity index 78%
copy from antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc
copy to antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/alternative-programming-models.adoc
index 0046b46756..4de6d219e8 100644
--- a/antora/components/userguide/modules/ROOT/pages/drop-downs-and-defaults.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/alternative-programming-models.adoc
@@ -1,10 +1,9 @@
-= Drop Downs and Defaults
+= Alternative Programming Models
: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:
+If you define an action as a xref:mixins.adoc[mixin], then there are two other ways in which the supporting methods for parameters can be specified.
-
-include::partial$drop-down-and-defaults/_intro.adoc[leveloffset=+1]
-include::partial$drop-down-and-defaults/progmodel.adoc[leveloffset=+1]
+Check out the mixin docs.
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/auto-complete.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/auto-complete.adoc
new file mode 100644
index 0000000000..b95069dbe4
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/auto-complete.adoc
@@ -0,0 +1,61 @@
+= AutoComplete
+
+: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 _autocomplete_ is similar to _choices_, but accepts a string parameter, to search for matching results.
+A property for example might have:
+
+[source,java]
+----
+public class Order {
+
+ @Property(editing = Editing.ENABLED) // <.>
+ @Getter @Setter
+ private Product product;
+
+ public List<Product> autoCompleteProduct( // <.>
+ @MinLength(2) String search) { // <.>
+ return productRepository.findByReferenceOrName(search);
+ }
+
+ // ...
+}
+----
+<.> If required; properties are by default disabled globally.
+<.> "autoComplete" prefix, suffix matches property name. +
+Returns a collection of the property's type.
+<.> The `@MinLength(...)` annotation indicates the minimum number of characters that must be entered before a search is initiated.
+
+Actions are very similar.
+Here the supporting "autoComplete" method is matched by number:
+
+[source,java]
+----
+public class Customer {
+
+ public Order invoice(
+ ShoppingCart cart,
+ String paymentMethod,
+ DiscountVoucher voucher,
+ LocalDate shipBy) {
+ ...
+ return this;
+ }
+
+ public List<DiscountVoucher> autoComplete2Invoice( // <.>
+ @MinLength(2) String voucherCode) {
+ return discountVoucherRepository.findByVoucherCode(this, voucherCode);
+ }
+
+ // ...
+}
+----
+<.> "autoComplete" prefix, N-th param, suffix matches action name. +
+Returns a collection of the parameters type.
+
+An _autoComplete_ method can be used in conjunction with a _default_ method, but it doesn't make sense to provide both an _autoComplete_ and a _choices_ method.
+
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/choices.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/choices.adoc
new file mode 100644
index 0000000000..a5f6f58515
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/choices.adoc
@@ -0,0 +1,54 @@
+= Choices
+
+: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:
+
+
+A drop-down list of _choices_ for a property can be specified using a supporting method matched by prefix, returned datatype and name:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
+
+public class Customer {
+
+ @Property(editing = Editing.ENABLED) // <.>
+ @Getter @Setter
+ private String paymentMethod;
+
+ public List<String> choicesPaymentMethod() { // <.>
+ return Arrays.asList("Visa", "Mastercard", "Amex");
+ }
+
+ // ...
+}
+----
+<.> If required; properties are by default disabled globally.
+<.> Note the "choices" prefix and the suffix matching up with the getter.
+The method must return a collection of the same type as the property.
+
+For an action, the _choices_ for the N-th parameter can be specified by a prefix, the parameter number, with the suffix being the name of the action:
+
+[source,java]
+----
+public class Customer {
+
+ public Order invoice(
+ ShoppingCart cart,
+ String paymentMethod,
+ DiscountVoucher voucher,
+ LocalDate shipBy) {
+ ...
+ return this;
+ }
+
+ public List<String> choices1Invoice() { // <.>
+ return this.getPaymentMethods();
+ }
+
+ // ...
+}
+----
+<.> "choices" prefix, N-th param, suffix matches up with the action's name.
+Returns a collection of the same type as the parameter.
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/defaults.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/defaults.adoc
new file mode 100644
index 0000000000..6703707aff
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/defaults.adoc
@@ -0,0 +1,35 @@
+= Defaults
+
+: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:
+
+
+
+For properties, there is no concept of a default value ; just initialize the field to an appropriate value the object is created.
+For actions, though, providing a default value for its parameters can substantially improve the user experience.
+
+For an action, the _choices_ for the N-th parameter can be specified by "number":
+
+[source,java]
+----
+public class Customer {
+
+ public Order invoice(
+ ShoppingCart cart,
+ String paymentMethod,
+ DiscountVoucher voucher,
+ LocalDate shipBy) {
+ ...
+ return this;
+ }
+
+ public String default1Invoice() { // <.>
+ return this.getPaymentMethod(); // <.>
+ }
+
+ // ...
+}
+----
+<.> "default" prefix, N-th param, the suffix matches up with the action's name. +
+Returns object of same type as parameter.
+<.> A common idiom is to return the current value of a property of the object.
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/dependent-dropdowns.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/dependent-dropdowns.adoc
new file mode 100644
index 0000000000..921265b2a8
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/dependent-dropdowns.adoc
@@ -0,0 +1,32 @@
+= Dependent choices for action parameters
+
+: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:
+
+
+
+
+For action it is also possible (in a limited form) to define dependencies between parameters.
+Specifically, if one parameter is a drop-down choice, then other drop-down choices can be derived from it.
+
+A good example is a category/sub-category:
+
+[source,java]
+----
+public ToDoItem categorize(
+ Category category,
+ Subcategory subcategory) {
+ setCategory(category);
+ setSubcategory(subcategory);
+}
+
+public List<Category> choices0Categorize() {
+ return categoryRepository.allCategories();
+}
+public List<Subcategory> choices1Categorize( // <.>
+ Category category) {
+ return subcategoryRepository.findBy(category);
+}
+----
+<.> Returns a list of choices for the 2nd parameter based on the argument provided for the first.
+
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/globally-defined-dropdowns.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/globally-defined-dropdowns.adoc
new file mode 100644
index 0000000000..5ab2d46bcf
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/globally-defined-dropdowns.adoc
@@ -0,0 +1,66 @@
+= "Globally" defined drop-downs
+
+: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:
+
+
+Very often the set of available choices depends on the data type of the property/action parameter, rather than the individual property/parameter itself.
+And similarly the algorithm to search for references again may well depend only on that reference type.
+
+In the case of _choices_, annotating a class as "bounded" (as in a "bounded" or fixed number of instances) means that a _choices_ drop-down will automatically be defined.
+For example:
+
+[source,java]
+----
+@DomainObject(
+ bounded = true
+)
+public class Product { /* ... */ }
+----
+
+For more on this, see xref:refguide:applib:index/annotation/DomainObject.adoc#bounding[@DomainObject#bounding].
+
+Or, if the data type is an enum, then a drop-down will be provided automatically.
+A payment method is a good example of this:
+
+
+[source,java]
+----
+public enum PaymentMethod {
+ VISA, MASTERCARD, AMEX;
+}
+----
+
+Something similar can be achieved for _autoComplete_.
+Here the domain object indicates a repository query to execute.
+For example:
+
+[source,java]
+----
+@DomainObject(
+ autoCompleteRepository = Customers.class,
+ autoCompleteMethod = "findByReferenceOrName"
+)
+public class Customer { /* ... */ }
+----
+
+with:
+
+[source,java]
+.Customers.java
+----
+@DomainService(nature = NatureOfService.VIEW)
+public class Customers {
+ @Action(semantics=SemanticsOf.SAFE)
+ public List<Customer> findByReferenceOrName(@MinLength(3) String refOrName) {
+ ...
+ }
+}
+----
+
+For more on this, see xref:refguide:applib:index/annotation/DomainObject.adoc#autoCompleteRepository[@DomainObject#autoCompleteRepository].
+
+[TIP]
+====
+There's no need for the nominated method to be an actual action; any method of any domain service will do, so long as it accepts a string and returns the correct list.
+====
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/multi-select-dropdowns.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/multi-select-dropdowns.adoc
new file mode 100644
index 0000000000..ed538c61ef
--- /dev/null
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/multi-select-dropdowns.adoc
@@ -0,0 +1,27 @@
+= Multi-select action parameters
+
+: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:
+
+
+
+As well as scalar values, action parameters can also be collections.
+For this to be valid, a _choices_ or _autoComplete_ supporting method must be provided.
+
+For example, suppose we want to "tag" or "label" an object:
+
+[source,java]
+----
+public StoryCard tag(List<Tag> tags) {
+ getTags().addAll(tags);
+}
+
+public List<Tag> autoCompleteTag(@MinLength(1) search) {
+ return tagRepository.findByName(search);
+}
+----
+
+
+If the action has been associated with a collection, using xref:refguide:applib:index/annotation/Action.adoc#choicesFrom[@Action#choicesFrom()], then the collection can be used to provide a list of candidate values.
+
+The xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] handles this by rendering checkboxes against the associated collection; the user can select/deselect these checkboxes and the selected items are taken as the values for the multi-select action.
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
deleted file mode 100644
index 4284ccdc9b..0000000000
--- a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
+++ /dev/null
@@ -1,269 +0,0 @@
-[[programming-model]]
-= Programming Model
-
-: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:
-
-
-Choices, defaults and auto-complete are defined using supporting methods, whose name has an appropriate prefix and returns the appropriate data type.
-But there are several different conventions available; choose the one that works best for you.
-
-== Choices
-
-A drop-down list of _choices_ for a property are specified using:
-
-[source,java]
-.Customer.java
-----
-import lombok.Getter;
-import lombok.Setter;
-
-public class Customer {
-
- @Property(editing = Editing.ENABLED) // <.>
- @Getter @Setter
- private String paymentMethod;
-
- public List<String> choicesPaymentMethod() { // <.>
- return Arrays.asList("Visa", "Mastercard", "Amex");
- }
-
- // ...
-}
-----
-<.> If required; properties are by default disabled globally.
-<.> Note the "choices" prefix and the suffix matching up with the getter.
-The method must return a collection of the same type as the property.
-
-For an action, the _choices_ for the N-th parameter can be specified by "number":
-
-[source,java]
-.Customer.java
-----
-public class Customer {
-
- public Order invoice(
- ShoppingCart cart,
- String paymentMethod,
- DiscountVoucher voucher,
- LocalDate shipBy) {
- ...
- return this;
- }
-
- public List<String> choices1Invoice() { // <.>
- return this.getPaymentMethods();
- }
-
- // ...
-}
-----
-<.> "choices" prefix, N-th param, suffix matches up with the action's name. +
-Returns a collection of the same type as the parameter.
-
-
-== Default
-
-For properties, there is no concept of a default value ; just initialize the field to an appropriate value the object is created.
-For actions, though, providing a default value for its parameters can substantially improve the user experience.
-
-For an action, the _choices_ for the N-th parameter can be specified by "number":
-
-[source,java]
-.Customer.java
-----
-public class Customer {
-
- public Order invoice(
- ShoppingCart cart,
- String paymentMethod,
- DiscountVoucher voucher,
- LocalDate shipBy) {
- ...
- return this;
- }
-
- public String default1Invoice() { // <.>
- return this.getPaymentMethod(); // <.>
- }
-
- // ...
-}
-----
-<.> "default" prefix, N-th param, the suffix matches up with the action's name. +
-Returns object of same type as parameter.
-<.> A common idiom is to return the current value of a property of the object.
-
-
-
-== AutoComplete
-
-The _autocomplete_ is similar to _choices_, but accepts a string parameter, to search for matching results.
-A property for example might have:
-
-[source,java]
-.Order.java
-----
-public class Order {
-
- @Property(editing = Editing.ENABLED) // <.>
- @Getter @Setter
- private Product product;
-
- public List<Product> autoCompleteProduct( // <.>
- @MinLength(2) String search) { // <.>
- return productRepository.findByReferenceOrName(search);
- }
-
- // ...
-}
-----
-<.> If required; properties are by default disabled globally.
-<.> "autoComplete" prefix, suffix matches property name. +
-Returns a collection of the property's type.
-<.> The `@MinLength(...)` annotation indicates the minimum number of characters that must be entered before a search is initiated.
-
-Actions are very similar.
-Here the supporting "autoComplete" method is matched by number:
-
-[source,java]
-.Order.java
-----
-public class Order {
-
- public Order changeProduct(Product product) {
- setProduct(product);
- return this;
- }
-
- public List<Product> autoComplete0Product( // <.>
- @MinLength(2) String search) {
- return productRepository.findByReferenceOrName(search);
- }
-
- // ...
-}
-----
-<.> "autoComplete" prefix, N-th param, suffix matches action name. +
-Returns a collection of the parameters type.
-
-An _autoComplete_ method can be used in conjunction with a _default_ method, but it doesn't make sense to provide both an _autoComplete_ and a _choices_ method.
-
-
-
-== "Globally" defined drop-downs
-
-Very often the set of available choices depends on the data type of the property/action parameter, rather than the individual property/parameter itself.
-And similarly the algorithm to search for references again may well depend only on that reference type.
-
-In the case of _choices_, annotating a class as "bounded" (as in a "bounded" or fixed number of instances) means that a _choices_ drop-down will automatically be defined.
-For example:
-
-[source,java]
-----
-@DomainObject(
- bounded = true
-)
-public class Product { /* ... */ }
-----
-
-For more on this, see xref:refguide:applib:index/annotation/DomainObject.adoc#bounding[@DomainObject#bounding].
-
-Or, if the data type is an enum, then a drop-down will be provided automatically.
-A payment method is a good example of this:
-
-
-[source,java]
-----
-public enum PaymentMethod {
- VISA, MASTERCARD, AMEX;
-}
-----
-
-Something similar can be achieved for _autoComplete_.
-Here the domain object indicates a repository query to execute.
-For example:
-
-[source,java]
-----
-@DomainObject(
- autoCompleteRepository = Customers.class,
- autoCompleteMethod = "findByReferenceOrName"
-)
-public class Customer { /* ... */ }
-----
-
-with:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.VIEW)
-public class Customers {
- @Action(semantics=SemanticsOf.SAFE)
- public List<Customer> findByReferenceOrName(@MinLength(3) String refOrName) {
- ...
- }
-}
-----
-
-For more on this, see xref:refguide:applib:index/annotation/DomainObject.adoc#autoCompleteRepository[@DomainObject#autoCompleteRepository].
-
-[TIP]
-====
-There's no need for the nominated method to be an actual action; any method of any domain service will do, so long as it accepts a string and returns the correct list.
-====
-
-
-== Multi-select action parameters
-
-As well as scalar values, action parameters can also be collections.
-For this to be valid, a _choices_ or _autoComplete_ supporting method must be provided.
-
-For example, suppose we want to "tag" or "label" an object:
-
-[source,java]
-----
-public StoryCard tag(List<Tag> tags) {
- getTags().addAll(tags);
-}
-
-public List<Tag> autoCompleteTag(@MinLength(1) search) {
- return tagRepository.findByName(search);
-}
-----
-
-
-If the action has been associated with a collection, using xref:refguide:applib:index/annotation/Action.adoc#choicesFrom[@Action#choicesFrom()], then the collection can be used to provide a list of candidate values.
-
-The xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] handles this by rendering checkboxes against the associated collection; the user can select/deselect these checkboxes and the selected items are taken as the values for the multi-select action.
-
-
-
-== Dependent choices for action parameters
-
-For action it is also possible (in a limited form) to define dependencies between parameters.
-Specifically, if one parameter is a drop-down choice, then other drop-down choices can be derived from it.
-
-A good example is a category/sub-category:
-
-[source,java]
-----
-public ToDoItem categorize(
- Category category,
- Subcategory subcategory) {
- setCategory(category);
- setSubcategory(subcategory);
-}
-
-public List<Category> choices0Categorize() {
- return categoryRepository.allCategories();
-}
-public List<Subcategory> choices1Categorize( // <.>
- Category category) {
- return subcategoryRepository.findBy(category);
-}
-----
-<.> Returns a list of choices for the 2nd parameter based on the argument provided for the first.
-
-p
-
[causeway] 01/02: CAUSEWAY-3395 : updates to user guide (object members)
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 667f1cd763a894355e8c549f80c360894660d6cf
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Jun 20 06:48:18 2023 +0100
CAUSEWAY-3395 : updates to user guide (object members)
---
...PropertyLayout-FieldSet-examples-and-usage.adoc | 4 +-
.../hooks/ActionLayout_010-examples-and-usage.adoc | 4 +-
.../CollectionLayout_010-examples-and-usage.adoc | 4 +-
.../annotation/hooks/Collection_022_hidden.adoc | 2 +-
.../DomainObjectLayout_010-examples-and-usage.adoc | 2 +-
.../hooks/HomePage_010-examples-and-usage.adoc | 2 +-
.../ParameterLayout_010-examples-and-usage.adoc | 2 +-
.../PropertyLayout_010-examples-and-usage.adoc | 4 +-
.../hooks/Object_downloadLayout_see-also.adoc | 2 +-
.../modules/applib-ant/partials/about/main.adoc | 4 +-
.../modules/applib-classes/pages/about.adoc | 2 +-
.../applib-methods/partials/ui-hints/layout.adoc | 2 +-
.../petclinic/pages/010-getting-started.adoc | 6 +-
.../userguide/modules/ROOT/pages/about.adoc | 4 +-
.../userguide/modules/ROOT/pages/modules.adoc | 2 +-
.../userguide/modules/ROOT/pages/overview.adoc | 8 +-
...rs.adoc => properties-collections-actions.adoc} | 10 +-
.../_intro.adoc => pages/ui-layout-and-hints.adoc} | 16 ++-
.../ROOT/partials/domain-services/progmodel.adoc | 2 +-
.../partials/drop-down-and-defaults/progmodel.adoc | 124 +++++++++++++++------
.../modules/ROOT/partials/events/progmodel.adoc | 4 +-
.../modules/ROOT/partials/module-nav.adoc | 4 +-
.../_intro.adoc | 8 +-
.../actions.adoc | 4 +-
.../collections.adoc | 6 +-
.../progmodel.adoc | 0
.../properties.adoc | 6 +-
.../ROOT/partials/the-theory/metamodel.adoc | 2 +-
.../ui-layout-and-hints/_intro.adoc} | 19 +---
.../action-icons-and-css.adoc | 2 +-
.../menubars-layout.adoc | 2 +-
.../names-and-descriptions.adoc | 0
.../{ui => ui-layout-and-hints}/object-layout.adoc | 0
.../object-titles-and-icons.adoc | 6 +-
.../{ui => ui-layout-and-hints}/progmodel.adoc | 0
.../{ui => ui-layout-and-hints}/table-columns.adoc | 0
.../btb/partials/programming-model/_intro.adoc | 2 +-
.../application-specific/application-css.adoc | 2 +-
.../adoc/modules/commandlog/pages/about.adoc | 2 +-
.../adoc/modules/executionlog/pages/about.adoc | 2 +-
.../ROOT/pages/customisation/custom-css.adoc | 2 +-
41 files changed, 170 insertions(+), 109 deletions(-)
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action-Collection-PropertyLayout-FieldSet-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action-Collection-PropertyLayout-FieldSet-examples-and-usage.adoc
index ce1c42b001..25e1d8c6fa 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action-Collection-PropertyLayout-FieldSet-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action-Collection-PropertyLayout-FieldSet-examples-and-usage.adoc
@@ -20,7 +20,7 @@ xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout]
=== Properties
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:ROOT:ui.adoc#object-layout[layout files].
+It corresponds to a `<fieldset>` if using xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout files].
For example:
@@ -54,7 +54,7 @@ public class Customer {
}
----
-TIP: It's possible to combine `@PropertyLayout` with xref:userguide:ROOT:ui.adoc#object-layout[layout file].
+TIP: It's possible to combine `@PropertyLayout` with xref:userguide:ROOT:ui-layout-and-hints.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
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 4e9aaacf23..70a9ece575 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
@@ -29,9 +29,9 @@ public class ToDoItems {
[TIP]
====
-As an alternative to using the `@ActionLayout` annotation, a xref:userguide:ROOT:ui.adoc#object-layout[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:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
== Usage Notes
-As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui.adoc#object-layout[file-based layout] can generally be used instead.
+As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
index ed5c0b885a..e927f64c0c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
@@ -22,7 +22,7 @@ public class ToDoItem {
[TIP]
====
-As an alternative to using the `@CollectionLayout` annotation, a xref:userguide:ROOT:ui.adoc#object-layout[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:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
[TIP]
@@ -33,4 +33,4 @@ This is specifically so that boilerplate-busting tools such as link:https://proj
== Usage Notes
-As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui.adoc#object-layout[file-based layout] can generally be used instead.
+As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Collection_022_hidden.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Collection_022_hidden.adoc
index 5c5fdde70b..71fa3fb3ab 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Collection_022_hidden.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Collection_022_hidden.adoc
@@ -46,5 +46,5 @@ public class Customer {
==== Alternatives
-It is also possible to use xref:refguide:applib:index/annotation/CollectionLayout.adoc#hidden[@CollectionLayout#hidden] or using xref:userguide:ROOT:ui.adoc#object-layout[file-based layout] such that the collection can be hidden at the view layer.
+It is also possible to use xref:refguide:applib:index/annotation/CollectionLayout.adoc#hidden[@CollectionLayout#hidden] or using xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] such that the collection can be hidden at the view layer.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_010-examples-and-usage.adoc
index 818da28425..9a1826e61b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_010-examples-and-usage.adoc
@@ -22,7 +22,7 @@ public class ToDoItem {
[NOTE]
====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:userguide:ROOT:ui.adoc#object-layout[.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:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file (only for properties, collections and actions are supported).
====
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/HomePage_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/HomePage_010-examples-and-usage.adoc
index 6e947c2b2f..191a432aa5 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/HomePage_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/HomePage_010-examples-and-usage.adoc
@@ -22,7 +22,7 @@ public class TodoAppDashboard {
public Blob exportToWordDoc() { /* ... */ } // <.>
}
----
-<.> associated using xref:userguide:ROOT:ui.adoc#object-layout[file-based layout] with the `notYetComplete` collection.
+<.> associated using xref:userguide:ROOT:ui-layout-and-hints.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/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_010-examples-and-usage.adoc
index 6260b8842e..65415bb835 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_010-examples-and-usage.adoc
@@ -28,7 +28,7 @@ public class ToDoItem {
[NOTE]
====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:userguide:ROOT:ui.adoc#object-layout[.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:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file (only for properties, collections and actions are supported).
====
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
index a2c2529379..83995cdbe6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
@@ -26,7 +26,7 @@ public class ToDoItem {
[TIP]
====
-As an alternative to using the `@PropertyLayout` annotation, a xref:userguide:ROOT:ui.adoc#object-layout[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:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
====
@@ -42,4 +42,4 @@ so that boilerplate-busting tools such as link:https://projectlombok.org/[Projec
== Usage Notes
-As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui.adoc#object-layout[file-based layout] can generally be used instead.
+As alternative to using the annotation, the dynamic xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/mixins/layout/hooks/Object_downloadLayout_see-also.adoc b/antora/components/refguide-index/modules/applib/pages/index/mixins/layout/hooks/Object_downloadLayout_see-also.adoc
index 93bbfd02c7..a8ecb95521 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/mixins/layout/hooks/Object_downloadLayout_see-also.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/mixins/layout/hooks/Object_downloadLayout_see-also.adoc
@@ -5,7 +5,7 @@
== See also
-* the structure of the xref:userguide:ROOT:ui.adoc#object-layout[layout XML] is described in the user guide.
+* the structure of the xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout XML] is described in the user guide.
* xref:refguide:applib:index/services/layout/LayoutService.adoc[LayoutService]
diff --git a/antora/components/refguide/modules/applib-ant/partials/about/main.adoc b/antora/components/refguide/modules/applib-ant/partials/about/main.adoc
index d5765e1529..5917e24736 100644
--- a/antora/components/refguide/modules/applib-ant/partials/about/main.adoc
+++ b/antora/components/refguide/modules/applib-ant/partials/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:userguide:ROOT:ui.adoc#object-layout[dynamic object layout].
+Most UI semantics can also be specified using xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[dynamic object layout].
====
@@ -23,7 +23,7 @@ The table below summarizes these most commonly used annotations in Apache Causew
|Annotation
|Purpose
|Layer
-|xref:userguide:ROOT:ui.adoc#object-layout[File-based layout]?
+|xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[File-based layout]?
|xref:refguide:applib:index/annotation/Action.adoc[@Action]
|Domain semantics for actions
diff --git a/antora/components/refguide/modules/applib-classes/pages/about.adoc b/antora/components/refguide/modules/applib-classes/pages/about.adoc
index 6a71fd8b89..52a2dad9a3 100644
--- a/antora/components/refguide/modules/applib-classes/pages/about.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/about.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 [...]
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:refguide:applib-svc:about.adoc[domain services], xref:userguide:ROOT:ui.adoc#object-layout[object layout] or xref:refguide:config:about.adoc[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:refguide:applib-svc:about.adoc[domain services], xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[object layout] or xref:refguide:config:about.adoc[configuration].
diff --git a/antora/components/refguide/modules/applib-methods/partials/ui-hints/layout.adoc b/antora/components/refguide/modules/applib-methods/partials/ui-hints/layout.adoc
index 918e635e53..041dee7304 100644
--- a/antora/components/refguide/modules/applib-methods/partials/ui-hints/layout.adoc
+++ b/antora/components/refguide/modules/applib-methods/partials/ui-hints/layout.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 [...]
-Every object has a xref:userguide:ROOT:ui.adoc#object-layout[layout] .
+Every object has a xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout] .
This may be specified using annotations such as
xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout],
xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout],
diff --git a/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc b/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
index 31d408aaf1..dd829dd04d 100644
--- a/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
+++ b/antora/components/tutorials/modules/petclinic/pages/010-getting-started.adoc
@@ -207,10 +207,10 @@ This is modelled upon bootstrap and so supports arbitrary rows and columns as we
** for example, with IntelliJ use menu:Run[Debugging Actions > Reload Changed Classes].
-You can learn more about file-based layouts in the fundamentals guide describing at xref:userguide:ROOT:ui.adoc#object-layout[Object Layout]s.
+You can learn more about file-based layouts in the fundamentals guide describing at xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[Object Layout]s.
It's also possible to change the order of columns at runtime, using the `SimpleObject.columnOrder.txt` file.
-For more on this topic, see the section of the fundamentals guide describing xref:userguide:ROOT:ui.adoc#table-columns[Table Columns].
+For more on this topic, see the section of the fundamentals guide describing xref:userguide:ROOT:ui-layout-and-hints.adoc#table-columns[Table Columns].
@@ -227,5 +227,5 @@ In a similar fashion, the actions of the various domain services are grouped int
** for example, with IntelliJ use menu:Run[Debugging Actions > Reload Changed Classes]/
-To learn more, see the section of the fundamentals guide describing xref:userguide:ROOT:ui.adoc#file-based-menus[file-based] menu bar layout.
+To learn more, see the section of the fundamentals guide describing xref:userguide:ROOT:ui-layout-and-hints.adoc#file-based-menus[file-based] menu bar layout.
diff --git a/antora/components/userguide/modules/ROOT/pages/about.adoc b/antora/components/userguide/modules/ROOT/pages/about.adoc
index 3584ce31ec..690aa7b188 100644
--- a/antora/components/userguide/modules/ROOT/pages/about.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/about.adoc
@@ -27,12 +27,12 @@ Domain services are (typically) singletons that act upon entities.
Common implementations are repositories (to find domain entities) or factories (to create entities), but they might also be holders of business logic that for whatever reason you want to keep outside an entity; perhaps it easier to test that way.
An example might be `InvoiceCalculationServices`.
-* xref:userguide:ROOT:object-members.adoc[Properties, Collections & Actions]
+* xref:userguide:ROOT:properties-collections-actions.adoc[Properties, Collections & Actions]
+
Properties and collections are the state that is maintained by domain entities (above), while actions can reside on either a domain entity or domain service.
The framework automatically exposes this state and behaviour in the user interface (unless you otherwise suppress it).
-* xref:userguide:ROOT:ui.adoc[UI Layout & Hints]
+* xref:userguide:ROOT:ui-layout-and-hints.adoc[UI Layout & Hints]
+
As noted above, Apache Causeway applications do not require you to write code to render your domain objects in the UI; the framework provides a generic UI.
But the framework _does_ allow you to provide optional hints so that the domain objects appear in the UI the way that you want them to appear.
diff --git a/antora/components/userguide/modules/ROOT/pages/modules.adoc b/antora/components/userguide/modules/ROOT/pages/modules.adoc
index f6b3df5d16..143ad35bca 100644
--- a/antora/components/userguide/modules/ROOT/pages/modules.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/modules.adoc
@@ -49,7 +49,7 @@ A common technique is to factor out from domain objects into mixins and then gen
* the internal xref:refguide:applib:index/services/eventbus/EventBusService.adoc[event bus] allows modules to influence other modules.
+
A subscriber in one module can subscribe to events emitted by domain objects in another module.
-These events can affect both the UI (eg hiding or disabling xref:object-members.adoc[object members], or allowing or vetoing interactions).
+These events can affect both the UI (eg hiding or disabling xref:properties-collections-actions.adoc[object members], or allowing or vetoing interactions).
A good example of this last is supporting (what in an RDBMS we would call) referential integrity.
Suppose the `customers` module has a `Customer` object and a `EmailAddress` object, with a customer having a collection of email addresses.
diff --git a/antora/components/userguide/modules/ROOT/pages/overview.adoc b/antora/components/userguide/modules/ROOT/pages/overview.adoc
index 60f198bad7..2f327745f0 100644
--- a/antora/components/userguide/modules/ROOT/pages/overview.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/overview.adoc
@@ -15,7 +15,7 @@ From the end-user's perspective the UI displays a single domain object instance
These will be either a xref:domain-entities.adoc[domain entity] (persisted state) or a xref:view-models.adoc[view model] (user-specific temporary state).
To access them, a menu xref:domain-services.adoc[domain service] will be used to find from the database (a repository service) or occasionally to create a new instance (a factory service).
-The state managed by entities and view models is expressed in terms of xref:object-members.adoc[properties and collections], with properties either referring to other domain objects or alternatively to values.
+The state managed by entities and view models is expressed in terms of xref:properties-collections-actions.adoc[properties and collections], with properties either referring to other domain objects or alternatively to values.
These values will have xref:value-types.adoc[value types] that are either built-in (such as primitives, strings or dates_, 3rd party or custom.
Actions allow the end-user to invoke business logic.
@@ -34,17 +34,17 @@ Similarly, JAXB annotations are often used for xref:view-models.adoc[view models
The framework also defines supplementary annotations, notably xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@DomainObjectLayout] and xref:refguide:applib:index/annotation/DomainServiceLayout.adoc[@DomainServiceLayout].
These provide hints relating to the layout of the domain object in the user interface.
-Alternatively, these UI hints might be defined in a supplementary xref:userguide:ROOT:ui.adoc#object-layout[.layout.xml] file.
+Alternatively, these UI hints might be defined in a supplementary xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file.
[[title-and-icon-and-css-class]]
== Title and Icon
-To allow the end-user to distinguish one domain object from another, it is rendered with a xref:ui.adoc#object-title[title] and an xref:ui.adoc#object-icon[icon].
+To allow the end-user to distinguish one domain object from another, it is rendered with a xref:ui-layout-and-hints.adoc#object-title[title] and an xref:ui-layout-and-hints.adoc#object-icon[icon].
The icon informally identifies the type of the domain object, while the title identifies the instance.
-It's also possible to customise other aspects of the domain object's presentation within the xref:ui.adoc[user interface].
+It's also possible to customise other aspects of the domain object's presentation within the xref:ui-layout-and-hints.adoc[user interface].
diff --git a/antora/components/userguide/modules/ROOT/pages/object-members.adoc b/antora/components/userguide/modules/ROOT/pages/properties-collections-actions.adoc
similarity index 68%
rename from antora/components/userguide/modules/ROOT/pages/object-members.adoc
rename to antora/components/userguide/modules/ROOT/pages/properties-collections-actions.adoc
index 26e22bb8d3..b4d3ddfdc9 100644
--- a/antora/components/userguide/modules/ROOT/pages/object-members.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/properties-collections-actions.adoc
@@ -1,4 +1,4 @@
-= Object Members
+= Properties, Collections & Actions
: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 [...]
@@ -6,7 +6,7 @@
-include::partial$object-members/_intro.adoc[leveloffset=+1]
-include::partial$object-members/properties.adoc[leveloffset=+1]
-include::partial$object-members/collections.adoc[leveloffset=+1]
-include::partial$object-members/actions.adoc[leveloffset=+1]
+include::partial$properties-collections-actions/_intro.adoc[leveloffset=+1]
+include::partial$properties-collections-actions/properties.adoc[leveloffset=+1]
+include::partial$properties-collections-actions/collections.adoc[leveloffset=+1]
+include::partial$properties-collections-actions/actions.adoc[leveloffset=+1]
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/_intro.adoc b/antora/components/userguide/modules/ROOT/pages/ui-layout-and-hints.adoc
similarity index 57%
rename from antora/components/userguide/modules/ROOT/partials/ui/_intro.adoc
rename to antora/components/userguide/modules/ROOT/pages/ui-layout-and-hints.adoc
index b55cfe7faa..fb5effc922 100644
--- a/antora/components/userguide/modules/ROOT/partials/ui/_intro.adoc
+++ b/antora/components/userguide/modules/ROOT/pages/ui-layout-and-hints.adoc
@@ -1,6 +1,18 @@
-[[introduction]]
-= Introduction
+[#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:
+
+
+
+include::partial$ui-layout-and-hints/_intro.adoc[leveloffset=+1]
+include::partial$ui-layout-and-hints/names-and-descriptions.adoc[leveloffset=+1]
+include::partial$ui-layout-and-hints/object-titles-and-icons.adoc[leveloffset=+1]
+include::partial$ui-layout-and-hints/action-icons-and-css.adoc[leveloffset=+1]
+
+include::partial$ui-layout-and-hints/menubars-layout.adoc[leveloffset=+1]
+include::partial$ui-layout-and-hints/object-layout.adoc[leveloffset=+1]
+
+include::partial$ui-layout-and-hints/table-columns.adoc[leveloffset=+1]
diff --git a/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
index 24662cc2f3..0ec314f9d5 100644
--- a/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/domain-services/progmodel.adoc
@@ -57,7 +57,7 @@ The menu service:
Menu services provide actions to be rendered on the menu.
For the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)], each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.
-Although these can be organised using annotations, it's usually easier to use a xref:userguide:ROOT:ui.adoc#file-based-menus[file-based layout file] (`menubars.layout.xml`).
+Although these can be organised using annotations, it's usually easier to use a xref:userguide:ROOT:ui-layout-and-hints.adoc#file-based-menus[file-based layout file] (`menubars.layout.xml`).
For the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)], all menu services are shown in the services representation.
diff --git a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
index 8b5154639c..4284ccdc9b 100644
--- a/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/drop-down-and-defaults/progmodel.adoc
@@ -5,48 +5,95 @@
:page-partial:
-== Choices and Default
+Choices, defaults and auto-complete are defined using supporting methods, whose name has an appropriate prefix and returns the appropriate data type.
+But there are several different conventions available; choose the one that works best for you.
-For example, _choices_ for a property are specified using:
+== Choices
+
+A drop-down list of _choices_ for a property are specified using:
[source,java]
+.Customer.java
----
import lombok.Getter;
import lombok.Setter;
-@Property(editing = Editing.ENABLED) // <.>
-@Getter @Setter
-private String paymentMethod;
+public class Customer {
+
+ @Property(editing = Editing.ENABLED) // <.>
+ @Getter @Setter
+ private String paymentMethod;
-public List<String> choicesPaymentMethod() { // <.>
- return Arrays.asList("Visa", "Mastercard", "Amex");
+ public List<String> choicesPaymentMethod() { // <.>
+ return Arrays.asList("Visa", "Mastercard", "Amex");
+ }
+
+ // ...
}
----
<.> If required; properties are by default disabled globally.
<.> Note the "choices" prefix and the suffix matching up with the getter.
The method must return a collection of the same type as the property.
-For an action the _choices_ and a suitable _default_ method would be:
+For an action, the _choices_ for the N-th parameter can be specified by "number":
[source,java]
+.Customer.java
----
-public Order changePaymentMethod(String paymentMethod) {
- setPaymentMethod(paymentMethod);
- return this;
-}
+public class Customer {
-public List<String> choices0ChangePaymentMethod() { // <.>
- return Arrays.asList("Visa", "Mastercard", "Amex");
-}
-public String default0ChangePaymentMethod() { // <.>
- return getPaymentMethod(); // <.>
+ public Order invoice(
+ ShoppingCart cart,
+ String paymentMethod,
+ DiscountVoucher voucher,
+ LocalDate shipBy) {
+ ...
+ return this;
+ }
+
+ public List<String> choices1Invoice() { // <.>
+ return this.getPaymentMethods();
+ }
+
+ // ...
}
----
<.> "choices" prefix, N-th param, suffix matches up with the action's name. +
Returns a collection of the same type as the parameter.
+
+
+== Default
+
+For properties, there is no concept of a default value ; just initialize the field to an appropriate value the object is created.
+For actions, though, providing a default value for its parameters can substantially improve the user experience.
+
+For an action, the _choices_ for the N-th parameter can be specified by "number":
+
+[source,java]
+.Customer.java
+----
+public class Customer {
+
+ public Order invoice(
+ ShoppingCart cart,
+ String paymentMethod,
+ DiscountVoucher voucher,
+ LocalDate shipBy) {
+ ...
+ return this;
+ }
+
+ public String default1Invoice() { // <.>
+ return this.getPaymentMethod(); // <.>
+ }
+
+ // ...
+}
+----
<.> "default" prefix, N-th param, the suffix matches up with the action's name. +
Returns object of same type as parameter.
-<.> Common idiom to return the current value of an property of the object.
+<.> A common idiom is to return the current value of a property of the object.
+
== AutoComplete
@@ -55,14 +102,20 @@ The _autocomplete_ is similar to _choices_, but accepts a string parameter, to s
A property for example might have:
[source,java]
+.Order.java
----
-@Property(editing = Editing.ENABLED) // <.>
-@Getter @Setter
-private Product product;
+public class Order {
-public List<Product> autoCompleteProduct( // <.>
- @MinLength(2) String search) { // <.>
- return productRepository.findByReferenceOrName(search);
+ @Property(editing = Editing.ENABLED) // <.>
+ @Getter @Setter
+ private Product product;
+
+ public List<Product> autoCompleteProduct( // <.>
+ @MinLength(2) String search) { // <.>
+ return productRepository.findByReferenceOrName(search);
+ }
+
+ // ...
}
----
<.> If required; properties are by default disabled globally.
@@ -70,18 +123,25 @@ public List<Product> autoCompleteProduct( // <.>
Returns a collection of the property's type.
<.> The `@MinLength(...)` annotation indicates the minimum number of characters that must be entered before a search is initiated.
-Actions are very similar:
+Actions are very similar.
+Here the supporting "autoComplete" method is matched by number:
[source,java]
+.Order.java
----
-public Order changeProduct(Product product) {
- setProduct(product);
- return this;
-}
+public class Order {
+
+ public Order changeProduct(Product product) {
+ setProduct(product);
+ return this;
+ }
+
+ public List<Product> autoComplete0Product( // <.>
+ @MinLength(2) String search) {
+ return productRepository.findByReferenceOrName(search);
+ }
-public List<Product> autoComplete0Product( // <.>
- @MinLength(2) String search) {
- return productRepository.findByReferenceOrName(search);
+ // ...
}
----
<.> "autoComplete" prefix, N-th param, suffix matches action name. +
diff --git a/antora/components/userguide/modules/ROOT/partials/events/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/events/progmodel.adoc
index 665767a63f..68fe5a19ce 100644
--- a/antora/components/userguide/modules/ROOT/partials/events/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/events/progmodel.adoc
@@ -41,13 +41,13 @@ For more details on the actual domain event classes, see the xref:refguide:appli
As explained xref:userguide:ROOT:overview.adoc#title-and-icon-and-css-class[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
-xref:userguide:ROOT:ui.adoc#object-titles-and-icons[Normally] the code to return title and icon of an object is part of the domain object's implementation.
+xref:userguide:ROOT:ui-layout-and-hints.adoc#object-titles-and-icons[Normally] the code to return title and icon of an object is part of the domain object's implementation.
However, UI events allow this title and icon to be provided instead by a subscriber.
UI events have higher precedence than the other mechanisms of supplying a title.
If annotated with xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#titleUiEvent[@DomainObjectLayout#titleUiEvent()], the appropriate (subclass of) `TitleUiEvent` will be emitted.
Similarly for xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#iconUiEvent[#iconUiEvent()].
-In addition, it is possible to use events to obtain a CSS class to render with the domain object, using xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassUiEvent[#cssClassUiEvent()], and to select an alternate xref:userguide:ROOT:ui.adoc#object-layout[layout file] using xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#layoutUiEvent[#layoutUiEvent()].
+In addition, it is possible to use events to obtain a CSS class to render with the domain object, using xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassUiEvent[#cssClassUiEvent()], and to select an alternate xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout file] using xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#layoutUiEvent[#layoutUiEvent()].
There are two use cases where this feature is useful:
diff --git a/antora/components/userguide/modules/ROOT/partials/module-nav.adoc b/antora/components/userguide/modules/ROOT/partials/module-nav.adoc
index 91fa33814b..fd29412f0d 100644
--- a/antora/components/userguide/modules/ROOT/partials/module-nav.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/module-nav.adoc
@@ -1,8 +1,8 @@
* xref:userguide::overview.adoc[10,000ft overview]
* xref:userguide::domain-entities.adoc[Domain Entities]
* xref:userguide::domain-services.adoc[Domain Services]
-* xref:userguide::object-members.adoc[Properties, Collections & Actions]
-* xref:userguide::ui.adoc[UI Layout & Hints]
+* xref:userguide::properties-collections-actions.adoc[Properties, Collections & Actions]
+* xref:userguide::ui-layout-and-hints.adoc[UI Layout & Hints]
* xref:userguide::business-rules.adoc[Business Rules]
* xref:userguide::drop-downs-and-defaults.adoc[Drop downs & Defaults]
* xref:userguide::view-models.adoc[View Models]
diff --git a/antora/components/userguide/modules/ROOT/partials/object-members/_intro.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/_intro.adoc
similarity index 93%
rename from antora/components/userguide/modules/ROOT/partials/object-members/_intro.adoc
rename to antora/components/userguide/modules/ROOT/partials/properties-collections-actions/_intro.adoc
index 63928cb2cd..5ef3ac56d2 100644
--- a/antora/components/userguide/modules/ROOT/partials/object-members/_intro.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/_intro.adoc
@@ -34,11 +34,11 @@ public class Customer {
}
----
<.> Depending on configuration settings, the xref:refguide:applib:index/annotation/Property.adoc[@Property] annotation may or may not be required; its role is to define additional domain-layer semantics
-<.> The xref:refguide:applib:index/annotation/PropertyLayout.adoc[@PropertyLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui.adoc#object-layout[layout.xml] file.
+<.> The xref:refguide:applib:index/annotation/PropertyLayout.adoc[@PropertyLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui-layout-and-hints.adoc#object-layout[layout.xml] file.
<.> It's commonplace to use link:https://projectlombok.org/features/GetterSetter[Project Lombok] to remove boilerplate.
As there is a `@Setter`, this property may also editable (though this does also depend on configuration settings).
<.> Depending on configuration settings, the xref:refguide:applib:index/annotation/Collection.adoc[@Collection] annotation may or may not be required; its role is to define additional domain-layer semantics
-<.> The xref:refguide:applib:index/annotation/CollectionLayout.adoc[@CollectionLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui.adoc#object-layout[layout.xml] file.
+<.> The xref:refguide:applib:index/annotation/CollectionLayout.adoc[@CollectionLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui-layout-and-hints.adoc#object-layout[layout.xml] file.
<.> Collections are immutable, so no setter is required.
<.> Typically entities implement `Comparable`, so `SortedSet` is typical.
(For entities, the actual implementation will be replaced by the ORM).
@@ -49,7 +49,7 @@ From this the framework infers the `Customer` domain entity, which in turn has a
[#actions]
== Actions
-While xref:userguide:ROOT:object-members.adoc#properties[properties] and xref:userguide:ROOT:object-members.adoc#collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+While xref:userguide:ROOT:properties-collections-actions.adoc#properties[properties] and xref:userguide:ROOT:properties-collections-actions.adoc#collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
An application that consists only of domain entities with just "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
Such applications are often called CRUD applications (create/read/update/delete).
@@ -91,7 +91,7 @@ public class Customer {
}
----
<.> Depending on configuration settings, the xref:refguide:applib:index/annotation/Action.adoc[@Action] annotation may or may not be required; its role is to define additional domain-layer semantics
-<.> The xref:refguide:applib:index/annotation/ActionLayout.adoc[@ActionLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui.adoc#object-layout[layout.xml] file.
+<.> The xref:refguide:applib:index/annotation/ActionLayout.adoc[@ActionLayout] annotation defines additional presentation-layer hints; alternatively this metadata can be provided using the xref:ui-layout-and-hints.adoc#object-layout[layout.xml] file.
<.> The xref:refguide:applib:index/annotation/Parameter.adoc[@Parameter] annotation defines additional domain-layer semantics.
This is optional though often required.
<.> The xref:refguide:applib:index/annotation/ParameterLayout.adoc[@ParameterLayout] annotation defines additional presentation-layer hints
diff --git a/antora/components/userguide/modules/ROOT/partials/object-members/actions.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc
similarity index 97%
rename from antora/components/userguide/modules/ROOT/partials/object-members/actions.adoc
rename to antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc
index 17f666180e..19f672bfae 100644
--- a/antora/components/userguide/modules/ROOT/partials/object-members/actions.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc
@@ -15,7 +15,7 @@ There are three operations here: set the end date of the original lease term, cr
Instead, all of these operations can be combined into a single action, "renew".
Through such means the xref:background-context-and-theory.adoc#ubiquitous-language[ubiquitous language] grows.
-TIP: This is the reason why Apache Causeway' default is xref:object-members.adoc#editable-properties[non-editable properties]: to encourage this sort of "knowledge crunching".
+TIP: This is the reason why Apache Causeway' default is xref:properties-collections-actions.adoc#editable-properties[non-editable properties]: to encourage this sort of "knowledge crunching".
You can find further discussion on when and why you should write actions xref:overview.adoc#actions[earlier].
@@ -167,7 +167,7 @@ public List<Product> autoComplete0AddToBasket( // <.>
}
----
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:refguide:applib:index/annotation/DomainObject.adoc[@DomainObject] on the referenced type (described xref:userguide:ROOT:object-members.adoc#reference-parameter-types[above]).
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:refguide:applib:index/annotation/DomainObject.adoc[@DomainObject] on the referenced type (described xref:userguide:ROOT:properties-collections-actions.adoc#reference-parameter-types[above]).
== Optional Parameters
diff --git a/antora/components/userguide/modules/ROOT/partials/object-members/collections.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc
similarity index 94%
rename from antora/components/userguide/modules/ROOT/partials/object-members/collections.adoc
rename to antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc
index a07fc7daef..dcc1535301 100644
--- a/antora/components/userguide/modules/ROOT/partials/object-members/collections.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc
@@ -16,7 +16,7 @@ Most collections (those that are modifiable) will also have a setter and, if per
And collections properties will also have a number of annotations:
* Apache Causeway defines its own xref xref:refguide:applib:index/annotation/Collection.adoc[@Collection] annotation for capturing domain semantics.
-It also provides a xref:refguide:applib:index/annotation/CollectionLayout.adoc[@CollectionLayout] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:userguide:ROOT:ui.adoc#object-layout[.layout.xml] file)
+It also provides a xref:refguide:applib:index/annotation/CollectionLayout.adoc[@CollectionLayout] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file)
* the collections of domain entities are often annotated with ORM annotation(s).
In the case of JDO/DataNucleus annotations this is most notably `javax.jdo.annotations.Persistent`.
@@ -26,8 +26,8 @@ Other annotations can be used to specify if the association is bidirectional, an
Apache Causeway may recognise some of these annotations from the persistence layer infers some domain semantics from them.
-Unlike xref:userguide:ROOT:object-members.adoc#properties[properties], the framework does not allow collections to be "edited".
-Instead, xref:userguide:ROOT:object-members.adoc#actions[action]s can be written that will modify the contents of the collection as a side-effect.
+Unlike xref:userguide:ROOT:properties-collections-actions.adoc#properties[properties], the framework does not allow collections to be "edited".
+Instead, xref:userguide:ROOT:properties-collections-actions.adoc#actions[action]s can be written that will modify the contents of the collection as a side-effect.
For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
diff --git a/antora/components/userguide/modules/ROOT/partials/object-members/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/progmodel.adoc
similarity index 100%
rename from antora/components/userguide/modules/ROOT/partials/object-members/progmodel.adoc
rename to antora/components/userguide/modules/ROOT/partials/properties-collections-actions/progmodel.adoc
diff --git a/antora/components/userguide/modules/ROOT/partials/object-members/properties.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/properties.adoc
similarity index 97%
rename from antora/components/userguide/modules/ROOT/partials/object-members/properties.adoc
rename to antora/components/userguide/modules/ROOT/partials/properties-collections-actions/properties.adoc
index 8485bc6ae9..642396921e 100644
--- a/antora/components/userguide/modules/ROOT/partials/object-members/properties.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/properties.adoc
@@ -16,11 +16,11 @@ Most properties (those that are editable/modifiable) will also have a setter and
And most properties will also have a number of annotations:
* Apache Causeway defines its own xref:refguide:applib:index/annotation/Property.adoc[@Property] annotation for capturing domain semantics.
-It also provides a xref:refguide:applib:index/annotation/PropertyLayout.adoc[@PropertyLayout] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:userguide:ROOT:ui.adoc#object-layout[.layout.xml] file)
+It also provides a xref:refguide:applib:index/annotation/PropertyLayout.adoc[@PropertyLayout] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file)
-* the properties of domain entities are usually also annotated with an ORM annotation.
+* the properties of domain entities are usually also annotated with ORM annotation(s).
+
-In the case of xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] this would be the link:http://www.datanucleus.org/products/datanucleus/jdo/annotations.html#Column[@javax.jdo.annotations.Column] annotation.
+For xref:pjpa::about.adoc[JPA/EclipseLink] this would be link:https://www.objectdb.com/api/java/jpa/Column[javax.persistence.Column], for xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] it is link:http://www.datanucleus.org/products/datanucleus/jdo/annotations.html#Column[@javax.jdo.annotations.Column] annotation.
For property references, there may be other annotations to indicate whether the reference is bidirectional.
It's also possible (using annotations) to define a link table to hold foreign key columns.
diff --git a/antora/components/userguide/modules/ROOT/partials/the-theory/metamodel.adoc b/antora/components/userguide/modules/ROOT/partials/the-theory/metamodel.adoc
index 611b24094a..bd503881ce 100644
--- a/antora/components/userguide/modules/ROOT/partials/the-theory/metamodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/the-theory/metamodel.adoc
@@ -21,7 +21,7 @@ The framework integrates an ORM for persistence, specifically DataNucleus and th
Both JDO and JPA can map to both relational databases and also to various NoSQL objectstores such as MongoDB or Neo4J.
Apache Causeway recognizes a number of these persistence-specific annotations, for example `@javax.jdo.annotations.Column(allowsNull=...)`.
-In addition, the framework builds up the metamodel for each domain object using xref:userguide:ROOT:ui.adoc#object-layout[layout hints], such as `Customer.layout.xml`.
+In addition, the framework builds up the metamodel for each domain object using xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout hints], such as `Customer.layout.xml`.
These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on.
The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.
diff --git a/antora/components/userguide/modules/ROOT/pages/ui.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/_intro.adoc
similarity index 77%
rename from antora/components/userguide/modules/ROOT/pages/ui.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/_intro.adoc
index 53a7afb626..7fade2f34e 100644
--- a/antora/components/userguide/modules/ROOT/pages/ui.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/_intro.adoc
@@ -1,10 +1,9 @@
-[#ui-layout-hints]
-= UI Layout & Hints
+[[introduction]]
+= Introduction
: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 Causeway infers as much information from the domain classes as possible.
Nevertheless, some metadata relating solely to the UI is inevitably required.
@@ -12,7 +11,7 @@ The Apache Causeway programming model includes several mechanisms to influence t
* the layout of application menu items (inferred from xref:domain-services.adoc[domain services])
-* the layout of domain objects (xref:domain-entities.adoc[domain entities] and xref:view-models.adoc[view models]) allow the positioning of the xref:object-members.adoc[object members] into columns and tabs
+* the layout of domain objects (xref:domain-entities.adoc[domain entities] and xref:view-models.adoc[view models]) allow the positioning of the xref:properties-collections-actions.adoc[object members] into columns and tabs
* UI hints provided by the domain object itself returning:
@@ -23,14 +22,4 @@ The Apache Causeway programming model includes several mechanisms to influence t
* in collections, how to customise which properties of the associated object appear as columns.
-This chapter discusses these topics.
-
-
-include::partial$ui/names-and-descriptions.adoc[leveloffset=+1]
-include::partial$ui/object-titles-and-icons.adoc[leveloffset=+1]
-include::partial$ui/action-icons-and-css.adoc[leveloffset=+1]
-
-include::partial$ui/menubars-layout.adoc[leveloffset=+1]
-include::partial$ui/object-layout.adoc[leveloffset=+1]
-
-include::partial$ui/table-columns.adoc[leveloffset=+1]
+This page discusses these topics.
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/action-icons-and-css.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/action-icons-and-css.adoc
similarity index 98%
rename from antora/components/userguide/modules/ROOT/partials/ui/action-icons-and-css.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/action-icons-and-css.adoc
index 2883e69af9..64142aef0c 100644
--- a/antora/components/userguide/modules/ROOT/partials/ui/action-icons-and-css.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/action-icons-and-css.adoc
@@ -25,7 +25,7 @@ public void renew() {
}
----
-Alternatively, you can specify these hints dynamically in the xref:ui.adoc#object-layout[layout file] for the entity:
+Alternatively, you can specify these hints dynamically in the xref:ui-layout-and-hints.adoc#object-layout[layout file] for the entity:
[source,xml]
----
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/menubars-layout.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/menubars-layout.adoc
similarity index 99%
rename from antora/components/userguide/modules/ROOT/partials/ui/menubars-layout.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/menubars-layout.adoc
index 41c41a682c..e7d0bc406d 100644
--- a/antora/components/userguide/modules/ROOT/partials/ui/menubars-layout.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/menubars-layout.adoc
@@ -77,7 +77,7 @@ There are some significant limitations, however:
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.
+The annotation based approach is therefore useful during very early prototyping, but in real-world applications you should use xref:ui-layout-and-hints.adoc#file-based-menus[file based] menu layouts.
[[file-based-menus]]
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/names-and-descriptions.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/names-and-descriptions.adoc
similarity index 100%
rename from antora/components/userguide/modules/ROOT/partials/ui/names-and-descriptions.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/names-and-descriptions.adoc
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/object-layout.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/object-layout.adoc
similarity index 100%
rename from antora/components/userguide/modules/ROOT/partials/ui/object-layout.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/object-layout.adoc
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/object-titles-and-icons.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/object-titles-and-icons.adoc
similarity index 97%
rename from antora/components/userguide/modules/ROOT/partials/ui/object-titles-and-icons.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/object-titles-and-icons.adoc
index 5e4594037e..dc30feffcb 100644
--- a/antora/components/userguide/modules/ROOT/partials/ui/object-titles-and-icons.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/object-titles-and-icons.adoc
@@ -14,7 +14,7 @@ This could represent the state of that object (eg a shipped order, say, or overd
It is also possible for an object to provide a CSS class hint.
In conjunction with xref:vw:ROOT:customisation.adoc#custom-css[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-Finally, a domain object can even indicate the xref:ui.adoc#object-layout[layout] that should be used to render it.
+Finally, a domain object can even indicate the xref:ui-layout-and-hints.adoc#object-layout[layout] that should be used to render it.
For example, a domain object may be rendered differently depending upon the role of the user viewing it.
[#object-title]
@@ -184,7 +184,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:index/annotation/DomainObjectLayout.adoc#cssClassFa[@DomainObjectLayout#cssClassFa()] attribute or in the xref:userguide:ROOT:ui.adoc#object-layout[layout.xml] file.
+This is specified using the xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFa[@DomainObjectLayout#cssClassFa()] attribute or in the xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout.xml] file.
For example:
@@ -267,7 +267,7 @@ In conjunction with a viewer-specific customisation of CSS (eg for the xref:vw:R
=== Declarative style
To render an object with a particular CSS, use
-xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClass[@DomainObjectLayout#cssClass()] or in the xref:userguide:ROOT:ui.adoc#object-layout[layout.xml] file.
+xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClass[@DomainObjectLayout#cssClass()] or in the xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout.xml] file.
The usage of this CSS class is viewer-specific.
In the case of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)], when the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`.
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/progmodel.adoc
similarity index 100%
rename from antora/components/userguide/modules/ROOT/partials/ui/progmodel.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/progmodel.adoc
diff --git a/antora/components/userguide/modules/ROOT/partials/ui/table-columns.adoc b/antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/table-columns.adoc
similarity index 100%
rename from antora/components/userguide/modules/ROOT/partials/ui/table-columns.adoc
rename to antora/components/userguide/modules/ROOT/partials/ui-layout-and-hints/table-columns.adoc
diff --git a/antora/components/userguide/modules/btb/partials/programming-model/_intro.adoc b/antora/components/userguide/modules/btb/partials/programming-model/_intro.adoc
index d9f62a989a..cfc80a52cf 100644
--- a/antora/components/userguide/modules/btb/partials/programming-model/_intro.adoc
+++ b/antora/components/userguide/modules/btb/partials/programming-model/_intro.adoc
@@ -5,7 +5,7 @@
:page-partial:
Apache Causeway works by building a xref:background-context-and-theory.adoc#metamodel[metamodel] of the domain objects: entities, domain services, view models and mixins.
-Dependent on the xref:overview.adoc#type-of-domain-objects[sort of domain object], the class methods represent both state -- (single-valued) xref:object-members.adoc#properties[properties] and (multi-valued) xref:object-members.adoc#collections[collections] -- and behaviour -- xref:object-members.adoc#actions[actions].
+Dependent on the xref:overview.adoc#type-of-domain-objects[sort of domain object], the class methods represent both state -- (single-valued) xref:properties-collections-actions.adoc#properties[properties] and (multi-valued) xref:properties-collections-actions.adoc#collections[collections] -- and behaviour -- xref:properties-collections-actions.adoc#actions[actions].
More specifically, both xref:domain-entities.adoc[entities] and xref:view-models.adoc[view models] can have properties, collections and actions, while xref:domain-services.adoc[domain services] have just actions.
xref:mixins.adoc[Mixins] also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
diff --git a/core/config/src/main/adoc/modules/config/pages/application-specific/application-css.adoc b/core/config/src/main/adoc/modules/config/pages/application-specific/application-css.adoc
index d5a7930567..8574c9953f 100644
--- a/core/config/src/main/adoc/modules/config/pages/application-specific/application-css.adoc
+++ b/core/config/src/main/adoc/modules/config/pages/application-specific/application-css.adoc
@@ -10,7 +10,7 @@ All the layout annotations provide the ability to specify adhoc CSS classes, ass
* xref:refguide:applib:index/annotation/PropertyLayout.adoc#cssClass[@PropertyLayout#cssClass()]
* xref:refguide:applib:index/annotation/CollectionLayout.adoc#cssClass[@CollectionLayout#cssClass()]
-CSS can also be specified using the xref:userguide:ROOT:ui.adoc#object-layout[Xxx.layout.xml] layout files.
+CSS can also be specified using the xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[Xxx.layout.xml] layout files.
The viewer can then use this information within the rendered page.
For example, the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] adds the CSS as a style in a containing `<div>` for each element.
diff --git a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
index a949eabb1e..8f4cad737a 100644
--- a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
+++ b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
@@ -158,7 +158,7 @@ The extension also provides these mixins:
+
This contributes a `recentCommands` collection to each and every domain object.
+
-This can be explicit positioned through the domain class' own xref:userguide:ROOT:ui.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`.
+This can be explicit positioned through the domain class' own xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`.
* xref:refguide:extensions:index/commandlog/applib/contributions/HasUsername_recentCommandsByUser.adoc[]
+
diff --git a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
index fbeb686594..8709e80778 100644
--- a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
+++ b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
@@ -142,7 +142,7 @@ The extension also provides these mixins:
+
This contributes a `recentExecutions` collection to each and every domain object.
+
-This can be explicit positioned through the domain class' own xref:userguide:ROOT:ui.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`.
+This can be explicit positioned through the domain class' own xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`.
* xref:refguide:extensions:index/executionlog/applib/contributions/HasUsername_recentExecutionsByUser.adoc[]
+
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/customisation/custom-css.adoc b/viewers/wicket/adoc/modules/ROOT/pages/customisation/custom-css.adoc
index a08ab901cc..c1b5bf2c29 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/customisation/custom-css.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/customisation/custom-css.adoc
@@ -91,7 +91,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:userguide:ROOT:ui.adoc#object-layout[layout file].
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[layout file].
== Table columns