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
The following commit(s) were added to refs/heads/master by this push:
new 1095536872 CAUSEWAY-2485: reworks @Action#named
1095536872 is described below
commit 1095536872ae52a2a5e056885f0ce27c9224f4e0
Author: danhaywood <[email protected]>
AuthorDate: Sun Apr 16 16:08:08 2023 +0100
CAUSEWAY-2485: reworks @Action#named
---
.../describedAs/ActionLayoutDescribedAsPage.java | 3 +-
.../named/ActionLayoutNamedPage-description.adoc | 69 ++++++++++++++++++++--
.../ActionLayout/named/ActionLayoutNamedPage.java | 59 ++++++++++++++----
.../named/ActionLayoutNamedPage.layout.xml | 26 +++-----
4 files changed, 122 insertions(+), 35 deletions(-)
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/describedAs/ActionLayoutDescribedAsPage.java
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/describedAs/ActionLayoutDescribedAsPage.java
index 999f907c6b..bc200b1b87 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/describedAs/ActionLayoutDescribedAsPage.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/describedAs/ActionLayoutDescribedAsPage.java
@@ -59,8 +59,7 @@ public class ActionLayoutDescribedAsPage
{
@Property
@XmlElement
- @Getter
- @Setter
+ @Getter @Setter
private String name;
@Collection()
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage-description.adoc
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage-description.adoc
index 384269554c..01139f3ad2 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage-description.adoc
+++
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage-description.adoc
@@ -1,11 +1,72 @@
: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 indicates the _name_ of this action as used for
rendering its button (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`.
+Sometimes the desired name of an action coincides with a reserved Java
keyword, for example "default" or "package".
+You will therefore need to use some other method name to implement the action.
+The
link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/ActionLayout.html#named[@ActionLayout#named]
element allows you to override the name (as used for rendering) from that
derived from the action's method name).
+
+This can also be used if you want the name to include characters such as
brackets `()[]` or quotation marks `' "`.
+
+
+
+=== How this demo works
+
+This page object has two properties and an associated action with each.
+Both of these actions use `@ActionLayout#named`, for different reasons:
+
+* the "reset" action uses a reserved Java name of "default" in the user
interface:
++
[source,java,indent=0]
----
-include::ActionLayoutNamedPage.java[tags=act]
+include::ActionLayoutNamedPage.java[tags=reset]
+----
+<.> specifies the name to use in the UI
+
+* the "updateNotes" action has a name that includes an invalid character, "(":
++
+[source,java,indent=0]
+----
+include::ActionLayoutNamedPage.java[tags=updateNotes]
+----
+<.> specifies the name to use in the UI.
+
+
+=== .layout.xml
+
+Instead of using `@ActionLayout#named`, it is also possible to specify a name
in the
link:https://causeway.apache.org/userguide/2.0.0-RC1/fun/ui.html#by-example[.layout.xml]
file:
+
+[source,xml]
+.Xxx.layout.xml
+----
+...
+<action id="updateNotes">
+ <named>Updates (changes) the notes property</named>
+</action>
+...
----
-<.> instead of `'Act'` the action's button is named `'xxx'`
+One advantage of using the `.layout.xml` file is that changes can be picked up
without having to restart the application.
+On the other hand, including descriptions can make that file rather large.
+
+
+=== Alternatives
+
+Where the `@ActionLayout#named` is being used to avoid a clash with a reserved
keyword, an alternative option is to use a mixin action.
+
+For example, a "package" action for the `Order` class could be implemented
using an `Order_package` mixin action:
+
+
+[source,java]
+.Order_package.java
+----
+@Action
+@RequiredArgsConstructor
+public class Order_package {
+
+ private final Order order;
+
+ public OrderPackage act(/*...*/) {
+ // ...
+ }
+}
+----
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.java
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.java
index 9eb2d9844d..e3efcd3868 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.java
@@ -21,6 +21,7 @@ package demoapp.dom.domain.actions.ActionLayout.named;
import javax.inject.Named;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
@@ -29,34 +30,70 @@ import org.apache.causeway.applib.annotation.ActionLayout;
import org.apache.causeway.applib.annotation.DomainObject;
import org.apache.causeway.applib.annotation.Nature;
import org.apache.causeway.applib.annotation.ObjectSupport;
+import org.apache.causeway.applib.annotation.Property;
+import org.apache.causeway.applib.annotation.SemanticsOf;
import demoapp.dom._infra.asciidocdesc.HasAsciiDocDescription;
-//tag::class[]
+import lombok.Getter;
+import lombok.Setter;
+
@DomainObject(
nature=Nature.VIEW_MODEL)
@Named("demo.ActionLayoutNamedVm")
@XmlRootElement(name = "root")
@XmlType
@XmlAccessorType(XmlAccessType.FIELD)
-public class ActionLayoutNamedPage implements HasAsciiDocDescription {
+//tag::class[]
+//...
+public class ActionLayoutNamedPage
+//end::class[]
+ implements HasAsciiDocDescription
+//tag::class[]
+{
+ @Property
+ @XmlElement
+ @Getter @Setter
+ private String name;
+
+ @Property
+ @XmlElement
+ @Getter @Setter
+ private String notes;
+
+ // ...
+//end::class[]
@ObjectSupport public String title() {
return "@ActionLayout#named";
}
-//tag::act[]
- @Action
+//tag::reset[]
+ @Action(semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE)
@ActionLayout(
- named = "xxx" // <.>
-//end::act[]
- ,describedAs = "@ActionLayout(named = \"xxx\")"
-//tag::act[]
- )
- public Object act(final String arg) {
+ named = "default", // <.>
+ describedAs = "Resets the name back to a default"
+ )
+ public Object reset() {
+ setName("Fred");
return this;
}
-//end::act[]
+//end::reset[]
+//tag::updateNotes[]
+ @Action(semantics = SemanticsOf.IDEMPOTENT)
+ @ActionLayout(
+ named = "Updates (changes) the notes property" // <.>
+ )
+ public Object updateNotes(String newNotes) {
+ setNotes(newNotes);
+ return this;
+ }
+ public String default0UpdateNotes() {
+ return getNotes();
+ }
+//end::updateNotes[]
+
+//tag::class[]
}
//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.layout.xml
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.layout.xml
index b7b4ab6651..f813a4dade 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.layout.xml
+++
b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/ActionLayout/named/ActionLayoutNamedPage.layout.xml
@@ -26,24 +26,14 @@
<bs3:row>
<bs3:col span="6">
- <cpt:fieldSet name="General" id="general"/>
- <cpt:fieldSet name="Annotated" id="annotated"/>
- <cpt:fieldSet name="Layout" id="layout">
- <cpt:action id="layoutPanel" position="PANEL">
- <cpt:named>Positioned on
panel</cpt:named>
- </cpt:action>
- <cpt:action id="layoutPanelDropDown"
position="PANEL_DROPDOWN">
- <cpt:named>Positioned on panel in drop
down</cpt:named>
- </cpt:action>
- <cpt:property id="readOnlyProperty2">
- <cpt:action id="layoutBelow"
position="BELOW">
- <cpt:named>Positioned
below</cpt:named>
- </cpt:action>
- <cpt:action id="layoutRight"
position="RIGHT">
- <cpt:named>Positioned
right</cpt:named>
- </cpt:action>
- </cpt:property>
- </cpt:fieldSet>
+ <cpt:fieldSet id="id" name="Identity">
+ <cpt:property id="name">
+ <cpt:action id="reset"/>
+ </cpt:property>
+ <cpt:property id="notes">
+ <cpt:action id="updateNotes"/>
+ </cpt:property>
+ </cpt:fieldSet>
<cpt:fieldSet name="Other" id="other"
unreferencedProperties="true"/>
</bs3:col>
<bs3:col span="6">
