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/05 13:56:42 UTC

[34/51] [abbrv] isis git commit: ISIS-1133: working on annotations.

ISIS-1133: working on annotations.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2af55a0a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2af55a0a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2af55a0a

Branch: refs/heads/master
Commit: 2af55a0a5798d06fccca461f2836a705bc20f66d
Parents: ba66f3c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 00:05:00 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 00:05:00 2015 +0100

----------------------------------------------------------------------
 ...erence-annotations_manpage-ActionLayout.adoc |   5 +
 ...notations_manpage-ActionLayout_position.adoc |  80 +++++++++++
 ...erence-annotations_manpage-DomainObject.adoc |   6 +
 ...annotations_manpage-DomainObject_nature.adoc |  59 ++++++++
 ...reference-annotations_manpage-Parameter.adoc |  58 +++++---
 ...nce-annotations_manpage-ParameterLayout.adoc |  44 ++----
 ...ations_manpage-ParameterLayout_cssClass.adoc |   5 +-
 ...ons_manpage-ParameterLayout_describedAs.adoc |  12 +-
 ...s_manpage-ParameterLayout_labelPosition.adoc |  44 +++++-
 ...tions_manpage-ParameterLayout_multiLine.adoc |  77 ++---------
 ...annotations_manpage-Parameter_maxLength.adoc |  19 +--
 ...annotations_manpage-Parameter_minLength.adoc |  35 -----
 ...notations_manpage-Parameter_mustSatisfy.adoc |  46 ++++---
 ...notations_manpage-Parameter_optionality.adoc |  34 +++--
 ...nce-annotations_manpage-Parameter_regex.adoc |  52 --------
 ...otations_manpage-Parameter_regexPattern.adoc |  31 +++++
 ..._reference-annotations_manpage-Property.adoc |  52 +++++---
 ...ence-annotations_manpage-PropertyLayout.adoc |   4 +-
 ...ns_manpage-PropertyLayout_labelPosition.adoc |  44 +++++-
 ...ations_manpage-PropertyLayout_multiLine.adoc |  80 +++--------
 ...-annotations_manpage-Property_maxLength.adoc |  31 ++++-
 ...nnotations_manpage-Property_mustSatisfy.adoc |  27 ++--
 ...nnotations_manpage-Property_optionality.adoc | 133 +++++++++++++++++++
 ...ence-annotations_manpage-Property_regex.adoc |  56 --------
 ...notations_manpage-Property_regexPattern.adoc |  28 ++++
 adocs/template/document.html.erb                |   2 +-
 26 files changed, 653 insertions(+), 411 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
index e842379..fde78ed 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
@@ -67,6 +67,10 @@ Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by
 
 A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
 
+|xref:_ug_reference-annotations_manpage-ActionLayout_position[`position()`]
+|`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
+|for actions associated (using xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
+
 
 |===
 
@@ -102,6 +106,7 @@ include::_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc[leveloff
 include::_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-ActionLayout_hidden.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-ActionLayout_named.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-ActionLayout_position.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
new file mode 100644
index 0000000..2ab5fc1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
@@ -0,0 +1,80 @@
+[[_ug_reference-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:_ug_reference-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_wicket-viewer[Wicket viewer]) as shown below:
+
+
+IMPORTANT: todo - wip
+
+
+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:
+
+IMPORTANT: todo - wip
+
+
+
+If the action is positioned as `PANEL`, then the action's button is rendered on the header of the panel that contains the property:
+
+IMPORTANT: todo - wip
+
+
+
+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:
+
+
+IMPORTANT: todo - wip
+
+
+
+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 the actions from potentially multiple properties grouped by that panel will be shown together.
+
+
+As an alternative to using the annotation, the dynamic xref:_ug_wicket-viewer_layout_dynamic-object-layout[`.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/2af55a0a/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 8f6f36f..ea6bc3e 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
@@ -48,6 +48,11 @@ The table below summarizes the annotation's attributes.
 |whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
 
 
+|xref:_ug_reference-annotations_manpage-DomainObject_nature[`nature()`]
+|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `VIEW_MODEL` (`NOT_SPECIFIED`)
+|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); and if an entity, how is its persistence managed
+
+
 |xref:_ug_reference-annotations_manpage-DomainObject_objectType[`objectType()`]
 |(none, which implies fully qualified class name)
 |specify an alias for the domain class used to uniquely identify the object both within the Isis runtime and externally
@@ -90,6 +95,7 @@ include::_ug_reference-annotations_manpage-DomainObject_auditing.adoc[leveloffse
 include::_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.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_nature.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-DomainObject_objectType.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-DomainObject_publishing.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
new file mode 100644
index 0000000..6098032
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
@@ -0,0 +1,59 @@
+[[_ug_reference-annotations_manpage-DomainObject_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/
+
+
+
+The `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer).  If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
+
+For example:
+
+[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class PieChartAnalysis {
+    ...
+}
+----
+
+Specifically, the nature must be one of:
+
+* `NOT_SPECIFIED,` +
++
+(the default); specifies no paricular semantics for the domain class.
+
+* `JDO_ENTITY` +
++
+indicates that the domain object is an entity whose persistence is managed internally by Isis, using the JDO/DataNucleus objectstore.
+
+* `EXTERNAL_ENTITY` +
++
+indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system.  For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
++
+The identity of an external entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+* `INMEMORY_ENTITY` +
++
+indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
++
+The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+* `VIEW_MODEL` +
++
+indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
+
+The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] or implement the xref:_ug_reference-classes_super_manpage-ViewModel[`ViewModel`] interface.
+
+
+[NOTE]
+====
+Under the covers Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
+
+Because this particular implementation was originally added to Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
+
+The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
index 1d353cb..bd231e2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
@@ -19,38 +19,41 @@ The table below summarizes the annotation's attributes.
 
 
 |xref:_ug_reference-annotations_manpage-Parameter_maxLength[`maxLength()`]
-|
-|
+|Positive integer
+|maximum number of characters for string parameters; ignored otherwise
 
 
-|xref:_ug_reference-annotations_manpage-Parameter_minLength[`minLength()`]
-|
-|
+|`minLength()`
+|Positive integer
+|Deprecated; use xref:_ug_reference-annotations_manpage-MinLength[`@MinLength`] instead. +
+
+Can be used to specify the minimum length for xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
 
 
 |xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`mustSatisfy()`]
-|
-|
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
 
 
 |xref:_ug_reference-annotations_manpage-Parameter_optionality[`optionality()`]
-|
-|
+|`MANDATORY`, `OPTIONAL` (`MANDATORY`)
+|specifies a parameter is optional rather than mandatory
 
 
-|xref:_ug_reference-annotations_manpage-Parameter_regex[regex()]
-|
-|
+|xref:_ug_reference-annotations_manpage-Parameter_regexPattern[regexPattern()]
+|regular expression
+|validates the contents of a string parameter against the regular expression pattern
 
 
 |`regexPatternFlags()`
-|
-|
+|value of flags as normally passed to `java.util.regex.` +
+`Pattern#compile(...)`
+|modifies the compilation of the regular expression
 
 
 |`regexPatternReplacement()`
 |
-|
+|Unused.
 
 
 |===
@@ -62,13 +65,32 @@ For example:
 
 [source,java]
 ----
+public class Customer {
+    public static class EmailSpecification extends AbstractSpecification<String> {
+        public String satisfiesSafely(String proposed) {
+            return EmailUtil.ensureValidEmail(proposed);    // <1>
+        }
+    }
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public Customer updateEmail(
+        @Parameter(
+            maxLength=30,
+            mustSatisfy=EmailSpecification.class,
+            optionality=Optionality.OPTIONAL,
+            regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+            regexPatternFlags=Pattern.CASE_INSENSITIVE
+        )
+        @ParameterLayout(named="New Email Address")
+        final String newEmailAddress
+        ...
+    }
+}
 ----
-
+<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
 
 include::_ug_reference-annotations_manpage-Parameter_maxLength.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter_minLength.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-Parameter_optionality.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter_regex.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Parameter_regexPattern.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
index 3da2894..53f5173 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
@@ -25,22 +25,27 @@ The table below summarizes the annotation's attributes.
 
 
 |xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[`describedAs()`]
-|
+|String
 |description of this parameter, eg to be rendered in a tooltip.
 
 
 |xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition()`]
-|
-|in forms, the positioning of the label (LEFT, TOP or NONE) relative to the parameter value. For boolean parameters it is also possible to specify RIGHT. Defaults to LEFT unless `multiLine` also specified (see below)
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Default is `LEFT`, unless xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean parameters.
 
 
 |xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`]
-|
-|for string parameters, render as a text area over multiple lines. If set &gt;1, then `labelPosition` defaults to TOP unless otherwise specified.
+|Positive integer
+|for string parameters, render as a text area over multiple lines. +
+
+If set > 1, then then xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
 
 
 |xref:_ug_reference-annotations_manpage-ParameterLayout_named[`named()`]
-|
+|String
 |the name of this parameter. +
 
 For Java 7 this is generally required. For Java 8, the name can often be inferred from the code so this attribute allows the name to be overridden.  A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
@@ -94,33 +99,6 @@ public class ToDoItem {
 Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:_ug_wicket-viewer_layout_dynamic-object-layout[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
-[TIP]
-.Specifying a default setting
-====
-If you want a consistent look-n-feel throughout the app, eg all action parameter labels to the top, then it'd be rather frustrating to have to annotate every property.
-
-Instead, a default can be specified in `isis.properties`:
-
-[source,java]
-----
-isis.viewers.parameterLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.parameterLayout.labelPosition=LEFT
-----
-
-If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
-====
-
-
-IMPORTANT: TODO - ensure this is also in the runtime config chapter
-
-
-
 
 
 include::_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
index b7fda28..4404db4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
@@ -17,7 +17,10 @@ For example:
 ----
 public class ToDoItem {
     public ToDoItem postpone(
-            @ParameterLayout(cssClass="x-key")
+            @ParameterLayout(
+                named="until",
+                cssClass="x-key"
+            )
             LocalDate until
         ) { ... }
     ...

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
index 40ed296..e130350 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
@@ -24,14 +24,12 @@ For example:
 public class Customer {
     public Order placeOrder(
                       Product product,
-                      @Named("Quantity")
-                      @DescribedAs("The quantity of the product being ordered")
+                      @ParameterLayout(
+                          named="Quantity",
+                          describedAs="The quantity of the product being ordered"
+                      )
                       int quantity) {
-        Order order = createTransientInstance(Order.class);
-        order.modifyCustomer(this);
-        order.modifyProduct(product);
-        order.setQuantity(quantity);
-        return order;
+        ...
     }
     ...
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
index efd3096..d1550f7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
@@ -6,10 +6,50 @@
 
 
 
+The `labelPosition()` attribute determines the positioning of labels for parameters.  This attribute can also be specified for xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[properties].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+
+For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
+
+For example:
+
+[source,java]
+----
+public class Order {
+    public Order changeStatus(
+                    OrderStatus newStatus
+                    @Parameter(
+                        optionality=Optionality.OPTIONAL
+                    )
+                    @ParameterLayout(
+                        named="Reason",
+                        labelPosition=LabelPosition.TOP
+                    )
+                    String reason) {
+        ...
+    }
+    ...
+}
+----
+
+
+To get an idea of how these are rendered (in the xref:_ug_wicket-viewer[Wicket viewer]), the default `LEFT` label positioning looks like:
+
+IMPORTANT: todo - wip
+
+
+The `TOP` label positioning is rendered:
+
+IMPORTANT: todo - wip
+
+
+And finally the `RIGHT` label positioning (for boolean checkboxes only) is rendered:
+
+IMPORTANT: todo - wip
+
 
-== anchor:reference-annotations_manpage-ParameterLayout[]`labelPosition()`
 
-IMPORTANT: WIP ... this section
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
index 35158db..535efc8 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
@@ -5,79 +5,28 @@
 :_imagesdir: images/
 
 
-IMPORTANT: WIP ... this section
 
-The `@MultiLine` annotation provides information about the carriage
-returns in a `String` property or action parameter, or for a
-string-based value type. It also implies a hint to the viewer that the
-widget to be used should be over multiple lines (eg a text area rather
-than a text field), with appropriate wrapping and/or scrollbars.
-
-More formally, the annotation indicates that:
-
-* the `String` property or parameter may contain carriage returns, and
-
-* (optionally) the typical number of such carriage returns (meaning
-the number of rows in the text area), and
-
-* (optionally) that the text should be wrapped (the default is that
-text is not wrapped).
-
-The syntax is:
-
-`@MultiLine([numberOfLines=&lt;typicalNumberOfCRs&gt;]
-        [,preventWrapping=&lt;false|true&gt;])`
+The `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines.  It is ignored for other parameter types.  The attribute is also supported for xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[properties].
 
 For example:
 
 [source,java]
 ----
 public class BugReport {
-    @MultiLine(numberOfLines=10)
-    public String getStepsToReproduce() { ... }
-    public void setStepsToReproduce(String stepsToReproduce) { ... }
+    public BugReport updateStepsToReproduce(
+                        @Parameter(named="Steps")
+                        @ParameterLayout(
+                            numberOfLines=10
+                        )
+                        final String steps) {
+        ...
+    }
     ...
 }
 ----
 
-Here the `stepsToReproduce` may be displayed in a text area of 10 rows,
-with no wrapping. A horizontal scrollbar may appear if the number of
-characters on any given row exceeds the width.
-
-Another example:
-
-[source,java]
-----
-public class Email {
-    @MultiLine(numberOfLines=20, preventWrapping=false)
-    public String getBody() { ... }
-    public void setBody(String body) { ... }
-    ...
-}
-----
-
-Here the body should be displayed in a text area of 20 rows, with
-wrapping.
-
-If the annotation is combined with the `@TypicalLength`, then the
-expected width of the text area in the user interface will be determined
-by the value of the typical length divided by the number of specified
-lines. For example:
-
-[source,java]
-----
-public class Email {
-    @MultiLine(numberOfLines=20, preventWrapping=false)
-    @TypicalLength(800)
-    public String getBody() { ... }
-    public void setBody(String body) { ... }
-    ...
-}
-----
-
-Here the body will (likely be) displayed in a text area of 20 rows, with
-40 columns.
-
-
-
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
index 28776a9..2a78ab9 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
@@ -5,10 +5,8 @@
 :_imagesdir: images/
 
 
-IMPORTANT: WIP ... this section
 
-
-The `@MaxLength` annotation indicates the maximum number of characters that the user may enter into a `String` property, or a `String` parameter in an action, or for a string-based value type. It is ignored if applied to any other type.
+The `maxLength()` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  It is ignored if applied to parameters of any other type.  This attribute can also be applied to xref:_ug_reference-annotations_manpage-Property_maxLength[properties].
 
 For example:
 
@@ -16,16 +14,19 @@ For example:
 ----
 public class CustomerRepository {
     public Customer newCustomer(
-        @MaxLength(30)
-        @Named("First Name") String firstName
-       ,@MaxLength(30)
-        @Named("Last Name") String lastName) {
-    ...
+        @Parameter(maxLength=30)
+        @ParameterLayout(named="First Name")  // <1>
+        final String firstName,
+        @Parameter(maxLength=50)
+        @ParameterLayout(named="Last Name")
+        final String lastName) {
+        ...
+    }
 }
 ----
+<1> the `@ParameterLayout(named=...)` attribute is required for Java 7; for Java 8 it can be omitted if the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension is used.
 
 
-If the model is being persisted to a relational database then `@MaxLength` should be specified for all `String` properties and action parameters.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_minLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_minLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_minLength.adoc
deleted file mode 100644
index e34a92e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_minLength.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_minLength]]
-= `minLength()`
-: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 `@MinLength` annotation is used to specify the minimum number of characters in a search of an link:../../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html[auto-complete].
-
-For example:
-
-[source,java]
-----
-public ToDoItem add(
-        @TypicalLength(20)
-        final ToDoItem toDoItem) {
-    getDependencies().add(toDoItem);
-    return this;
-}
-public List<ToDoItem> autoComplete0Add(
-        final @MinLength(2)
-        String search) {
-    final List<ToDoItem> list = toDoItems.autoComplete(search);
-    list.removeAll(getDependencies());
-    list.remove(this);
-    return list;
-}
-----
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
index a9417f3..4dabf87 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
@@ -6,37 +6,45 @@
 
 
 
-IMPORTANT: WIP ... this section
+The `mustSatisfy()` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.  The attribute is also supported on xref:_ug_reference-annotations_manpage-Property_mustSatisfy[properties].
 
+[TIP]
+====
+The specification implementations can (of course) be reused between parameters and xref:_ug_reference-annotations_manpage-Property_mustSatisfy[properties].
+====
 
-The `@MustSatisfy` annotation allows validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
+The `Specification` is consulted during validation, being passed the proposed value.  If the proposed value fails, then the value returned is the used as the invalidity reason.
 
 For example:
 
 [source,java]
 ----
+public class StartWithCapitalLetterSpecification
+        extends AbstractSpecification<String> {            // <1>
+    public String satisfiesSafely(String proposed) {
+        return "".equals(proposed)
+            ? "Empty string"
+            : !Character.isUpperCase(proposed.charAt(0))
+                ? "Does not start with a capital letter"
+                : null;
+    }
+}
 public class CustomerRepository {
     public Customer newCustomer(
-            @MustSatisfy(StartWithCapitalLetterSpecification.class)
-            @Named("First Name") firstName
-           ,@MustSatisfy(StartWithCapitalLetterSpecification.class)
-            @Named("Last Name") lastName) {
+            @Parameter(
+                mustSatisfy=StartWithCapitalLetterSpecification.class
+            )
+            @ParameterLayout(named="First Name")
+            final String firstName,
+            @Parameter(
+                mustSatisfy=StartWithCapitalLetterSpecification.class
+            )
+            @ParameterLayout(named="Last Name")
+            final String lastName) {
         ...
     }
     ...
 }
 ----
-
-The `Specification` is consulted during validation, being passed the
-proposed value.
-
-An alternative to using `@MustSatisfy` is to define a custom value type (though this introduces additional mapping complexity for both viewers and objectstore).
-
-
-[TIP]
-====
-Can also specify on property, so the specification class can be reused.
-====
-
-
+<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values.  The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
index 6495e9f..8d98853 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
@@ -6,27 +6,24 @@
 
 
 
-IMPORTANT: WIP ... this section
 
-
-By default, the system assumes that all properties of an object are
-required, and therefore will not let the user save a new object unless a
-value has been specified for each property. Similarly, by default, the
-system assumes that all parameters in an action are required and will
-not let the user execute that action unless values have been specified
-for each parameter.
-
-To indicate that an action parameter is optional use the `@Optional` annotation.
+By default, Apache Isis assumes that all parameters of an action are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:_ug_reference-annotations_manpage-Property_optionality[properties].
 
 
 [TIP]
 ====
-The `@Optional`annotation has no meaning for a primitive property (or parameter) such as `int` - because primitives will always return a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`).
+The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero).  If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
 ====
 
+The values for the attribute are:
 
+- `OPTIONAL` +
++
+The parameter is optional
 
-To indicate that an action may be invoked without having to specify a value for a particular parameter, annotate with `@Optional`.
+- `MANDATORY` +
++
+The parameter is mandatory
 
 For example:
 
@@ -34,15 +31,14 @@ For example:
 ----
 public class Customer {
     public Order placeOrder(
-            Product product
-           ,@Named("Quantity") int quantity
-           ,@Optional @Named("Special Instructions") String instr) {
+            final Product product,
+            @ParameterLayout(named = "Quantity")
+            final int quantity,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            @ParameterLayout(named = "Special Instructions")
+            final String instr) {
         ...
     }
     ...
 }
 ----
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regex.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regex.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regex.adoc
deleted file mode 100644
index c2f0504..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regex.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_regex]]
-= Regex
-: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 `@RegEx` annotation may be applied to any string property, or to any parameter within an action method. It can also be applied to any string-based value type. It serves both to validate and potentially to normalise the format of the input. `@Regex` is therefore similar in use to `@Mask` <!--(see ?)--> but provides more flexibility.
-
-The syntax is:
-
-`@RegEx(validation = &quot;regEx string&quot;,
-        format = &quot;regEx string&quot;, caseSensitive =
-        &lt;true|false&gt;)`
-
-Only the first parameter is required; the `format` defaults to "no
-formatting", and `caseSensitive` defaults to false.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public void updateEmail(
-            @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
-            @Named("Email") String email) {
-        ...
-    }
-    ...
-)
-----
-
-
-
-== `regexPattern()`
-
-IMPORTANT: WIP ... this section
-
-
-
-== `regexPatternFlags()`
-
-IMPORTANT: WIP ... this section
-
-
-
-== `regexPatternReplacement()`
-
-IMPORTANT: WIP ... this section

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
new file mode 100644
index 0000000..e027891
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
@@ -0,0 +1,31 @@
+[[_ug_reference-annotations_manpage-Parameter_regexPattern]]
+= `regexPattern()`
+: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 `regexPattern()` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Property_regexPattern[properties].
+
+The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern.  The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public void updateEmail(
+            @Parameter(
+                regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+                regexPatternFlags=Pattern.CASE_INSENSITIVE
+            )
+            @ParameterLayout(named = "Email")
+            final String email) {
+        ...
+    }
+)
+----
+
+The related `regexPatternReplacement()` attribute is currently unused.

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
index 9b2a1f7..a9fd831 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
@@ -42,12 +42,14 @@ It is also possible to apply the annotation to actions of domain services that a
 
 |xref:_ug_reference-annotations_manpage-Property_maxLength[`maxLength()`]
 |
-|
+|maximum number of characters for string parameters; ignored otherwise +
+
+In many/most cases you should however use xref:_ug_reference-annotations_manpage-Column[`@Column#length()`]
 
 
 |xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`mustSatisfy()`]
-|
-|
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
 
 
 |xref:_ug_reference-annotations_manpage-Property_notPersisted[`notPersisted()`]
@@ -63,22 +65,22 @@ Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in o
 
 |xref:_ug_reference-annotations_manpage-Property_optionality[`optionality()`]
 |
-|
+|specifies a property is optional rather than mandatory +
 
+In many/most cases you should however use xref:_ug_reference-annotations_manpage-Column[`@Column#allowNulls()`]
 
-|xref:_ug_reference-annotations_manpage-Property_regex[`regex()`]
-|
-|
 
 
-|`regexPatternFlags()`
-|
-|
+|xref:_ug_reference-annotations_manpage-Property_regexPattern[`regexPattern()`]
+|regular expression
+|validates the contents of a string parameter against the regular expression pattern
 
 
-|`regexPatternReplacement()`
-|
-|
+|`regexPatternFlags()`
+|value of flags as normally passed to `java.util.regex.` +
+`Pattern#compile(...)`
+|modifies the compilation of the regular expression
+
 
 |===
 
@@ -87,8 +89,28 @@ For example:
 
 [source,java]
 ----
+@DomainObject
+public class Customer {
+    public static class EmailSpecification extends AbstractSpecification<String> {
+        public String satisfiesSafely(String proposed) {
+            return EmailUtil.ensureValidEmail(proposed);    // <1>
+        }
+    }
+    @javax.jdo.annotations.Column(allowNulls="true")                // <2>
+    @Property(
+        maxLength=30,
+        minLength=5,
+        mustSatisfy=EmailSpecification.class,
+        regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+        regexPatternFlags=Pattern.CASE_INSENSITIVE
+    )
+    public String getEmailAddress() { ... }
+    public void setEmailAddress(String emailAddress) { ... }
+    ...
+}
 ----
-
+<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
+<2> generally use instead of the `@Property#optionality()` attribute
 
 
 
@@ -99,7 +121,7 @@ include::_ug_reference-annotations_manpage-Property_maxLength.adoc[leveloffset=+
 include::_ug_reference-annotations_manpage-Property_mustSatisfy.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-Property_notPersisted.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-Property_optionality.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_regex.adoc[leveloffset=+1]
+include::_ug_reference-annotations_manpage-Property_regexPattern.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
index ec8708b..9997c3c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
@@ -47,9 +47,9 @@ It is also possible to change the default through a xref:_ug_runtime_configuring
 
 |xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[`multiLine()`]
 |Positive integer
-|for string propertys, render as a text area over multiple lines.  +
+|for string properties, render as a text area over multiple lines.  +
 
-If set &gt;1, then xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
+If set > 1, then xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
 
 
 |xref:_ug_reference-annotations_manpage-PropertyLayout_named[`named()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
index 6e8e266..809c26b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
@@ -6,6 +6,43 @@
 
 
 
+
+The `labelPosition()` attribute determines the positioning of labels for properties.  This attribute can also be specified for xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[parameters].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+
+For boolean properties a positioning of `RIGHT` is also allowed; this is ignored for all other types.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+    @PropertyLayout(
+        labelPosition=LabelPosition.TOP
+    )
+    public String getDescription() { ... }
+    public void setDescription(String description) { ... }
+    ...
+}
+----
+
+
+To get an idea of how these are rendered (in the xref:_ug_wicket-viewer[Wicket viewer]), the default `LEFT` label positioning looks like:
+
+IMPORTANT: todo - wip
+
+
+The `TOP` label positioning is rendered:
+
+IMPORTANT: todo - wip
+
+
+And finally the `RIGHT` label positioning (for boolean checkboxes only) is rendered:
+
+IMPORTANT: todo - wip
+
+
 IMPORTANT: WIP ... this section
 
 
@@ -14,6 +51,11 @@ can be used instead, eg:
 
 [source,javascript]
 ----
+"description": {
+    "propertyLayout": {
+        "labelPosition": "TOP"
+    }
+}
 ----
 
 
@@ -23,7 +65,7 @@ can be used instead, eg:
 ====
 If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
 
-Instead, a default can be specified in `isis.properties`:
+Instead, a default can be specified using a xref:_ug_runtime_configuring-core[configuration property] in `isis.properties`:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
index a111f1f..14f3859 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
@@ -5,82 +5,23 @@
 :_imagesdir: images/
 
 
-
-
-IMPORTANT: WIP ... this section
-
-
-The `@MultiLine` annotation provides information about the carriage
-returns in a `String` property or action parameter, or for a
-string-based value type. It also implies a hint to the viewer that the
-widget to be used should be over multiple lines (eg a text area rather
-than a text field), with appropriate wrapping and/or scrollbars.
-
-More formally, the annotation indicates that:
-
-* the `String` property or parameter may contain carriage returns, and
-
-* (optionally) the typical number of such carriage returns (meaning
-the number of rows in the text area), and
-
-* (optionally) that the text should be wrapped (the default is that
-text is not wrapped).
-
-The syntax is:
-
-`@MultiLine([numberOfLines=&lt;typicalNumberOfCRs&gt;]
-        [,preventWrapping=&lt;false|true&gt;])`
+The `multiLine()` attribute specifies that the text field for a string property should span multiple lines.  It is ignored for other property types.  The attribute is also supported for xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[parameters].
 
 For example:
 
 [source,java]
 ----
 public class BugReport {
-    @MultiLine(numberOfLines=10)
+    @PropertyLayout(
+        numberOfLines=10
+    )
     public String getStepsToReproduce() { ... }
     public void setStepsToReproduce(String stepsToReproduce) { ... }
     ...
 }
 ----
 
-Here the `stepsToReproduce` may be displayed in a text area of 10 rows,
-with no wrapping. A horizontal scrollbar may appear if the number of
-characters on any given row exceeds the width.
-
-Another example:
-
-[source,java]
-----
-public class Email {
-    @MultiLine(numberOfLines=20, preventWrapping=false)
-    public String getBody() { ... }
-    public void setBody(String body) { ... }
-    ...
-}
-----
-
-Here the body should be displayed in a text area of 20 rows, with
-wrapping.
-
-If the annotation is combined with the `@TypicalLength`, then the
-expected width of the text area in the user interface will be determined
-by the value of the typical length divided by the number of specified
-lines. For example:
-
-[source,java]
-----
-public class Email {
-    @MultiLine(numberOfLines=20, preventWrapping=false)
-    @TypicalLength(800)
-    public String getBody() { ... }
-    public void setBody(String body) { ... }
-    ...
-}
-----
-
-Here the body will (likely be) displayed in a text area of 20 rows, with
-40 columns.
-
+Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
 
 
 
@@ -89,4 +30,15 @@ can be used instead, eg:
 
 [source,javascript]
 ----
+"stepsToReproduce": {
+    "propertyLayout": {
+        "numberOfLines": 10
+    }
+}
 ----
+
+
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
index e36298e..c0fcc3e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
@@ -6,21 +6,44 @@
 
 
 
+The `maxLength()` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  The attribute It is ignored if applied to properties of any other type.  This attribute can also be applied to xref:_ug_reference-annotations_manpage-Parameter_maxLength[parameters].
 
 
-IMPORTANT: WIP ... this section
-
-The `@MaxLength` annotation indicates the maximum number of characters that the user may enter into a `String` property, or a `String` parameter in an action, or for a string-based value type. It is ignored if applied to any other type.
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] will in any case need to be specified.  Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
 
 For example:
 
 [source,java]
 ----
 public class Customer {
-    @MaxLength(30)
+    @javax.jdo.annotations.Column(length=30)
     public String getFirstName() { ... }
     public void setFirstName(String firstName) { ... }
     ...
 }
 ----
 
+In this case there is therefore no need for the `@Property#maxLength()` attribute.
+
+
+
+== Non-persistent properties
+
+Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model).  For these non persistable properties the `maxLength()` attribute is still required.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotation.NotPersistent                    // <1>
+    @Property(maxLength=100)
+    public String getFullName() { ... }                    // <2>
+    public void setFullName(String fullName) { ... }       // <3>
+    ...
+}
+----
+<1> a non persisted (derived) property
+<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<3> implementation would most likely parse the input and update the constituent parts
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
index 4f621e2..ca82b3a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
@@ -7,31 +7,40 @@
 
 
 
-IMPORTANT: WIP ... this section
+The `mustSatisfy()` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
+ The attribute is also supported on xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[parameters].
 
+[TIP]
+====
+The specification implementations can (of course) be reused between properties and xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[parameters].
+====
 
-The `@MustSatisfy` annotation allows validation to be applied to
-properties and parameters using an (implementation of a)
-`org.apache.isis.applib.spec.Specification` object.
+The `Specification` is consulted during validation, being passed the proposed value.  If the proposed value fails, then the value returned is the used as the invalidity reason.
 
 For example:
 
 [source,java]
 ----
+public class StartWithCapitalLetterSpecification
+        extends AbstractSpecification<String> {            // <1>
+    public String satisfiesSafely(String proposed) {
+        return "".equals(proposed)
+            ? "Empty string"
+            : !Character.isUpperCase(proposed.charAt(0))
+                ? "Does not start with a capital letter"
+                : null;
+    }
+}
 public class Customer {
     @MustSatisfy(StartWithCapitalLetterSpecification.class)
     public String getFirstName() { ... }
     ...
 }
 ----
+<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values.  The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
 
 
-The `Specification` is consulted during validation, being passed the proposed value.
 
 
-[TIP]
-====
-Can also specify on property, so the specification class can be reused.
-====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
index 2ae964b..7ccbbd1 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
@@ -8,6 +8,139 @@
 
 
 
+By default, Apache Isis assumes that all properties of an domain object or view model are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:_ug_reference-annotations_manpage-Parameter_optionality[parameters].
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] should be specified. Isis can infer the maxLength directly from the equivalent @Column#length() annotation.
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] will in any case need to be specified.  Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowNulls()` annotation/attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotations.Column(allowNulls="true")
+    public String getMiddleInitial() { ... }
+    public void setMiddleInitial(String middleInitial) { ... }
+    ...
+}
+----
+
+In this case there is no need for the `@Property#optionality()` attribute.
+
+
+== Mismatched defaults
+
+If the `@Column#allowNulls()` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Isis' defaults and JDO's defaults differ.  Specifically, Isis always assumes properties are mandatory, whereas JDO specifies that primitives are mandatory, but all reference types are optional.
+
+When Isis initializes it checks for these mismatches during its metamodel validation phase, and will fail to boot ("fail-fast") if there is a mismatch.  The fix is usually to add the `@Column#allowsNulls()` annotation/attribute.
+
+
+== Superclass inheritance type
+
+There is one case (at least) it may be necessary to annotate the property with both `@Column#allowsNull` and also `@Property#optionality()`.  If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using `javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE`), then JDO requires that the property is annotated as `@Column#allowsNull="true"`: its value will be not defined for other subclasses.
+
+In this case we therefore require both annotations.
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public abstract class PaymentMethod {
+    ...
+}
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
+public class CreditCardPaymentMethod extends PaymentMethod {
+    private String cardNumber;
+    @javax.jdo.annotations.Column(allowNulls="true")
+    @Property(optionality=Optionality.MANDATORY)
+    public String getCardNumber() { return this.cardNumber; }
+    public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
+    ...
+}
+----
+
+Alternatively, you could rely on the fact that Isis never looks at fields (whereas JDO does) and move the JDO annotation to the field:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
+public class CreditCardPaymentMethod extends PaymentMethod {
+    @javax.jdo.annotations.Column(allowNulls="true")
+    private String cardNumber;
+    public String getCardNumber() { return this.cardNumber; }
+    public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
+    ...
+}
+----
+
+However this at first glance this might be read as eing that the property is optional whereas Isis' default (required) applies.  Also, in the future Isis may be extended to support reading annotations from fields.
+
+
+
+== Non-persistent properties
+
+Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model).  For these non persistable properties the `optionality()` attribute is still required.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotation.NotPersistent                    // <1>
+    @Property(optionality=Optionality.OPTIONAL)
+    public String getFullName() { ... }                    // <2>
+    public void setFullName(String fullName) { ... }       // <3>
+    ...
+}
+----
+<1> a non persisted (derived) property
+<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<3> implementation would most likely parse the input and update the constituent parts
+
+
+[TIP]
+====
+The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero).  If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
+====
+
+The values for the attribute are:
+
+- `OPTIONAL` +
++
+The parameter is optional
+
+- `MANDATORY` +
++
+The parameter is mandatory
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named = "Quantity")
+            final int quantity,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            @ParameterLayout(named = "Special Instructions")
+            final String instr) {
+        ...
+    }
+    ...
+}
+----
+
+
+
+
+
+
+
+
 
 By default, the system assumes that all properties of an object are required, and therefore will not let the user save a new object unless a value has been specified for each property. Similarly, by default, the system assumes that all parameters in an action are required and will not let the user execute that action unless values have been specified for each parameter.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regex.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regex.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regex.adoc
deleted file mode 100644
index 65a1f4f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regex.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_regex]]
-= Regex
-: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 `@RegEx` annotation may be applied to any string property, or to any
-parameter within an action method. It can also be applied to any
-string-based value type. It serves both to validate and potentially to
-normalise the format of the input. `@Regex` is therefore similar in use
-to `@Mask` <!--(see ?)--> but provides more flexibility.
-
-The syntax is:
-
-`@RegEx(validation = &quot;regEx string&quot;,
-        format = &quot;regEx string&quot;, caseSensitive =
-        &lt;true|false&gt;)`
-
-Only the first parameter is required; the `format` defaults to "no
-formatting", and `caseSensitive` defaults to false.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
-    public String getEmail() {}
-    ...
-}
-----
-
-
-
-== `regexPattern()`
-
-IMPORTANT: WIP ... this section
-
-
-
-== `regexPatternFlags()`
-
-IMPORTANT: WIP ... this section
-
-
-
-== `regexPatternReplacement()`
-
-IMPORTANT: WIP ... this section
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
new file mode 100644
index 0000000..73e4135
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
@@ -0,0 +1,28 @@
+[[_ug_reference-annotations_manpage-Property_regexPattern]]
+= `regexPattern()`
+: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 `regexPattern()` attribute validates the contents of any string property with respect to a regular expression pattern. It is ignored if applied to properties of any other type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Parameter_regexPattern[parameters].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @Property(
+        regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+        regexPatternFlags=Pattern.CASE_INSENSITIVE
+    )
+    public String getEmail() { ... }
+}
+----
+
+
+
+The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern.  The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2af55a0a/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index fe1fbd1..b423353 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -168,7 +168,7 @@
         body div#toc.toc2 {
             position: fixed;
             left: auto;
-            padding-top: 80px;
+            padding-top: 60px;
             z-index: auto;
             background-color: white;
             border-left-color: #eee;