This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-2873 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 0a8829e41046c19ed65c133d5cc82371d72806aa Author: Dan Haywood <[email protected]> AuthorDate: Sat May 25 14:12:50 2024 +0100 CAUSEWAY-2873: completes 03-08 --- .../images/03-07/new-parameters-are-optional.png | Bin 0 -> 8602 bytes ...antuml-md5-41d7321e937c89d99e72b59cadcbe005.png | Bin 37003 -> 0 bytes ...antuml-md5-5c0ff86629ce9ff23e5d52305493d5c6.svg | 2 +- ...antuml-md5-7e47437805fde198d7791595949fcf17.png | Bin 5096 -> 4464 bytes ...antuml-md5-bc5fc3dd9c919d1677af89bec5416f29.svg | 1 - .../petclinic/pages/030-petowner-entity.adoc | 102 +++++++++++++-------- .../modules/petclinic/pages/100-todo.adoc | 3 + 7 files changed, 70 insertions(+), 38 deletions(-) diff --git a/antora/components/tutorials/modules/petclinic/images/03-07/new-parameters-are-optional.png b/antora/components/tutorials/modules/petclinic/images/03-07/new-parameters-are-optional.png new file mode 100644 index 0000000000..06bedd5db0 Binary files /dev/null and b/antora/components/tutorials/modules/petclinic/images/03-07/new-parameters-are-optional.png differ diff --git a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-41d7321e937c89d99e72b59cadcbe005.png b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-41d7321e937c89d99e72b59cadcbe005.png deleted file mode 100644 index 9b948f4bae..0000000000 Binary files a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-41d7321e937c89d99e72b59cadcbe005.png and /dev/null differ diff --git a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-5c0ff86629ce9ff23e5d52305493d5c6.svg b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-5c0ff86629ce9ff23e5d52305493d5c6.svg index 6f3b8ba884..50b30fc348 100644 --- a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-5c0ff86629ce9ff23e5d52305493d5c6.svg +++ b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-5c0ff86629ce9ff23e5d52305493d5c6.svg @@ -1 +1 @@ -<?xml version='1.0' encoding='US-ASCII' standalone='no'?><svg contentStyleType='text/css' height='161px' preserveAspectRatio='none' style='width:141px;height:161px;background:#FFFFFF;' version='1.1' viewBox='0 0 141 161' width='141px' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns='http://www.w3.org/2000/svg' zoomAndPan='magnify'><defs/><g><g id='elem_Owner'><rect codeLine='4' fill='#F1F1F1' height='140.7144' id='Owner' rx='2.5' ry='2.5' style='stroke:#181818;stroke-width:0.5;' width=' [...] \ No newline at end of file +<?xml version='1.0' encoding='US-ASCII' standalone='no'?><svg contentStyleType='text/css' height='170px' preserveAspectRatio='none' style='width:136px;height:170px;background:#FFFFFF;' version='1.1' viewBox='0 0 136 170' width='136px' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns='http://www.w3.org/2000/svg' zoomAndPan='magnify'><defs/><g><g id='elem_Owner'><rect codeLine='4' fill='#F1F1F1' height='149.1055' id='Owner' rx='2.5' ry='2.5' style='stroke:#181818;stroke-width:0.5;' width=' [...] \ No newline at end of file diff --git a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-7e47437805fde198d7791595949fcf17.png b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-7e47437805fde198d7791595949fcf17.png index 12035b77b0..d4fdb061d9 100644 Binary files a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-7e47437805fde198d7791595949fcf17.png and b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-7e47437805fde198d7791595949fcf17.png differ diff --git a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-bc5fc3dd9c919d1677af89bec5416f29.svg b/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-bc5fc3dd9c919d1677af89bec5416f29.svg deleted file mode 100644 index a9963efc83..0000000000 --- a/antora/components/tutorials/modules/petclinic/images/diag-plantuml-md5-bc5fc3dd9c919d1677af89bec5416f29.svg +++ /dev/null @@ -1 +0,0 @@ -<?xml version='1.0' encoding='US-ASCII' standalone='no'?><svg contentStyleType='text/css' height='441px' preserveAspectRatio='none' style='width:520px;height:441px;background:#FFFFFF;' version='1.1' viewBox='0 0 520 441' width='520px' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns='http://www.w3.org/2000/svg' zoomAndPan='magnify'><defs/><g><g id='cluster_pets'><path d='M8.5,6 L38.5,6 A3.75,3.75 0 0 1 41,8.5 L48,28.9429 L282.5,28.9429 A2.5,2.5 0 0 1 285,31.4429 L285,431.5 A2.5,2.5 0 0 1 [...] \ No newline at end of file diff --git a/antora/components/tutorials/modules/petclinic/pages/030-petowner-entity.adoc b/antora/components/tutorials/modules/petclinic/pages/030-petowner-entity.adoc index 4d46d3bc39..383149ad87 100644 --- a/antora/components/tutorials/modules/petclinic/pages/030-petowner-entity.adoc +++ b/antora/components/tutorials/modules/petclinic/pages/030-petowner-entity.adoc @@ -186,12 +186,13 @@ Now add the two new properties: [source,java] .PetOwner.java ---- -@Column(length = 40, nullable = true, name = "telephoneNumber") +@Column(length = 40, nullable = true, name = "telephoneNumber") // <.> @Getter @Setter @Property(editing = Editing.ENABLED) @PropertyLayout(fieldSetId = "contact", sequence = "1.1") // <.> private String telephoneNumber; ---- +<.> The JPA `@Column` annotation indicates that the property is optional in the database; Causeway also understands this for the domain layer. <.> This places the property in a new "contact" fieldset group; we'll define that below * and add the `emailAddress` property: @@ -339,7 +340,7 @@ When you now run the application you should now find that there are 10 `PetOwner [#exercise-3-6-update-home-page-to-show-PetOwners] -== Ex 3.5: Update Home Page to show PetOwners +== Ex 3.6: Update Home Page to show PetOwners Every Causeway app can nominate a home page, basically a xref:userguide::view-models.adoc[view model] that's been annotated with xref:refguide:applib:index/annotation/HomePage.adoc[]. Currently the home page for our app is the one we inherited from the starter app, showing a list of ``SimpleObject``s. @@ -386,10 +387,7 @@ By default this will show all of the properties of `PetOwner`. image::03-06/home-page-default-columns.png[] -We can change this by creating a file `HomePageViewModel#petOwners.columnOrder.txt`, alongside the `HomePageViewModel`: - - -Instead +We can change this by creating a file `HomePageViewModel#petOwners.columnOrder.txt`, alongside the `HomePageViewModel`. [source,txt] .HomePageViewModel#petOwners.columnOrder.txt @@ -405,39 +403,29 @@ emailAddress TIP: the action "Download .columnOrder.txt files (ZIP)" (available only when prototyping) provides an easy way to obtain this file; you can then update as required. +TIP: You can config your IDE so that any changes made to this file are picked up automatically without having to restart the app. +If using IntelliJ for example, use "Reload Changed Classes" action. ----- ----- ----- ----- - ----- ----- +[#exercise-3-7-modify-the-menu-action-to-create-petowners] +== Ex 3.7: Modify the menu action to create PetOwners -TODO: change the home page to list the pet owners by default. +If we want to create a new `PetOwner` and specify additional details, at the moment it's a two stage process: create the `PetOwner` (using menu:PetOwners[create]), then set the additional details afterwards. -*UP TO HERE* - -[#exercise-3-4-modify-the-menu-action-to-create-petowners] -== Ex 3.4: Modify the menu action to create PetOwners - -If we want to create a new `PetOwner` and provide their `firstName`, at the moment it's a two stage process: create the `PetOwner` (using `PetOwners#create` action from the menu), then update their name (using the `updateName` action that we just looked at). - -In this exercise we'll simplify that workflow by allowing the `firstName` to optionally be specified during the initial create. +In this exercise we'll simplify that workflow by allowing the additional details to optionally be specified during the create. === Solution [source,bash] ---- -git checkout tags/03-04-modifies-PetOwners-create-action +git checkout tags/03-07-modifies-PetOwners-create-action mvn clean install mvn -pl spring-boot:run ---- === Tasks -* update `Orders#create` action, so that the end user can specify a `firstName` when creating a new `PetOwner`: +* update `PetOwners#create()` method, to allow the additional details to optionally be specified: + [source,java] .PetOwners.java @@ -445,30 +433,48 @@ mvn -pl spring-boot:run @Action(semantics = SemanticsOf.NON_IDEMPOTENT) @ActionLayout(promptStyle = PromptStyle.DIALOG_SIDEBAR) public PetOwner create( - @LastName final String lastName, - @FirstName final String firstName) { - return repositoryService.persist(PetOwner.withName(lastName, firstName)); + @Name final String name, + @Parameter(maxLength = 40, optionality = Optionality.OPTIONAL) + final String knownAs, + @Parameter(maxLength = 40, optionality = Optionality.OPTIONAL) + final String telephoneNumber, + @Parameter(maxLength = 40, optionality = Optionality.OPTIONAL) + final String emailAddress) { + final var petOwner = PetOwner.withName(name); + petOwner.setKnownAs(knownAs); + petOwner.setTelephoneNumber(telephoneNumber); + petOwner.setEmailAddress(emailAddress); + return repositoryService.persist(petOwner); } ---- +* also update `PetOwner_persona.Builder` fixture script, passing in `null` for the new parameters: ++ +[source,java] +.PetOwner_persona.java +---- +val petOwner = PetOwners.create(persona.name, null, null, null); +---- +When you run the app, confirm that only the `name` parameter is optional: +image::03-07/new-parameters-are-optional.png[width=80%] -[#exercise-3-6-prompt-styles] -== Ex 3.6: Prompt styles +[#exercise-3-8-prompt-styles] +== Ex 3.8: Prompt styles The framework provides many ways to customise the UI, either through the layout files or using the `@XxxLayout` annotations. Default UI conventions can also be specified using the `application.yml` configuration file. -In this exercise we'll change the prompt style for both a service (menu) action, ie `PetOwners#create`, and an object action, ie `PetOwner#updateName`. +In this exercise we'll change the prompt style for both a service (menu) action, ie menu::PetOwners[create], and an object action, ie `PetOwner#updateName`. === Solution [source,bash] ---- -git checkout tags/03-06-prompt-styles +git checkout tags/03-08-prompt-styles mvn clean install mvn -pl spring-boot:run ---- @@ -479,12 +485,36 @@ mvn -pl spring-boot:run * Service (menu) actions are always shown in a dialog, of which there are two styles: modal prompt, or sidebar. If not specified explicitly, they will default to dialog modal. + -Therefore remove the `@ActionLayout(promptStyle)` for `PetOwners#create` and confirm that the dialog is now shown as a modal prompt. +Therefore, remove the `@ActionLayout(promptStyle)` for `PetOwners#create` ++ +[source,java] +.PetOwners.java +---- +@Action(semantics = SemanticsOf.NON_IDEMPOTENT) +// @ActionLayout(promptStyle = PromptStyle.DIALOG_SIDEBAR) +public PetOwner create( ... ) { ... } +---- ++ +Confirm that the dialog is now shown as a modal prompt. * Object actions can be shown either inline or in a dialog, but default to inline. If forced to use a dialog, then they default to a sidebar prompt rather than a modal prompt. + -Therefore remove the `@ActionLayout(promptStyle)` for `PetOwner#updateName` and confirm that prompt is still inline. +Remove the `@ActionLayout(promptStyle)` for `PetOwner#updateName`: + +[source,java] +.PetOwner.java +---- +@Action( ... ) +@ActionLayout( + ... + // promptStyle = PromptStyle.INLINE, + ... +) +public PetOwner updateName( ... ) { ... } +---- ++ +Confirm that prompt is still inline. * Using a configuration property we can change the default for object actions to use a dialog rather than inline. + @@ -506,7 +536,7 @@ Remember to activate this new profile (`-Dspring.profiles.active=dev,custom`) an Switch the defaults so that service actions prefer to use a sidebar dialog, while object actions would use a modal dialog: + [source,yaml] -.application-custom.yaml +.application-dev.yaml ---- causeway: viewer: @@ -516,14 +546,14 @@ causeway: dialog-mode-for-menu: sidebar ---- -* Optional: now use `@ActionLayout(promptStyle=...)` to override these defaults. +* Optional: use `@ActionLayout(promptStyle=...)` to override these defaults. + Be aware that "inline" makes no sense/is not supported for service actions. * Finish off the exercises by setting up these defaults to retain the original behaviour: + [source,yaml] -.application-custom.yaml +.application-dev.yaml ---- causeway: viewer: diff --git a/antora/components/tutorials/modules/petclinic/pages/100-todo.adoc b/antora/components/tutorials/modules/petclinic/pages/100-todo.adoc index a669ffc86b..b8603a2c3b 100644 --- a/antora/components/tutorials/modules/petclinic/pages/100-todo.adoc +++ b/antora/components/tutorials/modules/petclinic/pages/100-todo.adoc @@ -2,3 +2,6 @@ TODO: ideas for future steps: - introduce a meta-annotation - introduce a custom type for these + + +add validation for telephone number and email address.
