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 2015/06/16 07:42:31 UTC
[43/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
new file mode 100644
index 0000000..7f7dd93
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_aaa_other]]
+= Other Isis Annotations
+: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/
+
+
+These annotations are also commonly used, but relate _not_ to objects or object members but instead to other aspects of the Isis metamodel.
+
+.Other Isis Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|xref:rg.adoc#_rg_object-layout_dynamic[Dynamic layout]?
+
+|xref:rg.adoc#_rg_annotations_manpage-Facets[`@Facets`]
+|Install arbitrary facets within the Isis metamodel.
+|(any)
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`]
+|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
+|UI
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]
+|Grouping of properties into groups, and organizing of properties, collections into columns.
+|UI
+|Yes
+
+
+|xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`]
+|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
+|UI
+|Yes
+
+
+|xref:rg.adoc#_rg_annotations_manpage-MinLength[`@MinLength`]
+|Minimum number of characters required for an auto-complete search argument.
+|UI
+|
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]
+|Ignore a public method, excluded from the Isis metamodel.
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`]
+|Indicates which of the object's properties should be used to build up a title for the object.
+|UI
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
new file mode 100644
index 0000000..8007bcf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
@@ -0,0 +1,92 @@
+[[_rg_annotations_aaa_partial]]
+= Incomplete/partial support
+: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/
+
+
+These annotations have only incomplete/partial support, primarily relating to the management of value types. We recommend that you do not use them for now. Future versions of Isis may either formally deprecate/retire them, or we may go the other way and properly support them. This will depend in part on the interactions between the Isis runtime, its two viewer implementations, and DataNucleus persistence.
+
+
+.Annotations with incomplete/partial support
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|`@Aggregated`
+|Indicates that the object is aggregated, or wholly owned, by a root object. +
+
+This information could in theory provide useful semantics for some object store implementations, eg to store the aggregated objects "inline". +
+
+Currently neither the JDO ObjectStore nor any of the viewers exploit this metadata.
+|Domain, Persistence
+
+|`@Defaulted`
+|Indicates that a (value) class has a default value. +
+
+The concept of "defaulted" means being able to provide a default value for the type by way of the `o.a.i.applib.adapters.DefaultsProvider` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
+
+For these reasons the `@Defaulted` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have a default value provided for them.|Domain
+
+|`@Encodable`
+|Indicates that a (value) class can be serialized/encoded. +
+
+Encodability means the ability to convert an object to-and-from a string, by way of the `o.a.i.applib.adapters.EncoderDecoder` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface.
+
+For these reasons the `@Encodable` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also be directly encoded.
+
+Currently neither the Wicket viewer nor the RO viewer use this API. The Wicket viewer uses Wicket APIs, while RO viewer has its own mechanisms (parsing data from input JSON representations, etc.)
+|Persistence
+
+|`@NotPersistable`
+|Indicates that a domain object may not be programmatically persisted. +
++
+This annotation indicates that transient instances of this class may be created but may not be persisted. The framework will not provide the user with an option to 'save' the object, and attempting to persist such an object programmatically would be an error.
+
+For example:
+
+[source,java]
+----
+@NotPersistable(By.USER)
+public class InputForm {
+ ...
+}
+----
+
+By default the annotated object is effectively transient (ie default to `By.USER_OR_PROGRAM`).
+
+This annotation is not supported by: Wicket viewer (which does not support transient objects). See also link:https://issues.apache.org/jira/browse/ISIS-743[ISIS-743] contemplating the removal of this annotation.
+|Domain, Persistence
+
+|`@Parseable`
+|Indicates that a (value) class can be reconstructed from a string. +
+
+Parseability means being able to parse a string representation into an object by way of the `o.a.i.applib.adapters.Parser` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
+
+For these reasons the `@Parser` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have be able to be parsed. +
+
+Note that the Wicket viewer uses Apache Wicket's Converter API instead.
+|UI, Domain
+
+|`@Value`
+|Specify that a class has value-semantics. +
+
+The `@Value` annotation indicates that a class should be treated as a value type rather than as a reference (or entity) type. It does this providing an implementation of a `o.a.i.applib.adapters.ValueSemanticsProvider`. +
+
+For example: +
+
+[source,java]
+----
+@Value(semanticsProviderClass=
+ ComplexNumberValueSemanticsProvider.class)
+public class ComplexNumber {
+ ...
+}
+----
+
+The `ValueSemanticsProvider` allows the framework to interact with the value, parsing strings and displaying as text, and encoding/decoding (for serialization).
+|Domain
+
+|===
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
new file mode 100644
index 0000000..2f2628b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
@@ -0,0 +1,134 @@
+[[_rg_annotations_manpage-Action]]
+= `@Action`
+: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` annotation groups together all domain-specific metadata for an invokable action on a domain object or domain service.
+
+The table below summarizes the annotation's attributes.
+
+.`@Action` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_command[`command()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the action invocation should be reified into a `o.a.i.applib.` +
+`services.command.Command` object through the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service.
+
+
+|`commandExecuteIn()`
+|`FOREGROUND`,`BACKGROUND` +
+(`FOREGROUND`)
+|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
+
+
+|`commandPersistence()`
+|`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
+(`PERSISTED`)
+|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] has been configured).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`domainEvent()`]
+|subtype of `ActionDomainEvent` +
+(`ActionDomainEvent.Default`)
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`hidden()`]
+|`EVERYWHERE`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the action should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`invokeOn()`]
+|`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
+(`OBJECT_ONLY`)
+|whether an action can be invoked on a single object and/or on many objects in a collection.
+
+Currently this is only supported for no-arg actions.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`publishing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the action invocation should be published to the registered xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+|`publishing-` +
+`PayloadFactory()`
+|subtype of `PublishingPayloadFactory-` `ForAction` (none)
+|specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event representing the action invocation
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`restrictTo()`]
+|`NO_RESTRICTIONS`,`PROTOTYPING` +
+(`NO_RESTRICTIONS`)
+|whether the action is only available in prototyping mode, or whether it is available also in production mode.
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`semantics()`]
+|`QUERY`, `IDEMPOTENT`, `NON_IDEMPOTENT` +
+(`NON_IDEMPOTENT`)
+|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change)
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[`typeOf()`]
+|(none)
+|if the action returns a collection, 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 CompletedEvent extends ActionDomainEvent<ToDoItem> {
+ private static final long serialVersionUID = 1L;
+ public CompletedEvent(
+ final ToDoItem source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super("completed", source, identifier, arguments);
+ }
+ }
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.FOREGROUND, // <1>
+ commandPersistence=CommandPersistence.NOT_PERSISTED, // <2>
+ domainEvent=CompletedEvent.class,
+ hidden = Where.NOWHERE, // <3>
+ invokeOn = InvokeOn.OBJECT_ONLY, // <4>
+ publishing = Publishing.ENABLED,
+ semantics = SemanticsOf.IDEMPOTENT
+ )
+ public ToDoItem completed() { ... }
+}
+----
+<1> default value, so could be omitted
+<2> default value, so could be omitted
+<3> default value, so could be omitted
+<4> default value, so could be omitted
+
+
+
+
+
+include::_rg_annotations_manpage-Action_command.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_domainEvent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_invokeOn.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_publishing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_restrictTo.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_semantics.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_typeOf.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
new file mode 100644
index 0000000..bac249d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
@@ -0,0 +1,133 @@
+[[_rg_annotations_manpage-ActionLayout]]
+= `@ActionLayout`
+: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 `@ActionLayout` annotation applies to actions, collecting together all UI hints within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@ActionLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`bookmarking()`]
+|`AS_ROOT`, `NEVER` +
+(`NEVER`)
+|indicates if an action (with safe xref:rg.adoc#_rg_annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`contributedAs()`]
+|`AS_BOTH`, `AS_ACTION`, `AS_ASSOCIATION`, `AS_NEITHER` +
+(`AS_BOTH`)
+|for a domain service action that can be contributed, whether to contribute as an action or as an association (ie a property or collection). +
+
+For a domain service action to be contributed, the domain services must have a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rg.adoc#_rg_annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`cssClass()`]
+|Any string valid as a CSS class
+|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]. +
+
+Supported by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] but currently ignored by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`cssClassFa()`]
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
+
+
+|`cssClassFaPosition()`
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Positioning of the icon on the button/menu item.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[`describedAs()`]
+|String.
+|provides a short description of the action, eg for rendering as a 'tool tip'.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the action should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[`named()`]
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_position[`position()`]
+|`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
+|for actions associated (using xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
+
+
+|===
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItems {
+ @Action(semantics=SemanticsOf.SAFE) // <1>
+ @ActionLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT,
+ cssClass="x-key",
+ cssClassFa="fa-checkbox",
+ describedAs="Mark the todo item as not complete after all",
+ hidden=Where.NOWHERE // <2>
+ )
+ @MemberOrder(sequence = "1")
+ public List<ToDoItem> notYetComplete() {
+ ...
+ }
+}
+----
+<1> required for bookmarkable actions
+<2> default value, so could be omitted
+
+
+
+
+As an alternative to using the `@ActionLayout` annotation, a dynamic layout using xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"notYetComplete": {
+ "actionLayout": {
+ "bookmarking": "AS_ROOT",
+ "cssClass": "x-key",
+ "cssClassFa": "fa-checkbox",
+ "describedAs": "Mark the todo item as not complete after all",
+ "hidden": "NOWHERE"
+ }
+}
+----
+
+
+
+include::_rg_annotations_manpage-ActionLayout_bookmarking.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_contributedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_position.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
new file mode 100644
index 0000000..cd73033
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-ActionLayout_bookmarking]]
+= `bookmarking()`
+: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 `bookmarking()` attribute indicates if an action (with safe xref:rg.adoc#_rg_annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[domain objects].
+
+
+
+In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], a link to a bookmarked object is shown in the bookmarks panel:
+
+image::{_imagesdir}reference-annotations/ActionLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/bookmarking.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+[TIP]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] supports `alt-[` as a shortcut for opening the bookmark panel. `Esc` will close.
+====
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItems {
+ @Action(semantics=SemanticsOf.SAFE)
+ @ActionLayout(bookmarking=BookmarkPolicy.AS_ROOT)
+ @MemberOrder(sequence = "1")
+ public List<ToDoItem> notYetComplete() {
+ ...
+ }
+}
+----
+
+indicates that the `notYetComplete()` action is bookmarkable.
+
+
+
+[NOTE]
+====
+The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmarked xref:rg.adoc#_rg_annotations_manpage-DomainObject_bookmarking[domain object]s.
+====
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"notYetComplete": {
+ "actionLayout": { "bookmarking": "AS_ROOT" }
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
new file mode 100644
index 0000000..888fdde
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
@@ -0,0 +1,54 @@
+[[_rg_annotations_manpage-ActionLayout_contributedAs]]
+= `contributedAs()`
+: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/
+
+
+
+For a domain service action that _can_ be contributed, the `contributedAs()` attribute determines how it is contributed: as an action or as an association (ie a property or collection).
+
+The distinction between property or collection is automatic: if the action returns a `java.util.Collection` (or subtype) then the action is contributed as a collection; otherwise it is contributed as a property.
+
+For a domain service action to be contributed, the domain services must have a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rg.adoc#_rg_annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class CustomerContributions {
+ @Action(semantics=SemanticsOf.SAFE)
+ @ActionLayout(contributedAs=Contributed.AS_ASSOCIATION)
+ public List<Order> mostRecentOrders(Customer customer) { ... }
+ ...
+}
+----
+
+[TIP]
+====
+The `@ActionLayout` is not required if the action does not have safe semantics, or if the action takes more than one argument; in these cases the action can only be contributed _as_ an action.
+====
+
+
+It's also possible to use the attribute to suppress the action completely:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW)
+public class OrderContributions {
+ @ActionLayout(contributedAs=Contributed.AS_NEITHER)
+ public void cancel(Order order);
+ ...
+}
+----
+
+In such cases, though, it would probably make more sense to annotate the action as either xref:rg.adoc#_rg_annotations_manpage-Action_hidden[hidden] or indeed xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`].
+
+
+
+[NOTE]
+====
+Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:rg.adoc#_rg_object-layout_dynamic[dynamic layout file] because it relates to the contributor domain service, not the contributee domain object.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
new file mode 100644
index 0000000..58f7fc5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
@@ -0,0 +1,41 @@
+[[_rg_annotations_manpage-ActionLayout_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 action. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @ActionLayout(cssClass="x-key")
+ public ToDoItem postpone(LocalDate until) { ... }
+ ...
+}
+----
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ActionLayout_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.
+====
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"postpone": {
+ "actionLayout": { "cssClass": "x-key" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
new file mode 100644
index 0000000..d8f18db
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-ActionLayout_cssClassFa]]
+= `cssClassFa()`
+: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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered on the action's representation as a button or menu item. The related `cssClassFaPosition()` attribute specifies the positioning of the icon, to the left or the right of the text.
+
+These attributes can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[domain objects] and to xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon.
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @ActionLayout(
+ cssClassFa="fa-step-backward"
+ )
+ public ToDoItem previous() { ... }
+
+ @ActionLayout(
+ cssClassFa="fa-step-forward",
+ cssClassFaPosition=ActionLayout.CssClassFaPosition.RIGHT
+ )
+ public ToDoItem next() { ... }
+}
+----
+
+There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list. 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:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"previous": {
+ "actionLayout": {
+ "cssClassFa": "fa-step-backward",
+ "cssClassFaPosition": "LEFT"
+ }
+},
+"next": {
+ "actionLayout": {
+ "cssClassFa": "fa-step-forward",
+ "cssClassFaPosition": "RIGHT"
+ }
+}
+----
+
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
new file mode 100644
index 0000000..eeee65b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-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:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
+
+This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
new file mode 100644
index 0000000..413f321
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[properties] and xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_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:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
new file mode 100644
index 0000000..be7320e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
@@ -0,0 +1,45 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_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:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
new file mode 100644
index 0000000..951a1cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
@@ -0,0 +1,80 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_wicket-viewer[Wicket viewer]) as shown below:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png.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.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.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.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:rg.adoc#_rg_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
new file mode 100644
index 0000000..b17e9f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
@@ -0,0 +1,134 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`]
+* xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`]
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundService[`BackgroundService`] and
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]
+
+
+Each action invocation is reified by the xref:rg.adoc#_rg_services-api_manpage-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:ug.adoc#_ug_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:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service).
+
+The default is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_services-spi_manpage-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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ug.adoc#_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
new file mode 100644
index 0000000..b2a679c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
@@ -0,0 +1,146 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_services-api_manpage-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 purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[collections] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { // <1>
+ private static final long serialVersionUID = 1L;
+ public CompletedEvent( // <2>
+ final ToDoItem source, // <3>
+ final Identifier identifier, // <4>
+ final Object... arguments) { // <5>
+ super("completed", source, identifier, arguments);
+ }
+ }
+ @Action(domainEvent=CompletedEvent.class)
+ public ToDoItem completed() { ... }
+}
+----
+<1> inherit from `ActionDomainEvent<T>` where `T` is the type of the domain object being interacted with
+<2> constructor called reflectively by the framework
+<3> populated with the object being interacted with (the source of the event)
+<4> identifier of the collection
+<5> action argument(s)
+
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-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
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ActionInteractionEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @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.getPhase()) {
+ 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.
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
new file mode 100644
index 0000000..0c4ffc8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
@@ -0,0 +1,49 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-Property_hidden[properties] and xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:rg.adoc#_rg_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:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
new file mode 100644
index 0000000..59c91ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
new file mode 100644
index 0000000..62119db
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
@@ -0,0 +1,53 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[domain objects], where it controls whether changed objects 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:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
+
+* `all` +
++
+all actions are published
+
+* `ignoreSafe` (or `ignoreQueryOnly`) +
++
+actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+
+* `none` +
++
+no actions 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.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
new file mode 100644
index 0000000..d526762
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
@@ -0,0 +1,30 @@
+[[_rg_annotations_manpage-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:ug.adoc#_ug_runtime_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
new file mode 100644
index 0000000..3fccf4c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-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 is safe (as no side-effects), is idempotent (may have side-effects but always has the same post-conditions), or is neither safe nor idempotent. If the annotation is missing then the framework assumes non-idempotent.
+
+[TIP]
+====
+The attribute was originally introduced for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] in order that action invocations could be made available using either HTTP GET, PUT or POST (respectively).
+
+Since then its use has been extended into the core runtime. For example, it is now aso used for the in-built concurrency checking; the invocation of a safe action 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)
+ public CreditRating checkCredit() { ... }
+
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public void changeOfAddress(Address address) { ... }
+
+ @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
+ public Order placeNewOrder() { ... }
+ ...
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
new file mode 100644
index 0000000..8647912
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
@@ -0,0 +1,31 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
new file mode 100644
index 0000000..2186eab
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
@@ -0,0 +1,106 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`domainEvent()`]
+|subtype of `CollectionDomainEvent` +
+(`CollectionDomainEvent.Default`)
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-Collection_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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> {
+ private static final long serialVersionUID = 1L;
+ public DependenciesChangedEvent(
+ ToDoItem source,
+ Identifier identifier,
+ Of of,
+ ToDoItem value) {
+ super(source, identifier, of, value);
+ }
+ }
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class,
+ editing = Editing.ENABLED,
+ hidden = Where.NOWHERE, // <1>
+ notPersisted = false, // <2>
+ typeOf = ToDoItem.class // <3>
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> default value, so could be omitted
+<2> default value, so could be omitted
+<3> default value, so could be omitted
+
+
+
+
+
+include::_rg_annotations_manpage-Collection_domainEvent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_editing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_notPersisted.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_typeOf.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
new file mode 100644
index 0000000..1e4988c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
@@ -0,0 +1,121 @@
+[[_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[`describedAs()`]
+|String.
+|description of this collection, eg to be rendered in a tooltip.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`render()`]
+|`EAGERLY`, `LAZILY` +
+(`LAZILY`)
+|whether the collection should be (eagerly) rendered open or (lazily) rendered closed
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_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"
+ }
+}
+----
+
+
+
+
+
+include::_rg_annotations_manpage-CollectionLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_paged.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_render.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_sortedBy.adoc[leveloffset=+1]
+
+
+
+
+
+