You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/31 07:10:38 UTC
[02/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
new file mode 100644
index 0000000..0c867ef
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
@@ -0,0 +1,143 @@
+[[_rgant-Property]]
+= `@Property`
+: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 `@Property` annotation applies to properties collecting together all domain semantics within a single annotation.
+
+It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
+
+
+
+.`@Property` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-Property_domainEvent[`domainEvent()`]
+|subtype of `PropertyDomainEvent` +
+(`PropertyDomainEvent.Default`)
+|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
+
+
+|xref:rgant.adoc#_rgant-Property_editing[`editing()`]
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
+(`AS_CONFIGURED`)
+|whether a property can be modified or cleared from within the UI
+
+
+|xref:rgant.adoc#_rgant-Property_fileAccept[`fileAccept()`]
+|Media type or file extension
+|Hints the files to be uploaded to a xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+ or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]. +
+ +
+Note that this does not prevent the user from uploading some other file type; rather it merely defaults the file type in the file open dialog.
+
+
+|xref:rgant.adoc#_rgant-Property_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
+
+
+|xref:rgant.adoc#_rgant-Property_maxLength[`maxLength()`]
+|
+|maximum number of characters for string parameters; ignored otherwise +
+
+In many/most cases you should however use xref:rgant.adoc#_rgant-Column[`@Column#length()`]
+
+
+|xref:rgant.adoc#_rgant-Property_mustSatisfy[`mustSatisfy()`]
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
+
+
+|xref:rgant.adoc#_rgant-Property_notPersisted[`notPersisted()`]
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
+
+
+|xref:rgant.adoc#_rgant-Property_optionality[`optionality()`]
+|
+|specifies a property is optional rather than mandatory +
+
+In many/most cases you should however use xref:rgant.adoc#_rgant-Column[`@Column#allowsNull()`]
+
+
+
+|xref:rgant.adoc#_rgant-Property_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
+
+
+|===
+
+
+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(allowsNull="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
+
+
+
+
+
+[TIP]
+====
+The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method. This is specifically
+so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
+====
+
+
+include::_rgant-Property_domainEvent.adoc[leveloffset=+1]
+include::_rgant-Property_editing.adoc[leveloffset=+1]
+include::_rgant-Property_fileAccept.adoc[leveloffset=+1]
+include::_rgant-Property_hidden.adoc[leveloffset=+1]
+include::_rgant-Property_maxLength.adoc[leveloffset=+1]
+include::_rgant-Property_mustSatisfy.adoc[leveloffset=+1]
+include::_rgant-Property_notPersisted.adoc[leveloffset=+1]
+include::_rgant-Property_optionality.adoc[leveloffset=+1]
+include::_rgant-Property_regexPattern.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
new file mode 100644
index 0000000..6ed862f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
@@ -0,0 +1,142 @@
+[[_rgant-PropertyLayout]]
+= `@PropertyLayout`
+: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 `@PropertyLayout` annotation applies to properties collecting together all UI hints within a single annotation.
+
+
+The table below summarizes the annotation's attributes.
+
+.`@PropertyLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`cssClass()`]
+|Any string valid as a CSS class
+|the css class that a property should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`describedAs()`]
+|String
+|description of this property, eg to be rendered in a tooltip.
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition()`]
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Defaults is `LEFT`, unless xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine`] in which case `TOP`. The value `RIGHT` is only supported for boolean properties. +
+
+It is also possible to change the default through a xref:rgcfg.adoc#__rgcfg_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine()`]
+|Positive integer
+|for string properties, render as a text area over multiple lines. +
+
+If set > 1, then xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_named[`named()`]
+|String
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|`namedEscaped()`
+|`true`, `false` +
+(`true`)
+|whether to HTML escape the name of this property.
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|`true`, `false` +
+(`false`)
+|for date properties only, render the date as one day prior to the actually stored date.
+
+
+|xref:rgant.adoc#_rgant-PropertyLayout_typicalLength[`typicalLength()`]
+|Positive integer.
+|the typical entry length of a field, use to determine the optimum width for display
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(
+ cssClass="x-key",
+ named="Description of this <i>item</i>",
+ namedEscaped=false,
+ describedAs="What needs to be done",
+ labelPosition=LabelPosition.LEFT,
+ typicalLength=80
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
+
+
+
+As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "cssClass": "x-key",
+ "describedAs": "What needs to be done",
+ "labelPosition": "LEFT",
+ "typicalLength": 80
+ }
+}
+----
+
+
+
+
+[TIP]
+====
+The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-Property[`@Property`]) that can also be applied to the field, rather than the getter method. This is specifically
+so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
+====
+
+
+
+include::_rgant-PropertyLayout_cssClass.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_describedAs.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_labelPosition.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_multiLine.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_named.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_renderedAsDayBefore.adoc[leveloffset=+1]
+include::_rgant-PropertyLayout_typicalLength.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
new file mode 100644
index 0000000..a32476b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
@@ -0,0 +1,36 @@
+[[_rgant-PropertyLayout_cssClass]]
+= `cssClass()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property. xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+
+This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(cssClass="x-key")
+ public LocalDate getDueBy() { ... }
+}
+----
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dueBy": {
+ "propertyLayout": { "cssClass": "x-key" }
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
new file mode 100644
index 0000000..f61e807
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
@@ -0,0 +1,33 @@
+[[_rgant-PropertyLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `describedAs()` attribute is used to provide a short description of the property to the user. In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @DescribedAs("The name that the customer has indicated that they wish to be " +
+ "addressed as (e.g. Johnny rather than Jonathan)")
+ public String getFirstName() { ... }
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"firstName:" {
+ "propertyLayout": {
+ "describedAs": "The name that the customer has indicated that they wish to be addressed as (e.g. Johnny rather than Jonathan)"
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
new file mode 100644
index 0000000..4366517
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
@@ -0,0 +1,78 @@
+[[_rgant-PropertyLayout_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `hidden()` attribute indicates where (in the UI) the property should be hidden from the user. This attribute can also be applied to xref:rgant.adoc#_rgant-Action_hidden[actions] and xref:rgant.adoc#_rgant-Collection_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the property can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @PropertyLayout(
+ hidden=Where.ALL_TABLES
+ )
+ public int getInternalId() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The property should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The property should be hidden when displayed within an object form.
+
+* `Where.PARENTED_TABLES` +
++
+The property should be hidden when displayed as a column of a table within a parent object's collection.
+
+* `Where.STANDALONE_TABLES` +
++
+The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
+
+* `Where.ALL_TABLES` +
++
+The property should be hidden 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` +
++
+The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
+
+For example, if a property is annotated with xref:rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
+tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
+
+
+[NOTE]
+====
+The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
+====
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"internalId": {
+ "propertyLayout": { "hidden": "ALL_TABLES" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
new file mode 100644
index 0000000..98a64d4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
@@ -0,0 +1,96 @@
+[[_rgant-PropertyLayout_labelPosition]]
+= `labelPosition()`
+: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 `labelPosition()` attribute determines the positioning of labels for properties. This attribute can also be specified for xref:rgant.adoc#_rgant-ParameterLayout_labelPosition[parameters].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:rgant.adoc#_rgant-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.
+
+It is also possible to suppress the label altogether, using `NONE`.
+
+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:ugvw.adoc#[Wicket viewer]), we can look at the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] that happens to have examples of most of these various label positions.
+
+The default `LEFT` label positioning is used by the `cost` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png"]
+
+
+The `TOP` label positioning is used by the `category` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png"]
+
+
+Labels are suppressed, using `NONE`, for the `subcategory` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png"]
+
+
+The todoapp's `complete` (boolean) property renders the label to the LEFT (the default):
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png"]
+
+Moving the label to the `RIGHT` looks like:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png"]
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "labelPosition": "TOP"
+ }
+}
+----
+
+
+
+[TIP]
+.Specifying a default setting for label positions
+====
+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 using a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] in `isis.properties`:
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=TOP
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+If these are not present then Apache 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.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
new file mode 100644
index 0000000..0599c47
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
@@ -0,0 +1,44 @@
+[[_rgant-PropertyLayout_multiLine]]
+= `multiLine()`
+: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 `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:rgant.adoc#_rgant-ParameterLayout_multiLine[parameters].
+
+For example:
+
+[source,java]
+----
+public class BugReport {
+ @PropertyLayout(
+ numberOfLines=10
+ )
+ public String getStepsToReproduce() { ... }
+ public void setStepsToReproduce(String stepsToReproduce) { ... }
+ ...
+}
+----
+
+Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"stepsToReproduce": {
+ "propertyLayout": {
+ "numberOfLines": 10
+ }
+}
+----
+
+
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:rgant.adoc#_rgant-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/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
new file mode 100644
index 0000000..69e687c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
@@ -0,0 +1,51 @@
+[[_rgant-PropertyLayout_named]]
+= named()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `named()` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(
+ named="Description of this <i>item</i>",
+ namedEscaped=false
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "named": "Description of this <i>item</i>",
+ "namedEscaped": false
+ }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
new file mode 100644
index 0000000..cab45f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
@@ -0,0 +1,45 @@
+[[_rgant-PropertyLayout_renderedAsDayBefore]]
+= `renderedAsDayBefore()`
+: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 `renderedAsDayBefore()` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for properties of other types. This attribute is also supported for xref:rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[parameters].
+
+This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time. In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
+
+However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
+
+This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
+
+For example:
+
+[source,java]
+----
+public class Tenancy {
+ public LocalDate getStartDate() { ... }
+ public void setStartDate(LocalDate startDate) { ... }
+ @PropertyLayout(
+ renderedAsDayBefore=true
+ )
+ public LocalDate getEndDate() { ... }
+ public void setEndDate(LocalDate EndDate) { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"endDate": {
+ "propertyLayout": {
+ "renderedAsDayBefore": true
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
new file mode 100644
index 0000000..647957b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
@@ -0,0 +1,25 @@
+[[_rgant-PropertyLayout_typicalLength]]
+= `typicalLength()`
+: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 `typicalLength()` attribute indicates the typical length of a string property. It is ignored for properties of other types. The attribute is also supported for xref:rgant.adoc#_rgant-ParameterLayout_typicalLength[parameters].
+
+The information is intended as a hint to the UI to determine the space that should be given to render a particular string property. That said, note that the xref:ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=30)
+ @ParameterLayout(typicalLength=20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
new file mode 100644
index 0000000..9be1d74
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
@@ -0,0 +1,154 @@
+[[_rgant-Property_domainEvent]]
+= `domainEvent()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's properties, the events that are fired are:
+
+* hide phase: to check that the property is visible (has not been hidden)
+* disable phase: to check that the property is usable (has not been disabled)
+* validate phase: to check that the property's arguments are valid (to modify/clear its value)
+* pre-execute phase: before the modification of the property
+* post-execute: after the modification of the property
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+By default the event raised is `PropertyDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Property()
+ public LocalDate getDueBy() { ... }
+ ...
+}
+----
+
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+ xref:rgant.adoc#_rgant-Action_domainEvent[actions] and
+ xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DueByChangedEvent extends PropertyDomainEvent<ToDoItem, LocalDate> { } // <1>
+ @Property(domainEvent=ToDoItem.DueByChangedEvent)
+ public LocalDate getDueBy() { ... }
+ ...
+}
+----
+<1> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+[NOTE]
+====
+As of `1.10.0` the framework provides no-arg constructor and will initialize the domain event using (non-API) setters
+rather than through the constructor. This substantially reduces the boilerplate.
+====
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(PropertyDomainEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DueByChangedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the property being modified
+* steps to perform after the property has been modified.
+
+The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(PropertyDomainEvent ev) {
+ switch(ev.getEventPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the property
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the property
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if proposed property value is invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+
+
+
+== Default, Doop and Noop events
+
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
+wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
new file mode 100644
index 0000000..d914c48
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
@@ -0,0 +1,43 @@
+[[_rgant-Property_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/
+
+
+The `editing()` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for xref:rgant.adoc#_rgant-Collection_editing[collections], and can also be specified for the xref:rgant.adoc#_rgant-DomainObject_editing[domain object].
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the property cannot be modified directly.
+
+Whether a property is enabled or disabled depends upon these factors:
+
+* whether the domain object has been configured as immutable through the xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
+
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`. If set to `false`, then the object's properties (and collections) are _not_ editable
+
+* else, then the value of the `@Property(editing=...)` attribute itself
+
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
+
+
+Thus, to make a property read-only even if the object would otherwise be editable, use:
+
+[source,java]
+----
+public class Customer {
+ @Property(
+ editing=Editing.DISABLED,
+ editingDisabledReason="The credit rating is derived from multiple factors"
+ )
+ public int getInitialCreditRating(){ ... }
+ public void setInitialCreditRating(int initialCreditRating) { ... }
+}
+----
+
+[NOTE]
+====
+To reiterate, it is _not_ possible to enable editing for a property if editing has been disabled at the object-level.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
new file mode 100644
index 0000000..d73e923
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
@@ -0,0 +1,35 @@
+[[_rgant-Property_fileAccept]]
+= `fileAccept()`
+: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 `fileAccept()` attribute applies only to xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] parameters, indicating the type of file to accept when
+uploading a new value. The attribute is also supported on xref:rgant.adoc#_rgant-Parameter_fileAccept[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ScannedDocument {
+
+ @Property(fileAccept="image/*") // <1>
+ private Blob scannedImage;
+ // getters and setters omitted
+
+}
+----
+<1> as per link:http://www.w3schools.com/tags/att_input_accept.asp[reference docs], either a media type (such as
+`image/*`) or a file type extension (such as `.png`).
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
new file mode 100644
index 0000000..4384bc2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
@@ -0,0 +1,66 @@
+[[_rgant-Property_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+Properties can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:rgant.adoc#_rgant-CollectionLayout_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rgant.adoc#_rgant-Property_hidden[`@Property#hidden()`] to hide an action at the domain layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+====
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Property(hidden=Where.EVERYWHERE)
+ public int getInternalId() { ... }
+ @Property(hidden=Where.ALL_TABLES)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The property should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The property should be hidden when displayed within an object form.
+
+* `Where.PARENTED_TABLES` +
++
+The property should be hidden when displayed as a column of a table within a parent object's collection.
+
+* `Where.STANDALONE_TABLES` +
++
+The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
+
+* `Where.ALL_TABLES` +
++
+The property should be hidden 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` +
++
+The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
+
+For example, if a property is annotated with xref:rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
+tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
+
+
+[NOTE]
+====
+The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
new file mode 100644
index 0000000..37b93ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
@@ -0,0 +1,49 @@
+[[_rgant-Property_maxLength]]
+= `maxLength()`
+: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 `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:rgant.adoc#_rgant-Parameter_maxLength[parameters].
+
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified. Apache Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @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/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
new file mode 100644
index 0000000..e88ca71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
@@ -0,0 +1,57 @@
+[[_rgant-Property_mustSatisfy]]
+= `mustSatisfy()`
+: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 `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:rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
+
+[TIP]
+====
+The specification implementations can (of course) be reused between properties and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
+====
+
+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 {
+ @Property(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".
+
+
+It is also possible to provide translatable reasons. Rather than implement `Specification`, instead implement `Specification2` which defines the API:
+
+[source,java]
+----
+public interface Specification2 extends Specification {
+ public TranslatableString satisfiesTranslatable(Object obj); // <1>
+}
+----
+<1> Return `null` if specification satisfied, otherwise the reason as a translatable string
+
+With `Specification2` there is no need to implement the inherited `satifies(Object)`; that method will never be called.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
new file mode 100644
index 0000000..7bde4bf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
@@ -0,0 +1,61 @@
+[[_rgant-Property_notPersisted]]
+= `notPersisted()`
+: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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:rgant.adoc#_rgant-Collection_notPersisted[collections].
+
+
+[WARNING]
+====
+This annotation does _not_ specify that a property is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the property for this.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Property(notPersisted=true)
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
+ ...
+}
+----
+
+Historically this annotation also hinted as to whether the property's value contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a property is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Property(notPersisted=true) // <1>
+ @javax.jdo.annotations.NotPersistent // <2>
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
+ ...
+}
+----
+<1> ignored by Apache Isis
+<2> ignored by JDO/DataNucleus
+
+
+
+
+
+Alternatively, if the property is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Order {
+ public Order getPreviousOrder() {...}
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
new file mode 100644
index 0000000..1713bb4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
@@ -0,0 +1,134 @@
+[[_rgant-Property_optionality]]
+= `optionality()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+
+By default, 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:rgant.adoc#_rgant-Parameter_optionality[parameters].
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rgant.adoc#_rgant-Column[`@Column`] should be specified. Apache 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:rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified. Apache Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowsNull()` annotation/attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(allowsNull="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#allowsNull()` 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 Apache 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#allowsNull()` 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(allowsNull="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 Apache 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(allowsNull="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 Apache 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 simply `OPTIONAL` or `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) {
+ ...
+ }
+ ...
+}
+----
+
+
+[NOTE]
+====
+It is also possible to specify optionality using xref:rgant.adoc#_rgant_Nullable[`@Nullable`] annotation.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
new file mode 100644
index 0000000..db0ae15
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
@@ -0,0 +1,47 @@
+[[_rgant-Property_publishing]]
+= `publishing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+The `publishing()` attribute determines whether and how a property edit is published via the registered implementation
+of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. This attribute is also supported
+for xref:rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects are
+published as events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
+whether property edits are published as events.
+
+A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
+The default value for the attribute is `AS_CONFIGURED`, meaning that the
+xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.properties` is used to
+determine the whether the property is published:
+
+* `all` +
++
+all property edits are published
+
+* `none` +
++
+no property edits are published
+
+If there is no configuration property in `isis.properties` then publishing is automatically enabled.
+
+This default can be overridden on an property-by-property basis; if `publishing()` is set to `ENABLED` then the
+property edit is published irrespective of the configured value; if set to `DISABLED` then the property edit is
+_not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Property(publishing=Publishing.ENABLED) // <1>
+ public int getQuantity() { ... }
+ public void setQuantity(int quantity) { ... }
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
new file mode 100644
index 0000000..279cdce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
@@ -0,0 +1,35 @@
+[[_rgant-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/
+
+
+
+There are three attributes related to enforcing regular expressions:
+
+* 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:rgant.adoc#_rgant-Parameter_regexPattern[parameters].
+
+* The `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)`.
+
+* The related `regexPatternReplacement()` attribute specifies the error message to show if
+the provided argument does not match the regex pattern.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Property(
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE,
+ regexPatternReplacement = "Must be valid email address (containing a '@') symbol" // <1>
+ )
+ public String getEmail() { ... }
+}
+----
+<1> Note that there is currently no i18n support for this phrase.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
new file mode 100644
index 0000000..7372d56
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
@@ -0,0 +1,50 @@
+[[_rgant-RequestScoped]]
+= `@RequestScoped` (`javax`)
+: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 `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:rgant.adoc#_rgant-DomainService[domain service] should be request-scoped rather than a singleton.
+
+Although Apache Isis does not (currently) leverage CDI, the semantics are the same as request-scoped service; a new instance is created for each HTTP request, reserved for the exclusive use of all objects interacted with during that request.
+
+One of the built-in domain services that uses this annotation is xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects. Here is the full source code of this service is:
+
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.DOMAIN
+)
+@RequestScoped
+public class Scratchpad {
+ private final Map<Object, Object> userData = Maps.newHashMap(); // <1>
+ @Programmatic
+ public Object get(Object key) {
+ return userData.get(key); // <2>
+ }
+ @Programmatic
+ public void put(Object key, Object value) {
+ userData.put(key, value); // <3>
+ }
+ @Programmatic
+ public void clear() {
+ userData.clear(); // <4>
+ }
+}
+----
+<1> Provides a mechanism for each object being acted upon to pass data to the next object.
+<2> Obtain user-data, as set by a previous object being acted upon.
+<3> Set user-data, for the use of a subsequent object being acted upon.
+<4> Clear any user data.
+
+
+The vast majority of domain services in Apache Isis tend to be singletons (which requires no special annotation); but as you can see setting up request-scoped services is very straightforward.
+
+[NOTE]
+====
+Behind the covers Apache Isis creates a (singleton) wrapper for the domain service; the individual request-scoped instances are held in a thread-local of this wrapper. One consequence of this implementation is that request-scoped methods should not be marked as `final`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
new file mode 100644
index 0000000..0b92462
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
@@ -0,0 +1,62 @@
+[[_rgant-Title]]
+= `@Title`
+: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 `@Title` annotation is used to indicate which property or properties make up the object title. If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
+
+For example:
+
+[source,java]
+----
+public void Customer {
+ @Title(sequence="1.0")
+ public String getLastName() { ... } // <1>
+ ...
+ @Title(sequence="1.5", prepend=", ")
+ public String getFirstName() { ... }
+ ...
+ @Title(sequence="1.7", append=".")
+ public String getMidInitial() { ... }
+ ...
+}
+----
+<1> backing field and setters omitted
+
+could be used to create names of the style "Bloggs, Joe K."
+
+It is also possible to annotate reference properties; in this case the
+title will return the title of the referenced object (rather than, say,
+its string representation).
+
+An additional convention for `@Title` properties is that they are hidden
+in tables (in other words, it implies `@Hidden(where=Where.ALL_TABLES)`.
+For viewers that support this annotation (for example, the Wicket
+viewer), this convention excludes any properties whose value is already
+present in the title column. This convention can be overridden using
+`@Hidden(where=Where.NOWHERE)`.
+
+== Lombok support
+
+If xref:dg.adoc#_dg_ide_project-lombok[Project Lombok] is being used, then `@Title` can be specified on the backing field.
+
+For example:
+
+[source,java]
+----
+public void Customer {
+ @Title(sequence="1.0")
+ @Getter @Setter
+ private String name;
+
+ @Title(sequence="1.5", prepend=", ")
+ @Getter @Setter
+ private String firstName;
+
+ @Title(sequence="1.7", append=".")
+ @Getter @Setter
+ private String midInitial;
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
new file mode 100644
index 0000000..000586c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
@@ -0,0 +1,50 @@
+[[_rgant-ViewModel]]
+= `@ViewModel`
+: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 `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model.
+
+View models are not persisted to the database, instead their state is encoded within their identity (ultimately
+represented in the URL). As such, view models are immutable.
+
+For example:
+
+[source,java]
+----
+@ViewModel
+public class MyViewModel {
+ public MyViewModel() {} // <1>
+ ...
+}
+----
+<1> must have a no-arg constructor for subsequent "recreation" by the framework.
+
+
+To instantiate a view model, you can either instantiate directly using its constructor, or indirectly using `DomainObjectContainer#newTransientInstance()`. If you use the former, also programmatically call `DomainObjectContainer#injectServicesInto(...)` to ensure that any dependencies are injected into the service.
+
+
+[TIP]
+====
+Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is for view models that implement `ViewModel` interface and can be safely ignored.
+====
+
+
+The view model's memento will be derived from the value of the view model object's properties. Any xref:rgant.adoc#_rgant-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] properties. Properties that are merely xref:rgant.adoc#_rgant-Property_hidden[hidden] _are_ included in the memento.
+
+Only properties supported by the configured xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
+
+(As of 1.8.0) there are some limitations:
+* view models cannot hold collections other view models (simple properties _are_ supported, though)
+* collections (of either view models or entities) are ignored.
+
+
+[WARNING]
+====
+The `@ViewModel` does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the xref:rgcfg.adoc#__rgcfg_configuring-core_metamodel-validation[`explicitObjectType`] configuration property.
+
+Instead, use xref:rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] with `Nature.VIEW_MODEL`, and specify xref:rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`].
+====