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 2017/03/31 07:10:42 UTC
[06/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
new file mode 100644
index 0000000..a427714
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
@@ -0,0 +1,37 @@
+[[_rgant-ActionLayout_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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `describedAs()` attribute is used to provide a short description of the action to the user. In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
+
+This attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @ActionLayout(describedAs="Place a repeat order of the last (most recently placed) order")
+ public Order placeRepeatOrder(...) { ... }
+}
+----
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"postpone": {
+ "actionLayout": { "describedAs": "Place a repeat order of the last (most recently placed) order" }
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
new file mode 100644
index 0000000..4fa2a67
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
@@ -0,0 +1,57 @@
+[[_rgant-ActionLayout_hidden]]
+= `hidden()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `hidden()` attribute indicates where (in the UI) the action should be hidden from the user. This attribute can also be applied to xref:rgant.adoc#_rgant-PropertyLayout_hidden[properties] and xref:rgant.adoc#_rgant-CollectionLayout_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] to hide an action at the domain 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]
+----
+public class Customer {
+ @ActionLayout(hidden=Where.EVERYWHERE)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The action should be hidden at all times.
+
+* `Where.NOWHERE` +
++
+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:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"updateStatus": {
+ "actionLayout": { "hidden": "EVERYWHERE" }
+}
+----
+
+
+[NOTE]
+====
+For actions of domain services the visibility is dependent upon its xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
new file mode 100644
index 0000000..70dbebd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
@@ -0,0 +1,45 @@
+[[_rgant-ActionLayout_named]]
+= `named()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `named()` attribute explicitly specifies the action's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @ActionLayout(named="Get credit rating")
+ public CreditRating obtainCreditRating() { ... }
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"obtainCreditRating": {
+ "actionLayout": { "named": "Get credit rating" }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
new file mode 100644
index 0000000..9fbedb4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
@@ -0,0 +1,80 @@
+[[_rgant-ActionLayout_position]]
+= `position()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+
+The `position()` attribute pertains only to actions that have been associated with properties using xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder#named()`]. For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
+
+The attribute can take one of four values: `BELOW`, `RIGHT`, `PANEL` or `PANEL_DROPDOWN`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+ @Property(
+ editing=Editing.DISABLED // <1>
+ )
+ public CustomerStatus getStatus() { ... }
+ public void setStatus(CustomerStatus customerStatus) { ... }
+
+ @MemberOrder(
+ named="status", // <2>
+ sequence="1"
+ )
+ @ActionLayout(
+ named="Update", // <3>
+ position=Position.BELOW
+ )
+ public CreditRating updateStatus(Customer ) { ... }
+}
+----
+<1> indicate the property as read-only, such that it can only be updated using an action
+<2> associate the "updateStatus" action with the "status" property
+<3> give the action an abbreviated name, because the fact that the "status" property is to be updated is implied by its positioning
+
+
+The default is `BELOW`, which is rendered (by the xref:ugvw.adoc#[Wicket viewer]) as shown below:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png"]
+
+
+If the action is positioned as `RIGHT`, then the action's button is rendered to the right of the property's field, in a compact drop-down. This is ideal if there are many actions associated with a property:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png"]
+
+
+
+If the action is positioned as `PANEL`, then the action's button is rendered on the header of the panel that contains the property:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png"]
+
+
+
+And finally, if the action is positioned as `PANEL_DROPDOWN`, then the action's button is again rendered on the panel header, but as a drop-down:
+
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png"]
+
+
+
+If there are multiple actions associated with a single property then the positioning can be mix'ed-and-match'ed as required. 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:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"obtainCreditRating": {
+ "actionLayout": { "named": "Get credit rating" }
+}
+----
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
new file mode 100644
index 0000000..759d684
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
@@ -0,0 +1,134 @@
+[[_rgant-Action_command]]
+= `command()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `@Action(command=...)` attribute (and the related `@Action(commandPersistence=...)` and `@Action(commandExecuteIn=...)` attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this is enhanced profiling/auditing, and it also supports the deferring the execution of the action such that it can be invoked in the background.
+
+The annotation works with (and is influenced by the behaviour of) a number of domain services:
+
+* xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
+* xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]
+* xref:rgsvc.adoc#_rgsvc_spi_BackgroundService[`BackgroundService`] and
+* xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]
+
+
+Each action invocation is reified by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
+
+If an appropriate `CommandService` is configured (for example using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module), then the `Command` itself is persisted.
+
+By default, actions are invoked in directly in the thread of the invocation. If there is an implementation of `BackgroundCommandService` (as the http://github.com/isisaddons/isis-module-command[Isis addons' command] module does provide), then this means in turn that the `BackgroundService` can be used by the domain object code to programmatically create background ``Command``s.
+
+[NOTE]
+====
+If background ``Command``s are used, then an external scheduler, using xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[headless access], must also be configured.
+====
+
+
+
+The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service).
+
+The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
+
+* `all` +
++
+all actions are reified
+
+* `ignoreSafe` (or `ignoreQueryOnly`) +
++
+actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+
+* `none` +
++
+no actions are reified.
+
+If there is no configuration property in `isis.properties` then all actions are reified into ``Command``s.
+
+[NOTE]
+====
+Note: `Command` reification does not necessarily imply that `Command` objects will be persisted; that depends on whether there is a xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] configured that will persist said ``Command``s.
+====
+
+This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(command=CommandReification.ENABLED)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+corresponds to the behaviour described above; the `Command` object is persisted (assuming an appropriate `CommandService` is defined, and executed immediately in the foreground).
+
+
+
+
+== `commandPersistence()`
+
+If the action has been reified, then the `commandPersistence()` attribute determines whether that `Command` object
+should then also be persisted (the default), or not persisted, or only if hinted.
+
+To explain this last alternative:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandPersistence=CommandPersistence.IF_HINTED
+ )
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`].
+
+On the other hand:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.FOREGROUND,
+ commandPersistence=CommandPersistence.NOT_PERSISTED
+ )
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will prevent the parent `Command` object from being persisted, _even if_ a child background `Command` is created.
+
+
+
+
+
+== `commandExecuteIn()`
+
+For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
+
+Background execution means that the command is not executed immediately, but is available for a configured xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.BACKGROUND)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will result in the `Command` being persisted but its execution deferred to a background execution mechanism. The
+returned object from this action is the persisted `Command` itself.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
new file mode 100644
index 0000000..b5bef05
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
@@ -0,0 +1,164 @@
+[[_rgant-Action_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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+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:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations 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 `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+xref:rgant.adoc#_rgant-Collection_domainEvent[collections] and
+xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+
+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]
+====
+As of `1.10.0` 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.
+====
+
+
+
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ActionDomainEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.CompletedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+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]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(ActionDomainEvent ev) {
+ switch(ev.getEventPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the action
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the action
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if action arguments are invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+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 `domainEvent` attribute 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` attribute 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` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
new file mode 100644
index 0000000..7459e15
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
@@ -0,0 +1,49 @@
+[[_rgant-Action_hidden]]
+= `hidden()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+Actions can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rgant.adoc#_rgant-Property_hidden[properties] and xref:rgant.adoc#_rgant-Collection_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the action 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]
+----
+public class Customer {
+ @Action(hidden=Where.EVERYWHERE)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The action should be hidden at all times.
+
+* `Where.NOWHERE` +
++
+The action should not be hidden.
+
+
+The other values of the `Where` enum have no meaning for a collection.
+
+
+
+[NOTE]
+====
+For actions of domain services the visibility is dependent upon its xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_invokeOn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_invokeOn.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_invokeOn.adoc
new file mode 100644
index 0000000..c7540dc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_invokeOn.adoc
@@ -0,0 +1,64 @@
+[[_rgant-Action_invokeOn]]
+= `invokeOn()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `invokeOn()` attribute indicates whether the an action can be invoked on a single object (the default) and/or on many objects in a collection.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+ public void markAsCompleted() {
+ setCompleted(true);
+ }
+ ...
+}
+----
+
+
+Actions to be invoked on collection (currently) have a number of constraints. It:
+
+* must take no arguments
+* cannot be hidden (any annotations or supporting methods to that effect will be ignored)
+* cannot be disabled (any annotations or supporting methods to that effect will be ignored).
+
+The example given above is probably ok, because `setCompleted()` is most likely idempotent. However, if the action also called some other method, then we should add a guard.
+
+For example, for this non-idempotent action:
+
+[source,java]
+----
+@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+public void markAsCompleted() {
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+}
+----
+
+we should instead write it as:
+
+[source,java]
+----
+@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+public void markAsCompleted() {
+ if(isCompleted()) {
+ return;
+ }
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+}
+----
+
+[NOTE]
+====
+This attribute has no meaning if annotated on an action of a domain service.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
new file mode 100644
index 0000000..d5abc01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
@@ -0,0 +1,71 @@
+[[_rgant-Action_publishing]]
+= `publishing()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+The `publishing()` attribute determines whether and how an action invocation is published via the registered
+implementation of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. This attribute is also
+supported for xref:rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects
+are published as events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
+whether property edits are published as events.
+
+A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
+The default value for the attribute is `AS_CONFIGURED`, meaning that the
+xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.actions` 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 `isis.properties` then publishing is automatically enabled.
+
+This default can be overridden on an action-by-action basis; if `publishing()` 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(publishing=Publishing.ENABLED) // <1>
+ public Invoice generateInvoice(...) { ... }
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
+
+
+
+== `publishingPayloadFactory()`
+
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to
+be published by the publishing factory.
+
+Rather than simply broadcast that the action was invoked, the payload factory allows a "fatter" payload to be
+instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers
+this should avoid the necessity to query back for additional information.
+
+[WARNING]
+====
+Be aware that this attribute is only honoured by the (deprecated) xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated. It
+is ignored by the replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
new file mode 100644
index 0000000..f07ca6f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
@@ -0,0 +1,30 @@
+[[_rgant-Action_restrictTo]]
+= `restrictTo()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+By default actions are available irrespective of the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment mode]. The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeNewOrder() { ... }
+ public List<Order> listRecentOrders() { ... }
+
+ @Action(restrictTo=RestrictTo.PROTOTYPING)
+ public List<Order> listAllOrders() { ... }
+ ...
+}
+----
+
+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.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
new file mode 100644
index 0000000..78e8ecf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
@@ -0,0 +1,91 @@
+[[_rgant-Action_semantics]]
+= `semantics()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `semantics()` attribute 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 attribute was originally introduced for the xref:ugvro.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:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`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:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
+
+Continuing the example above, imagine code that loops over a set of ``Order``s where each `Order` has an associated `Customer`. We want to check the credit rating of each `Customer` (a potentially expensive operation) but we don't want to do it more than once per `Customer`. Invoking through the `WrapperFactory` will allow us to accomplish this by exploiting the semantics of `checkCredit()` action:
+
+[source,java]
+----
+public void dispatchToCreditWorthyCustomers(final List<Order> orders) {
+ for(Order order: orders) {
+ Customer customer = order.getCustomer();
+ CreditRating creditRating = wrapperFactory.wrapSkipRules(customer).checkCredit(); // <1>
+ if(creditRating.isWorthy()) {
+ order.dispatch();
+ }
+ }
+}
+@Inject
+WrapperFactory wrapperFactory;
+----
+<1> wrap the customer to dispatch.
+
+In the above example we've used `wrapSkipRules(...)` but if we wanted to enforce any business rules associated with the `checkCredit()` method, we would have used `wrap(...)`.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
new file mode 100644
index 0000000..22b6e58
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
@@ -0,0 +1,31 @@
+[[_rgant-Action_typeOf]]
+= `typeOf()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `typeOf()` attribute 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. This attribute can also be specified for xref:rgant.adoc#_rgant-Collection_typeOf[collections].
+
+
+For example:
+
+[source,java]
+----
+public void AccountService {
+ @Action(typeOf=Customer.class)
+ public List errantAccounts() {
+ return customers.allNewCustomers();
+ }
+ ...
+
+ @Inject
+ CustomerRepository customers;
+}
+----
+
+[TIP]
+====
+In general we recommend that you use generics instead, eg `List<Customer>`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
new file mode 100644
index 0000000..569928b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
@@ -0,0 +1,105 @@
+[[_rgant-Collection]]
+= `@Collection`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `@Collection` annotation applies to collections collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@Collection` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-Collection_domainEvent[`domainEvent()`]
+|subtype of `CollectionDomainEvent` +
+(`CollectionDomainEvent.Default`)
+|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
+
+
+|xref:rgant.adoc#_rgant-Collection_editing[`editing()`]
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
+(`AS_CONFIGURED`)
+|whether a collection can be added to or removed from within the UI
+
+
+|`editingDisabledReason()`
+|String value
+|if `editing()` is `DISABLED`, provides a reason as to why.
+
+
+|xref:rgant.adoc#_rgant-Collection_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rgant.adoc#_rgant-Collection_notPersisted[`notPersisted()`]
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
+
+
+
+|xref:rgant.adoc#_rgant-Collection_typeOf[`typeOf()`]
+|
+|hints as to the run-time type of the objects within that collection (as a fallback)
+
+|===
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DependenciesChangedEvent
+ extends CollectionDomainEvent<ToDoItem, ToDoItem> { } // <1>
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class,
+ editing = Editing.ENABLED,
+ hidden = Where.NOWHERE, // <2>
+ notPersisted = false, // <3>
+ typeOf = ToDoItem.class // <4>
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> as of `1.10.0`, can use no-arg constructor.
+<2> default value, so could be omitted
+<3> default value, so could be omitted
+<4> default value, so could be omitted
+
+
+
+
+[TIP]
+====
+The annotation is one of a handful (others including xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method. This is specifically
+so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
+====
+
+
+
+include::_rgant-Collection_domainEvent.adoc[leveloffset=+1]
+include::_rgant-Collection_editing.adoc[leveloffset=+1]
+include::_rgant-Collection_hidden.adoc[leveloffset=+1]
+include::_rgant-Collection_notPersisted.adoc[leveloffset=+1]
+include::_rgant-Collection_typeOf.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
new file mode 100644
index 0000000..697577f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
@@ -0,0 +1,137 @@
+[[_rgant-CollectionLayout]]
+= `@CollectionLayout`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `@CollectionLayout` annotation applies to collections, collecting together all UI hints within a single
+annotation. It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.
+
+The table below summarizes the annotation's attributes.
+
+.`@CollectionLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`cssClass()`]
+|Any string valid as a CSS class
+|the css class that a collection should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`defaultView()`]
+|`table`, `excel`, `calendar`, `map`, ...
+|Which view is selected by default, if multiple views are available.
+
+See (non-ASF) link:http://isisaddons.org[Isis Addons] for further views.
+
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`describedAs()`]
+|String.
+|description of this collection, eg to be rendered in a tooltip.
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_named[named()]
+|String.
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|namedEscaped()
+|`true`,`false` (`true`)
+|whether to HTML escape the name of this property.
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table.
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_render[`render()`]
+|`EAGERLY`, `LAZILY` +
+(`LAZILY`)
+|whether the collection should be (eagerly) rendered open or (lazily) rendered closed
+
+
+|xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`sortedBy()`]
+|Subclass of `java.util.Comparator` for element type
+|indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ cssClass="x-key",
+ named="Todo items that are <i>dependencies</i> of this item.",
+ namedEscaped=false,
+ describedAs="Other todo items that must be completed before this one",
+ labelPosition=LabelPosition.LEFT,
+ render=EAGERLY)
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "cssClass": "x-key",
+ "named": "Todo items that are <i>dependencies</i> of this item.",
+ "namedEscaped": false,
+ "describedAs": "Other todo items that must be completed before this one",
+ "labelPosition": "LEFT",
+ "render": "EAGERLY"
+ }
+}
+----
+
+
+
+
+[TIP]
+====
+The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method. This is specifically
+so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
+====
+
+
+
+include::_rgant-CollectionLayout_cssClass.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_defaultView.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_describedAs.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_hidden.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_named.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_paged.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_render.adoc[leveloffset=+1]
+include::_rgant-CollectionLayout_sortedBy.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
new file mode 100644
index 0000000..5da72b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
@@ -0,0 +1,36 @@
+[[_rgant-CollectionLayout_cssClass]]
+= `cssClass()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection. xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+
+This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ cssClass="x-important"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "cssClass": "x-important" }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
new file mode 100644
index 0000000..aebfc52
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
@@ -0,0 +1,43 @@
+[[_rgant-CollectionLayout_defaultView]]
+= `defaultView()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The xref:ugvw.adoc#[Wicket viewer] allows additional views to be configured to render collections of objects; at the time of writing thesee include the (non-ASF) (non-ASF) link:http://isisaddons.org[Isis Addons]' (non-ASF) http://github.com/isisaddons/isis-wicket-excel[excel] view, the http://github.com/isisaddons/isis-wicket-fullcalendar2[fullcalendar2] view, and the http://github.com/isisaddons/isis-wicket-gmap3[gmap3] view. If the objects to be rendered have the correct "shape", then the appropriate view will be made available. For example, objects with a date can be rendered using `calendar`; objects with locations can be rendered using `map`.
+
+The `defaultView()` attribute is used to select which of these views should be used by default for a given collection.
+
+
+For example:
+
+[source,java]
+----
+public class BusRoute {
+ @CollectionLayout(
+ defaultView="map"
+ )
+ public SortedSet<BusStop> getStops() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "defaultView": "map"
+ }
+}
+----
+
+[NOTE]
+====
+This attribute takes precedence over any value for the xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout#render()`] attribute. For example, if the
+`defaultView` attribute is defined to "table", then the table will be show even if `render` is set to `LAZILY`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
new file mode 100644
index 0000000..5e1ae23
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
@@ -0,0 +1,38 @@
+[[_rgant-CollectionLayout_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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `describedAs()` attribute is used to provide a short description of the collection to the user. In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
+
+The `describedAs()` attribute can also be specified for xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ describedAs="Other todo items that must be completed before this one"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "describedAs": "Other todo items that must be completed before this one"
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
new file mode 100644
index 0000000..ba89ed4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
@@ -0,0 +1,58 @@
+[[_rgant-CollectionLayout_hidden]]
+= `hidden()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to xref:rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:rgant.adoc#_rgant-PropertyLayout_hidden[properties].
+
+
+[TIP]
+====
+It is also possible to use xref:rgant.adoc#_rgant-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain 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]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ hidden=Where.EVERYWHERE
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The collection should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The collection should be hidden when displayed within an object form.
+
+* `Where.NOWHERE` +
++
+The collection 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:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "hidden": "EVERYWHERE" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
new file mode 100644
index 0000000..0ec434f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
@@ -0,0 +1,53 @@
+[[_rgant-CollectionLayout_named]]
+= `named()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. 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`.
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ named="Todo items that are <i>dependencies</i> of this item",
+ namedEscaped=false
+ )
+ public SortedSet<ToDoItem getDependencies() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "named": "Todo items that are <i>dependencies</i> of this item",
+ "namedEscaped": false,
+ }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
new file mode 100644
index 0000000..5500ca5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
@@ -0,0 +1,45 @@
+[[_rgant-CollectionLayout_paged]]
+= `paged()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_paged[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_paged[view models].
+
+
+[WARNING]
+====
+The xref:ugvro.adoc#[RestfulObjects viewer] currently does not support paging. The xref:ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(paged=15)
+ public SortedSet<OrderLine> getDetails() {...}
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.parented`.
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "paged": 15
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
new file mode 100644
index 0000000..e235807
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
@@ -0,0 +1,42 @@
+[[_rgant-CollectionLayout_render]]
+= `render()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `render()` attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(render=RenderType.EAGERLY)
+ public SortedSet<LineItem> getDetails() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "render": "EAGERLY"
+ }
+}
+----
+
+
+[NOTE]
+====
+Note that xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
+
+Also, if a xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`] attribute has been specified then that will take precedence over the value of the `render()` attribute.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
new file mode 100644
index 0000000..60bc839
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
@@ -0,0 +1,59 @@
+[[_rgant-CollectionLayout_sortedBy]]
+= `sortedBy()`
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `sortedBy()` attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).
+
+For example:
+
+[source,java]
+----
+public class ToDoItem implements Comparable<ToDoItem> { // <1>
+ public static class DependenciesComparator // <2>
+ implements Comparator<ToDoItem> {
+ @Override
+ public int compare(ToDoItem p, ToDoItem q) {
+ return ORDERING_BY_DESCRIPTION // <3>
+ .compound(Ordering.<ToDoItem>natural())
+ .compare(p, q);
+ }
+ }
+ @CollectionLayout(sortedBy=DependenciesComparator.class) // <4>
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> the class has a natural ordering (implementation not shown)
+<2> declaration of the comparator class
+<3> ordering defined as being by the object's `description` property (not shown), and then by the natural ordering of the class
+<4> specify the comparator to use
+
+When the `dependencies` collection is rendered, the elements are sorted by the `description` property first:
+
+image::{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png[width="720px",link="{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "sortedBy": "com.mycompany.myapp.dom.ToDoItem.DependenciesComparator"
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
new file mode 100644
index 0000000..51b2aee
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
@@ -0,0 +1,174 @@
+[[_rgant-Collection_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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+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 collections, the events that are fired are:
+
+* hide phase: to check that the collection is visible (has not been hidden)
+* disable phase: to check that the collection is usable (has not been disabled)
+* validate phase: to check that the collection's arguments are valid (to add or remove an element)
+* pre-execute phase: before the modification of the collection
+* post-execute: after the modification of the collection
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+
+[WARNING]
+====
+The xref:ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only. However, domain events are still relevant to determine if such collections should be hidden.
+
+The workaround is to create add/remove actions and use xref:rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
+====
+
+By default the event raised is `CollectionDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Collection()
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+xref:rgant.adoc#_rgant-Action_domainEvent[actions] and
+xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DependenciesChangedEvent
+ extends CollectionDomainEvent<ToDoItem, ToDoItem> { } // <1>
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> inherit from `CollectionDomainEvent<T,E>` where `T` is the type of the domain object being interacted with, and `E` is the type of the element in the collection (both `ToDoItem` in this example)
+
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+[NOTE]
+====
+As of `1.10.0` 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.
+====
+
+
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(CollectionDomainEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DependenciesChangedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+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) the element being added to/removed from the collection
+* steps to perform prior to the collection being added to/removed from
+* steps to perform after the collection has been added to/removed from.
+
+The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(CollectionDomainEvent ev) {
+ switch(ev.getEventPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the collection
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the collection
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if object being added/removed to collection is invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+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 `domainEvent` attribute is not explicitly specified (is left as its default value, `CollectionDomainEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault`
+configuration collection 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 `CollectionDomainEvent.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 collection setting.
+
+And, conversely, the framework also provides `CollectionDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+