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 2016/03/29 19:43:16 UTC
[20/23] isis-site git commit: ISIS-1287: updating docs for 1.12.0
http://git-wip-us.apache.org/repos/asf/isis-site/blob/09aecf2c/content/guides/rgant.html
----------------------------------------------------------------------
diff --git a/content/guides/rgant.html b/content/guides/rgant.html
index b7a7328..889c4a2 100644
--- a/content/guides/rgant.html
+++ b/content/guides/rgant.html
@@ -4086,14 +4086,610 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</tr>
</table>
</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_rgant-CollectionLayout">6. <code>@CollectionLayout</code></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The <code>@CollectionLayout</code> annotation applies to collections, collecting together all UI hints within a single
+annotation. It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.</p>
+</div>
+<div class="paragraph">
+<p>The table below summarizes the annotation’s attributes.</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 11. <code>@CollectionLayout</code> attributes</caption>
+<colgroup>
+<col style="width: 25%;">
+<col style="width: 25%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Attribute</th>
+<th class="tableblock halign-left valign-top">Values (default)</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_cssClass"><code>cssClass()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Any string valid as a CSS class</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>the css class that a collection should have, to allow more targetted styling in <a href="rgcfg.html#_rgcfg_application-specific_application-css"><code>application.css</code></a></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_defaultView"><code>defaultView()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>table</code>, <code>excel</code>, <code>calendar</code>, <code>map</code>, …​</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>Which view is selected by default, if multiple views are available.</p>
+</div>
+<div class="paragraph">
+<p>See (non-ASF) <a href="http://isisaddons.org">Isis Addons</a> for further views.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_describedAs"><code>describedAs()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">String.</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>description of this collection, eg to be rendered in a tooltip.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_hidden"><code>hidden()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>EVERYWHERE</code>, <code>OBJECT_FORMS</code>, <code>NOWHERE</code><br>
+(<code>NOWHERE</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>indicates where (in the UI) the collection should be hidden from the user.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_named">named()</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">String.</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>to override the name inferred from the collection’s name in code.<br></p>
+</div>
+<div class="paragraph">
+<p>A typical use case is if the desired name is a reserved Java keyword, such as <code>default</code> or <code>package</code>.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">namedEscaped()</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code> (<code>true</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>whether to HTML escape the name of this property.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_paged"><code>paged()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Positive integer</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>the page size for instances of this class when rendered within a table.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_render"><code>render()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>EAGERLY</code>, <code>LAZILY</code><br>
+(<code>LAZILY</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>whether the collection should be (eagerly) rendered open or (lazily) rendered closed</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgant-CollectionLayout_sortedBy"><code>sortedBy()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Subclass of <code>java.util.Comparator</code> for element type</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>indicates that the elements in the <code>java.util.SortedSet</code> collection should be sorted according to a specified <code>Comparator</code> rather than their natural sort order.</p>
+</div></div></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ cssClass=<span class="string"><span class="delimiter">"</span><span class="content">x-key</span><span class="delimiter">"</span></span>,
+ named=<span class="string"><span class="delimiter">"</span><span class="content">Todo items that are <i>dependencies</i> of this item.</span><span class="delimiter">"</span></span>,
+ namedEscaped=<span class="predefined-constant">false</span>,
+ describedAs=<span class="string"><span class="delimiter">"</span><span class="content">Other todo items that must be completed before this one</span><span class="delimiter">"</span></span>,
+ labelPosition=LabelPosition.LEFT,
+ render=EAGERLY)
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the <code>@CollectionLayout</code> annotation, a dynamic layout using <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a> file can be specified; for example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">cssClass</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">x-key</span><span class="delimiter">"</span></span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">named</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">Todo items that are <i>dependencies</i> of this item.</span><span class="delimiter">"</span></span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">namedEscaped</span><span class="delimiter">"</span></span>: <span class="predefined-constant">false</span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">describedAs</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">Other todo items that must be completed before this one</span><span class="delimiter">"</span></span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">labelPosition</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">LEFT</span><span class="delimiter">"</span></span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">render</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">EAGERLY</span><span class="delimiter">"</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The annotation is one of a handful (others including <a href="#_rgant-Collection"><code>@Collection</code></a>, <a href="#_rgant-Property"><code>@Property</code></a> and <a href="#_rgant-PropertyLayout"><code>@PropertyLayout</code></a>) that can also be applied to the field, rather than the getter method. This is specifically
+so that boilerplate-busting tools such as <a href="https://projectlombok.org/">Project Lombok</a> can be used.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_cssClass">6.1. <code>cssClass()</code></h3>
+<div class="paragraph">
+<p>The <code>cssClass()</code> attribute can be used to render additional CSS classes in the HTML (a wrapping <code><div></code>) that represents the collection. <a href="rgcfg.html#_rgcfg_application-specific_application-css">Application-specific CSS</a> can then be used to target and adjust the UI representation of that particular element.</p>
+</div>
+<div class="paragraph">
+<p>This attribute can also be applied to <a href="#_rgant-DomainObjectLayout_cssClass">domain objects</a>, <a href="#_rgant-ViewModelLayout_cssClass">view models</a>, <a href="#_rgant-ActionLayout_cssClass">actions</a>, <a href="#_rgant-PropertyLayout_cssClass">properties</a> and <a href="#_rgant-ParameterLayout_cssClass">parameters</a>.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ cssClass=<span class="string"><span class="delimiter">"</span><span class="content">x-important</span><span class="delimiter">"</span></span>
+ )
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: { <span class="key"><span class="delimiter">"</span><span class="content">cssClass</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">x-important</span><span class="delimiter">"</span></span> }
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_defaultView">6.2. <code>defaultView()</code></h3>
+<div class="paragraph">
+<p>The <a href="ugvw.html">Wicket viewer</a> allows additional views to be configured to render collections of objects; at the time of writing thesee include the (non-ASF) (non-ASF) <a href="http://isisaddons.org">Isis Addons</a>' (non-ASF) <a href="http://github.com/isisaddons/isis-wicket-excel">excel</a> view, the <a href="http://github.com/isisaddons/isis-wicket-fullcalendar2">fullcalendar2</a> view, and the <a href="http://github.com/isisaddons/isis-wicket-gmap3">gmap3</a> view. If the objects to be rendered have the correct "shape", then the appropriate view will be made available. For example, objects with a date can be rendered using <code>calendar</code>; objects with locations can be rendered using <code>map</code>.</p>
+</div>
+<div class="paragraph">
+<p>The <code>defaultView()</code> attribute is used to select which of these views should be used by default for a given collection.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">BusRoute</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ defaultView=<span class="string"><span class="delimiter">"</span><span class="content">map</span><span class="delimiter">"</span></span>
+ )
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><BusStop> getStops() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">defaultView</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">map</span><span class="delimiter">"</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>This attribute takes precedence over any value for the <a href="#_rgant-CollectionLayout_render"><code>@CollectionLayout#render()</code></a> attribute. For example, if the
+<code>defaultView</code> attribute is defined to "table", then the table will be show even if <code>render</code> is set to <code>LAZILY</code>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_describedAs">6.3. <code>describedAs()</code></h3>
+<div class="paragraph">
+<p>The <code>describedAs()</code> attribute is used to provide a short description of the collection to the user. In the <a href="ugvw.html">Wicket viewer</a> it is displayed as a 'tool tip'.</p>
+</div>
+<div class="paragraph">
+<p>The <code>describedAs()</code> attribute can also be specified for <a href="#_rgant-PropertyLayout_describedAs">properties</a>, <a href="#_rgant-ActionLayout_describedAs">actions</a>, <a href="#_rgant-ParameterLayout_describedAs">parameters</a>, <a href="#_rgant-DomainObjectLayout_describedAs">domain objects</a> and <a href="#_rgant-ViewModelLayout_describedAs">view models</a>.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ describedAs=<span class="string"><span class="delimiter">"</span><span class="content">Other todo items that must be completed before this one</span><span class="delimiter">"</span></span>
+ )
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">describedAs</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">Other todo items that must be completed before this one</span><span class="delimiter">"</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_hidden">6.4. <code>hidden()</code></h3>
+<div class="paragraph">
+<p>The <code>hidden()</code> attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to <a href="#_rgant-ActionLayout_hidden">actions</a> and <a href="#_rgant-PropertyLayout_hidden">properties</a>.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>It is also possible to use <a href="#_rgant-Collection_hidden"><code>@Collection#hidden()</code></a> 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.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ hidden=Where.EVERYWHERE
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The acceptable values for the <code>where</code> parameter are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>Where.EVERYWHERE</code> or <code>Where.ANYWHERE</code><br></p>
+<div class="paragraph">
+<p>The collection should be hidden everywhere.</p>
+</div>
+</li>
+<li>
+<p><code>Where.ANYWHERE</code><br></p>
+<div class="paragraph">
+<p>Synonym for everywhere.</p>
+</div>
+</li>
+<li>
+<p><code>Where.OBJECT_FORMS</code><br></p>
+<div class="paragraph">
+<p>The collection should be hidden when displayed within an object form.</p>
+</div>
+</li>
+<li>
+<p><code>Where.NOWHERE</code><br></p>
+<div class="paragraph">
+<p>The collection should not be hidden.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The other values of the <code>Where</code> enum have no meaning for a collection.</p>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: { <span class="key"><span class="delimiter">"</span><span class="content">hidden</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">EVERYWHERE</span><span class="delimiter">"</span></span> }
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_named">6.5. <code>named()</code></h3>
+<div class="paragraph">
+<p>The <code>named()</code> attribute explicitly specifies the collection’s name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for <a href="#_rgant-ActionLayout_named">actions</a>, <a href="#_rgant-PropertyLayout_named">properties</a>, <a href="#_rgant-ParameterLayout_named">parameters</a>, <a href="#_rgant-DomainObjectLayout_named">domain objects</a>, <a href="#_rgant-ViewModelLayout_named">view models</a> and <a href="#_rgant-DomainServiceLayout_named">domain services</a>.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Following the <a href="http://en.wikipedia.org/wiki/Don%27t_repeat_yourself">don’t repeat yourself</a> 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.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>By default the name is HTML escaped. To allow HTML markup, set the related <code>namedEscaped()</code> attribute to <code>false</code>.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> {
+ <span class="annotation">@CollectionLayout</span>(
+ named=<span class="string"><span class="delimiter">"</span><span class="content">Todo items that are <i>dependencies</i> of this item</span><span class="delimiter">"</span></span>,
+ namedEscaped=<span class="predefined-constant">false</span>
+ )
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">named</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">Todo items that are <i>dependencies</i> of this item</span><span class="delimiter">"</span></span>,
+ <span class="key"><span class="delimiter">"</span><span class="content">namedEscaped</span><span class="delimiter">"</span></span>: <span class="predefined-constant">false</span>,
+ }
+}</code></pre>
+</div>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The framework also provides a separate, powerful mechanism for <a href="ugbtb.html#_ugbtb_i18n">internationalization</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_paged">6.6. <code>paged()</code></h3>
+<div class="paragraph">
+<p>The <code>paged()</code> attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to <a href="#_rgant-DomainObjectLayout_paged">domain objects</a> and <a href="#_rgant-ViewModelLayout_paged">view models</a>.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The <a href="ugvro.html">RestfulObjects viewer</a> currently does not support paging. The <a href="ugvw.html">Wicket viewer</a> <em>does</em> support paging, but note that the paging is performed client-side rather than server-side.</p>
+</div>
+<div class="paragraph">
+<p>We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+ <span class="annotation">@CollectionLayout</span>(paged=<span class="integer">15</span>)
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><OrderLine> getDetails() {...}
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>It is also possible to specify a global default for the page size of standalone collections, using the <a href="rgcfg.html#_rgcfg_configuring-core">configuration property</a> <code>isis.viewer.paged.parented</code>.</p>
+</div>
<div class="paragraph">
-<p>Unresolved directive in rgant.adoc - include::_rgant-Collectionlayout.adoc[leveloffset=+1]
-:leveloffset: +1</p>
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">details</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">paged</span><span class="delimiter">"</span></span>: <span class="integer">15</span>
+ }
+}</code></pre>
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_render">6.7. <code>render()</code></h3>
+<div class="paragraph">
+<p>The <code>render()</code> attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).</p>
</div>
-<h1 id="_rgant-Column" class="sect0"><code>@Column</code> (<code>javax.jdo</code>)</h1>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+ <span class="annotation">@CollectionLayout</span>(render=RenderType.EAGERLY)
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><LineItem> getDetails() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">details</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">render</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">EAGERLY</span><span class="delimiter">"</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Note that <a href="ugfun.html#_ugfun_how-tos_contributed-members">contributed collections</a> (which, under the covers are just action invocations against a domain service) are always rendered eagerly.</p>
+</div>
+<div class="paragraph">
+<p>Also, if a <a href="#_rgant-CollectionLayout_defaultView"><code>@CollectionLayout#defaultView()</code></a> attribute has been specified then that will take precedence over the value of the <code>render()</code> attribute.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rgant-CollectionLayout_sortedBy">6.8. <code>sortedBy()</code></h3>
+<div class="paragraph">
+<p>The <code>sortedBy()</code> attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> <span class="directive">implements</span> <span class="predefined-type">Comparable</span><ToDoItem> { <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">DependenciesComparator</span> <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="directive">implements</span> <span class="predefined-type">Comparator</span><ToDoItem> {
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> <span class="type">int</span> compare(ToDoItem p, ToDoItem q) {
+ <span class="keyword">return</span> ORDERING_BY_DESCRIPTION <i class="conum" data-value="3"></i><b>(3)</b>
+ .compound(Ordering.<ToDoItem>natural())
+ .compare(p, q);
+ }
+ }
+ <span class="annotation">@CollectionLayout</span>(sortedBy=DependenciesComparator.class) <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>the class has a natural ordering (implementation not shown)</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>declaration of the comparator class</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>ordering defined as being by the object’s <code>description</code> property (not shown), and then by the natural ordering of the class</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>specify the comparator to use</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>When the <code>dependencies</code> collection is rendered, the elements are sorted by the <code>description</code> property first:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/reference-annotations/CollectionLayout/sortedby-dependencies.png"><img src="images/reference-annotations/CollectionLayout/sortedby-dependencies.png" alt="sortedby dependencies" width="720px"></a>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Note that this screenshot shows an earlier version of the <a href="ugvw.html">Wicket viewer</a> UI (specifically, pre 1.8.0).</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.</p>
+</div>
+<div class="paragraph">
+<p>As an alternative to using the annotation, the dynamic <a href="ugfun.html#_ugfun_object-layout_dynamic"><code>.layout.json</code></a>
+can be used instead, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="javascript"><span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">collectionLayout</span><span class="delimiter">"</span></span>: {
+ <span class="key"><span class="delimiter">"</span><span class="content">sortedBy</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">com.mycompany.myapp.dom.ToDoItem.DependenciesComparator</span><span class="delimiter">"</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_rgant-Column">7. <code>@Column</code> (<code>javax.jdo</code>)</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>The JDO <code>@javax.jdo.annotation.Column</code> provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).</p>
</div>
@@ -4120,9 +4716,8 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
<div class="paragraph">
<p>This section identifies which attributes of <code>@Column</code> are recognized and used by Apache Isis.</p>
</div>
-<div class="sect1">
-<h2 id="_nullability">1. Nullability</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_nullability">7.1. Nullability</h3>
<div class="paragraph">
<p>The <code>allowsNull()</code> attribute is used to specify if a property is mandatory or is optional.</p>
</div>
@@ -4147,10 +4742,8 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
<p>In the vast majority of cases you should be fine just to add the <code>@Column#allowsNull()</code> attribute to the getter. But see the documentation for <a href="#_rgant-Property_optionality"><code>@Property#optionality()</code></a> attribute for discussion on one or two minor edge cases.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_length_for_code_string_code_s">2. Length for <code>String</code>s</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_length_for_code_string_code_s">7.2. Length for <code>String</code>s</h3>
<div class="paragraph">
<p>The <code>length()</code> attribute is used to specify the length of <code>java.lang.String</code> property types as they map to <code>varchar(n)</code> columns.</p>
</div>
@@ -4175,10 +4768,8 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
<p>Isis also provides <a href="#_rgant-Property_maxLength"><code>@Property#maxLength()</code></a> attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_length_scale_for_code_bigdecimal_code_s">3. Length/scale for <code>BigDecimal</code>s</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_length_scale_for_code_bigdecimal_code_s">7.3. Length/scale for <code>BigDecimal</code>s</h3>
<div class="paragraph">
<p>The <code>length()</code> and <code>scale()</code> attributes are used to infer the precision/scale of <code>java.math.BigDecimal</code> property types as they map to <code>decimal(n,p)</code> columns.</p>
</div>
@@ -4200,15 +4791,13 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
<p>If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_hints_and_tips">4. Hints and Tips</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_hints_and_tips">7.4. Hints and Tips</h3>
<div class="paragraph">
<p>This seems to be a good place to describe some additional common mappings that use <code>@Column</code>. Unlike the sections above, the attributes specified in these hints and tips aren’t actually part of Apache Isis metamodel.</p>
</div>
-<div class="sect2">
-<h3 id="_mapping_foreign_keys">4.1. Mapping foreign keys</h3>
+<div class="sect3">
+<h4 id="_mapping_foreign_keys">7.4.1. Mapping foreign keys</h4>
<div class="paragraph">
<p>The <code>name()</code> attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.</p>
</div>
@@ -4230,10 +4819,8 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_mapping_code_blob_code_s_and_code_clob_code_s">5. Mapping <code>Blob</code>s and <code>Clob</code>s</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_mapping_code_blob_code_s_and_code_clob_code_s">7.5. Mapping <code>Blob</code>s and <code>Clob</code>s</h3>
<div class="paragraph">
<p>Isis provides custom value types for <a href="rgcms.html#_rgcms_classes_value-types_Blob"><code>Blob</code></a>s and <a href="rgcms.html#_rgcms_classes_value-types_Clob"><code>Clob</code></a>s. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using <code>@Column</code> within JDO’s <code>@Persistent</code> annotation.</p>
</div>
@@ -4276,8 +4863,9 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
</div>
+</div>
<div class="sect1">
-<h2 id="_rgant-Digits">6. <code>@Digits</code> (<code>javax</code>)</h2>
+<h2 id="_rgant-Digits">8. <code>@Digits</code> (<code>javax</code>)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@javax.validation.constraints.Digits</code> annotation is recognized by Apache Isis as a means to specify the precision for properties and action parameters of type <code>java.math.BigDecimal</code>.</p>
@@ -4323,7 +4911,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-Discriminator">7. <code>@Discriminator</code> (<code>javax.jdo</code>)</h2>
+<h2 id="_rgant-Discriminator">9. <code>@Discriminator</code> (<code>javax.jdo</code>)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@javax.jdo.annotation.Discriminator</code> is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.</p>
@@ -4427,7 +5015,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-DomainObject">8. <code>@DomainObject</code></h2>
+<h2 id="_rgant-DomainObject">10. <code>@DomainObject</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@DomainObject</code> annotation applies to domain objects, collecting together all domain semantics within a single annotation.</p>
@@ -4436,7 +5024,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 11. <code>@DomainObject</code> attributes</caption>
+<caption class="title">Table 12. <code>@DomainObject</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -4601,7 +5189,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</table>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_auditing">8.1. <code>auditing()</code></h3>
+<h3 id="_rgant-DomainObject_auditing">10.1. <code>auditing()</code></h3>
<div class="paragraph">
<p>The <code>auditing()</code> attribute indicates that if the object is modified, then each of its changed properties should be submitted to the <a href="rgsvc.html#_rgsvc_spi_AuditingService"><code>AuditingService</code></a>, if one has been configured.</p>
</div>
@@ -4653,7 +5241,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_autoCompleteRepository">8.2. <code>autoCompleteRepository()</code></h3>
+<h3 id="_rgant-DomainObject_autoCompleteRepository">10.2. <code>autoCompleteRepository()</code></h3>
<div class="paragraph">
<p>The <code>autoCompleteRepository()</code> attribute nominates a single method on a domain service as the fallback means for lookuping up instances of the domain object using a simple string.</p>
</div>
@@ -4712,7 +5300,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</table>
</div>
<div class="sect3">
-<h4 id="__code_autocompleteaction_code">8.2.1. <code>autoCompleteAction()</code></h4>
+<h4 id="__code_autocompleteaction_code">10.2.1. <code>autoCompleteAction()</code></h4>
<div class="paragraph">
<p>As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional <code>autoCompleteAction()</code> attribute allows the method on the repository to be overridden.</p>
</div>
@@ -4759,7 +5347,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_bounded">8.3. <code>bounded()</code></h3>
+<h3 id="_rgant-DomainObject_bounded">10.3. <code>bounded()</code></h3>
<div class="paragraph">
<p>Some domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.</p>
</div>
@@ -4804,7 +5392,7 @@ wrapping the target object using the <a href="rgsvc.html#_rgsvc_api_WrapperFacto
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_createdLifecycleEvent">8.4. createdLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_createdLifecycleEvent">10.4. createdLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired. This is typically when the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>'s <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-creation-api"><code>newTransientInstance()</code></a> is called;
it will also happen if the object is simply instantiated with <code>new(…​)</code>, and then the container’s
@@ -4849,7 +5437,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_3">8.4.1. Subscribers</h4>
+<h4 id="_subscribers_3">10.4.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -4899,7 +5487,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_3">8.4.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_3">10.4.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>createdLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectCreatedEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -4920,7 +5508,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_editing">8.5. <code>editing()</code></h3>
+<h3 id="_rgant-DomainObject_editing">10.5. <code>editing()</code></h3>
<div class="paragraph">
<p>The <code>editing()</code> attribute determines whether a domain object’s properties and collections are not editable (are read-only).</p>
</div>
@@ -5004,7 +5592,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_loadedLifecycleEvent">8.6. loadedLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_loadedLifecycleEvent">10.6. loadedLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a persistent domain object is loaded from the database, a "loaded" lifecycle event is fired.</p>
</div>
@@ -5047,7 +5635,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_4">8.6.1. Subscribers</h4>
+<h4 id="_subscribers_4">10.6.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5097,7 +5685,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_4">8.6.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_4">10.6.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>loadedLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectLoadedEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -5118,7 +5706,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_nature">8.7. <code>nature()</code></h3>
+<h3 id="_rgant-DomainObject_nature">10.7. <code>nature()</code></h3>
<div class="paragraph">
<p>The <code>nature()</code> 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.</p>
</div>
@@ -5217,7 +5805,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_persistedLifecycleEvent">8.8. persistedLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_persistedLifecycleEvent">10.8. persistedLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle
event is fired.</p>
@@ -5275,7 +5863,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_5">8.8.1. Subscribers</h4>
+<h4 id="_subscribers_5">10.8.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5325,7 +5913,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_5">8.8.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_5">10.8.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>persistedLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectPersistedEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -5346,7 +5934,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_persistingLifecycleEvent">8.9. persistingLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_persistingLifecycleEvent">10.9. persistingLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a (just created, still transient) domain object is about to be saved (INSERTed in)to the database, a "persisting" lifecycle
event is fired.</p>
@@ -5407,7 +5995,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_6">8.9.1. Subscribers</h4>
+<h4 id="_subscribers_6">10.9.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5457,7 +6045,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_6">8.9.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_6">10.9.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>persistingLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectPersistingEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -5478,7 +6066,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_objectType">8.10. <code>objectType()</code></h3>
+<h3 id="_rgant-DomainObject_objectType">10.10. <code>objectType()</code></h3>
<div class="paragraph">
<p>The <code>objectType()</code> attribute is used to provide a unique alias for the object’s class name.</p>
</div>
@@ -5556,7 +6144,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_publishing">8.11. <code>publishing()</code></h3>
+<h3 id="_rgant-DomainObject_publishing">10.11. <code>publishing()</code></h3>
<div class="paragraph">
<p>The <code>publishing()</code> attribute determines whether and how a modified object instance is published via the registered implementation of a <a href="rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>). This attribute is also supported for <a href="#_rgant-Action_publishing">actions</a>, where it controls whether action invocations are published as events.</p>
</div>
@@ -5610,7 +6198,7 @@ then no event will be posted.</p>
</table>
</div>
<div class="sect3">
-<h4 id="__code_publishingpayloadfactory_code_2">8.11.1. <code>publishingPayloadFactory()</code></h4>
+<h4 id="__code_publishingpayloadfactory_code_2">10.11.1. <code>publishingPayloadFactory()</code></h4>
<div class="paragraph">
<p>The (optional) related <code>publishingPayloadFactory()</code> specifies the class to use to create the (payload of the) event to be published by the publishing factory.</p>
</div>
@@ -5620,7 +6208,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_removingLifecycleEvent">8.12. removingLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_removingLifecycleEvent">10.12. removingLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a (persistent) domain object is about to be removed (DELETEd) from the database, a "removing"
lifecycle event is fired.</p>
@@ -5681,7 +6269,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_7">8.12.1. Subscribers</h4>
+<h4 id="_subscribers_7">10.12.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5731,7 +6319,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_7">8.12.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_7">10.12.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>removingLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectRemovingEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -5752,7 +6340,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_updatingLifecycleEvent">8.13. updatingLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_updatingLifecycleEvent">10.13. updatingLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a (persistent) domain object has been modified and is about to be updated to the database, an "updating"
lifecycle event is fired.</p>
@@ -5813,7 +6401,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_8">8.13.1. Subscribers</h4>
+<h4 id="_subscribers_8">10.13.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5863,7 +6451,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_8">8.13.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_8">10.13.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>updatingLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectUpdatingEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -5884,7 +6472,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObject_updatedLifecycleEvent">8.14. updatedLifecycleEvent()</h3>
+<h3 id="_rgant-DomainObject_updatedLifecycleEvent">10.14. updatedLifecycleEvent()</h3>
<div class="paragraph">
<p>Whenever a (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle
event is fired.</p>
@@ -5941,7 +6529,7 @@ attribute is available for other lifecycle events.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_9">8.14.1. Subscribers</h4>
+<h4 id="_subscribers_9">10.14.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -5991,7 +6579,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_9">8.14.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_9">10.14.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>updatedLifecycleEvent</code> attribute is not explicitly specified (is left as its default value, <code>ObjectUpdatedEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -6014,7 +6602,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-DomainObjectLayout">9. <code>@DomainObjectLayout</code></h2>
+<h2 id="_rgant-DomainObjectLayout">11. <code>@DomainObjectLayout</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@DomainObjectLayout</code> annotation applies to domain classes, collecting together all UI hints within a single annotation.</p>
@@ -6037,7 +6625,7 @@ then no event will be posted.</p>
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 12. <code>@DomainObjectLayout</code> attributes</caption>
+<caption class="title">Table 13. <code>@DomainObjectLayout</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -6171,7 +6759,7 @@ then no event will be posted.</p>
</table>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_bookmarking">9.1. <code>bookmarking()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_bookmarking">11.1. <code>bookmarking()</code></h3>
<div class="paragraph">
<p>The <code>bookmarking()</code> attribute indicates that an entity is automatically bookmarked. This attribute is also supported for <a href="#_rgant-Action_bookmarking">domain objects</a>.</p>
</div>
@@ -6259,7 +6847,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_cssClass">9.2. <code>cssClass()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_cssClass">11.2. <code>cssClass()</code></h3>
<div class="paragraph">
<p>The <code>cssClass()</code> attribute can be used to render additional CSS classes in the HTML (a wrapping <code><div></code>) that represents the domain object. <a href="rgcfg.html#_rgcfg_application-specific_application-css">Application-specific CSS</a> can then be used to target and adjust the UI representation of that particular element.</p>
</div>
@@ -6294,7 +6882,7 @@ to be rendered as the icon for classes.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_cssClassFa">9.3. <code>cssClassFa()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_cssClassFa">11.3. <code>cssClassFa()</code></h3>
<div class="paragraph">
<p>The <code>cssClassFa()</code> attribute is used to specify the name of a <a href="http://fortawesome.github.io/Font-Awesome/icons/">Font Awesome icon</a> name, to be rendered as the domain object’s icon.</p>
</div>
@@ -6339,7 +6927,7 @@ member so that it can be styled in an application-specific way.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_cssClassUiEvent">9.4. cssClassUiEvent()</h3>
+<h3 id="_rgant-DomainObjectLayout_cssClassUiEvent">11.4. cssClassUiEvent()</h3>
<div class="paragraph">
<p>Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
in any wrapping <code><div></code>s and <code><span></code>s that render the domain object. This is as an alternative to implementing
@@ -6401,7 +6989,7 @@ attribute is available for titles and icons.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_10">9.4.1. Subscribers</h4>
+<h4 id="_subscribers_10">11.4.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -6454,7 +7042,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_10">9.4.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_10">11.4.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>cssClassUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>CssClassUiEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -6474,7 +7062,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_raising_events_programmatically_3">9.4.3. Raising events programmatically</h4>
+<h4 id="_raising_events_programmatically_3">11.4.3. Raising events programmatically</h4>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
by calling the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> API directly, or as a result
@@ -6484,7 +7072,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_describedAs">9.5. <code>describedAs()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_describedAs">11.5. <code>describedAs()</code></h3>
<div class="paragraph">
<p>The <code>describedAs()</code> attribute is used to provide a short description of the domain object to the user. In the <a href="ugvw.html">Wicket viewer</a> it is displayed as a 'tool tip'. The attribute can also be specified for <a href="#_rgant-CollectionLayout_describedAs">collections</a>, <a href="#_rgant-PropertyLayout_describedAs">properties</a>, <a href="#_rgant-ActionLayout_describedAs">actions</a>, <a href="#_rgant-ParameterLayout_describedAs">parameters</a> and <a href="#_rgant-ViewModelLayout_describedAs">view models</a>.</p>
</div>
@@ -6502,7 +7090,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_iconUiEvent">9.6. iconUiEvent()</h3>
+<h3 id="_rgant-DomainObjectLayout_iconUiEvent">11.6. iconUiEvent()</h3>
<div class="paragraph">
<p>Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
object (if possible). This is as an alternative to implementing
@@ -6564,7 +7152,7 @@ attribute is available for titles and CSS classes.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_11">9.6.1. Subscribers</h4>
+<h4 id="_subscribers_11">11.6.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -6617,7 +7205,7 @@ using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The e
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_11">9.6.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_11">11.6.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>iconUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>IconUiEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -6637,7 +7225,7 @@ then no event will be posted.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_raising_events_programmatically_4">9.6.3. Raising events programmatically</h4>
+<h4 id="_raising_events_programmatically_4">11.6.3. Raising events programmatically</h4>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
by calling the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> API directly, or as a result
@@ -6647,7 +7235,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_named">9.7. <code>named()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_named">11.7. <code>named()</code></h3>
<div class="paragraph">
<p>The <code>named()</code> attribute explicitly specifies the domain object’s name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for <a href="#_rgant-ActionLayout_named">actions</a>, <a href="#_rgant-CollectionLayout_named">collections</a>, <a href="#_rgant-PropertyLayout_named">properties</a>, <a href="#_rgant-ParameterLayout_named">parameters</a>, <a href="#_rgant-ViewModelLayout_named">view models</a> and <a href="#_rgant-DomainServiceLayout_named">domain services</a>.</p>
</div>
@@ -6697,7 +7285,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_paged">9.8. <code>paged()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_paged">11.8. <code>paged()</code></h3>
<div class="paragraph">
<p>The <code>paged()</code> attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to <a href="#_rgant-CollectionLayout_paged">collections</a> and <a href="#_rgant-ViewModelLayout_paged">view models</a>.</p>
</div>
@@ -6734,7 +7322,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_plural">9.9. <code>plural()</code></h3>
+<h3 id="_rgant-DomainObjectLayout_plural">11.9. <code>plural()</code></h3>
<div class="paragraph">
<p>When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.</p>
</div>
@@ -6757,7 +7345,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainObjectLayout_titleUiEvent">9.10. titleUiEvent()</h3>
+<h3 id="_rgant-DomainObjectLayout_titleUiEvent">11.10. titleUiEvent()</h3>
<div class="paragraph">
<p>Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
This is as an alternative to implementing <a href="rgcms.html#_rgcms_methods_reserved_title"><code>title()</code></a> reserved method, or
@@ -6819,7 +7407,7 @@ attribute is available for icon names and CSS classes.</p>
<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
<div class="sect3">
-<h4 id="_subscribers_12">9.10.1. Subscribers</h4>
+<h4 id="_subscribers_12">11.10.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
or (if the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> has been appropriately configured)
@@ -6873,7 +7461,7 @@ actually specify the title to be used.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_default_doop_and_noop_events_12">9.10.2. Default, Doop and Noop events</h4>
+<h4 id="_default_doop_and_noop_events_12">11.10.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>titleUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>TitleUiEvent.Default</code>),
then the framework will, by default, post an event.</p>
@@ -6893,7 +7481,7 @@ thn no event will be posted.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_raising_events_programmatically_5">9.10.3. Raising events programmatically</h4>
+<h4 id="_raising_events_programmatically_5">11.10.3. Raising events programmatically</h4>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
by calling the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a> API directly, or as a result
@@ -6905,7 +7493,7 @@ of calling the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>Domai
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-DomainService">10. <code>@DomainService</code></h2>
+<h2 id="_rgant-DomainService">12. <code>@DomainService</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@DomainService</code> annotation indicates that the (concrete) class should be automatically instantiated as a domain service.</p>
@@ -6918,7 +7506,7 @@ discovered automatically on the CLASSPATH.</p>
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 13. <code>@DomainService</code> attributes</caption>
+<caption class="title">Table 14. <code>@DomainService</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -6971,7 +7559,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainService_nature">10.1. <code>nature()</code></h3>
+<h3 id="_rgant-DomainService_nature">12.1. <code>nature()</code></h3>
<div class="paragraph">
<p>By default, a domain service’s actions will be rendered in the application menu bar <em>and</em> be contributed <em>and</em> appear in the REST API <em>and</em> (of course) be available to invoke programmatically wherever that domain service is injected. This is great for initial prototyping, but later on you may prefer to add a little more structure. This is the purpose of the <code>nature()</code> attribute: to indicates the intent of (all of) the actions defined within the domain service.</p>
</div>
@@ -7102,7 +7690,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainService_repositoryFor">10.2. <code>repositoryFor()</code></h3>
+<h3 id="_rgant-DomainService_repositoryFor">12.2. <code>repositoryFor()</code></h3>
<div class="paragraph">
<p>The <code>repositoryFor()</code> attribute is intended for domain services (probably with a <a href="#_rgant-DomainService_nature"><code>nature=DOMAIN</code></a>) that are intended to act as repositories for domain entities.</p>
</div>
@@ -7128,7 +7716,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-DomainServiceLayout">11. <code>@DomainServiceLayout</code></h2>
+<h2 id="_rgant-DomainServiceLayout">13. <code>@DomainServiceLayout</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@DomainServiceLayout</code> annotation applies to domain services, collecting together all view layout semantics within a single annotation.</p>
@@ -7151,7 +7739,7 @@ discovered automatically on the CLASSPATH.</p>
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 14. <code>@DomainServiceLayout</code> attributes</caption>
+<caption class="title">Table 15. <code>@DomainServiceLayout</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -7219,7 +7807,7 @@ discovered automatically on the CLASSPATH.</p>
</table>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainServiceLayout_menuBar">11.1. <code>menuBar()</code></h3>
+<h3 id="_rgant-DomainServiceLayout_menuBar">13.1. <code>menuBar()</code></h3>
<div class="paragraph">
<p>The <code>menuBar()</code> attribute is a hint to specify where on the application menu a domain service’s actions should be rendered.</p>
</div>
@@ -7278,7 +7866,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainServiceLayout_menuOrder">11.2. <code>menuOrder()</code></h3>
+<h3 id="_rgant-DomainServiceLayout_menuOrder">13.2. <code>menuOrder()</code></h3>
<div class="paragraph">
<p>The <code>menuOrder()</code> attribute determines the ordering of a domain service’s actions as menu items within a specified menu bar and top-level menu.</p>
</div>
@@ -7385,7 +7973,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-DomainServiceLayout_named">11.3. <code>named()</code></h3>
+<h3 id="_rgant-DomainServiceLayout_named">13.3. <code>named()</code></h3>
<div class="paragraph">
<p>The <code>named()</code> attribute explicitly specifies the domain service’s name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for <a href="#_rgant-ActionLayout_named">actions</a>, <a href="#_rgant-CollectionLayout_named">collections</a>, <a href="#_rgant-PropertyLayout_named">properties</a>, <a href="#_rgant-ParameterLayout_named">parameters</a>, <a href="#_rgant-DomainObjectLayout_named">domain objects</a> and <a href="#_rgant-ViewModelLayout_named">view models</a>.</p>
</div>
@@ -7421,7 +8009,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-Facets">12. <code>@Facets</code></h2>
+<h2 id="_rgant-Facets">14. <code>@Facets</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@Facets</code> annotation allows <code>FacetFactory</code> implementations and so can be used to run install arbitrary <code>Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory</code> is not typically included.</p>
@@ -7443,7 +8031,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-HomePage">13. <code>@HomePage</code></h2>
+<h2 id="_rgant-HomePage">15. <code>@HomePage</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@HomePage</code> annotation allows a <em>single</em> (no-arg, query-only) action on a <em>single</em> domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.</p>
@@ -7505,7 +8093,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-Inject">14. <code>@Inject</code> (<code>javax</code>)</h2>
+<h2 id="_rgant-Inject">16. <code>@Inject</code> (<code>javax</code>)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Apache Isis automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into <a href="ugtst.html#_ugtst_integ-test-support">integration tests</a> and <a href="ugtst.html#_ugtst_fixture-scripts">fixture scripts</a>.</p>
@@ -7554,7 +8142,7 @@ discovered automatically on the CLASSPATH.</p>
</table>
</div>
<div class="sect2">
-<h3 id="_alternative_syntaxes">14.1. Alternative syntaxes</h3>
+<h3 id="_alternative_syntaxes">16.1. Alternative syntaxes</h3>
<div class="paragraph">
<p>Isis also supports setter-based injection:</p>
</div>
@@ -7582,7 +8170,7 @@ discovered automatically on the CLASSPATH.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_injecting_collection_of_services">14.2. Injecting collection of services</h3>
+<h3 id="_injecting_collection_of_services">16.2. Injecting collection of services</h3>
<div class="paragraph">
<p>It can sometimes be useful to have declared multiple implementations of a particular domain service. For example,
you may have a module that defines an SPI service, where multiple other modules might provide implementations of that SPI
@@ -7642,7 +8230,7 @@ the event. This alternative design is used in the (non-ASF) <a href="http://git
</div>
</div>
<div class="sect2">
-<h3 id="_manually_injecting_services">14.3. Manually injecting services</h3>
+<h3 id="_manually_injecting_services">16.3. Manually injecting services</h3>
<div class="paragraph">
<p>Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the <code>DomainObjectContainer</code>.</p>
</div>
@@ -7714,7 +8302,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-MemberGroupLayout">15. <code>@MemberGroupLayout</code></h2>
+<h2 id="_rgant-MemberGroupLayout">17. <code>@MemberGroupLayout</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@MemberGroupLayout</code> annotation specifies how an object’s properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the <a href="#_rgant-MemberOrder"><code>@MemberOrder</code></a> annotation.</p>
@@ -7742,7 +8330,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-MemberOrder">16. <code>@MemberOrder</code></h2>
+<h2 id="_rgant-MemberOrder">18. <code>@MemberOrder</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@MemberOrder</code> annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the <a href="#_rgant-MemberGroupLayout"><code>@MemberGroupLayout</code></a> annotation.</p>
@@ -7802,7 +8390,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-NotPersistent">17. <code>@NotPersistent</code> (<code>javax.jdo</code>)</h2>
+<h2 id="_rgant-NotPersistent">19. <code>@NotPersistent</code> (<code>javax.jdo</code>)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@javax.jdo.annotation.NotPersistent</code> annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database.</p>
@@ -7830,7 +8418,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-MinLength">18. <code>@MinLength</code></h2>
+<h2 id="_rgant-MinLength">20. <code>@MinLength</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@MinLength</code> annotation is used to specify the minimum number of characters in a search of an <a href="rgcms.html#_rgcms_methods_prefixes_autoComplete"><code>autoComplete…​()</code></a> supporting method.</p>
@@ -7862,7 +8450,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-Parameter">19. <code>@Parameter</code></h2>
+<h2 id="_rgant-Parameter">21. <code>@Parameter</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@Parameter</code> annotation applies to action parameters collecting together all domain semantics within a single annotation.</p>
@@ -7871,7 +8459,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 15. <code>@Paramter</code> attributes</caption>
+<caption class="title">Table 16. <code>@Paramter</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -7976,7 +8564,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</table>
</div>
<div class="sect2">
-<h3 id="_rgant-Parameter_maxLength">19.1. <code>maxLength()</code></h3>
+<h3 id="_rgant-Parameter_maxLength">21.1. <code>maxLength()</code></h3>
<div class="paragraph">
<p>The <code>maxLength()</code> attribute applies only to <code>String</code> 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 <a href="#_rgant-Property_maxLength">properties</a>.</p>
</div>
@@ -8008,7 +8596,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-Parameter_mustSatisfy">19.2. <code>mustSatisfy()</code></h3>
+<h3 id="_rgant-Parameter_mustSatisfy">21.2. <code>mustSatisfy()</code></h3>
<div class="paragraph">
<p>The <code>mustSatisfy()</code> attribute allows arbitrary validation to be applied to parameters using an (implementation of a) <code>org.apache.isis.applib.spec.Specification</code> object. The attribute is also supported on <a href="#_rgant-Property_mustSatisfy">properties</a>.</p>
</div>
@@ -8093,7 +8681,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-Parameter_optionality">19.3. <code>optionality()</code></h3>
+<h3 id="_rgant-Parameter_optionality">21.3. <code>optionality()</code></h3>
<div class="paragraph">
<p>By default, Apache Isis assumes that all parameters of an action are required (mandatory). The <code>optionality()</code> attribute allows this to be relaxed. The attribute is also supported for <a href="#_rgant-Property_optionality">properties</a>.</p>
</div>
@@ -8135,7 +8723,7 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-Parameter_regexPattern">19.4. <code>regexPattern()</code></h3>
+<h3 id="_rgant-Parameter_regexPattern">21.4. <code>regexPattern()</code></h3>
<div class="paragraph">
<p>There are three attributes related to enforcing regular expressions:</p>
</div>
@@ -8185,7 +8773,7 @@ the provided argument does not match the regex pattern.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_rgant-ParameterLayout">20. <code>@ParameterLayout</code></h2>
+<h2 id="_rgant-ParameterLayout">22. <code>@ParameterLayout</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>@ParameterLayout</code> annotation applies to action parameters, collecting together all UI hints within a single annotation.</p>
@@ -8194,7 +8782,7 @@ the provided argument does not match the regex pattern.</p>
<p>The table below summarizes the annotation’s attributes.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 16. <code>@ParameterLayout</code> attributes</caption>
+<caption class="title">Table 17. <code>@ParameterLayout</code> attributes</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -8313,7 +8901,7 @@ the provided argument does not match the regex pattern.</p>
</table>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_cssClass">20.1. <code>cssClass()</code></h3>
+<h3 id="_rgant-ParameterLayout_cssClass">22.1. <code>cssClass()</code></h3>
<div class="paragraph">
<p>The <code>cssClass()</code> attribute can be used to render additional CSS classes in the HTML (a wrapping <code><div></code>) that represents the action parameter. <a href="rgcfg.html#_rgcfg_application-specific_application-css">Application-specific CSS</a> can then be used to target and adjust the UI representation of that particular element.</p>
</div>
@@ -8339,7 +8927,7 @@ the provided argument does not match the regex pattern.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_describedAs">20.2. <code>describedAs()</code></h3>
+<h3 id="_rgant-ParameterLayout_describedAs">22.2. <code>describedAs()</code></h3>
<div class="paragraph">
<p>The <code>describedAs()</code> attribute is used to provide a short description of the action parameter to the user. In the <a href="ugvw.html">Wicket viewer</a> it is displayed as a 'tool tip'. The <code>describedAs()</code> attribute can also be specified for <a href="#_rgant-CollectionLayout_describedAs">collections</a>, <a href="#_rgant-PropertyLayout_describedAs">properties</a>, <a href="#_rgant-ActionLayout_describedAs">actions</a>, <a href="#_rgant-DomainObjectLayout_describedAs">domain objects</a> and <a href="#_rgant-ViewModelLayout_describedAs">view models</a>.</p>
</div>
@@ -8375,7 +8963,7 @@ declaration.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_labelPosition">20.3. <code>labelPosition()</code></h3>
+<h3 id="_rgant-ParameterLayout_labelPosition">22.3. <code>labelPosition()</code></h3>
<div class="paragraph">
<p>The <code>labelPosition()</code> attribute determines the positioning of labels for parameters. This attribute can also be specified for <a href="#_rgant-PropertyLayout_labelPosition">properties</a>.</p>
</div>
@@ -8415,7 +9003,7 @@ declaration.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_multiLine">20.4. <code>multiLine()</code></h3>
+<h3 id="_rgant-ParameterLayout_multiLine">22.4. <code>multiLine()</code></h3>
<div class="paragraph">
<p>The <code>multiLine()</code> 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 <a href="#_rgant-PropertyLayout_multiLine">properties</a>.</p>
</div>
@@ -8453,7 +9041,7 @@ declaration.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_named">20.5. <code>named()</code></h3>
+<h3 id="_rgant-ParameterLayout_named">22.5. <code>named()</code></h3>
<div class="paragraph">
<p>The <code>named()</code> attribute explicitly specifies the action parameter’s name. This attribute can also be specified for <a href="#_rgant-ActionLayout_named">actions</a>, <a href="#_rgant-CollectionLayout_named">collections</a>, <a href="#_rgant-PropertyLayout_named">properties</a>, <a href="#_rgant-DomainObjectLayout_named">domain objects</a>, <a href="#_rgant-ViewModelLayout_named">view models</a> and <a href="#_rgant-DomainServiceLayout_named">domain services</a>.</p>
</div>
@@ -8505,7 +9093,7 @@ declaration.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_rgant-ParameterLayout_renderedAsDayBefore">20.6. <code>renderedAsDayBefore()</code></h3>
+<h3 id="_rgant-ParameterLayout_renderedAsDayBefore">22.6. <code>renderedAsDayBefore()</code></h3>
<div class="paragraph">
<p>The <code>renderedAsDayBefore()</code> attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for parameters of other types. This attribute is also supported for <a href="#_rgant-PropertyLayout_renderedAsDayBefore">properties</a>.</p>
</div>
@@ -8539,7 +9127,7 @@ dec
<TRUNCATED>