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 46f06b83427b76aa0ef6a5b1b820068993a0aa76 Author: danhaywood <[email protected]> AuthorDate: Mon May 15 19:27:41 2023 +0100 CAUSEWAY-2485: completes Action defaults demo --- .../ActionAutoCompletePage-description.adoc | 4 +- .../progmodel/choices/ActionChoicesMenu.java | 2 +- .../choices/ActionChoicesPage-description.adoc | 4 +- .../defaults/ActionDefaultsPage-description.adoc | 73 +++++++--------------- ...onDefaultsPage-multipleDefaultsDescription.adoc | 5 +- ...nDefaultsPage-parameterMatchingDescription.adoc | 4 +- ...ctionDefaultsPage-singleDefaultDescription.adoc | 5 +- ...ActionDefaultsPage_selectTvCharacterByShow.java | 9 ++- .../ActionDefaultsPage_selectTvCharacters.java | 6 +- ...efaultsPage_selectTvCharactersByShowAndSex.java | 23 ++++--- .../demoapp/dom/homepage/DemoHomePage-welcome.adoc | 8 +-- 11 files changed, 63 insertions(+), 80 deletions(-) diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/autocomplete/ActionAutoCompletePage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/autocomplete/ActionAutoCompletePage-description.adoc index bc61c31531..889f07a886 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/autocomplete/ActionAutoCompletePage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/autocomplete/ActionAutoCompletePage-description.adoc @@ -38,8 +38,8 @@ It matches the supporting "autoComplete" method with the parameter by number. ---- include::ActionAutoCompletePage_selectTvCharacter.java[tags=class] ---- -<.> defines the 0th-param -<.> provides the candidate arguments for the 0-th parameter. +<.> defines the 0^th^ parameter +<.> provides the candidate arguments for the 0^th^ parameter. The collection's element type must match that of the parameter. <.> prompts for a search string, which is then used to limit the candidate arguments from an original larger list diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesMenu.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesMenu.java index 243c7028d1..8fce7fb361 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesMenu.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesMenu.java @@ -44,7 +44,7 @@ public class ActionChoicesMenu { final TvCharacterPopulator tvCharacterPopulator; @Action - @ActionLayout(cssClassFa="fa-bolt") + @ActionLayout(cssClassFa="fa-list-ul") public ActionChoicesPage choices(){ val page = factoryService.viewModel(new ActionChoicesPage()); tvCharacterPopulator.populate(page.getTvCharacters()); diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesPage-description.adoc index 8d040dcef2..9d4f3cea90 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/choices/ActionChoicesPage-description.adoc @@ -38,8 +38,8 @@ It matches the supporting "choices" method with the parameter by number. ---- include::ActionChoicesPage_selectTvCharacter.java[tags=class] ---- -<.> defines the 0th-param -<.> provides the candidate arguments for the 0-th parameter. +<.> defines the 0^th^-param +<.> provides the candidate arguments for the 0^th^ parameter. The collection's element type must match that of the parameter. * this action is similar, but allows multiple TV characters to be selected. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-description.adoc index ddc6e89457..02c5d23426 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-description.adoc @@ -1,26 +1,18 @@ :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 [...] -WARNING: TODO - update these works - Before an action can be invoked, the end-user has to provide an argument for each of its parameters. -If the parameter is a value (String, number, date etc.) then they can just enter the value in a field. -But if the parameter is a reference type, then some other mechanism is required. - -A "choices" supporting method provides a set of candidate arguments for the parameter type, rendered in the UI as a drop-down list. -The list of candidates is expected to be small; if there is a larger list then instead use an "autoComplete" supporting method instead. - -The method should also (if possible) only proffer candidates that would also pass any validation rules, to avoid an otherwise frustrating user experience. +The purpose of the "default" supporting method is to provide an initial value for the action parameter that it corresponds to. There are several variations: -* the parameter for which candidates are being supplied can be either a scalar or a collection -* the supporting "choices" method can be associated with the parameter by number, or by name -* the list of candidates for a parameter can depend upon the value already selected for an earlier parameter. -** The preceding N-1 parameters are supplied to the Nth "choices" supporting method. +* the parameter argument being defaulted could be either a scalar or a collection +* the supporting "default" method can be associated with the parameter by number, or by name +* the default for a parameter can depend upon the value already selected for an earlier parameter. +** The preceding N-1 parameters are supplied to the Nth "default" supporting method. ** Or a single record-like structure can be defined and this can be passed through to all supporting methods instead. -As noted above, a supporting method to return a list of candidate arguments is _always_ required for reference types. -It is also possible to specify choices for value types, though this is much less commonly done. +It's common for "default" supporting method to be paired with a "choices" or "autoComplete" supporting method, but this won't always be the case. +For example, a parameter with a date parameter might default it to today's date. == How this demo works @@ -28,7 +20,7 @@ On the left hand side is a list of objects representing TV characters, also indi Below is a list of selected characters, initially empty. In the middle are a set of actions, each of which can be used to select a TV character or characters. -These demonstrate the variations listed in the introduction above. +A property of the main page can be used to pre-select a value, in which case it will be used as the default for the action's parameter(s). In terms of code: @@ -36,55 +28,36 @@ In terms of code: It matches the supporting "choices" method with the parameter by number. + [source,java] -.ActionChoicesPage_selectTvCharacter.java +.ActionDefaultsPage_selectTvCharacterByShow.java ---- -include::ActionChoicesPage_selectTvCharacter.java[tags=class] +include::ActionDefaultsPage_selectTvCharacterByShow.java[tags=class] ---- -<.> defines the 0th-param -<.> provides the candidate arguments for the 0-th parameter. +<.> 0^th^ parameter is defaulted with the property from the page +<.> 1^st^ parameter's default depends upon the 0^th^ parameter's value. The collection's element type must match that of the parameter. * this action is similar, but allows multiple TV characters to be selected. This time, it matches the supporting "choices" method with the parameter by name. + [source,java] -.ActionChoicesPage_selectTvCharacters.java ----- -include::ActionChoicesPage_selectTvCharacters.java[tags=class] ----- -<.> provides the candidate arguments for the "tvCharacters" parameter - -* the next example demonstrates dependent arguments, so that the TV characters are first filtered by the show that they appeared in. -+ -[source,java] -.ActionChoicesPage_selectTvCharacterByShow.java ----- -include::ActionChoicesPage_selectTvCharacterByShow.java[tags=class] ----- -<.> this parameter is used to filter the TV characters -<.> the "choices" method is matched by number ... -<.> \... and has a subset of the parameters of the action itself ("N-1" of them). - -* the next example is similar; dependent arguments but with a multiple selection, and using names to match the "choices" method: -+ -[source,java] -.ActionChoicesPage_selectTvCharactersByShows.java +.ActionDefaultsPage_selectTvCharacters.java ---- -include::ActionChoicesPage_selectTvCharactersByShows.java[tags=class] +include::ActionDefaultsPage_selectTvCharacters.java[tags=class] ---- -<.> the "choices" method matches a parameter of the action by name ... -<.> \... and accepts all the parameters defined in the action _up to_ (but not including) the matched parameter. +<.> provides the default values for the "tvCharacters" parameter ... +<.> \... filtered according to the pre-selected character's sex -* the final example also demonstrates dependent arguments, but using a "Parameters" record. +* the final example also demonstrates dependent defaults, this time using a "Parameters" record. + [source,java] -.ActionChoicesPage_selectTvCharactersByShow.java +.ActionDefaultsPage_selectTvCharactersByShowAndSex.java ---- -include::ActionChoicesPage_selectTvCharactersByShow.java[tags=class] +include::ActionDefaultsPage_selectTvCharactersByShowAndSex.java[tags=class] ---- -<.> the set of parameters of the action ... -<.> \... are also defined as fields of a `Parameters` type -<.> +<.> default for first parameter, simply taken from the page +<.> default for second parameter, again simply taken from the page +<.> default for last parameter ... +<.> \...uses the `Parameters` object to access the argument values of the preceding parameters <.> the framework will set the fields of `Parameters` object as appropriate + diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-multipleDefaultsDescription.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-multipleDefaultsDescription.adoc index f8eb13d005..fcbe049b45 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-multipleDefaultsDescription.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-multipleDefaultsDescription.adoc @@ -1,4 +1,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 [...] -WARNING: TODO - update these works +The action above illustrates how to provide a default for a collection (multi-valued) parameter. +Use the property below to pre-select which character sex (if any) should be used to filter the default values. + +The action associates the supporting "default" methods with the parameter by name (`defaultNTvCharacters`). diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-parameterMatchingDescription.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-parameterMatchingDescription.adoc index f8eb13d005..0b1be210d4 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-parameterMatchingDescription.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-parameterMatchingDescription.adoc @@ -1,4 +1,6 @@ :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 [...] -WARNING: TODO - update these works +The action in this section shows a variation on the default for dependent arguments, using a "record" structure to represent the set of parameters accepted by the action. +With this coding convention it's idiomatic to associate the supporting method by *name* rather than number. +Use the properties below to pre-select which TV show and character sex should be used to filter the defaults for the last parameter. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-singleDefaultDescription.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-singleDefaultDescription.adoc index f8eb13d005..16954608fe 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-singleDefaultDescription.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage-singleDefaultDescription.adoc @@ -1,4 +1,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 [...] -WARNING: TODO - update these works +The action above illustrates how to provide a default for a scalar (single-valued) action parameter, for both for the first and second parameters, with the default of the second being dependent upon the first. +Use the property below to select an initial value (if any) for the first parameter. + +The action associates the supporting "default" methods with the parameter by number (`defaultNAct`). diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacterByShow.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacterByShow.java index c93561456f..ff24444c81 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacterByShow.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacterByShow.java @@ -40,17 +40,17 @@ public class ActionDefaultsPage_selectTvCharacterByShow { @Parameter(optionality = Optionality.MANDATORY) final TvShow tvShow, // <.> @Parameter(optionality = Optionality.MANDATORY) - final TvCharacter tvCharacter + final TvCharacter tvCharacter // <.> ) { page.getSelectedTvCharacters().clear(); page.getSelectedTvCharacters().add(tvCharacter); return page; } - @MemberSupport public TvShow default0Act() { // <.> + @MemberSupport public TvShow default0Act() { // <1> return page.getPreselectTvShow(); } - @MemberSupport public TvCharacter default1Act( // <.> + @MemberSupport public TvCharacter default1Act( // <2> final TvShow tvShow ) { return choices1Act(tvShow).stream().findFirst().orElse(null); @@ -58,11 +58,14 @@ public class ActionDefaultsPage_selectTvCharacterByShow { @MemberSupport public Collection<TvCharacter> choices1Act( final TvShow tvShow ) { + //... +//end::class[] return page.getTvCharacters() .stream() .filter(tvCharacter -> tvShow == null || tvShow == tvCharacter.getTvShow()) .collect(Collectors.toList()); +//tag::class[] } } //end::class[] diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacters.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacters.java index b692ea1972..0e5f81a3ee 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacters.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharacters.java @@ -41,7 +41,7 @@ public class ActionDefaultsPage_selectTvCharacters { @MemberSupport public ActionDefaultsPage act( @Parameter(optionality = Optionality.MANDATORY) - final List<TvCharacter> tvCharacters // <.> + final List<TvCharacter> tvCharacters // <.> ) { page.getSelectedTvCharacters().clear(); page.getSelectedTvCharacters().addAll(tvCharacters); @@ -51,8 +51,8 @@ public class ActionDefaultsPage_selectTvCharacters { @MemberSupport public Collection<TvCharacter> choicesTvCharacters() { return page.getTvCharacters(); } - @MemberSupport public List<TvCharacter> defaultTvCharacters() { // <1> - TvCharacter.Sex preselectCharacterSex = page.getPreselectCharacterSex(); + @MemberSupport public List<TvCharacter> defaultTvCharacters() { // <1> + TvCharacter.Sex preselectCharacterSex = page.getPreselectCharacterSex(); // <.> return choicesTvCharacters().stream() .filter(tvCharacter -> preselectCharacterSex == null || tvCharacter.getSex() == preselectCharacterSex) diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharactersByShowAndSex.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharactersByShowAndSex.java index 9c4ad55931..6f12cbe08e 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharactersByShowAndSex.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/progmodel/defaults/ActionDefaultsPage_selectTvCharactersByShowAndSex.java @@ -18,6 +18,7 @@ */ package demoapp.dom.domain.actions.progmodel.defaults; +import java.util.ArrayList; import java.util.List; import java.util.stream.Collectors; @@ -48,7 +49,7 @@ public class ActionDefaultsPage_selectTvCharactersByShowAndSex { @Parameter(optionality = Optionality.MANDATORY) final TvCharacter.Sex sex, // <.> @Parameter(optionality = Optionality.MANDATORY) - final List<TvCharacter> tvCharacters + final List<TvCharacter> tvCharacters // <.> ) { page.getSelectedTvCharacters().clear(); page.getSelectedTvCharacters().addAll(tvCharacters); @@ -62,27 +63,25 @@ public class ActionDefaultsPage_selectTvCharactersByShowAndSex { List<TvCharacter> tvCharacters; } - @MemberSupport public TvShow defaultTvShow() { // <.> + @MemberSupport public TvShow defaultTvShow() { // <1> return page.getPreselectTvShow2(); } - @MemberSupport public TvCharacter.Sex defaultSex() { // <.> + @MemberSupport public TvCharacter.Sex defaultSex() { // <2> return page.getPreselectCharacterSex2(); } - @MemberSupport public List<TvCharacter> defaultTvCharacters( - final Parameters params // <2> - ) { - return choicesTvCharacters(params); - } - @MemberSupport public List<TvCharacter> choicesTvCharacters( - final Parameters params // <2> + @MemberSupport public List<TvCharacter> defaultTvCharacters( // <3> + final Parameters params // <4> ) { val tvShowSelected = params.tvShow(); // <.> - val sexSelected = params.sex; // <.> - return page.getTvCharacters() + val sexSelected = params.sex; // <5> + return choicesTvCharacters() .stream() .filter(tvCharacter -> tvShowSelected == tvCharacter.getTvShow()) .filter(tvCharacter -> sexSelected == tvCharacter.getSex()) .collect(Collectors.toList()); } + @MemberSupport public List<TvCharacter> choicesTvCharacters() { + return new ArrayList<>(page.getTvCharacters()); + } } //end::class[] diff --git a/examples/demo/domain/src/main/java/demoapp/dom/homepage/DemoHomePage-welcome.adoc b/examples/demo/domain/src/main/java/demoapp/dom/homepage/DemoHomePage-welcome.adoc index 372e776627..114f4b6db0 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/homepage/DemoHomePage-welcome.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/homepage/DemoHomePage-welcome.adoc @@ -1,10 +1,10 @@ :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 is an link:https://causeway.apache.org[Apache Causeway] application to demonstrate the programming model for the various features provided by the framework. +This is an link:https://causeway.apache.org[Apache Causeway] application to demonstrate the various features of the framework. -On the left hand side of each web page you'll find the feature, and on the right hand side you'll find an explanation of the feature with code examples. +On the left hand side of each page you'll find a working example of the feature, while on the right hand side you'll find a description of the feature with annotated code examples. -=== Page Layout +== Page Layout This is as good place as any to explain the page layout of an Apache Causeway webapp: @@ -22,7 +22,7 @@ The `welcome` property - what you are reading now - is on the left, the `descrip + If running in prototype mode then there are a number of actions contributed by the framework (their label is in _italics_) so you can dig into the internal implementation. -* At the bottom is a menu bar with credits, and to allow the user to *switch theme*. +* At the bottom is a menu bar with credits, and to allow the user to *change theme*. Click into the application and try things out.
