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:41 UTC
[causeway] 02/02: CAUSEWAY-3395 : reworks user guide, choices and defaults
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
-