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/05/28 15:03:51 UTC

[25/29] isis git commit: ISIS-1133: fixing references, breaking out annotation pages for each attribute (for more consistent cross-referencing).

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
new file mode 100644
index 0000000..381f39f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
@@ -0,0 +1,33 @@
+[[_ug_reference-annotations_manpage-Collection_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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+The `@TypeOf` annotation is used to specify the type of elements in a collection, when for whatever reason it is not possible to use generics.
+
+[NOTE]
+====
+Given that Apache Isis only supports Java 1.7 and later, it's not that obvious what such a reason might be...
+====
+
+
+For example:
+
+[source,java]
+----
+public void AccountService {
+    @TypeOf(Customer.class)
+    public List errantAccounts() {
+        return CustomerDatabase.allNewCustomers();
+    }
+    ...
+}
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
index 92f971b..2c9c26e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
@@ -19,372 +19,53 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:__a_id_reference_annotations_manpage_domainobject_a_code_auditing_code[`auditing()`]
+|xref:_ug_reference-annotations_manpage-DomainObject_auditing[`auditing()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobject_a_code_autocomplete_code[`autoComplete()`]
+|xref:_ug_reference-annotations_manpage-DomainObject_autoComplete[`autoComplete()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobject_a_code_bounded_code[`bounded()`]
+|xref:_ug_reference-annotations_manpage-DomainObject_bounded[`bounded()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobject_a_code_editing_code[`editing()`]
+|xref:_ug_reference-annotations_manpage-DomainObject_editing[`editing()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobject_a_publishing[`publishing()`]
+|xref:_ug_reference-annotations_manpage-DomainObject_objectType[`objectType()`]
 |
 |
 
 
-|`publishingPayloadFactory()`
+|xref:_ug_reference-annotations_manpage-DomainObject_publishing[`publishing()`]
 |
 |
 
-|===
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObject[]`auditing()`
-
-IMPORTANT: WIP ... this section
-
-
-This annotation, which applies only to objects, indicates that if the object is modified, then it should be submitted to the  xref:__a_id_reference_services_spi_manpage_a_code_auditingservice3_code[`AuditingService3`], if one has been configured.
-
-For example:
-
-[source,java]
-----
-@Audited
-public class Customer extends AbstractDomainObject {
-   ....
-}
-----
-
-The `AuditingService` is defined within the applib (in the
-`org.apache.isis.applib.services.audit` package):
-
-[source,java]
-----
-public interface AuditingService {
-    @Hidden
-    public void audit(String user, long currentTimestampEpoch, String objectType, String identifier, String preValue, String postValue);
-}
-----
-
-At the time of writing only the JDO Object Store supported this
-annotation. Check with the documentation of the object store or ask on
-the mailing list to determine whether auditing is supported for other object stores.
-
-
-
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObject[]`autoComplete()`
-
-IMPORTANT: WIP ... this section
-
-
-This annotation is to support an auto-complete capability for reference
-properties and action parameters, the idea being that the user enters a
-few characters to locate a reference, and these are shown - for example
-- in a drop-down list box.
-
-The annotation is specified on the type, and specifies an action on a
-repository; this action should take a single string and should return a
-list of the type.
-
-For example:
-
-[source,java]
-----
-@AutoComplete(repository=Customers.class, action="autoComplete")
-public class Customer extends AbstractDomainObject {
-   ....
-}
-----
-
-where:
-
-[source,java]
-----
-public interface Customers {
-
-    @Hidden
-    List<Customer> autoComplete(String search);
-    ...
-}
-----
-
-
-[NOTE]
-====
-In many cases you may require additional control. For this, you can use the `autoComplete` method prefix, associated either with link:../../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html[action parameter] or with the link:../../how-tos/how-to-03-015-How-to-specify-an-autocomplete-for-a-property.html[property].
-====
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObject[]`bounded()`
-
-IMPORTANT: WIP ... this section
-
-
-For immutable objects where there is a bounded set of instances, the
-`@Bounded` annotation can be used.
-
-For example:
-
-[source,java]
-----
-@Bounded
-public class County {
-    ...
-}
-----
-
-The number of instances is expected to be small enough that all instance can be held in memory. The viewer will use this information to render all the instances of this class in a drop-down list or equivalent.
-
-
-[NOTE]
-====
-Although this is not enforced, `@Bounded` is intended for use on `final` classes. Its behaviour when used on interfaces, or classes with sub-classes is not specified
-
-====
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObject[]`editing()`
-
-IMPORTANT: WIP ... this section
-
-
-[NOTE]
-====
-Fully supported by: Wicket viewer; other viewers do not yet support the `where` attribute.
-====
-
-
-
-The `@Disabled` annotation means that the member cannot be used in any instance of the class. When applied to the property it means that the user may not modify the value of that property (though it may still be modified programmatically). When applied to an action method, it means that the user cannot invoke that method.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    @Disabled
-    public void assessCreditWorthiness() { ... }
-
-    @Disabled
-    public int getInitialCreditRating(){ ... }
-    public void setInitialCreditRating(int initialCreditRating) { ... }
-}
-----
-
-Note that if an action is marked as `@Disabled`, it will be shown on the
-user interface but cannot ever be invoked. The only possible reason we
-can think to do this is during prototyping, to indicate an action that
-is still to be developed. If a method is intended for programmatic use,
-but not intended ever to be invoked directly by a user, then it should
-be marked as `@Hidden` instead.
-
-This annotation can also take two parameter indicating where (in the UI)
-it is to be disabled, and when (in the object's lifecycle) it is to be
-disabled. For example:
-
-[source,java]
-----
-public class Customer {
-    (when=When.UNTIL_PERSISTED)
-    public void assessCreditWorthiness() { ... }
-}
-----
-
-would disable the action until the object has been saved. And:
-
-[source,java]
-----
-public class Customer {
-    (where=Where.PARENTED_TABLES)
-    public void getFirstName() { ... }
-}
-----
-
-would disable the property in parented tables but not in regular object
-forms (though note: this would only be used by viewers that provide
-in-table editing capability).
-
-The acceptable values for the `where` parameter are:
-
-* `Where.ANYWHERE` +
-+
-The member should be disabled everywhere.
-
-* `Where.OBJECT_FORMS` +
-+
-The member should be disabled when displayed within an object form.
-For most viewers, this applies to property and collection members,
-not actions.
-
-* `Where.PARENTED_TABLES` +
-+
-The member should be disabled when displayed as a column of a table
-within a parent object's collection. For most (all?) viewers, this
-will have meaning only if applied to a property member.
-
-* `Where.STANDALONE_TABLES` +
-+
-The member should be disabled when displayed as a column of a table
-showing a standalone list of objects, for example as returned by a
-repository query. For most (all?) viewers, this will have meaning
-only if applied to a property member.
-
-* `Where.ALL_TABLES` +
-+
-The member should be disabled when displayed as a column of a table,
-either an object's * collection or a standalone list. This combines
-`PARENTED_TABLES` and `STANDALONE_TABLES`
-
-* `Where.NOWHERE` +
-+
-Has no meaning for the `@Disabled` annotation (though is used by the
-`@Hidden` annotation which also uses the `Where` enum<!--, see ?-->).
-
-The acceptable values for the `when` parameter are:
-
-* `When.ALWAYS` +
-+
-The member should be disabled at all times.
-
-* `When.NEVER` +
-+
-The member should never be disabled (unless disabled through some
-other mechanism, for example an imperative disableXxx() supporting
-method)..
-
-* `When.ONCE_PERSISTED` +
-+
-The member should be enabled for transient objects, but disabled for
-persisted objects.
-
-* `When.UNTIL_PERSISTED` +
-+
-The member should be disabled for transient objects, but enabled for
-persisted objects.
-
-By default the annotated property or action is always disabled (ie
-defaults to `Where.ANYWHERE`, `When.ALWAYS`).
-
-
-
-
-
-
-The `@Immutable` annotation may be applied to a class, and indicates to the framework that the state of such objects may not be changed. The viewers will prevent any change through the user interface, and moreover the object stores will reject any changes to the objects that might have occurred programmatically.
-
-For example:
-
-[source,java]
-----
-@Immutable
-public class Country {
-    ...
-}
-----
-
-This annotation can also take a single parameter indicating when it is
-to become immutable. For example:
-
-[source,java]
-----
-@Immutable(When.ONCE_PERSISTED)
-public class Email {
-    ...
-}
-----
-
-This would allow the user to create an email object and set it up, and
-then prevent any changes once it has been saved.
-
-The acceptable values for the parameter are:
-
-* `When.ALWAYS`
-
-* `When.NEVER`
-
-* `When.ONCE_PERSISTED`
-
-* `When.UNTIL_PERSISTED`
-
-By default the annotated property or action is always immutable (ie
-defaults to `When.ALWAYS`).
-
-
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObject[]`objectType()`
-
-IMPORTANT: WIP ... this section
-
-The `@ObjectType` annotation is used to provide a unique abbreviation for the object's class name. This is used internally to generate a string representation of an objects identity (the `Oid`).
-
-For example:
-
-[source,java]
-----
-@ObjectType("ORD")
-public class Order {
-
-    ...
-}
-----
-
-If no `@ObjectType` annotation is present, then the framework uses the
-fully-qualified class name.
-
-If an `@ObjectType` is not unique, then the framework will fail to boot.
-
-
-
-
 
+|`publishingPayloadFactory()`
+|
+|
 
-== anchor:reference-annotations_manpage-DomainObject[]Publishing
+|===
 
 
-This annotation on an entity type causes an events to be published by the registered implementation of a xref:__a_id_reference_services_spi_manpage_a_code_publishingservice_code[`PublishingService`] if an instance of that type is inserted, updated or deleted .
 
 
+include::_ug_reference-annotations_manpage-DomainObject_auditing.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject_autoComplete.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject_bounded.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject_editing.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject_objectType.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObject_publishing.adoc[leveloffset=+1]
 
-=== `publishing()`
 
-IMPORTANT: WIP ... this section
 
-=== `publishingPayloadFactory()`
 
-IMPORTANT: WIP ... this section
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
index 1091679..29292a5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
@@ -20,43 +20,43 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_bookmarking_code[`bookmarking()`]
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking[`bookmarking()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_cssclass_code[`cssClass()`]
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssclass[`cssClass()`]
 |
 |the css class that a domain class (type) should have, to allow more targetted styling in `application.css`
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_describedas_code[`describedAs()`]
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`cssClassFa()`]
 |
-|description of this class, eg to be rendered in a tooltip.
-
+|the name of this class (overriding the name derived from its name in code)
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_cssclassfa[`cssClassFa()`]
+|`cssClassFaPosition()`
 |
 |the name of this class (overriding the name derived from its name in code)
 
 
-|`cssClassFaPosition()`
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
 |
-|the name of this class (overriding the name derived from its name in code)
+|description of this class, eg to be rendered in a tooltip.
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_named_code[`named()`]
+
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[`named()`]
 |
 |
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_paged_code[`paged()`]
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[`paged()`]
 |
 |the page size for instances of this class when rendered within a table.
 
 
-|xref:__a_id_reference_annotations_manpage_domainobjectlayout_a_code_plural_code[`plural()`]
+|xref:_ug_reference-annotations_manpage-DomainObjectLayout_plural[`plural()`]
 |
 |the plural name of the class
 
@@ -64,8 +64,6 @@ The table below summarizes the annotation's attributes.
 
 
 
-
-
 For example:
 
 [source,java]
@@ -88,373 +86,12 @@ equivalent link:./ViewModelLayout.html[@ViewModelLayout] can be used.
 
 
 
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`bookmarking()`
-
-IMPORTANT: WIP ... this section
-
-
-The `@Bookmarkable` annotation indicates that an entity or an action (with safe link:./ActionSemantics.html[action semantics]) is automatically bookmarked.
-
-(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel that slides out from the left:
-
-<img src="images/Bookmarkable.png" width="640px"/>
-
-For example:
-
-[source,java]
-----
-@Bookmarkable
-public class ToDoItem ... {
-    ...
-}
-----
-
-indicates that the `ToDoItem` class is bookmarkable, while:
-
-[source,java]
-----
-@Named("ToDos")
-public class ToDoItems {
-
-    @Bookmarkable
-    @ActionSemantics(Of.SAFE)
-    @MemberOrder(sequence = "1")
-    public List<ToDoItem> notYetComplete() {
-        ...
-    }
-
-}
-----
-
-indicates that the "not yet complete" action is bookmarkable.
-
-It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
-
-<img src="images/Bookmarkable-nested.png" width="640px"/>
-
-For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark (the default), but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark if its parent `Property` has already been visited. This is accomplished with the following annotations:
-
-[source,java]
-----
-@Bookmarkable
-public class Property { ... }
-----
-
-and
-
-[source,java]
-----
-@Bookmarkable(BookmarkPolicy.AS_CHILD)
-public abstract class Unit { ... }
-----
-
-The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting 3 deep: `Lease` -&gt; `LeaseItem` -&gt; `LeaseTerm`.
-
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`cssClass()`
-
-IMPORTANT: WIP ... this section
-
-
-The `CssClass` annotation applies to object and also to any object member
-(property, collection or action). It is used by the Wicket viewer as a UI hint
-to render specified CSS classes around the representation of the element.
-
-Application-specific CSS can then be used to target and adjust the UI representation
-of that particular element.
-
-For example:
-
-[source,java]
-----
-@CssClass("x-main")
-public class ToDoItem { ... }
-----
-
-or
-
-[source,java]
-----
-public class ToDoItem {
-
-    @CssClass("x-key")
-    public LocalDate getDueBy() { ... }
-
-}
-----
-
-=== Alternatives (`.layout.json`)
-
-As an alternative to using the `@CssClass` annotation, the `.layout.json`
-link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layout file]
-can be specified, eg:
-
-[source,javascript]
-----
-{
-    "span": 6,
-    "memberGroups": {
-        "Priority": {
-            "members": {
-                ...
-                "dueBy": {
-                    "cssClass": { "value": "x-key" }
-                }
-                ....
-            }
-        },
-        ...
-    }
-}
-----
-
-Note that this (currently) only supports class members, not classes
-
-
-[NOTE]
-====
-The similar link:./CssClassFa-deprecated.html[CssClassFa] annotation is also used as a hint
-to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
-to be rendered on action butotns or as the icon for classes.
-====
-
-
-
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]cssClassFa
-
-
-=== `cssClassFa()`
-
-IMPORTANT: WIP ... this section
-
-
-The `CssClassFa` annotation applies to objects and also to object actions,
-and is used by the Wicket viewer as a UI hint.
-
-For object actions, the viewer will render the specified
-http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon]
-on the action's button (or menu item).
-
-For objects, it will be used as an icon. Note that this is only used if
-the object does not have a `getIconName()` method.
-
-For example:
-
-[source,java]
-----
-@CssClassFa("fa-check-circle")
-public class ToDoItem { ... }
-----
-
-or
-
-[source,java]
-----
-public class ToDoItem {
-
-    @CssClass("fa-step-backward")
-    public ToDoItem previous() { ... }
-
-    @CssClass("fa-step-forward")
-    public ToDoItem next() { ... }
-
-}
-----
-
-There can be multiple "fa-" classes, eg to mirror or rotate the icon. There
-is no need to include the "fa" class; it will be automatically appended.
-
-=== Alternatives (`.layout.json`)
-
-As an alternative to using the `@CssClass` annotation, the `.layout.json`
-link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layout file]
-can be specified, eg:
-
-[source,javascript]
-----
-{
-    "span": 6,
-    "memberGroups": {
-        "Priority": {
-            "members": {
-                ...
-                 "relativePriority": {
-                    "actions": {
-                        "previous": {
-                            "cssClassFa": { "value": "fa-step-backward" }
-                        },
-                        "next": {
-                            "cssClassFa": { "value": "fa-step-forward" }
-                        }
-                    }
-                },
-                ....
-            }
-        },
-        ...
-    }
-}
-----
-
-Note that this (currently) only supports class members, not classes.
-
-
-[TIP]
-====
-The similar link:./CssClass-deprecated.html[CssClass] annotation 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.
-====
-
-
-
-
-=== `cssClassFaPosition()`
-
-IMPORTANT: WIP ... this section
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`describedAs()`
-
-IMPORTANT: WIP ... this section
-
-The `@DescribedAs` annotation is used to provide a short description of something that features on the user interface. How this description is used will depend upon the viewing mechanism - but it may be thought of as being like a 'tool tip'.
-
-Descriptions may be provided for objects, members (properties, collections and actions), and for individual parameters within an action method. `@DescribedAs` therefore works in a very similar manner to `@Named`.
-
-For example:
-
-[source,java]
-----
-@DescribedAs("A customer who may have originally become known to us via " +
-             "the marketing system or who may have contacted us directly.")
-public class ProspectiveSale {
-   ...
-}
-----
-
-
-
-
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`named()`
-
-IMPORTANT: WIP ... this section
-
-
-By default the name of an object is derived, reflectively from the class
-name. To specify a different name for an object, use the `@Named`
-annotation in front of the class declaration.
-
-The `@Named` annotation is used when you want to specify the way
-something is named on the user interface i.e. when you do not want to
-use the name generated automatically by the system. It can be applied to
-objects, members (properties, collections, and actions) and to
-parameters within an action method.
-
-
-[WARNING]
-====
-Generally speaking it is better to rename the property, collection or action. The only common case where `@Named` is common is to rename parameters for built-in value types. Even here though a custom value type can be defined using `@Value` so that the value type is used as the parameter name. `@Named` may also be used if the name needs punctuation or other symbols in the name presented to the user.
-====
-
-
-For example:
-
-[source,java]
-----
-@Named("Customer")
-public class CustomerImpl implements Customer{
-   ...
-}
-----
-
-See also the `@Plural` annotation <!--, ?-->.
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`paged()`
-
-IMPORTANT: WIP ... this section
-
-This annotation is used to indicate that parented and/or standalone
-collections should be paginated.
-
-When annotated on a collection, `@Paged` indicates the page size of a parented collection. When annotated on a type, `@Paged` indicates the page size of a standalone collection.
-
-For example:
-
-[source,java]
-----
-@Paged(30)
-public class Order {
-
-}
-----
-
-This indicates a page size of 30 for standalone collections.
-
-When omitting a parameter value or omitting the annotation completely,
-the configured defaults in `isis.properties` will be used.
-
-For example:
-
-[source,ini]
-----
-isis.viewers.paged.standalone=20
-isis.viewers.paged.parented=5
-----
-
-IMPORTANT: TODO - update runtime config chapter.
-
-
-This indicates a page size of 5 for parented collections and a page size
-of 20 for standalone collections.
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainObjectLayout[]`plural()`
-
-IMPORTANT: WIP ... this section
-
-When the framework displays a collection of several objects it may use the plural form of the object type in the title. By default the plural name will be created by adding an 's' to the end of the singular name (whether that is the class name or another name specified using `@Named`). Where the single name ends in 'y' then the default plural name will end in 'ies' - for example a collection of `Country` objects will be titled 'Countries'. Where these conventions do not work, the programmer may specify the plural form of the name using `@Plural`.
-
-For example:
-
-[source,java]
-----
-@Plural("Children")
-public class Child {
-    // members and actions here
-}
-----
-
-
-
+include::_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
new file mode 100644
index 0000000..f6a2223
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
@@ -0,0 +1,69 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+The `@Bookmarkable` annotation indicates that an entity or an action (with safe link:./ActionSemantics.html[action semantics]) is automatically bookmarked.
+
+(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel that slides out from the left:
+
+<img src="images/Bookmarkable.png" width="640px"/>
+
+For example:
+
+[source,java]
+----
+@Bookmarkable
+public class ToDoItem ... {
+    ...
+}
+----
+
+indicates that the `ToDoItem` class is bookmarkable, while:
+
+[source,java]
+----
+@Named("ToDos")
+public class ToDoItems {
+
+    @Bookmarkable
+    @ActionSemantics(Of.SAFE)
+    @MemberOrder(sequence = "1")
+    public List<ToDoItem> notYetComplete() {
+        ...
+    }
+
+}
+----
+
+indicates that the "not yet complete" action is bookmarkable.
+
+It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
+
+<img src="images/Bookmarkable-nested.png" width="640px"/>
+
+For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark (the default), but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark if its parent `Property` has already been visited. This is accomplished with the following annotations:
+
+[source,java]
+----
+@Bookmarkable
+public class Property { ... }
+----
+
+and
+
+[source,java]
+----
+@Bookmarkable(BookmarkPolicy.AS_CHILD)
+public abstract class Unit { ... }
+----
+
+The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting 3 deep: `Lease` -&gt; `LeaseItem` -&gt; `LeaseTerm`.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
new file mode 100644
index 0000000..e1bd2fc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
@@ -0,0 +1,75 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+The `CssClass` annotation applies to object and also to any object member
+(property, collection or action). It is used by the Wicket viewer as a UI hint
+to render specified CSS classes around the representation of the element.
+
+Application-specific CSS can then be used to target and adjust the UI representation
+of that particular element.
+
+For example:
+
+[source,java]
+----
+@CssClass("x-main")
+public class ToDoItem { ... }
+----
+
+or
+
+[source,java]
+----
+public class ToDoItem {
+
+    @CssClass("x-key")
+    public LocalDate getDueBy() { ... }
+
+}
+----
+
+=== Alternatives (`.layout.json`)
+
+As an alternative to using the `@CssClass` annotation, the `.layout.json`
+link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layout file]
+can be specified, eg:
+
+[source,javascript]
+----
+{
+    "span": 6,
+    "memberGroups": {
+        "Priority": {
+            "members": {
+                ...
+                "dueBy": {
+                    "cssClass": { "value": "x-key" }
+                }
+                ....
+            }
+        },
+        ...
+    }
+}
+----
+
+Note that this (currently) only supports class members, not classes
+
+
+[NOTE]
+====
+The similar link:./CssClassFa-deprecated.html[CssClassFa] annotation is also used as a hint
+to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
+to be rendered on action butotns or as the icon for classes.
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
new file mode 100644
index 0000000..56be48b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
@@ -0,0 +1,101 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa]]
+= Font-awesome icons
+: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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+
+== `cssClassFa()`
+
+IMPORTANT: WIP ... this section
+
+
+The `CssClassFa` annotation applies to objects and also to object actions,
+and is used by the Wicket viewer as a UI hint.
+
+For object actions, the viewer will render the specified
+http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon]
+on the action's button (or menu item).
+
+For objects, it will be used as an icon. Note that this is only used if
+the object does not have a `getIconName()` method.
+
+For example:
+
+[source,java]
+----
+@CssClassFa("fa-check-circle")
+public class ToDoItem { ... }
+----
+
+or
+
+[source,java]
+----
+public class ToDoItem {
+
+    @CssClass("fa-step-backward")
+    public ToDoItem previous() { ... }
+
+    @CssClass("fa-step-forward")
+    public ToDoItem next() { ... }
+
+}
+----
+
+There can be multiple "fa-" classes, eg to mirror or rotate the icon. There
+is no need to include the "fa" class; it will be automatically appended.
+
+=== Alternatives (`.layout.json`)
+
+As an alternative to using the `@CssClass` annotation, the `.layout.json`
+link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layout file]
+can be specified, eg:
+
+[source,javascript]
+----
+{
+    "span": 6,
+    "memberGroups": {
+        "Priority": {
+            "members": {
+                ...
+                 "relativePriority": {
+                    "actions": {
+                        "previous": {
+                            "cssClassFa": { "value": "fa-step-backward" }
+                        },
+                        "next": {
+                            "cssClassFa": { "value": "fa-step-forward" }
+                        }
+                    }
+                },
+                ....
+            }
+        },
+        ...
+    }
+}
+----
+
+Note that this (currently) only supports class members, not classes.
+
+
+[TIP]
+====
+The similar link:./CssClass-deprecated.html[CssClass] annotation 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.
+====
+
+
+
+
+== `cssClassFaPosition()`
+
+IMPORTANT: WIP ... this section

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
new file mode 100644
index 0000000..d1f8adb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
@@ -0,0 +1,29 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_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/
+
+
+
+IMPORTANT: WIP ... this section
+
+The `@DescribedAs` annotation is used to provide a short description of something that features on the user interface. How this description is used will depend upon the viewing mechanism - but it may be thought of as being like a 'tool tip'.
+
+Descriptions may be provided for objects, members (properties, collections and actions), and for individual parameters within an action method. `@DescribedAs` therefore works in a very similar manner to `@Named`.
+
+For example:
+
+[source,java]
+----
+@DescribedAs("A customer who may have originally become known to us via " +
+             "the marketing system or who may have contacted us directly.")
+public class ProspectiveSale {
+   ...
+}
+----
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
new file mode 100644
index 0000000..f1a1866
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
@@ -0,0 +1,42 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+By default the name of an object is derived, reflectively from the class
+name. To specify a different name for an object, use the `@Named`
+annotation in front of the class declaration.
+
+The `@Named` annotation is used when you want to specify the way
+something is named on the user interface i.e. when you do not want to
+use the name generated automatically by the system. It can be applied to
+objects, members (properties, collections, and actions) and to
+parameters within an action method.
+
+
+[WARNING]
+====
+Generally speaking it is better to rename the property, collection or action. The only common case where `@Named` is common is to rename parameters for built-in value types. Even here though a custom value type can be defined using `@Value` so that the value type is used as the parameter name. `@Named` may also be used if the name needs punctuation or other symbols in the name presented to the user.
+====
+
+
+For example:
+
+[source,java]
+----
+@Named("Customer")
+public class CustomerImpl implements Customer{
+   ...
+}
+----
+
+See also the `@Plural` annotation <!--, ?-->.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
new file mode 100644
index 0000000..6ee520a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
@@ -0,0 +1,48 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_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/
+
+
+
+
+IMPORTANT: WIP ... this section
+
+This annotation is used to indicate that parented and/or standalone
+collections should be paginated.
+
+When annotated on a collection, `@Paged` indicates the page size of a parented collection. When annotated on a type, `@Paged` indicates the page size of a standalone collection.
+
+For example:
+
+[source,java]
+----
+@Paged(30)
+public class Order {
+
+}
+----
+
+This indicates a page size of 30 for standalone collections.
+
+When omitting a parameter value or omitting the annotation completely,
+the configured defaults in `isis.properties` will be used.
+
+For example:
+
+[source,ini]
+----
+isis.viewers.paged.standalone=20
+isis.viewers.paged.parented=5
+----
+
+IMPORTANT: TODO - update runtime config chapter.
+
+
+This indicates a page size of 5 for parented collections and a page size
+of 20 for standalone collections.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
new file mode 100644
index 0000000..8461275
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
@@ -0,0 +1,26 @@
+[[_ug_reference-annotations_manpage-DomainObjectLayout_plural]]
+= `plural()`
+: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/
+
+
+
+IMPORTANT: WIP ... this section
+
+When the framework displays a collection of several objects it may use the plural form of the object type in the title. By default the plural name will be created by adding an 's' to the end of the singular name (whether that is the class name or another name specified using `@Named`). Where the single name ends in 'y' then the default plural name will end in 'ies' - for example a collection of `Country` objects will be titled 'Countries'. Where these conventions do not work, the programmer may specify the plural form of the name using `@Plural`.
+
+For example:
+
+[source,java]
+----
+@Plural("Children")
+public class Child {
+    // members and actions here
+}
+----
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
new file mode 100644
index 0000000..83383fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
@@ -0,0 +1,41 @@
+[[_ug_reference-annotations_manpage-DomainObject_auditing]]
+= `auditing()`
+: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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+This annotation, which applies only to objects, indicates that if the object is modified, then it should be submitted to the  xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService3`], if one has been configured.
+
+For example:
+
+[source,java]
+----
+@Audited
+public class Customer extends AbstractDomainObject {
+   ....
+}
+----
+
+The `AuditingService` is defined within the applib (in the
+`org.apache.isis.applib.services.audit` package):
+
+[source,java]
+----
+public interface AuditingService {
+    @Programmatic
+    public void audit(String user, long currentTimestampEpoch, String objectType, String identifier, String preValue, String postValue);
+}
+----
+
+At the time of writing only the JDO Object Store supported this
+annotation. Check with the documentation of the object store or ask on
+the mailing list to determine whether auditing is supported for other object stores.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoComplete.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoComplete.adoc
new file mode 100644
index 0000000..3096276
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoComplete.adoc
@@ -0,0 +1,49 @@
+[[_ug_reference-annotations_manpage-DomainObject_autoComplete]]
+= `autoComplete()`
+: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/
+
+
+IMPORTANT: WIP ... this section
+
+
+This annotation is to support an auto-complete capability for reference
+properties and action parameters, the idea being that the user enters a
+few characters to locate a reference, and these are shown - for example
+- in a drop-down list box.
+
+The annotation is specified on the type, and specifies an action on a
+repository; this action should take a single string and should return a
+list of the type.
+
+For example:
+
+[source,java]
+----
+@AutoComplete(repository=Customers.class, action="autoComplete")
+public class Customer extends AbstractDomainObject {
+   ....
+}
+----
+
+where:
+
+[source,java]
+----
+public interface Customers {
+
+    @Hidden
+    List<Customer> autoComplete(String search);
+    ...
+}
+----
+
+
+[NOTE]
+====
+In many cases you may require additional control. For this, you can use the `autoComplete` method prefix, associated either with link:../../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html[action parameter] or with the link:../../how-tos/how-to-03-015-How-to-specify-an-autocomplete-for-a-property.html[property].
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
new file mode 100644
index 0000000..79eaa23
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
@@ -0,0 +1,36 @@
+[[_ug_reference-annotations_manpage-DomainObject_bounded]]
+= `bounded()`
+: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/
+
+
+
+IMPORTANT: WIP ... this section
+
+
+For immutable objects where there is a bounded set of instances, the
+`@Bounded` annotation can be used.
+
+For example:
+
+[source,java]
+----
+@Bounded
+public class County {
+    ...
+}
+----
+
+The number of instances is expected to be small enough that all instance can be held in memory. The viewer will use this information to render all the instances of this class in a drop-down list or equivalent.
+
+
+[NOTE]
+====
+Although this is not enforced, `@Bounded` is intended for use on `final` classes. Its behaviour when used on interfaces, or classes with sub-classes is not specified
+
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
new file mode 100644
index 0000000..913bc33
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
@@ -0,0 +1,177 @@
+[[_ug_reference-annotations_manpage-DomainObject_editing]]
+= `editing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or 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/
+
+
+
+
+IMPORTANT: WIP ... this section
+
+
+[NOTE]
+====
+Fully supported by: Wicket viewer; other viewers do not yet support the `where` attribute.
+====
+
+
+
+The `@Disabled` annotation means that the member cannot be used in any instance of the class. When applied to the property it means that the user may not modify the value of that property (though it may still be modified programmatically). When applied to an action method, it means that the user cannot invoke that method.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @Disabled
+    public void assessCreditWorthiness() { ... }
+
+    @Disabled
+    public int getInitialCreditRating(){ ... }
+    public void setInitialCreditRating(int initialCreditRating) { ... }
+}
+----
+
+Note that if an action is marked as `@Disabled`, it will be shown on the
+user interface but cannot ever be invoked. The only possible reason we
+can think to do this is during prototyping, to indicate an action that
+is still to be developed. If a method is intended for programmatic use,
+but not intended ever to be invoked directly by a user, then it should
+be marked as `@Hidden` instead.
+
+This annotation can also take two parameter indicating where (in the UI)
+it is to be disabled, and when (in the object's lifecycle) it is to be
+disabled. For example:
+
+[source,java]
+----
+public class Customer {
+    (when=When.UNTIL_PERSISTED)
+    public void assessCreditWorthiness() { ... }
+}
+----
+
+would disable the action until the object has been saved. And:
+
+[source,java]
+----
+public class Customer {
+    (where=Where.PARENTED_TABLES)
+    public void getFirstName() { ... }
+}
+----
+
+would disable the property in parented tables but not in regular object
+forms (though note: this would only be used by viewers that provide
+in-table editing capability).
+
+The acceptable values for the `where` parameter are:
+
+* `Where.ANYWHERE` +
++
+The member should be disabled everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The member should be disabled when displayed within an object form.
+For most viewers, this applies to property and collection members,
+not actions.
+
+* `Where.PARENTED_TABLES` +
++
+The member should be disabled when displayed as a column of a table
+within a parent object's collection. For most (all?) viewers, this
+will have meaning only if applied to a property member.
+
+* `Where.STANDALONE_TABLES` +
++
+The member should be disabled when displayed as a column of a table
+showing a standalone list of objects, for example as returned by a
+repository query. For most (all?) viewers, this will have meaning
+only if applied to a property member.
+
+* `Where.ALL_TABLES` +
++
+The member should be disabled when displayed as a column of a table,
+either an object's * collection or a standalone list. This combines
+`PARENTED_TABLES` and `STANDALONE_TABLES`
+
+* `Where.NOWHERE` +
++
+Has no meaning for the `@Disabled` annotation (though is used by the
+`@Hidden` annotation which also uses the `Where` enum<!--, see ?-->).
+
+The acceptable values for the `when` parameter are:
+
+* `When.ALWAYS` +
++
+The member should be disabled at all times.
+
+* `When.NEVER` +
++
+The member should never be disabled (unless disabled through some
+other mechanism, for example an imperative disableXxx() supporting
+method)..
+
+* `When.ONCE_PERSISTED` +
++
+The member should be enabled for transient objects, but disabled for
+persisted objects.
+
+* `When.UNTIL_PERSISTED` +
++
+The member should be disabled for transient objects, but enabled for
+persisted objects.
+
+By default the annotated property or action is always disabled (ie
+defaults to `Where.ANYWHERE`, `When.ALWAYS`).
+
+
+
+
+
+
+The `@Immutable` annotation may be applied to a class, and indicates to the framework that the state of such objects may not be changed. The viewers will prevent any change through the user interface, and moreover the object stores will reject any changes to the objects that might have occurred programmatically.
+
+For example:
+
+[source,java]
+----
+@Immutable
+public class Country {
+    ...
+}
+----
+
+This annotation can also take a single parameter indicating when it is
+to become immutable. For example:
+
+[source,java]
+----
+@Immutable(When.ONCE_PERSISTED)
+public class Email {
+    ...
+}
+----
+
+This would allow the user to create an email object and set it up, and
+then prevent any changes once it has been saved.
+
+The acceptable values for the parameter are:
+
+* `When.ALWAYS`
+
+* `When.NEVER`
+
+* `When.ONCE_PERSISTED`
+
+* `When.UNTIL_PERSISTED`
+
+By default the annotated property or action is always immutable (ie
+defaults to `When.ALWAYS`).
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
new file mode 100644
index 0000000..d1175ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
@@ -0,0 +1,31 @@
+[[_ug_reference-annotations_manpage-DomainObject_objectType]]
+= `objectType()`
+: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/
+
+
+
+IMPORTANT: WIP ... this section
+
+The `@ObjectType` annotation is used to provide a unique abbreviation for the object's class name. This is used internally to generate a string representation of an objects identity (the `Oid`).
+
+For example:
+
+[source,java]
+----
+@ObjectType("ORD")
+public class Order {
+
+    ...
+}
+----
+
+If no `@ObjectType` annotation is present, then the framework uses the
+fully-qualified class name.
+
+If an `@ObjectType` is not unique, then the framework will fail to boot.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
new file mode 100644
index 0000000..276773d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
@@ -0,0 +1,21 @@
+[[_ug_reference-annotations_manpage-DomainObject_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/
+
+
+
+
+This annotation on an entity type causes an events to be published by the registered implementation of a xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] if an instance of that type is inserted, updated or deleted .
+
+
+
+=== `publishing()`
+
+IMPORTANT: WIP ... this section
+
+=== `publishingPayloadFactory()`
+
+IMPORTANT: WIP ... this section
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
index 2c9acda..5b2a667 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
@@ -22,19 +22,19 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:__a_id_reference_annotations_manpage_domainservice_a_code_nature_code[`nature()`]
+|xref:_ug_reference-annotations_manpage-DomainService_nature[`nature()`]
 |
 |the nature of this service: providing actions for menus, contributed actions, or neither (1.8.0)
 
 
-|xref:__a_id_reference_annotations_manpage_domainservice_a_code_repositoryfor_code[`repositoryFor()`]
+|xref:_ug_reference-annotations_manpage-DomainService_repositoryFor[`repositoryFor()`]
 |
 |if this domain service acts as a repository for an entity type, specify that entity type. (This is currently informational only)
 
 
-|xref:__a_id_reference_annotations_manpage_domainservice_a_code_menuorder_code[`menuOrder()`]
+|`menuOrder()`
 |
-|the order of the service's menu with respect to other service's (deprecated in 1.8.0)
+|Deprecated in 1.8.0; use instead `@DomainServiceLayout(menuOrder=...)`
 
 |===
 
@@ -42,73 +42,8 @@ The table below summarizes the annotation's attributes.
 
 
 
-
-
-== anchor:reference-annotations_manpage-DomainService[]`nature()`
-
-IMPORTANT: WIP ... this section
-
-IMPORTANT: TODO - now also VIEW_REST_ONLY
-
-
-
-The `@NotContributed` annotation applies only to action methods, and
-specifically to the actions of services. If present, it indicates that
-the action should not be contributed to any of its domain object
-arguments.
-
-For example:
-
-[source,java]
-----
-public class OrderServices {
-    @NotContributed
-    public void cancel(Order order);
-    ...
-}
-----
-
-If the action should neither be contributed nor appear in the service's
-service menu, then you could instead simply mark it as `@Hidden`.
-
-=== Contributing of one-arg actions
-
-Actions that accept a single argument will, by default, also be contributed as an association:
-
-* if the action returns a single object (value or entity) then the action will be contributed as a property
-
-* if the action returns a list then the action will be contributed as a collection
-
-This behaviour can be influenced by specifying the "As." attribute:
-
-* use `@NotContributed(As.ACTION)` to contribute the action as an association
-* use `@NotContributed(As.ASSOCIATION)` to contribute the action as an action
-* use `@NotContributed` to not contribute the action at all.
-
-
-
-
-
-The `@NotInServiceMenu` annotation applies only to action methods, and specifically to the actions of services. If present, it indicates that the action should not appear in the service menu for the service. It may, however, still be contributed to any of its domain object arguments.
-
-
-For example:
-
-[source,java]
-----
-public class OrderServices {
-    @NotInServiceMenu
-    public void cancel(Order order);
-    ...
-}
-----
-
-
-
-If the action should neither be contributed (see ?) nor appear in the
-service's service menu, then you could instead simply mark it as `@Hidden`
-<!--(see ?)-->.
-
+include::_ug_reference-annotations_manpage-DomainService_nature.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
index 65c466e..4025456 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
@@ -20,78 +20,34 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:__a_id_reference_annotations_manpage_domainservicelayout_a_code_named_code[`named()`]
-|string, eg "Customers"
-|name of this class (overriding the name derived from its name in code)
-
-
-|xref:__a_id_reference_annotations_manpage_domainservicelayout_a_code_menubar_code[`menuBar()`]
+|xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`]
 |`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
 |the menubar in which the menu that holds this service's actions should reside.
 
 
-|xref:__a_id_reference_annotations_manpage_domainservicelayout_a_code_menuorder_code[`menuOrder()`]
+|xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`]
 |
 |the order of the service's menu with respect to other service's.
 
-|===
-
-
-
-It is not (currently) possible to specify the UI hints through any other means (specifically: is _not_ supported through a `.layout.json` file).
-
-
-
-
-
-
-== anchor:reference-annotations_manpage-DomainServiceLayout[]`named()`
-
-IMPORTANT: WIP ... this section
-
-
-By default the name of an object is derived, reflectively from the class name.
-
-To specify a different name for an object, use the `@Named` annotation in front of the class declaration.
-
-The `@Named` annotation is used when you want to specify the way something is named on the user interface i.e. when you do not want to use the name generated automatically by the system. It can be applied to objects, members (properties, collections, and actions) and to parameters within an action method.
-
-
-[WARNING]
-====
-Generally speaking it is better to rename the property, collection or action. The only common case where `@Named` is common is to rename parameters for built-in value types. Even here though a custom value type can be defined using `@Value` so that the value type is used as the parameter name. `@Named` may also be used if the name needs punctuation or other symbols in the name presented to the user.
-====
-
-
-For example:
-
-[source,java]
-----
-@Named("Customer")
-public class CustomerImpl implements Customer{
-   ...
-}
-----
-
-See also the `@Plural` annotation <!--, ?-->.
-
-
 
+|xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[`named()`]
+|string, eg "Customers"
+|name of this class (overriding the name derived from its name in code)
 
 
 
-== anchor:reference-annotations_manpage-DomainServiceLayout[]`menuBar()`
+|===
 
-IMPORTANT: WIP ... this section
 
 
-In the xref:__a_id_chapter_a_wicket_viewer[Wicket viewer] the `PRIMARY` menu bar is left-aligned, the `SECONDARY` menu bar is right aligned, and the `TERTIARY` menu bar is associated with the user's name (far top-right).
+It is not (currently) possible to specify the UI hints through any other means (specifically: is _not_ supported through a `.layout.json` file).
 
 
 
+include::_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc[leveloffset=+1]
 
 
-== anchor:reference-annotations_manpage-DomainServiceLayout[]`menuOrder()`
 
-IMPORTANT: WIP ... this section
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
new file mode 100644
index 0000000..4463768
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
@@ -0,0 +1,15 @@
+[[_ug_reference-annotations_manpage-DomainServiceLayout_menuBar]]
+= `menuBar()`
+: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/
+
+
+
+
+IMPORTANT: WIP ... this section
+
+
+In the xref:_ug_wicket-viewer[Wicket viewer] the `PRIMARY` menu bar is left-aligned, the `SECONDARY` menu bar is right aligned, and the `TERTIARY` menu bar is associated with the user's name (far top-right).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
new file mode 100644
index 0000000..2d352c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
@@ -0,0 +1,12 @@
+[[_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder]]
+= `menuOrder()`
+: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/
+
+
+
+
+IMPORTANT: WIP ... this section
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
new file mode 100644
index 0000000..91d3cc6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
@@ -0,0 +1,37 @@
+[[_ug_reference-annotations_manpage-DomainServiceLayout_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/
+
+
+
+
+IMPORTANT: WIP ... this section
+
+
+By default the name of an object is derived, reflectively from the class name.
+
+To specify a different name for an object, use the `@Named` annotation in front of the class declaration.
+
+The `@Named` annotation is used when you want to specify the way something is named on the user interface i.e. when you do not want to use the name generated automatically by the system. It can be applied to objects, members (properties, collections, and actions) and to parameters within an action method.
+
+
+[WARNING]
+====
+Generally speaking it is better to rename the property, collection or action. The only common case where `@Named` is common is to rename parameters for built-in value types. Even here though a custom value type can be defined using `@Value` so that the value type is used as the parameter name. `@Named` may also be used if the name needs punctuation or other symbols in the name presented to the user.
+====
+
+
+For example:
+
+[source,java]
+----
+@Named("Customer")
+public class CustomerImpl implements Customer{
+   ...
+}
+----
+
+See also the `@Plural` annotation <!--, ?-->.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
new file mode 100644
index 0000000..aedf6a5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
@@ -0,0 +1,74 @@
+[[_ug_reference-annotations_manpage-DomainService_nature]]
+= `nature()`
+: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/
+
+
+
+IMPORTANT: WIP ... this section; also VIEW_REST_ONLY
+
+
+
+The `@NotContributed` annotation applies only to action methods, and
+specifically to the actions of services. If present, it indicates that
+the action should not be contributed to any of its domain object
+arguments.
+
+For example:
+
+[source,java]
+----
+public class OrderServices {
+    @NotContributed
+    public void cancel(Order order);
+    ...
+}
+----
+
+If the action should neither be contributed nor appear in the service's
+service menu, then you could instead simply mark it as `@Hidden`.
+
+=== Contributing of one-arg actions
+
+Actions that accept a single argument will, by default, also be contributed as an association:
+
+* if the action returns a single object (value or entity) then the action will be contributed as a property
+
+* if the action returns a list then the action will be contributed as a collection
+
+This behaviour can be influenced by specifying the "As." attribute:
+
+* use `@NotContributed(As.ACTION)` to contribute the action as an association
+* use `@NotContributed(As.ASSOCIATION)` to contribute the action as an action
+* use `@NotContributed` to not contribute the action at all.
+
+
+
+
+
+The `@NotInServiceMenu` annotation applies only to action methods, and specifically to the actions of services. If present, it indicates that the action should not appear in the service menu for the service. It may, however, still be contributed to any of its domain object arguments.
+
+
+For example:
+
+[source,java]
+----
+public class OrderServices {
+    @NotInServiceMenu
+    public void cancel(Order order);
+    ...
+}
+----
+
+
+
+If the action should neither be contributed (see ?) nor appear in the
+service's service menu, then you could instead simply mark it as `@Hidden`
+<!--(see ?)-->.
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
new file mode 100644
index 0000000..a86ee71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
@@ -0,0 +1,10 @@
+[[_ug_reference-annotations_manpage-DomainService_repositoryFor]]
+= `repositoryFor()`
+: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/
+
+
+
+IMPORTANT: TODO
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
index 66fe116..e8620bf 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
@@ -12,7 +12,7 @@ Title: @HomePage
 
 [NOTE]
 ====
-Currently only by the xref:__a_id_chapter_a_wicket_viewer[Wicket Viewer].
+Currently only by the xref:_ug_wicket-viewer[Wicket Viewer].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
index 3d08ece..7c36094 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
@@ -9,7 +9,7 @@ IMPORTANT: TODO
 
 
 
-See also xref:__a_id_wicket_viewer_layout_a_dynamic_object_layout[dynamic object layouts].
+See also xref:_ug_wicket-viewer_layout_dynamic-object-layout[dynamic object layouts].
 
 `@MemberOrder` is the recommended mechanism for specifying the order in
 which fields and/or actions are presented to the user. (`@ActionOrder`
@@ -56,7 +56,7 @@ will be indeterminate.
 
 [NOTE]
 ====
-The xref:__a_id_chapter_a_wicket_viewer[Wicket viewer] lays out an object's properties and its collections separately, in which case the relative member order of properties and collections will be evaluated separately. In general, though, consider the layout of all properties and collections together, and of all actions together.
+The xref:_ug_wicket-viewer[Wicket viewer] lays out an object's properties and its collections separately, in which case the relative member order of properties and collections will be evaluated separately. In general, though, consider the layout of all properties and collections together, and of all actions together.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
index fbb38a0..fdbc9a5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:__a_id_reference_methods_prefixes_manpage_a_code_autocomplete_code[`autoComplete...()`] supporting method.
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
 
 
 For example: