You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/02/23 20:04:04 UTC
[isis] branch ISIS-2444 updated: ISIS-2444: adds final lot of hooks
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/ISIS-2444 by this push:
new 6740704 ISIS-2444: adds final lot of hooks
6740704 is described below
commit 6740704020a7ab2a542f0dbe6c2f51bdd75497c5
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Feb 23 20:03:33 2021 +0000
ISIS-2444: adds final lot of hooks
---
.../hooks/ActionLayout_010-examples-and-usage.adoc | 1 +
...tyle.adoc => ActionLayout_021-promptStyle.adoc} | 5 +-
...osition.adoc => ActionLayout_022-position.adoc} | 2 -
...edAs.adoc => ActionLayout_023-describedAs.adoc} | 2 -
...ssClass.adoc => ActionLayout_024-cssClass.adoc} | 4 -
...assFa.adoc => ActionLayout_025-cssClassFa.adoc} | 2 -
...king.adoc => ActionLayout_026-bookmarking.adoc} | 3 -
...25-hidden.adoc => ActionLayout_027-hidden.adoc} | 2 -
..._026-named.adoc => ActionLayout_028-named.adoc} | 3 +-
.../hooks/ActionLayout_029-redirect.adoc | 3 -
.../hooks/Action_010-examples-and-usage.adoc | 595 +--------------------
.../annotation/hooks/Action_021-associating.adoc | 51 ++
.../hooks/Action_022-action-semantics.adoc | 79 +++
.../hooks/Action_023-deployment-modes.adoc | 37 ++
.../annotation/hooks/Action_024-domain-events.adoc | 175 ++++++
.../hooks/Action_025-execution-publishing.adoc | 43 ++
.../hooks/Action_026-command-processing.adoc | 136 +++++
...bedAs.adoc => Action_027-collection-types.adoc} | 28 +-
.../annotation/hooks/Action_030-see-also.adoc | 31 ++
.../CollectionLayout_010-examples-and-usage.adoc | 1 +
....adoc => CollectionLayout_021-defaultView.adoc} | 3 -
...-paged.adoc => CollectionLayout_022-paged.adoc} | 2 -
.../hooks/CollectionLayout_023-describedAs.adoc | 2 -
...dBy.adoc => CollectionLayout_024-sortedBy.adoc} | 1 -
...ass.adoc => CollectionLayout_025-cssClass.adoc} | 2 -
...-named.adoc => CollectionLayout_026-named.adoc} | 2 +-
...idden.adoc => CollectionLayout_027-hidden.adoc} | 4 +-
...doc => DomainObjectLayout_021-describedAs.adoc} | 0
...s.adoc => DomainObjectLayout_022-cssClass.adoc} | 0
...adoc => DomainObjectLayout_023-cssClassFa.adoc} | 0
...tType.adoc => DomainObject_021-objectType.adoc} | 0
...28-nature.adoc => DomainObject_022-nature.adoc} | 0
...-editing.adoc => DomainObject_023-editing.adoc} | 0
...ts.adoc => DomainObject_024-domain-events.adoc} | 0
...adoc => DomainObject_025-lifecycle-events.adoc} | 0
...ounding.adoc => DomainObject_027-bounding.adoc} | 0
...> DomainObject_028-autoCompleteRepository.adoc} | 0
...thod.adoc => DomainObject_029-mixinMethod.adoc} | 0
...ee-also.adoc => DomainObject_040-see-also.adoc} | 0
...adoc => ParameterLayout_021-labelPosition.adoc} | 22 +
...ine.adoc => ParameterLayout_022-multiLine.adoc} | 0
...s.adoc => ParameterLayout_023-describedAs.adoc} | 0
...lass.adoc => ParameterLayout_024-cssClass.adoc} | 0
...Day.adoc => ParameterLayout_025-renderDay.adoc} | 0
...5-named.adoc => ParameterLayout_026-named.adoc} | 0
.../hooks/ParameterLayout_027-typicalLength.adoc | 1 -
...onality.adoc => Parameter_021-optionality.adoc} | 0
...attern.adoc => Parameter_024-regexPattern.adoc} | 0
...leAccept.adoc => Parameter_025-fileAccept.adoc} | 0
.../PropertyLayout_010-examples-and-usage.adoc | 2 +
....adoc => PropertyLayout_021_labelPosition.adoc} | 45 +-
...le.adoc => PropertyLayout_022_promptStyle.adoc} | 7 +-
...Line.adoc => PropertyLayout_023_multiLine.adoc} | 18 +-
...able.adoc => PropertyLayout_024_navigable.adoc} | 5 +-
...As.adoc => PropertyLayout_025_describedAs.adoc} | 17 +-
...Class.adoc => PropertyLayout_026_cssClass.adoc} | 19 +-
...rDay.adoc => PropertyLayout_027_renderDay.adoc} | 12 +-
...ing.adoc => PropertyLayout_028_repainting.adoc} | 5 +-
.../named.adoc => PropertyLayout_029_named.adoc} | 22 +-
.../hidden.adoc => PropertyLayout_030_hidden.adoc} | 64 +--
...h.adoc => PropertyLayout_31_typicalLength.adoc} | 11 +-
...ionality.adoc => Property_021-optionality.adoc} | 5 +-
.../editing.adoc => Property_022-editing.adoc} | 17 +-
.../maxLength.adoc => Property_023-maxLength.adoc} | 5 +-
...tSatisfy.adoc => Property_024-mustSatisfy.adoc} | 5 +-
...rojecting.adoc => Property_025-projecting.adoc} | 5 +-
...nEvent.adoc => Property_026-domain-events.adoc} | 38 +-
...adoc => Property_027-execution-publishing.adoc} | 22 +-
...g.adoc => Property_028-command-processing.adoc} | 32 +-
...Pattern.adoc => Property_029-regexPattern.adoc} | 11 +-
.../snapshot.adoc => Property_030-snapshot.adoc} | 9 +-
...ileAccept.adoc => Property_031-fileAccept.adoc} | 5 +-
.../hidden.adoc => Property_033-hidden.adoc} | 10 +-
.../PropertyLayout/describedAs.adoc | 30 --
74 files changed, 723 insertions(+), 940 deletions(-)
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
index 10fe719..2c503e6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_010-examples-and-usage.adoc
@@ -34,3 +34,4 @@ As an alternative to using the `@ActionLayout` annotation, a xref:userguide:fun:
== Usage Notes
+As alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-promptStyle.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-promptStyle.adoc
similarity index 92%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-promptStyle.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-promptStyle.adoc
index 4618339..af4990b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-promptStyle.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-promptStyle.adoc
@@ -9,7 +9,7 @@ For more on sidebar vs modal dialogs, see xref:vw:ROOT:features.adoc#sidebar-vs-
The prompt style is influenced by two xref:vw:ROOT:configuration-properties.adoc[configuration properties]:
-* if the `promptStyle` attribute is set to `DIALOG`, then a configuration property is used to determine whether to render using a modal dialog or a sidebar:
+* if the xref:refguide:applib:index/annotation/ActionLayout.adoc#promptStyle[promptStyle()] element is set to `DIALOG`, then a configuration property is used to determine whether to render using a modal dialog or a sidebar:
** xref:refguide:config:sections/isis.viewer.wicket.adoc#isis.viewer.wicket.dialog-mode[`isis.viewer.wicket.dialog-mode`] if the action is for a domain object (entity or view model)
+
@@ -59,6 +59,3 @@ Assuming that the corresponding property is not itself editable, this means that
The net effect is that a property conceptually consisting of different parts (eg a name, an address or a date) can be updated using an action that lets each separate part be specified independently.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-position.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
similarity index 90%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-position.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
index 017c581..03081aa 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-position.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-position.adoc
@@ -64,5 +64,3 @@ If there are multiple actions associated with a single property then the positio
If the `PANEL` or `PANEL_DROPDOWN` are used, then (as the screenshots above show) the actions from potentially multiple properties grouped by that panel will be shown together.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-The fact that the layout is dynamic (does not require a rebuild/restart) is particularly useful in that the look-n-feel can be easily experimented with and adjusted.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-describedAs.adoc
similarity index 90%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-describedAs.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-describedAs.adoc
index 1442ea5..ddaa8e8 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-describedAs.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-describedAs.adoc
@@ -18,5 +18,3 @@ public class Customer {
----
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-cssClass.adoc
similarity index 91%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-cssClass.adoc
index f912a4c..da52433 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_022-cssClass.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_024-cssClass.adoc
@@ -22,7 +22,3 @@ public class ToDoItem {
The similar xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClassFa[`@ActionLayout#cssClassFa`] annotation attribute is also used as a hint to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] on action menu items or buttons.
====
-==== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-cssClassFa.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-cssClassFa.adoc
similarity index 93%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-cssClassFa.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-cssClassFa.adoc
index 49ec516..1a68661 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_023-cssClassFa.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-cssClassFa.adoc
@@ -36,5 +36,3 @@ There is no need to include the mandatory `fa` "marker" CSS class; it will be au
The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-bookmarking.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
similarity index 92%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-bookmarking.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
index 44c65e4..780d8c5 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_021-bookmarking.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-bookmarking.adoc
@@ -38,6 +38,3 @@ The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmar
====
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-hidden.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-hidden.adoc
similarity index 91%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-hidden.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-hidden.adoc
index 2b96487..56f241d 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_025-hidden.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_027-hidden.adoc
@@ -37,5 +37,3 @@ The action should not be hidden.
The other values of the `Where` enum have no meaning for a collection.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-named.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-named.adoc
similarity index 92%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-named.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-named.adoc
index 2540e57..688dc22 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_026-named.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_028-named.adoc
@@ -25,7 +25,8 @@ public class Customer {
<.> "get" normally indicates a property rather than an action.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
+
+==== Alternatives
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_029-redirect.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_029-redirect.adoc
index 4cd0efb..4127e3e 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_029-redirect.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ActionLayout_029-redirect.adoc
@@ -56,6 +56,3 @@ public class Customer {
If `switchToEditMode()` action is invoked, then the UI will attempt to render the customer using a `Customer.layout.edit.xml` layout file (instead of the default `Customer.layout.xml`).
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_010-examples-and-usage.adoc
index 47ebaa1..797f2e8 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_010-examples-and-usage.adoc
@@ -1,8 +1,9 @@
-== Examples
-
: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:
+
+== Examples
+
For example:
[source,java]
@@ -27,593 +28,3 @@ public class ToDoItem {
== Usage Notes
-
-=== Associating actions with properties and collections
-
-The `associateWith` element allows an action to be associated with other properties or collections of the same domain object.
-The optional `associateWithSequence` element specifies the order of the action in the UI.
-
-For example, an `Order` could have a collection of ``OrderItem``s, and might provide actions to add and remove items:
-
-[source,java]
-----
-public class Order {
-
- @Getter @Setter
- @Collection
- private final SortedSet<OrderItem> items = ...
-
- @Action(
- associateWith="items", // <.>
- associateWithSequence="1" ) // <.>
- public Order addItem(Product p, int quantity) {
- // ...
- }
-
- @Action(
- associateWith="items", // <.>
- associateWithSequence="2" ) // <.>
- public Order removeItem(OrderItem item) {
- // ...
- }
-
- // ...
-}
-----
-
-<.> matches the name of the collection
-<.> first action in the list of all associated actions
-<.> matches the name of the collection
-<.> second action in the list of all associated actions
-
-These actions - `addItem()` and `removeItem()` can be thought of as associated with with the `items` collection because that is the state that they primarily affect.
-
-In the user interface associated actions are rendered close to the member to which they relate.
-
-[NOTE]
-====
-The same effect can be accomplished using `@MemberOrder` or with the `.layout.xml` file.
-====
-
-==== Inferred Defaults and Choices
-
-If an action is associated with a collection, then any scalar or collection parameter of the action that is the same type as that collection will automatically have a list of choices provided for it, being the items of the associated collection.
-
-This is only done provided that there isn't already an explicit `choicesNXxx()` or `autoCompleteNXxx()` supporting method.
-However, this list of choices _does_ take priority over any choices that are inferred from the parameter type itself (as per either an `@DomainObject(autoCompleteRepository=...)` or `@DomainObject(bounded=...)`).
-
-In addition, if the action has a collection parameter of the same type as the associated collection, then the Wicket viewer will render the collection with checkboxes.
-The user can use these checkboxes can be used to select the items of the action parameter.
-
-For example, suppose we have a "removeItems(...)" action:
-
-[source,java]
-----
-import lombok.Getter;
-import lombok.Setter;
-
-public class Order {
-
- @Getter @Setter
- @Collection
- private final SortedSet<OrderItem> items = ...
-
- @Action(
- associateWith="items",
- associateWithSequence="2" )
- public Order removeItems(SortedSet<OrderItem> items) {
- // ...
- }
-
- // ...
-}
-----
-
-The Wicket viewer will then render the "items" collection with checkboxes, and any selected items will be used as the pre-selected set of items if the action is invoked.
-
-=== Command Processing
-
-Every action invocation (and xref:refguide:applib:index/annotation/Property.adoc#commandPublishing[property edit] for that matter) is normally reified into a concrete `Command` object, basically a wrapper around the xref:schema:cmd.adoc[CommandDto] that also captures some timing metrics about the execution as well as the outcome.
-
-The main uses cases are:
-
-* as a means to allow asynchronous child commands to be executed, using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] service;
-
-* as a means to audit (persist) commands, by implementing the xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI.
-+
-The xref:extensions:command-log:about.adoc[Command Log] extension _does_ provide such an implementation.
-+
-TIP: Another option to achieve this is to use the xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] SPI.
-
-* to replay commands onto a secondary system, for regression testing.
-+
-This is implemented by the xref:extensions:command-replay:about.adoc[Command Replay] extension, working in conjunction with the xref:extensions:command-log:about.adoc[Command Log] extension.
-
-
-==== CommandDtoProcessor implementations
-
-The `commandDtoProcessor` element allows an implementation of `CommandDtoProcessor` to be specified.
-This interface has the following API:
-
-[source,java]
-----
-public interface CommandDtoProcessor {
- CommandDto process( // <.>
- CommandDto dto); // <.>
-}
-----
-<.> The returned `CommandDto`.
-This will typically be the `CommandDto` passed in, but may be supplemented in some way.
-<.> The `CommandDto` obtained already from the `Command`.
-
-This interface is used by the framework-provided implementations of xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] for the REST API, allowing ``Command``s implementations that also implement `CommandWithDto` to be further customised as they are serialized out.
-The primary use case for this capability is in support of primary/secondary replication.
-
-* on the primary, ``Command``s are serialized to XML.
-This includes the identity of the target object and the argument values of all parameters.
-
-+
-[IMPORTANT]
-====
-Any ``Blob``s and ``Clob``s are deliberately excluded from this XML (they are instead stored as references).
-This is to prevent the storage requirements for `Command` from becoming excessive.
-A `CommandDtoProcessor` can be provided to re-attach blob information if required.
-====
-
-* replaying ``Command``s requires this missing parameter information to be reinstated.
-The `CommandDtoProcessor` therefore offers a hook to dynamically re-attach the missing `Blob` or `Clob` argument.
-
-As a special case, returning `null` means that the command's DTO is effectively excluded when retrieving the list of commands.
-If replicating from master to slave, this effectively allows certain commands to be ignored.
-The `CommandDtoProcessor.Null` class provides a convenience implementation for this requirement.
-
-[NOTE]
-====
-If `commandDtoProcessor()` is specified, then `commandPublishing()` is assumed to be ENABLED.
-====
-
-==== Example implementation
-
-Consider the following method:
-
-[source,java]
-----
-@Action(
- domainEvent = IncomingDocumentRepository.UploadDomainEvent.class,
- commandDtoProcessor = DeriveBlobArg0FromReturnedDocument.class
-)
-public Document upload(final Blob blob) {
- final String name = blob.getName();
- final DocumentType type = DocumentTypeData.INCOMING.findUsing(documentTypeRepository);
- final ApplicationUser me = meService.me();
- String atPath = me != null ? me.getAtPath() : null;
- if (atPath == null) {
- atPath = "/";
- }
- return incomingDocumentRepository.upsertAndArchive(type, atPath, name, blob);
-}
-----
-
-The `Blob` argument will not be persisted in the memento of the `Command`, but the information is implicitly available in the `Document` that is returned by the action.
-The `DeriveBlobArg0FromReturnedDocument` processor retrieves this information and dynamically adds:
-
-[source,java]
-----
-public class DeriveBlobArg0FromReturnedDocument
- extends CommandDtoProcessorForActionAbstract {
-
- @Override
- public CommandDto process(Command command, CommandDto commandDto) {
- final Bookmark result = commandWithDto.getResult();
- if(result == null) {
- return commandDto;
- }
- try {
- final Document document = bookmarkService.lookup(result, Document.class);
- if (document != null) {
- ParamDto paramDto = getParamDto(commandDto, 0);
- CommonDtoUtils.setValueOn(paramDto, ValueType.BLOB, document.getBlob(), bookmarkService);
- }
- } catch(Exception ex) {
- return commandDto;
- }
- return commandDto;
- }
- @Inject
- BookmarkService bookmarkService;
-}
-----
-
-==== Null implementation
-
-The null implementation can be used to simply indicate that no DTO should be returned for a `Command`.
-The effect is to ignore it for replay purposes:
-
-[source,xml]
-----
-pubc interface CommandDtoProcessor {
- ...
- class Null implements CommandDtoProcessor {
- public CommandDto process(Command command, CommandDto commandDto) {
- return null;
- }
- }
-}
-----
-
-
-=== Domain events
-
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
-In the cases of the domain object's actions, the events that are fired are:
-
-* hide phase: to check that the action is visible (has not been hidden)
-* disable phase: to check that the action is usable (has not been disabled)
-* validate phase: to check that the action's arguments are valid
-* pre-execute phase: before the invocation of the action
-* post-execute: after the invocation of the action
-
-Subscribers subscribe through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`] and can influence each of these phases.
-
-By default the event raised is `ActionDomainEvent.Default`.
-For example:
-
-[source,java]
-----
-public class ToDoItem {
-
- @Action()
- public ToDoItem completed() {
- // ...
- }
- ...
-}
-----
-
-The xref:refguide:applib:index/annotation/Action.adoc#domainEvent[domainEvent()] element allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { } // <1>
- @Action(domainEvent=CompletedEvent.class)
- public ToDoItem completed() { /* ... */ }
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-[NOTE]
-====
-The framework provides no-arg constructor and will initialize the domain event using (non-API) setters rather than through the constructor.
-This substantially reduces the boilerplate required in subclasses because no explicit constructor is required.
-====
-
-==== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ActionDomainEvent.class)
- public void on(ActionDomainEvent ev) {
- ...
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ToDoItem.CompletedEvent.class)
- public void on(ToDoItem.CompletedEvent ev) {
- ...
- }
-}
-----
-
-The subscriber's method is called (up to) 5 times:
-
-* whether to veto visibility (hide)
-* whether to veto usability (disable)
-* whether to veto execution (validate)
-* steps to perform prior to the action being invoked
-* steps to perform after the action has been invoked
-
-The subscriber can distinguish these by calling `ev.getEventPhase()`.
-Thus the general form is:
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
-
- @EventListener(ActionDomainEvent.class)
- public void on(ActionDomainEvent ev) {
- switch(ev.getEventPhase()) {
-
- case HIDE: // <.>
- break;
- case DISABLE: // <.>
- break;
- case VALIDATE: // <.>
- break;
-
- case EXECUTING:
- break;
- case EXECUTED:
- break;
- }
- }
-}
-----
-
-<.> call `ev.hide()` or `ev.veto("")` to hide the action
-
-<.> call `ev.disable("...")` or `ev.veto("...")` to disable the action
-
-<.> call ev.invalidate("...") or ev.veto("...") if action arguments are invalid
-
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
-If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-==== Default, Doop and Noop events
-
-If the xref:refguide:applib:index/annotation/Action.adoc#domainEvent[domainEvent()] element is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` element to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` element is set to this class, then no event will be posted.
-
-=== Class-level default
-
-Sometimes a subscriber is interested in all of the actions of a given class, though not any individual action.
-A common use case is to hide or disable all actions for some particular object for some particular user group.
-
-For this use, the default action domain event can be annotated using `@DomainObject`:
-
-[source,java]
-----
-@DomainObject(
- actionDomainEvent=ToDoItem.ActionDomainEvent.class
-)
-public class ToDoItem {
- public static class ActionDomainEvent extends
- org.apache.isis.applib.events.domain.ActionDomainEvent<Object> { }
- // ...
-
- public void updateDescription(final String description) {
- this.description = description;
- }
-
-}
-----
-
-
-==== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically either by calling the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] API directly, or by emulating the UI by wrapping the target object using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] domain service.
-
-
-
-=== Execution Publishing
-
-The xref:refguide:applib:index/annotation/Action.adoc#executionPublishing[executionPublishing()] element determines whether and how an action invocation is published via the registered implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber].
-
-A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-
-
-The xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property.execution-publishing[`isis.applib.annotation.property.execution-publishing`] configuration property is used to determine the whether the action is published:
-
-* `all`
-+
-all action invocations are published
-
-* `ignoreSafe` (or `ignoreQueryOnly`)
-+
-invocations of actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
-
-* `none`
-+
-no action invocations are published
-
-If there is no configuration property in `application.properties` then publishing is automatically enabled.
-
-This default can be overridden on an action-by-action basis; if `executionPublishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Action(executionPublishing=Publishing.ENABLED) // <.>
- public Invoice generateInvoice(...) {
- // ...
- }
-}
-----
-
-<.> because set to enabled, will be published irrespective of the configured value.
-
-
-=== Deployment modes
-
-By default actions are available irrespective of the xref:refguide:config:about.adoc#deployment-types[deployment mode].
-The xref:refguide:applib:index/annotation/Action.adoc#restrictTo[restrictTo()] element specifies whether the action should instead be restricted to only available in prototyping mode.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Action
- public Order placeNewOrder() {
- // ...
- }
- @Action(semantics=SemanticsOf.SAFE)
- public List<Order> listRecentOrders() {
- // ...
- }
-
- @Action(restrictTo=RestrictTo.PROTOTYPING) // <.>
- public List<Order> listAllOrders() {
- // ...
- }
- ...
-}
-----
-
-<.> Only visible in prototype mode.
-
-In this case the listing of all orders (in the `listAllOrders()` action) probably doesn't make sense for production; there could be thousands or millions.
-However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.
-
-
-=== Action Semantics
-
-
-The xref:refguide:applib:index/annotation/Action.adoc#semantics[semantics()] element describes whether the invocation modifies state of the system, and if so whether it does so idempotently.
-If the action invocation does _not_ modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.
-
-The `semantics` element was originally introduced for the xref:vro:ROOT:about.adoc[RestfulObjects viewer] in order that action invocations could be using the appropriate `HTTP` verb (`GET`, `PUT` and `POST`).
-
-The table below summarizes the semantics:
-
-[cols="2,1,3,1",options="header"]
-|===
-| Semantic
-| Changes state
-| Effect of multiple calls
-| HTTP verb +
-(Restful Objects)
-
-| `SAFE_AND_REQUEST_CACHEABLE`
-| No
-| Will always return the same result each time invoked (within a given request scope)
-| `GET`
-
-| `SAFE`
-| No
-| Might result in different results each invocation
-| `GET`
-
-| `IDEMPOTENT` +
-`IDEMPOTENT_ARE_YOU_SURE`
-| Yes
-| Will make no further changes if called multiple times (eg sets a property or adds to a `Set`). +
-The "are you sure" variant requires that the user must explicitly confirm the action.
-| `PUT`
-
-| `NON_IDEMPOTENT` +
-`NON_IDEMPOTENT_ARE_YOU_SURE`
-| Yes
-| Might change the state of the system each time called (eg increments a counter or adds to a `List`). +
-The "are you sure" variant requires that the user must explicitly confirm the action.
-| `POST`
-
-|===
-
-The actions' semantics are also used by the core runtime as part of the in-built concurrency checkng; invocation of a safe action (which includes request-cacheable) does _not_ perform a concurrency check, whereas non-safe actions _do_ perform a concurrency check.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Action(semantics=SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)
- public CreditRating checkCredit() {
- // ...
- }
-
- @Action(semantics=SemanticsOf.IDEMPOTENT)
- public void changeOfAddress(Address address) {
- // ...
- }
-
- @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
- public Order placeNewOrder() {
- // ...
- }
-
- // ...
-}
-----
-
-Actions that are safe and request-cacheable automatically use the xref:refguide:applib:index/services/queryresultscache/QueryResultsCache.adoc[`QueryResultsCache`] service to cache the result of the method.
-Note though that the results of this caching will only be apparent if the action is invoked from another method using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] service.
-
-
-=== Collection type
-
-The xref:refguide:applib:index/annotation/Action.adoc#typeOf[typeOf()] element specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.
-
-For example:
-
-[source,java]
-----
-public void AccountService {
-
- @Action(typeOf=Customer.class)
- public List errantAccounts() {
- return customers.allNewCustomers();
- }
- ...
-
- @Inject CustomerRepository customers;
-}
-----
-
-In general we recommend that you use generics instead, eg `List<Customer>`.
-
-
-
-
-== Related SPIs
-
-* xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI
-+
-foractions with xref:refguide:applib:index/annotation/Action.adoc#commandPublishing[commandPublishing] enabled
-
-** xref:extensions:command-log:about.adoc[Command Log] extension
-+
-provides an implementation that simply logs actions for
-
-** xref:extensions:command-replay:about.adoc[Command Replay] extension
-+
-provides an implementation to replicate commands from a primary to a secondary system.
-+
-This implementation also leverages xref:refguide:applib:index/annotation/Action.adoc#commandDtoProcessor[commandDtoProcessor()] to process ``CommandDto``s before being replciated
-
-* xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] SPI
-+
-for actions where xref:refguide:applib:index/annotation/Action.adoc#executionPublishing[executionPublishing] is enabled
-
-== See also
-
-* xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService]
-+
-which broadcast the action's domain event -- as specified by xref:refguide:applib:index/annotation/Action.adoc#domainEvent[domainEvent()] -- for business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execute).
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc
new file mode 100644
index 0000000..d6c1040
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_021-associating.adoc
@@ -0,0 +1,51 @@
+: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:
+
+
+=== Associating actions with properties and collections
+
+The `associateWith` element allows an action to be associated with other properties or collections of the same domain object.
+The optional `associateWithSequence` element specifies the order of the action in the UI.
+
+For example, an `Order` could have a collection of ``OrderItem``s, and might provide actions to add and remove items:
+
+[source,java]
+----
+public class Order {
+
+ @Getter @Setter
+ @Collection
+ private final SortedSet<OrderItem> items = ...
+
+ @Action(
+ associateWith="items", // <.>
+ associateWithSequence="1" ) // <.>
+ public Order addItem(Product p, int quantity) {
+ // ...
+ }
+
+ @Action(
+ associateWith="items", // <.>
+ associateWithSequence="2" ) // <.>
+ public Order removeItem(OrderItem item) {
+ // ...
+ }
+
+ // ...
+}
+----
+
+<.> matches the name of the collection
+<.> first action in the list of all associated actions
+<.> matches the name of the collection
+<.> second action in the list of all associated actions
+
+These actions - `addItem()` and `removeItem()` can be thought of as associated with with the `items` collection because that is the state that they primarily affect.
+
+In the user interface associated actions are rendered close to the member to which they relate.
+
+[NOTE]
+====
+The same effect can be accomplished using `@MemberOrder` or with the `.layout.xml` file.
+====
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_022-action-semantics.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_022-action-semantics.adoc
new file mode 100644
index 0000000..5e46a1a
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_022-action-semantics.adoc
@@ -0,0 +1,79 @@
+: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:
+
+
+
+=== Action Semantics
+
+
+The xref:refguide:applib:index/annotation/Action.adoc#semantics[semantics()] element describes whether the invocation modifies state of the system, and if so whether it does so idempotently.
+If the action invocation does _not_ modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.
+
+The `semantics` element was originally introduced for the xref:vro:ROOT:about.adoc[RestfulObjects viewer] in order that action invocations could be using the appropriate `HTTP` verb (`GET`, `PUT` and `POST`).
+
+The table below summarizes the semantics:
+
+[cols="2,1,3,1",options="header"]
+|===
+| Semantic
+| Changes state
+| Effect of multiple calls
+| HTTP verb +
+(Restful Objects)
+
+| `SAFE_AND_REQUEST_CACHEABLE`
+| No
+| Will always return the same result each time invoked (within a given request scope)
+| `GET`
+
+| `SAFE`
+| No
+| Might result in different results each invocation
+| `GET`
+
+| `IDEMPOTENT` +
+`IDEMPOTENT_ARE_YOU_SURE`
+| Yes
+| Will make no further changes if called multiple times (eg sets a property or adds to a `Set`). +
+The "are you sure" variant requires that the user must explicitly confirm the action.
+| `PUT`
+
+| `NON_IDEMPOTENT` +
+`NON_IDEMPOTENT_ARE_YOU_SURE`
+| Yes
+| Might change the state of the system each time called (eg increments a counter or adds to a `List`). +
+The "are you sure" variant requires that the user must explicitly confirm the action.
+| `POST`
+
+|===
+
+The actions' semantics are also used by the core runtime as part of the in-built concurrency checkng; invocation of a safe action (which includes request-cacheable) does _not_ perform a concurrency check, whereas non-safe actions _do_ perform a concurrency check.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+ @Action(semantics=SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)
+ public CreditRating checkCredit() {
+ // ...
+ }
+
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public void changeOfAddress(Address address) {
+ // ...
+ }
+
+ @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
+ public Order placeNewOrder() {
+ // ...
+ }
+
+ // ...
+}
+----
+
+Actions that are safe and request-cacheable automatically use the xref:refguide:applib:index/services/queryresultscache/QueryResultsCache.adoc[`QueryResultsCache`] service to cache the result of the method.
+Note though that the results of this caching will only be apparent if the action is invoked from another method using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] service.
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_023-deployment-modes.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_023-deployment-modes.adoc
new file mode 100644
index 0000000..9dbbc97
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_023-deployment-modes.adoc
@@ -0,0 +1,37 @@
+: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:
+
+
+=== Deployment modes
+
+By default actions are available irrespective of the xref:refguide:config:about.adoc#deployment-types[deployment mode].
+The xref:refguide:applib:index/annotation/Action.adoc#restrictTo[restrictTo()] element specifies whether the action should instead be restricted to only available in prototyping mode.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+ @Action
+ public Order placeNewOrder() {
+ // ...
+ }
+ @Action(semantics=SemanticsOf.SAFE)
+ public List<Order> listRecentOrders() {
+ // ...
+ }
+
+ @Action(restrictTo=RestrictTo.PROTOTYPING) // <.>
+ public List<Order> listAllOrders() {
+ // ...
+ }
+ ...
+}
+----
+
+<.> Only visible in prototype mode.
+
+In this case the listing of all orders (in the `listAllOrders()` action) probably doesn't make sense for production; there could be thousands or millions.
+However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_024-domain-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_024-domain-events.adoc
new file mode 100644
index 0000000..cee4120
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_024-domain-events.adoc
@@ -0,0 +1,175 @@
+: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:
+
+
+=== Domain events
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
+In the cases of the domain object's actions, the events that are fired are:
+
+* hide phase: to check that the action is visible (has not been hidden)
+* disable phase: to check that the action is usable (has not been disabled)
+* validate phase: to check that the action's arguments are valid
+* pre-execute phase: before the invocation of the action
+* post-execute: after the invocation of the action
+
+Subscribers subscribe through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`] and can influence each of these phases.
+
+By default the event raised is `ActionDomainEvent.Default`.
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+
+ @Action()
+ public ToDoItem completed() {
+ // ...
+ }
+ ...
+}
+----
+
+The xref:refguide:applib:index/annotation/Action.adoc#domainEvent[domainEvent()] element allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { } // <1>
+ @Action(domainEvent=CompletedEvent.class)
+ public ToDoItem completed() { /* ... */ }
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+[NOTE]
+====
+The framework provides a no-arg constructor and will initialize the domain event using (non-API) setters rather than through the constructor.
+This substantially reduces the boilerplate required in subclasses because no explicit constructor is required.
+====
+
+==== Subscribers
+
+Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`].
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Service;
+
+@Service
+public class SomeSubscriber {
+ @EventListener(ActionDomainEvent.class)
+ public void on(ActionDomainEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Service;
+
+@Service
+public class SomeSubscriber {
+ @EventListener(ToDoItem.CompletedEvent.class)
+ public void on(ToDoItem.CompletedEvent ev) {
+ ...
+ }
+}
+----
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the action being invoked
+* steps to perform after the action has been invoked
+
+The subscriber can distinguish these by calling `ev.getEventPhase()`.
+Thus the general form is:
+
+[source,java]
+----
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Service;
+
+@Service
+public class SomeSubscriber {
+
+ @EventListener(ActionDomainEvent.class)
+ public void on(ActionDomainEvent ev) {
+ switch(ev.getEventPhase()) {
+
+ case HIDE: // <.>
+ break;
+ case DISABLE: // <.>
+ break;
+ case VALIDATE: // <.>
+ break;
+
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+ }
+}
+----
+
+<.> call `ev.hide()` or `ev.veto("")` to hide the action
+<.> call `ev.disable("...")` or `ev.veto("...")` to disable the action
+<.> call ev.invalidate("...") or ev.veto("...") if action arguments are invalid
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
+If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+==== Default, Doop and Noop events
+
+If the xref:refguide:applib:index/annotation/Action.adoc#domainEvent[domainEvent()] element is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`), then the framework will, by default, post an event.
+
+If this is not required, then the xref:config:sections/isis.applib.adoc#isis.applib.annotation.action.domain-event.post-for-default[isis.applib.annotation.action.domain-event.post-for-default] configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` element to this class will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` element is set to this class, then no event will be posted.
+
+==== Class-level default
+
+Sometimes a subscriber is interested in all of the actions of a given class, though not any individual action.
+A common use case is to hide or disable all actions for some particular object for some particular user group.
+
+For this use, the default action domain event can be annotated using `@DomainObject`:
+
+[source,java]
+----
+@DomainObject(
+ actionDomainEvent=ToDoItem.ActionDomainEvent.class
+)
+public class ToDoItem {
+ public static class ActionDomainEvent extends
+ org.apache.isis.applib.events.domain.ActionDomainEvent<Object> { }
+ // ...
+
+ public void updateDescription(final String description) {
+ this.description = description;
+ }
+}
+----
+
+
+==== Raising events programmatically
+
+Normally events are only raised for interactions through the UI.
+However, events can be raised programmatically either by calling the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] API directly, or by emulating the UI by wrapping the target object using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] domain service.
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_025-execution-publishing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_025-execution-publishing.adoc
new file mode 100644
index 0000000..5f77cb3
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_025-execution-publishing.adoc
@@ -0,0 +1,43 @@
+: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:
+
+
+=== Execution Publishing
+
+The xref:refguide:applib:index/annotation/Action.adoc#executionPublishing[executionPublishing()] element determines whether and how an action invocation is published via the registered implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber].
+
+A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
+
+The xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property.execution-publishing[`isis.applib.annotation.property.execution-publishing`] configuration property is used to determine the whether the action invocation is published:
+
+* `all`
++
+all action invocations are published
+
+* `ignoreSafe` (or `ignoreQueryOnly`)
++
+invocations of actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+
+* `none`
++
+no action invocations are published
+
+If there is no configuration property in `application.properties` then publishing is automatically enabled.
+
+This default can be overridden on an action-by-action basis; if `executionPublishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(executionPublishing=Publishing.ENABLED) // <.>
+ public Invoice generateInvoice(...) {
+ // ...
+ }
+}
+----
+
+<.> because set to enabled, will be published irrespective of the configured value.
+
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_026-command-processing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_026-command-processing.adoc
new file mode 100644
index 0000000..e42bb80
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_026-command-processing.adoc
@@ -0,0 +1,136 @@
+: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:
+
+
+=== Command Processing
+
+Every action invocation (and xref:refguide:applib:index/annotation/Property.adoc#commandPublishing[property edit] for that matter) is normally reified into a concrete `Command` object, basically a wrapper around the xref:schema:cmd.adoc[CommandDto] that also captures some timing metrics about the execution as well as the outcome.
+
+The main uses cases are:
+
+* as a means to allow asynchronous child commands to be executed, using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] service;
+
+* as a means to audit (persist) commands, by implementing the xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI.
++
+The xref:extensions:command-log:about.adoc[Command Log] extension _does_ provide such an implementation.
++
+TIP: Another option to achieve this is to use the xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] SPI.
+
+* to replay commands onto a secondary system, for regression testing.
++
+This is implemented by the xref:extensions:command-replay:about.adoc[Command Replay] extension, working in conjunction with the xref:extensions:command-log:about.adoc[Command Log] extension.
+
+The xref:refguide:applib:index/annotation/Action.adoc#commandPublishing[commandPublishing()] element can be used to explicitly enable or disable command publishing for the action invocation.
+
+
+==== CommandDtoProcessor implementations
+
+The xref:refguide:applib:index/annotation/Action.adoc#commandDtoProcessor[commandDtoProcessor()] element allows an implementation of `CommandDtoProcessor` to be specified.
+This interface has the following API:
+
+[source,java]
+----
+public interface CommandDtoProcessor {
+ CommandDto process( // <.>
+ CommandDto dto); // <.>
+}
+----
+<.> The returned `CommandDto`.
+This will typically be the `CommandDto` passed in, but may be supplemented in some way.
+<.> The `CommandDto` obtained already from the `Command`.
+
+This interface is used by the framework-provided implementations of xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] for the REST API, allowing ``Command``s implementations that also implement `CommandWithDto` to be further customised as they are serialized out.
+The primary use case for this capability is in support of primary/secondary replication.
+
+* on the primary, ``Command``s are serialized to XML.
+This includes the identity of the target object and the argument values of all parameters.
+
++
+[IMPORTANT]
+====
+Any ``Blob``s and ``Clob``s are deliberately excluded from this XML (they are instead stored as references).
+This is to prevent the storage requirements for `Command` from becoming excessive.
+A `CommandDtoProcessor` can be provided to re-attach blob information if required.
+====
+
+* replaying ``Command``s requires this missing parameter information to be reinstated.
+The `CommandDtoProcessor` therefore offers a hook to dynamically re-attach the missing `Blob` or `Clob` argument.
+
+As a special case, returning `null` means that the command's DTO is effectively excluded when retrieving the list of commands.
+If replicating from master to slave, this effectively allows certain commands to be ignored.
+The `CommandDtoProcessor.Null` class provides a convenience implementation for this requirement.
+
+[NOTE]
+====
+If `commandDtoProcessor()` is specified, then `commandPublishing()` is assumed to be ENABLED.
+====
+
+==== Example
+
+Consider the following method:
+
+[source,java]
+----
+@Action(
+ domainEvent = IncomingDocumentRepository.UploadDomainEvent.class,
+ commandDtoProcessor = DeriveBlobArg0FromReturnedDocument.class
+)
+public Document upload(final Blob blob) {
+ final String name = blob.getName();
+ final DocumentType type = DocumentTypeData.INCOMING.findUsing(documentTypeRepository);
+ final ApplicationUser me = meService.me();
+ String atPath = me != null ? me.getAtPath() : null;
+ if (atPath == null) {
+ atPath = "/";
+ }
+ return incomingDocumentRepository.upsertAndArchive(type, atPath, name, blob);
+}
+----
+
+The `Blob` argument will not be persisted in the memento of the `Command`, but the information is implicitly available in the `Document` that is returned by the action.
+The `DeriveBlobArg0FromReturnedDocument` processor retrieves this information and dynamically adds:
+
+[source,java]
+----
+public class DeriveBlobArg0FromReturnedDocument
+ extends CommandDtoProcessorForActionAbstract {
+
+ @Override
+ public CommandDto process(Command command, CommandDto commandDto) {
+ final Bookmark result = commandWithDto.getResult();
+ if(result == null) {
+ return commandDto;
+ }
+ try {
+ final Document document = bookmarkService.lookup(result, Document.class);
+ if (document != null) {
+ ParamDto paramDto = getParamDto(commandDto, 0);
+ CommonDtoUtils.setValueOn(paramDto, ValueType.BLOB, document.getBlob(), bookmarkService);
+ }
+ } catch(Exception ex) {
+ return commandDto;
+ }
+ return commandDto;
+ }
+ @Inject
+ BookmarkService bookmarkService;
+}
+----
+
+==== Null implementation
+
+The null implementation can be used to simply indicate that no DTO should be returned for a `Command`.
+The effect is to ignore it for replay purposes:
+
+[source,xml]
+----
+pubc interface CommandDtoProcessor {
+ ...
+ class Null implements CommandDtoProcessor {
+ public CommandDto process(Command command, CommandDto commandDto) {
+ return null;
+ }
+ }
+}
+----
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_027-collection-types.adoc
similarity index 57%
copy from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc
copy to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_027-collection-types.adoc
index 082476b..443d07c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_027-collection-types.adoc
@@ -1,29 +1,29 @@
-=== Descriptions
-
: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 xref:refguide:applib:index/annotation/ParameterLayout.adoc#describedAs[describedAs()] element is used to provide a short description of the action parameter to the user.
+=== Collection type
-In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'.
+The xref:refguide:applib:index/annotation/Action.adoc#typeOf[typeOf()] element specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.
For example:
[source,java]
----
-public class Customer {
-
- public Order placeOrder(
- Product product,
- @ParameterLayout(
- describedAs = "The quantity of the product being ordered"
- )
- int quantity) {
- // ...
+public void AccountService {
+
+ @Action(typeOf=Customer.class)
+ public List errantAccounts() {
+ return customers.allNewCustomers();
}
+ ...
- // ...
+ @Inject CustomerRepository customers;
}
----
+In general we recommend that you use generics instead, eg `List<Customer>`.
+
+
+
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_030-see-also.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_030-see-also.adoc
new file mode 100644
index 0000000..56340fc
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Action_030-see-also.adoc
@@ -0,0 +1,31 @@
+: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:
+
+
+== Related SPIs
+
+* xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI
++
+for actions where command publishing (as per xref:refguide:applib:index/annotation/Action.adoc#commandPublishing[@Action#commandPublishing()]) is enabled
+
+** xref:extensions:command-log:about.adoc[Command Log] extension
++
+provides an implementation that simply logs actions using the logging library
+
+** xref:extensions:command-replay:about.adoc[Command Replay] extension
++
+provides an implementation to replicate commands from a primary to a secondary system.
++
+This implementation also leverages xref:refguide:applib:index/annotation/Action.adoc#commandDtoProcessor[commandDtoProcessor()] to process ``CommandDto``s before being replciated
+
+* xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] SPI
++
+for actions where execution publishing (as per xref:refguide:applib:index/annotation/Action.adoc#executionPublishing[@Action#executionPublishing]) is enabled
+
+
+== See also
+
+* xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService]
++
+which broadcasts domain events as per xref:refguide:applib:index/annotation/Action.adoc#domainEvent[@Action#domainEvent()]
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
index 63f0daa..946e2d9 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_010-examples-and-usage.adoc
@@ -33,3 +33,4 @@ This is specifically so that boilerplate-busting tools such as link:https://proj
== Usage Notes
+As alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-defaultView.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-defaultView.adoc
similarity index 92%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-defaultView.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-defaultView.adoc
index ddd9fea..9c59b8a 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-defaultView.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-defaultView.adoc
@@ -27,6 +27,3 @@ public class BusRoute {
The xref:vw:ROOT:about.adoc[Wicket viewer] allows additional views to be configured to render collections of objects, eg xref:vw:exceldownload:about.adoc[Excel Download] ("excel"), xref:vw:fullcalendar:about.adoc[Fullcalendar] ("fullcalendar") and xref:vw:gmap3:about.adoc[Gmap3] ("map") extensions.
This attribute can be used to select any of these alternative views instead.
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-paged.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-paged.adoc
similarity index 92%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-paged.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-paged.adoc
index d15d68b..2a22ed2 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-paged.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_022-paged.adoc
@@ -31,5 +31,3 @@ public class Order {
It is also possible to specify a global default for the page size of parented collections, using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.collection-layout.paged[`isis.applib.annotation.collection-layout.paged`] configuration property.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_023-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_023-describedAs.adoc
index 588f2b0..96f94ef 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_023-describedAs.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_023-describedAs.adoc
@@ -24,5 +24,3 @@ public class ToDoItem {
}
----
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-sortedBy.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-sortedBy.adoc
similarity index 93%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-sortedBy.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-sortedBy.adoc
index d5b38e3..c25ee28 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-sortedBy.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-sortedBy.adoc
@@ -36,4 +36,3 @@ public class ToDoItem implements Comparable<ToDoItem> { // <.>
When the `dependencies` collection is rendered, the elements are sorted by the `description` property first.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-cssClass.adoc
similarity index 91%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-cssClass.adoc
index 1a71a85..465f35c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_021-cssClass.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-cssClass.adoc
@@ -24,5 +24,3 @@ public class ToDoItem {
}
----
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-named.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-named.adoc
similarity index 93%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-named.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-named.adoc
index 737b026..0ff2408 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_025-named.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_026-named.adoc
@@ -33,7 +33,7 @@ public class ToDoItem {
----
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
+==== Alternatives
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-hidden.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-hidden.adoc
similarity index 88%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-hidden.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-hidden.adoc
index 64f839e..6144c59 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_024-hidden.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/CollectionLayout_027-hidden.adoc
@@ -45,7 +45,5 @@ public class ToDoItem {
==== Alternatives
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-It is also possible to use xref:refguide:applib:index/annotation/Collection.adoc#hidden[`@Collection#hidden`] to hide an action at the domain layer.
+It is also possible to use xref:refguide:applib:index/annotation/Collection.adoc#hidden[`@Collection#hidden`] to hide a collection at the domain layer.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_023-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_021-describedAs.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_023-describedAs.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_021-describedAs.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_021-cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_022-cssClass.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_021-cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_022-cssClass.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_022-cssClassFa.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_023-cssClassFa.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_022-cssClassFa.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_023-cssClassFa.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_029-objectType.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-objectType.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_029-objectType.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-objectType.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_028-nature.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_028-nature.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_025-editing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_023-editing.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_025-editing.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_023-editing.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-domain-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_024-domain-events.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-domain-events.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_024-domain-events.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-lifecycle-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_025-lifecycle-events.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-lifecycle-events.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_025-lifecycle-events.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_024-bounding.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_027-bounding.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_024-bounding.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_027-bounding.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_023-autoCompleteRepository.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_028-autoCompleteRepository.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_023-autoCompleteRepository.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_028-autoCompleteRepository.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_027-mixinMethod.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_029-mixinMethod.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_027-mixinMethod.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_029-mixinMethod.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_030-see-also.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_040-see-also.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_030-see-also.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_040-see-also.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-labelPosition.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_021-labelPosition.adoc
similarity index 68%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-labelPosition.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_021-labelPosition.adoc
index d45498d..7bad118 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-labelPosition.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_021-labelPosition.adoc
@@ -33,3 +33,25 @@ public class Order {
}
----
+==== Default settings
+
+If you want a consistent look-n-feel throughout the app, eg all parameter labels to the top, then it'd be rather frustrating to have to annotate every parameter.
+
+Instead, a default can be specified using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.parameter-layout.label-position[`isis.applib.annotation.parameter-layout.label-position`] configuration property:
+
+[source,ini]
+.application.properties
+----
+isis.applib.annotation.parameter-layout.label-position=TOP
+----
+
+or
+
+[source,ini]
+.application.properties
+----
+isis.applib.annotation.parameter-layout.label-position=LEFT
+----
+
+If these are not present then the framework will render according to internal defaults.
+At the time of writing, this means labels are to the left for all datatypes except multiline strings.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_024-multiLine.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-multiLine.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_024-multiLine.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-multiLine.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-describedAs.adoc
similarity index 100%
copy from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc
copy to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_023-describedAs.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_021-cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_024-cssClass.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_021-cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_024-cssClass.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_026-renderDay.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_025-renderDay.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_026-renderDay.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_025-renderDay.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_025-named.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_026-named.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_025-named.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_026-named.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_027-typicalLength.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_027-typicalLength.adoc
index 1dff7bb..cf42415 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_027-typicalLength.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_027-typicalLength.adoc
@@ -7,7 +7,6 @@
The xref:refguide:applib:index/annotation/ParameterLayout.adoc#typicalLength[typicalLength()] element indicates the typical length of a string parameter.
It is ignored for parameters of other types.
-The attribute is also supported for xref:refguide:applib:index/annotation/PropertyLayout.adoc#typicalLength[properties].
The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_024-optionality.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_021-optionality.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_024-optionality.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_021-optionality.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_025-regexPattern.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_024-regexPattern.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_025-regexPattern.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_024-regexPattern.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_021-fileAccept.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_025-fileAccept.adoc
similarity index 100%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_021-fileAccept.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Parameter_025-fileAccept.adoc
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
index 94b8518..73c24f6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_010-examples-and-usage.adoc
@@ -41,3 +41,5 @@ so that boilerplate-busting tools such as link:https://projectlombok.org/[Projec
== Usage Notes
+
+As alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can generally be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/labelPosition.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_021_labelPosition.adoc
similarity index 53%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/labelPosition.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_021_labelPosition.adoc
index 56b35c8..324b2cc 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/labelPosition.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_021_labelPosition.adoc
@@ -1,15 +1,13 @@
-[#labelPosition]
-= `labelPosition()`
+=== Label Positioning
: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 `labelPosition` attribute determines the positioning of labels for properties.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#labelPosition[labelPosition()] element determines the positioning of labels for properties.
The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.
-The one exception is xref:refguide:applib:index/annotation/ParameterLayout.adoc#multiLine[`multiLine`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+The one exception is xref:refguide:applib:index/annotation/PropertyLayout.adoc#multiLine[`multiLine`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
For boolean properties a positioning of `RIGHT` is also allowed; this is ignored for all other types.
@@ -34,32 +32,7 @@ public class ToDoItem {
}
----
-To get an idea of how these are rendered (in the xref:vw:ROOT:about.adoc[Wicket viewer]), we can look at some examples of most of these various label positions.
-
-The default `LEFT` label positioning is used by the `cost` property:
-
-image::reference-annotations/PropertyLayout/labelPosition-LEFT.png[width="720px"]
-
-
-The `TOP` label positioning is used by the `category` property:
-
-image::reference-annotations/PropertyLayout/labelPosition-TOP.png[width="720px"]
-
-
-Labels are suppressed, using `NONE`, for the `subcategory` property:
-
-image::reference-annotations/PropertyLayout/labelPosition-NONE.png[width="720px"]
-
-
-The todoapp's `complete` (boolean) property renders the label to the LEFT (the default):
-
-image::reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png[width="720px"]
-
-Moving the label to the `RIGHT` looks like:
-
-image::reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[width="720px"]
-
-== Default settings
+==== Default settings
If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
@@ -79,15 +52,7 @@ or
isis.applib.annotation.property-layout.label-position=LEFT
----
-If these are not present then Apache Isis will render according to internal defaults.
+If these are not present then the framework will render according to internal defaults.
At the time of writing, this means labels are to the left for all datatypes except multiline strings.
-== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-== See also
-
-This attribute can also be specified for xref:refguide:applib:index/annotation/ParameterLayout.adoc#labelPosition[parameters].
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/promptStyle.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_022_promptStyle.adoc
similarity index 79%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/promptStyle.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_022_promptStyle.adoc
index b5e1b99..9f3a324 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/promptStyle.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_022_promptStyle.adoc
@@ -1,11 +1,10 @@
-[#promptStyle]
-= `promptStyle()`
+=== Prompt Style
: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 `promptStyle` attribute is used to specify whether, when editing a domain object property, the new value for the property is prompted by way of a dialog box, or is prompted using an inline panel (replacing the property on the page).
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#promptStyle[promptStyle()] element is used to specify whether, when editing a domain object property, the new value for the property is prompted by way of a dialog box, or is prompted using an inline panel (replacing the property on the page).
If the attribute is not set, then the value of the xref:refguide:config:sections/isis.viewer.wicket.adoc#isis.viewer.wicket.prompt-style[`isis.viewer.wicket.prompt-style`] configuration property is used.
If this is itself not set, then an inline prompt is used.
@@ -28,8 +27,8 @@ public class Customer {
// ...
}
----
+
<.> prompt for the new value for the property using an inline panel
Note that the value `INLINE_AS_IF_EDIT` does not make sense for properties; if specified then it will be interpreted as just `INLINE`.
-Alternatively, the `promptStyle()` can be specified using xref:userguide:fun:ui.adoc#object-layout[file-based layouts].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/multiLine.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_023_multiLine.adoc
similarity index 72%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/multiLine.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_023_multiLine.adoc
index 3562f8c..b74c16a 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/multiLine.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_023_multiLine.adoc
@@ -1,13 +1,13 @@
-[#multiLine]
-= `multiLine()`
+=== Text boxes
: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 `multiLine` attribute specifies that the text field for a string property should span multiple lines.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#multiLine[multiLine()] element specifies that the text field for a string property should span multiple lines.
It is ignored for other property types.
-The attribute is also supported for xref:refguide:applib:index/annotation/ParameterLayout.adoc#multiLine[parameters].
+
+If set > 1 (as would normally be the case), then the default xref:refguide:applib:index/annotation/PropertyLayout.adoc#labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
For example:
@@ -28,14 +28,6 @@ public class BugReport {
}
----
-Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
-
-[NOTE]
-====
-If set > 1 (as would normally be the case), then the default xref:refguide:applib:index/annotation/PropertyLayout.adoc#labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
-====
-
-== Alternatives
+Here the `stepsToReproduce` property will be displayed in a text box of 10 rows.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/navigable.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_024_navigable.adoc
similarity index 84%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/navigable.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_024_navigable.adoc
index db2171d..0b6ec6b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/navigable.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_024_navigable.adoc
@@ -1,11 +1,10 @@
-[#navigable]
-= `navigable()`
+=== Breadcrumbs (where am I?)
: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 `navigable` attribute allows to specify a domain object's (or view's) navigable parent, as utilized by the 'Where am I' feature.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#navigable[navigable()] element allows to specify a domain object's (or view's) navigable parent, as utilized by the 'Where am I' feature.
For example, suppose:
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_025_describedAs.adoc
similarity index 70%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_025_describedAs.adoc
index 082476b..1266450 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/ParameterLayout_022-describedAs.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_025_describedAs.adoc
@@ -4,7 +4,8 @@
:page-partial:
-The xref:refguide:applib:index/annotation/ParameterLayout.adoc#describedAs[describedAs()] element is used to provide a short description of the action parameter to the user.
+
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#describedAs[describedAs()] element is used to provide a short description of the property to the user.
In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'.
@@ -14,16 +15,14 @@ For example:
----
public class Customer {
- public Order placeOrder(
- Product product,
- @ParameterLayout(
- describedAs = "The quantity of the product being ordered"
- )
- int quantity) {
- // ...
- }
+ @PropertyLayout(
+ describedAs = "The name that the customer has indicated " +
+ "that they wish to be addressed as " +
+ "(e.g. Johnny rather than Jonathan)")
+ private String firstName;
// ...
}
----
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_026_cssClass.adoc
similarity index 62%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_026_cssClass.adoc
index b045b67..3682864 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/cssClass.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_026_cssClass.adoc
@@ -1,11 +1,10 @@
-[#cssClass]
-= `cssClass()`
+=== CSS Styling
: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 `cssClass` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#cssClass[cssClass()] element can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.
xref:refguide:config:application-specific/application-css.adoc[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
For example:
@@ -25,17 +24,3 @@ public class ToDoItem {
}
----
-== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-== See also
-
-This attribute can also be applied to:
-
-* xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClass[domain objects]
-* xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClass[actions]
-* xref:refguide:applib:index/annotation/CollectionLayout.adoc#cssClass[collections]
-* xref:refguide:applib:index/annotation/ParameterLayout.adoc#cssClass[parameters].
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/renderDay.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_027_renderDay.adoc
similarity index 80%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/renderDay.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_027_renderDay.adoc
index 30dd69f..5e5e325 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/renderDay.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_027_renderDay.adoc
@@ -1,11 +1,10 @@
-[#renderDay]
-= `renderDay()`
+=== Date intervals
: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 `renderDay` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#renderDay[renderDay()] element applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.
It is ignored for properties of other types.
This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.
@@ -37,11 +36,4 @@ public class Tenancy {
}
----
-== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-== See also
-
-This attribute is also supported for xref:refguide:applib:index/annotation/ParameterLayout.adoc#renderDay[parameters].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/repainting.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_028_repainting.adoc
similarity index 88%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/repainting.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_028_repainting.adoc
index 0e6c20e..9197f0b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/repainting.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_028_repainting.adoc
@@ -1,11 +1,10 @@
-[#repainting]
-= `repainting()`
+=== Smoother UI
: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 `repainting` attribute is used to indicate that the value held by the property never changes over time, even when other properties of the object do change.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#repainting[repainting()] element is used to indicate that the value held by the property never changes over time, even when other properties of the object do change.
Setting this attribute to `true` is used as a hint to the viewer to not redraw the property after an AJAX update of some other property/ies of the object have changed.
This is primarily for performance, eg can improve the user experience when rendering PDFs/blobs.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/named.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_029_named.adoc
similarity index 63%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/named.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_029_named.adoc
index d9ed34a..c29e5cf 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/named.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_029_named.adoc
@@ -1,11 +1,10 @@
-[#named]
-= `named()`
+=== Names
: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 `named` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#named[named()] element explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code.
[TIP]
====
@@ -13,8 +12,9 @@ We recommend that you only use this element when the desired name cannot be used
Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
====
+
By default the name is HTML escaped.
-To allow HTML markup, set the related `namedEscaped` attribute to `false`.
+To allow HTML markup, set the related xref:refguide:applib:index/annotation/PropertyLayout.adoc#namedEscaped[namedEscaped()] to `false`.
For example:
@@ -36,19 +36,7 @@ public class ToDoItem {
}
----
-== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
+==== Alternatives
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
-== See also
-
-This attribute can also be specified for:
-
-* xref:refguide:applib:index/annotation/ActionLayout.adoc#named[actions]
-* xref:refguide:applib:index/annotation/CollectionLayout.adoc#named[collections]
-* xref:refguide:applib:index/annotation/ParameterLayout.adoc#named[parameters]
-* xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#named[domain objects]
-* xref:refguide:applib:index/annotation/DomainServiceLayout.adoc#named[domain services].
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/hidden.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_030_hidden.adoc
similarity index 68%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/hidden.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_030_hidden.adoc
index f5bafff..b0d515b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/hidden.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_030_hidden.adoc
@@ -1,36 +1,10 @@
-[#hidden]
-= `hidden()`
+=== Hiding properties
: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 `hidden` attribute indicates where (in the UI) the property should be hidden from the user.
-
-[TIP]
-====
-It is also possible to use xref:refguide:applib:index/annotation/PropertyLayout.adoc#hidden[`@PropertyLayout#hidden`] or a xref:userguide:fun:ui.adoc#object-layout[file-based layout] such that the property can be hidden at the view layer.
-Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
-====
-
-For example:
-
-[source,java]
-----
-import lombok.Getter;
-import lombok.Setter;
-
-public class Customer {
-
- @PropertyLayout(
- hidden=Where.ALL_TABLES
- )
- @Getter @Setter
- private int internalId;
-
- // ...
-}
-----
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#hidden[hidden()] element attribute indicates where (in the UI) the property should be hidden from the user.
The acceptable values for the `where` parameter are:
@@ -63,22 +37,38 @@ This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
+
The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden.
-For example, if a property is annotated with xref:refguide:applib:index/annotation/Title.adoc[`@Title`], then normally this should be hidden from all tables.
-Annotating with `@Property(where=Where.NOWHERE)` overrides this.
-
[NOTE]
====
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] has only partial support for these `Where` enums.
====
-== Alternatives
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
+==== Examples
+
+For example:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
+
+public class Customer {
+
+ @PropertyLayout(
+ hidden=Where.ALL_TABLES
+ )
+ @Getter @Setter
+ private int internalId;
+
+ // ...
+}
+----
-== See also
-This attribute can also be applied to:
+As one specific use case, if a property is annotated with xref:refguide:applib:index/annotation/Title.adoc[`@Title`], then normally this should be hidden from all tables.
+Annotating with `@Property(where=Where.NOWHERE)` overrides this.
+
-* xref:refguide:applib:index/annotation/Action.adoc#hidden[actions]
-* xref:refguide:applib:index/annotation/Collection.adoc#hidden[collections].
+==== Alternatives
+It is also possible to use xref:refguide:applib:index/annotation/PropertyLayout.adoc#hidden[`@PropertyLayout#hidden`] to hide a property at the domain layer.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/typicalLength.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_31_typicalLength.adoc
similarity index 72%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/typicalLength.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_31_typicalLength.adoc
index fb12068..b9fb4b9 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/typicalLength.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/PropertyLayout_31_typicalLength.adoc
@@ -1,17 +1,15 @@
-[#typicalLength]
-= `typicalLength()`
+=== Typical (string) length
: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 `typicalLength` attribute indicates the typical length of a string property.
+The xref:refguide:applib:index/annotation/PropertyLayout.adoc#typicalLength[typicalLength()] element indicates the typical length of a string property.
It is ignored for properties of other types.
-The attribute is also supported for xref:refguide:applib:index/annotation/ParameterLayout.adoc#typicalLength[parameters].
The information is intended as a hint to the UI to determine the space that should be given to render a particular string property.
-That said, note that the xref:vw:ROOT:about.adoc[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+
For example:
@@ -31,6 +29,5 @@ public class Customer {
}
----
-== Alternatives
+NOTE: All that said, the xref:vw:ROOT:about.adoc[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this element.
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/optionality.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc
similarity index 97%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/optionality.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc
index e8043e9..416fe3c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/optionality.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc
@@ -1,12 +1,11 @@
-[#optionality]
-= `optionality()`
+=== Mandatory vs optional
: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:
By default, Apache Isis assumes that all properties of an domain object or view model are required (mandatory).
-The `optionality` attribute allows this to be relaxed.
+The xref:applib:index/annotation/Property.adoc#optionality[optionality()] attribute allows this to be relaxed.
The attribute is also supported for xref:refguide:applib:index/annotation/Parameter.adoc#optionality[parameters].
That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[`@Column`] should be specified.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/editing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_022-editing.adoc
similarity index 78%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/editing.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_022-editing.adoc
index 5e274a4..16207c5 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/editing.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_022-editing.adoc
@@ -1,22 +1,22 @@
-[#editing]
-= `editing()`
+=== Editing
: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 `editing` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only.
+The xref:applib:index/annotation/Property.adoc#editing[editing()] element can be used to prevent a property from being modified or cleared, ie to make it read-only.
-The related `editingDisabledReason` attribute specifies the a hard-coded reason why the property cannot be modified directly.
+The related xref:applib:index/annotation/Property.adoc#editingDisabledReason[editingDisabledReason()] element specifies a hard-coded reason why the property cannot be modified directly.
Whether a property is enabled or disabled depends upon these factors:
-* whether the domain object has been configured as immutable through the xref:refguide:applib:index/annotation/DomainObject.adoc#editing[`@DomainObject#editing()`] attribute
+* whether the domain object has been configured as immutable through the xref:refguide:applib:index/annotation/DomainObject.adoc#editing[@DomainObject#editing()] element
* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing['isis.applib.annotation.domain-object.editing'] configuration property.
++
If set to `false`, then the object's properties (and collections) are __not__ editable
-* else, then the value of the `@Property(editing=...)` attribute itself
+* else, the value of the `@Property(editing=...)` attribute itself
* else, the result of invoking any supporting xref:refguide:applib-methods:prefixes.adoc#disable[`disable...()`] supporting methods
@@ -40,8 +40,3 @@ public class Customer {
----
-== See also
-
-This attribute can also be specified for:
-
-* xref:refguide:applib:index/annotation/DomainObject.adoc#editing[domain object].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/maxLength.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc
similarity index 90%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/maxLength.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc
index 6710d36..560de90 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/maxLength.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc
@@ -1,12 +1,11 @@
-[#maxLength]
-= `maxLength()`
+=== Maximum (string) length
: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 `maxLength` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).
+The xref:applib:index/annotation/Property.adoc#maxLength[maxLength()] attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).
The attribute It is ignored if applied to properties of any other type.
That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[`@Column`] will in any case need to be specified.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/mustSatisfy.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_024-mustSatisfy.adoc
similarity index 91%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/mustSatisfy.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_024-mustSatisfy.adoc
index d6b1b5c..5ce5a95 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/mustSatisfy.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_024-mustSatisfy.adoc
@@ -1,12 +1,11 @@
-[#mustSatisfy]
-= `mustSatisfy()`
+=== Declarative validation
: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 `mustSatisfy` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
+The xref:applib:index/annotation/Property.adoc#mustSatisfy[mustSatisfy()] element allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
The attribute is also supported on xref:refguide:applib:index/annotation/Parameter.adoc#mustSatisfy[parameters].
[TIP]
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/projecting.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_025-projecting.adoc
similarity index 89%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/projecting.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_025-projecting.adoc
index 8b6975b..e648fb8 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/projecting.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_025-projecting.adoc
@@ -1,5 +1,4 @@
-[#projecting]
-= `projecting()`
+=== Projections
: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:
@@ -10,7 +9,7 @@ A common use case for view models is to act as a projection of some underlying e
Very often the object that is of interest to the end-user is the underlying entity, not the view model per se.
If the view model is displayed within a table (on a home page, say), then when the user clicks the entity/icon link for the view model, they will in fact want to drill-down to the underlying entity and skip the view model completely.
-The `projecting` attribute allows the view model to indicate which of its properties holds a reference to the underlying entity of which it is a projection.
+The xref:applib:index/annotation/Property.adoc#projecting[projecting()] element allows the view model to indicate which of its properties holds a reference to the underlying entity of which it is a projection.
For example:
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/domainEvent.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_026-domain-events.adoc
similarity index 76%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/domainEvent.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_026-domain-events.adoc
index bf5c226..abf68c6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/domainEvent.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_026-domain-events.adoc
@@ -1,10 +1,9 @@
-[#domainEvent]
-= `domainEvent()`
-
: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:
+=== Domain events
+
Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
In the cases of the domain object's properties, the events that are fired are:
@@ -14,7 +13,7 @@ In the cases of the domain object's properties, the events that are fired are:
* pre-execute phase: before the modification of the property
* post-execute: after the modification of the property
-Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`], and can influence each of these phases.
+Subscribers subscribe through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`] and can influence each of these phases.
By default the event raised is `PropertyDomainEvent.Default`.
For example:
@@ -26,7 +25,7 @@ import lombok.Setter;
public class ToDoItem {
- @Property
+ @Property()
@Getter @Setter
private LocalDate dueBy;
@@ -34,7 +33,7 @@ public class ToDoItem {
}
----
-The `domainEvent` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
+The xref:refguide:applib:index/annotation/Property.adoc#domainEvent[domainEvent()] element allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
For example:
@@ -55,17 +54,17 @@ public class ToDoItem {
// ...
}
----
-<1> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
+<.> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
-The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
[NOTE]
====
The framework provides a no-arg constructor and will initialize the domain event using (non-API) setters rather than through the constructor.
-This substantially reduces the boilerplate in the subclasses because no explicit constructor is required..
+This substantially reduces the boilerplate required in subclasses because no explicit constructor is required.
====
-== Subscribers
+==== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`].
@@ -140,34 +139,27 @@ public class SomeSubscriber {
}
}
----
+
<.> call `ev.hide()` or `ev.veto("")` to hide the property
<.> call `ev.disable("...")` or `ev.veto("...")` to disable the property
<.> call ev.invalidate("...") or ev.veto("...") if proposed new value for property is invalid
-
It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-== Default, Doop and Noop events
+==== Default, Doop and Noop events
-If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`), then the framework will, by default, post an event.
+If the xref:refguide:applib:index/annotation/Property.adoc#domainEvent[domainEvent()] element is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
+If this is not required, then the xref:config:sections/isis.applib.adoc#isis.applib.annotation.property.domain-event.post-for-default[isis.applib.annotation.property.domain-event.post-for-default] configuration property can be set to "false"; this will disable posting.
On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
-== Raising events programmatically
+==== Raising events programmatically
Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically by wrapping the target object using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] service.
-
-== See also
-
-This attribute is also supported for:
-
-* xref:refguide:applib:index/annotation/Action.adoc#domainEvent[actions] and
-* xref:refguide:applib:index/annotation/Property.adoc#domainEvent[properties].
+However, events can be raised programmatically either by calling the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] API directly, or by emulating the UI by wrapping the target object using the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[WrapperFactory] domain service.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/executionPublishing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_027-execution-publishing.adoc
similarity index 62%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/executionPublishing.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_027-execution-publishing.adoc
index c23681e..3e6239b 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/executionPublishing.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_027-execution-publishing.adoc
@@ -1,15 +1,14 @@
-[#executionPublishing]
-= `executionPublishing()`
-
: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:
-CAUTION: TODO: v2 - publishing/auditing got a complete overhaul
-The `executionPublishing` attribute determines whether and how a property edit is published via the registered implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[`ExecutionSubscriber`].
+=== Execution Publishing
+
+The xref:refguide:applib:index/annotation/Property.adoc#executionPublishing[executionPublishing()] element determines whether and how a property edit is published via the registered implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[`ExecutionSubscriber`].
A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property.executionPublishing[`isis.applib.annotation.property.executionPublishing`] configuration property is used to determine the whether the property edits are published:
+
+The xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property.execution-publishing[`isis.applib.annotation.property.execution-publishing`] configuration property is used to determine the whether the property edits are published:
* `all`
+
@@ -39,16 +38,7 @@ public class Order {
// ...
}
----
-<.> because set to enabled, will be published irrespective of the configured value.
-== See also
-
-This attribute can also be specified for:
+<.> because set to enabled, will be published irrespective of the configured value.
-* xref:refguide:applib:index/annotation/DomainObject.adoc#publishing[domain objects]
-+
-where it controls whether changed objects are published as events, and for
-* xref:refguide:applib:index/annotation/Action.adoc#executionPublishing[actions]
-+
-where it controls whether action invocations are published as events.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/commandPublishing.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_028-command-processing.adoc
similarity index 74%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/commandPublishing.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_028-command-processing.adoc
index d8ef3d6..3216b3a 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/commandPublishing.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_028-command-processing.adoc
@@ -1,10 +1,8 @@
-[#commandPublishing]
-= Command Persistence and Processing
-
: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:
-CAUTION: TODO: v2 - publishing/auditing got a complete overhaul
+
+=== Command Processing
Every property edit (and xref:refguide:applib:index/annotation/Action.adoc#commandPublishing[action invocation] for that matter) is normally reified into a concrete `Command` object, basically a wrapper around the XML invocation xref:schema:cmd.adoc[Command] schema that also captures some timing metrics about the execution as well as the outcome.
@@ -22,18 +20,12 @@ TIP: Another option to achieve this is to use the xref:refguide:applib:index/ser
+
This is implemented by the xref:extensions:command-replay:about.adoc[Command Replay] extension, working in conjunction with the xref:extensions:command-log:about.adoc[Command Log] extension.
+The xref:refguide:applib:index/annotation/Property.adoc#commandPublishing[commandPublishing()] element can be used to explicitly enable or disable command publishing for the property edit.
-== `commandPublishing`
-
-The `commandPublishing()` attribute can be used to explicitly enable or disable command publishing for the property edit.
-
+==== CommandDtoProcessor implementations
-
-[#commanddtoprocessor]
-== `commandDtoProcessor()`
-
-The `commandDtoProcessor` attribute allows an implementation of `CommandDtoProcessor` to be specified.
+The xref:refguide:applib:index/annotation/Action.adoc#commandDtoProcessor[commandDtoProcessor()] element allows an implementation of `CommandDtoProcessor` to be specified.
This interface has the following API:
[source,java]
@@ -47,16 +39,16 @@ public interface CommandDtoProcessor {
This will typically be the `CommandDto` passed in, but may be supplemented in some way.
<.> The `CommandDto` obtained already from the `Command`.
-This interface is used by the framework-provided implementations of `ContentMappingService` for the REST API, allowing ``Command``s implementations that also implement `CommandWithDto` to be further customised as they are serialized out.
-The primary use case for this capability is in support of master/slave replication.
+This interface is used by the framework-provided implementations of xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] for the REST API, allowing ``Command``s implementations that also implement `CommandWithDto` to be further customised as they are serialized out.
+The primary use case for this capability is in support of primary/secondary replication.
-* on the master, ``Command``s are serialized to XML.
-This includes the identity of the target object and the intended new value of the property.
+* on the primary, ``Command``s are serialized to XML.
+This includes the identity of the target object and the argument values of all parameters.
+
[IMPORTANT]
====
-However, any ``Blob``s and ``Clob``s are deliberately excluded from this XML (they are instead stored as references).
+Any ``Blob``s and ``Clob``s are deliberately excluded from this XML (they are instead stored as references).
This is to prevent the storage requirements for `Command` from becoming excessive.
A `CommandDtoProcessor` can be provided to re-attach blob information if required.
====
@@ -73,8 +65,8 @@ The `CommandDtoProcessor.Null` class provides a convenience implementation for t
If `commandDtoProcessor()` is specified, then `commandPublishing()` is assumed to be ENABLED.
====
+==== Example
-
-For an example application, see xref:refguide:applib:index/annotation/Action.adoc#command[`Action#command()`].
+For an example, see xref:refguide:applib:index/annotation/Action.adoc#commandPublishing[`Action#command()`].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/regexPattern.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_029-regexPattern.adoc
similarity index 71%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/regexPattern.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_029-regexPattern.adoc
index 2816da4..fa3a11c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/regexPattern.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_029-regexPattern.adoc
@@ -1,20 +1,19 @@
-[#regexPattern]
-= `regexPattern()`
+=== Regular expressions
: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:
-There are three attributes related to enforcing regular expressions:
+There are three elements related to enforcing regular expressions:
-* The `regexPattern` attribute validates the contents of any string property with respect to a regular expression pattern.
+* The xref:applib:index/annotation/Property.adoc#regexPattern[regexPattern()] element validates the contents of any string property with respect to a regular expression pattern.
It is ignored if applied to properties of any other type.
-* The `regexPatternFlags` attribute specifies flags that modify the handling of the pattern.
+* The xref:applib:index/annotation/Property.adoc#regexPatternFlags[regexPatternFlags()] element specifies flags that modify the handling of the pattern.
The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
-* The related `regexPatternReplacement` attribute specifies the error message to show if the provided argument does not match the regex pattern.
+* The xref:applib:index/annotation/Property.adoc#regexPatternReplacement[regexPatternReplacement()] attribute specifies the error message to show if the provided argument does not match the regex pattern.
For example:
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/snapshot.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_030-snapshot.adoc
similarity index 74%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/snapshot.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_030-snapshot.adoc
index f69642a..28c3623 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/snapshot.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_030-snapshot.adoc
@@ -1,12 +1,9 @@
-[#snapshot]
-= `snapshot()`
+=== Snapshotting state
: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:
-CAUTION: this documentation may be inaccurate.
-
-The `snapshot` attribute indicates whether the property should be included/excluded from any snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[`XmlSnapshotService`].
+The xref:applib:index/annotation/Property.adoc#snapshot[snapshot()] element indicates whether the property should be included/excluded from any snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[`XmlSnapshotService`].
For example:
@@ -25,7 +22,7 @@ public class Order {
}
----
-Alternatively, if the property is derived, then providing only a "getter" will also work:
+If the property is derived, then providing only a "getter" will also work:
[source,java]
----
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/fileAccept.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_031-fileAccept.adoc
similarity index 80%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/fileAccept.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_031-fileAccept.adoc
index b2c0c9c..d05b079 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/fileAccept.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_031-fileAccept.adoc
@@ -1,11 +1,10 @@
-[#fileAccept]
-= `fileAccept()`
+=== Uploading Blobs and Clobs
: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 `fileAccept` attribute applies only to xref:applib-classes:value-types.adoc#Blob[`Blob`] or xref:applib-classes:value-types.adoc#Clob[`Clob`] parameters, indicating the type of file to accept when uploading a new value.
+The xref:applib:index/annotation/Property.adoc#fileAccept[fileAccept()] element applies only to xref:applib-classes:value-types.adoc#Blob[`Blob`] or xref:applib-classes:value-types.adoc#Clob[`Clob`] parameters, indicating the type of file to accept when uploading a new value.
The attribute is also supported on xref:refguide:applib:index/annotation/Parameter.adoc#fileAccept[parameters].
For example:
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/hidden.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_033-hidden.adoc
similarity index 91%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/hidden.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_033-hidden.adoc
index 3998bd7..a2aeabd 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/Property/hidden.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_033-hidden.adoc
@@ -1,11 +1,9 @@
-[#hidden]
-= `hidden()`
+=== Hiding properties
: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:
-
Properties can be hidden at the domain-level, indicating that they are not visible to the end-user.
[TIP]
@@ -68,9 +66,3 @@ Annotating with `@Property(where=Where.NOWHERE)` overrides this.
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] has only partial support for these `Where` enums.
====
-== See also
-
-This attribute can also be applied to:
-
-* xref:refguide:applib:index/annotation/ActionLayout.adoc#hidden[actions]
-* xref:refguide:applib:index/annotation/CollectionLayout.adoc#hidden[collections].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/describedAs.adoc
deleted file mode 100644
index c60bda6..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/PropertyLayout/describedAs.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[#describedAs]
-= `describedAs()`
-
-: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 `describedAs` attribute is used to provide a short description of the property to the user. In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:refguide:applib:index/annotation/CollectionLayout.adoc#describedAs[collections], xref:refguide:applib:index/annotation/ActionLayout.adoc#describedAs[actions], xref:refguide:applib:index/annotation/ParameterLayout.adoc#describedAs[parameters] and xref:refguide:applib:ind [...]
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @PropertyLayout(
- describedAs = "The name that the customer has indicated " +
- "that they wish to be addressed as " +
- "(e.g. Johnny rather than Jonathan)")
- private String firstName;
-
- // ...
-}
-----
-
-
-== Alternatives
-
-As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.