This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-2485 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 782ff47921543fe02f0ed56f2410f93ae6587a82 Author: danhaywood <[email protected]> AuthorDate: Sun Apr 30 16:25:39 2023 +0100 CAUSEWAY-2485: fleshes out @CollectionLayout#describedAs and @CollectionLayout#named --- .../hidden/CollectionLayoutHiddenPage.java | 2 +- .../CollectionLayoutNamedPage-description.adoc | 36 +++++++++++++++++++--- .../named/CollectionLayoutNamedPage.java | 4 +-- .../named/CollectionLayoutNamedPage.layout.xml | 4 ++- .../named/PropertyLayoutNamedPage-description.adoc | 24 ++++++--------- .../named/PropertyLayoutNamedPage.java | 2 +- 6 files changed, 49 insertions(+), 23 deletions(-) diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/hidden/CollectionLayoutHiddenPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/hidden/CollectionLayoutHiddenPage.java index 5048ee68db..b8dc6c5ccf 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/hidden/CollectionLayoutHiddenPage.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/hidden/CollectionLayoutHiddenPage.java @@ -88,7 +88,7 @@ public class CollectionLayoutHiddenPage implements HasAsciiDocDescription { @XmlElement(name = "child") @Getter @Setter private List<CollectionLayoutHiddenChildVm> yetMoreChildren = new ArrayList<>(); -//end::more-children[] +//end::yet-more-children[] } //end::class[] diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage-description.adoc index 13ead9567c..c8b582ac6a 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage-description.adoc @@ -1,7 +1,35 @@ :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 [...] -The `named` attribute ... +The name of a collection is used as the label of the field in the UI. +Normally the name is inferred from the name of the corresponding field or getter method in code. +This inferred name can be however be overridden using either the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/CollectionLayout.html#named[@CollectionLayout#named] attribute, or using the link:https://causeway.apache.org/userguide/2.0.0-RC1/fun/ui.html#by-example[.layout.xml] layout file. + +This is useful for example if the desired name is a Java keyword (such as "package"). + + +== How this demo works + +This page object has two collections, and both has had their name explicitly specified using each of the two mechanisms. + +In terms of code: + +* the `children` property has its name specified using the `@CollectionLayout#named()` annotation: ++ +[source,java,indent=0] +---- +include::CollectionLayoutNamedPage.java[tags=children] +---- +<.> explicitly specifies the name of the collection + +* meanwhile, the `moreChildren` property has its name specified using the `Xxx.layout.xml` file: ++ +[source,xml,indent=0,tabsize=4] +---- +<cpt:collection id="moreChildren"> + <cpt:named>Named using layout.xml</cpt:named> +</cpt:collection> +---- ++ +One advantage of the layout file over the annotation is that the layout file is dynamic: it can be modified and the changes reloaded in a running application. + -WARNING: TODO[CAUSEWAY-3311] -Name of this collection (overriding the name derived from its name in code). -A typical use case is if the desired name is a reserved Java keyword, such as default or package. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.java index cb23883730..20ad49e20c 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.java @@ -62,7 +62,7 @@ public class CollectionLayoutNamedPage implements HasAsciiDocDescription { //tag::children[] @Collection() @CollectionLayout( - named = "Collection of child objects" // <.> + named = "Named using @CollectionLayout" // <.> ) @XmlElementWrapper(name = "children") @XmlElement(name = "child") @@ -72,7 +72,7 @@ public class CollectionLayoutNamedPage implements HasAsciiDocDescription { //tag::more-children[] @Collection() - @CollectionLayout() // <.> + @CollectionLayout() // <.> @XmlElementWrapper(name = "moreChildren") @XmlElement(name = "child") @Getter @Setter diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.layout.xml index d7450c3c78..cd60f67ce5 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.layout.xml +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/collections/CollectionLayout/named/CollectionLayoutNamedPage.layout.xml @@ -29,7 +29,9 @@ <bs3:row> <bs3:col span="12"> <cpt:collection id="children"/> - <cpt:collection id="moreChildren"/> + <cpt:collection id="moreChildren"> + <cpt:named>Named using layout.xml</cpt:named> + </cpt:collection> </bs3:col> </bs3:row> <bs3:row> diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage-description.adoc index 63fe04444a..56081da820 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage-description.adoc @@ -1,7 +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 [...] The name of a property or parameter is used as the label of the field in the UI. -Normally the name is inferred from the name of the corresponding field or parameter in code. +Normally the name is inferred from the name of the corresponding field (or getter method) or parameter in code. This inferred name can be however be overridden using various mechanisms with an explicit value: * for properties, the name can be specified using the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/PropertyLayout.html#named[@PropertyLayout#named] attribute, or using the link:https://causeway.apache.org/userguide/2.0.0-RC1/fun/ui.html#by-example[.layout.xml] layout file. @@ -13,11 +13,12 @@ This is useful for example if the desired name is a Java keyword (such as "defau == How this demo works -=== Annotated +This page object has two properties, and both has had their name explicitly specified using each of the two mechanisms. +The first also has an action whose parameter name has been explicitly set. -The name can be specified explicitly using an annotation: +In terms of code: -* for properties, using `@PropertyLayout#named()`: +* the `propertyUsingAnnotation` property, unsurprisingly, has its name specified using the `@PropertyLayout#named()` annotation: + [source,java,indent=0] ---- @@ -25,7 +26,7 @@ include::PropertyLayoutNamedPage.java[tags=annotation] ---- <.> explicitly specifies the name of the property -* for parameters, using `@ParameterLayout#named()`: +* the parameter of the action that updates it has _its_ parameter named using `@ParameterLayout#named()`: + [source,java,indent=0] ---- @@ -33,13 +34,9 @@ include::PropertyLayoutNamedPage_updateWithParameterLayout.java[tags=annotation] ---- <.> explicitly specifies the name of the parameter -=== Layout File +* meanwhile, the `propertyUsingLayout` property has its name specified using the `Xxx.layout.xml` file: -The name can be specified using the `Xxx.layout.xml` file: - -WARNING: currently this does not work; link:https://issues.apache.org/jira/browse/CAUSEWAY-3443[CAUSEWAY-3443]. - -* property definition: +** the property's field is: + [source,java,indent=0] ---- @@ -47,7 +44,7 @@ include::PropertyLayoutNamedPage.java[tags=layout-file] ---- <.> `named` hint is _not_ present. -* layout file snippet: +** while its layout file snippet is: + [source,xml,indent=0,tabsize=4] ---- @@ -55,9 +52,8 @@ include::PropertyLayoutNamedPage.java[tags=layout-file] <cpt:named>Named using layout.xml</cpt:named> </cpt:property> ---- -// TODO: for some reason this doesn't include correctly in the app... -//include::PropertyLayoutNamedPage.layout.xml[tags=layout-file] ++ One advantage of the layout file over the annotation is that the layout file is dynamic: it can be modified and the changes reloaded in a running application. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage.java index 30e120c134..6d090a6b88 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/PropertyLayout/named/PropertyLayoutNamedPage.java @@ -55,7 +55,7 @@ public class PropertyLayoutNamedPage implements HasAsciiDocDescription { //tag::annotation[] @Property(optionality = Optionality.OPTIONAL) @PropertyLayout( - named = "Named using @PropertyLayout" + named = "Named using @PropertyLayout" // <.> ) @XmlElement(required = false) @Getter @Setter
