http://git-wip-us.apache.org/repos/asf/isis-site/blob/6ad91949/content/guides/ugvw/ugvw.html ---------------------------------------------------------------------- diff --git a/content/guides/ugvw/ugvw.html b/content/guides/ugvw/ugvw.html index 7d0da78..c31d0fa 100644 --- a/content/guides/ugvw/ugvw.html +++ b/content/guides/ugvw/ugvw.html @@ -374,8 +374,7 @@ <div id="doc-content"> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc""; style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="sect1"> - <h2 id="_ugvw">1. Wicket Viewer</h2> - <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <h2 id="__ugvw">1. Wicket Viewer</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Wicket Viewer automatically exposes an Apache Isis domain object model for use by end-users. The viewer is implemented using <a href="http://wicket.apache.org";>Apache Wicket</a>.</p> @@ -450,7 +449,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/recent-pages/recent-pages.png"><img src="images/wicket-viewer/recent-pages/recent-pages.png" alt="recent pages" width="800px"></a> + <a class="image" href="images/recent-pages/recent-pages.png"><img src="images/recent-pages/recent-pages.png" alt="recent pages" width="800px"></a> </div> </div> <div class="admonitionblock note"> @@ -460,7 +459,7 @@ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> - <p>Note that this screenshot show an earlier version of the <a href="#">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> + <p>Note that this screenshot show an earlier version of the <a href="../ugvw/ugvw.html">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> </div> </td> </tr> </tbody> @@ -482,7 +481,7 @@ <div class="sect3"> <h4 id="_related_functionality">2.1.4. Related functionality</h4> <div class="paragraph"> - <p>The <a href="#_ugvw_features_bookmarked-pages">bookmarked pages</a> (sliding panel) also provides links to recently visited objects, but only those explicitly marked as <code>@DomainObject(bookmarking=â¦â)</code>. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).</p> + <p>The <a href="../ugvw/ugvw.html#_ugvw_features_bookmarked-pages">bookmarked pages</a> (sliding panel) also provides links to recently visited objects, but only those explicitly marked as <code>@DomainObject(bookmarking=â¦â)</code>. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).</p> </div> </div> <div class="sect3"> @@ -496,7 +495,7 @@ <h3 id="_ugvw_features_bookmarked-pages">2.2. Bookmarked pages</h3> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>The Wicket viewer supports the bookmarking of both domain objects and query-only (<a href="rgant.html#_rgant-Action_semantics">@Action(semantics=â¦â)</a>) actions.</p> + <p>The Wicket viewer supports the bookmarking of both domain objects and query-only (<a href="../rgant/rgant.html#_rgant-Action_semantics">@Action(semantics=â¦â)</a>) actions.</p> </div> <div class="paragraph"> <p>Domain objects, if bookmarkable, can be nested.</p> @@ -511,7 +510,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/bookmarked-pages/panel.png"><img src="images/wicket-viewer/bookmarked-pages/panel.png" alt="panel" width="800px"></a> + <a class="image" href="images/bookmarked-pages/panel.png"><img src="images/bookmarked-pages/panel.png" alt="panel" width="800px"></a> </div> </div> <div class="admonitionblock note"> @@ -521,7 +520,7 @@ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> - <p>Note that these screenshots show an earlier version of the <a href="#">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> + <p>Note that these screenshots show an earlier version of the <a href="../ugvw/ugvw.html">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> </div> </td> </tr> </tbody> @@ -535,7 +534,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/bookmarked-pages/panel-estatio.png"><img src="images/wicket-viewer/bookmarked-pages/panel-estatio.png" alt="panel estatio" width="800px"></a> + <a class="image" href="images/bookmarked-pages/panel-estatio.png"><img src="images/bookmarked-pages/panel-estatio.png" alt="panel estatio" width="800px"></a> </div> </div> <div class="paragraph"> @@ -545,7 +544,7 @@ <div class="sect3"> <h4 id="_domain_code_2">2.2.2. Domain Code</h4> <div class="paragraph"> - <p>To indicate a class is bookmarkable, use the <a href="rgant.html#_rgant-DomainObjectLayout">@DomainObjectLayout</a> annotation:</p> + <p>To indicate a class is bookmarkable, use the <a href="../rgant/rgant.html#_rgant-DomainObjectLayout">@DomainObjectLayout</a> annotation:</p> </div> <div class="listingblock"> <div class="content"> @@ -567,7 +566,7 @@ </div> </div> <div class="paragraph"> - <p>To indicate that a safe (query only) action is bookmarkable, use the <a href="rgant.html#_rgant-ActionLayout">@ActionLayout</a> annotation:</p> + <p>To indicate that a safe (query only) action is bookmarkable, use the <a href="../rgant/rgant.html#_rgant-ActionLayout">@ActionLayout</a> annotation:</p> </div> <div class="listingblock"> <div class="content"> @@ -608,7 +607,7 @@ <div class="sect4"> <h5 id="_related_functionality_2">Related functionality</h5> <div class="paragraph"> - <p>The <a href="#_ugvw_features_recent-pages">Recent Pages</a> also lists recently visited pages, selected from a drop-down.</p> + <p>The <a href="../ugvw/ugvw.html#_ugvw_features_recent-pages">Recent Pages</a> also lists recently visited pages, selected from a drop-down.</p> </div> </div> </div> @@ -648,7 +647,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/copy-link/010-copy-link-button.png"><img src="images/wicket-viewer/copy-link/010-copy-link-button.png" alt="010 copy link button" width="800px"></a> + <a class="image" href="images/copy-link/010-copy-link-button.png"><img src="images/copy-link/010-copy-link-button.png" alt="010 copy link button" width="800px"></a> </div> </div> <div class="admonitionblock note"> @@ -658,7 +657,7 @@ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> - <p>Note that these screenshots show an earlier version of the <a href="#">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> + <p>Note that these screenshots show an earlier version of the <a href="../ugvw/ugvw.html">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> </div> </td> </tr> </tbody> @@ -669,7 +668,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/copy-link/020-copy-link-dialog.png"><img src="images/wicket-viewer/copy-link/020-copy-link-dialog.png" alt="020 copy link dialog" width="800px"></a> + <a class="image" href="images/copy-link/020-copy-link-dialog.png"><img src="images/copy-link/020-copy-link-dialog.png" alt="020 copy link dialog" width="800px"></a> </div> </div> <div class="paragraph"> @@ -691,7 +690,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/copy-link/030-hints.png"><img src="images/wicket-viewer/copy-link/030-hints.png" alt="030 hints" width="800px"></a> + <a class="image" href="images/copy-link/030-hints.png"><img src="images/copy-link/030-hints.png" alt="030 hints" width="800px"></a> </div> </div> <div class="paragraph"> @@ -702,7 +701,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/copy-link/040-copy-link-with-hints.png"><img src="images/wicket-viewer/copy-link/040-copy-link-with-hints.png" alt="040 copy link with hints" width="800px"></a> + <a class="image" href="images/copy-link/040-copy-link-with-hints.png"><img src="images/copy-link/040-copy-link-with-hints.png" alt="040 copy link with hints" width="800px"></a> </div> </div> <div class="paragraph"> @@ -724,7 +723,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/copy-link/050-title-url.png"><img src="images/wicket-viewer/copy-link/050-title-url.png" alt="050 title url" width="800px"></a> + <a class="image" href="images/copy-link/050-title-url.png"><img src="images/copy-link/050-title-url.png" alt="050 title url" width="800px"></a> </div> </div> </div> @@ -833,7 +832,7 @@ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> - <p>It is also possible to configure the Wicket viewer to <a href="#_ugvw_configuration-properties_abbreviating-titles">abbreviate titles or suppress them</a> completely.</p> + <p>It is also possible to configure the Wicket viewer to <a href="../ugvw/ugvw.html#_ugvw_configuration-properties_abbreviating-titles">abbreviate titles or suppress them</a> completely.</p> </div> </td> </tr> </tbody> @@ -844,7 +843,7 @@ <h3 id="_ugvw_features_blob-attachments">2.5. File upload/download</h3> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>The Isis application library provides the <a href="rgcms.html#_rgcms_classes_value-types_Blob">Blob</a> value type (binary large objects) and also the <a href="rgcms.html#_rgcms_classes_value-types_Clob">Clob</a> value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).</p> + <p>The Isis application library provides the <a href="../rgcms/rgcms.html#_rgcms_classes_value-types_Blob">Blob</a> value type (binary large objects) and also the <a href="../rgcms/rgcms.html#_rgcms_classes_value-types_Clob">Clob</a> value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).</p> </div> <div class="paragraph"> <p>A class can define a property using either of these types, for example:</p> @@ -861,7 +860,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/010-attachment-field.png"><img src="images/wicket-viewer/blob-attachments/010-attachment-field-940.png" alt="010 attachment field 940" width="800px"></a> + <a class="image" href="images/blob-attachments/010-attachment-field.png"><img src="images/blob-attachments/010-attachment-field-940.png" alt="010 attachment field 940" width="800px"></a> </div> </div> <div class="admonitionblock note"> @@ -871,7 +870,7 @@ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> - <p>Note that these screenshots show an earlier version of the <a href="#">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> + <p>Note that these screenshots show an earlier version of the <a href="../ugvw/ugvw.html">Wicket viewer</a> UI (specifically, pre 1.8.0).</p> </div> </td> </tr> </tbody> @@ -885,7 +884,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/020-edit-choose-file.png"><img src="images/wicket-viewer/blob-attachments/020-edit-choose-file-940.png" alt="020 edit choose file 940" width="800px"></a> + <a class="image" href="images/blob-attachments/020-edit-choose-file.png"><img src="images/blob-attachments/020-edit-choose-file-940.png" alt="020 edit choose file 940" width="800px"></a> </div> </div> </div> @@ -896,7 +895,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/030-choose-file-using-browser.png"><img src="images/wicket-viewer/blob-attachments/030-choose-file-using-browser-520.png" alt="030 choose file using browser 520" width="520px"></a> + <a class="image" href="images/blob-attachments/030-choose-file-using-browser.png"><img src="images/blob-attachments/030-choose-file-using-browser-520.png" alt="030 choose file using browser 520" width="520px"></a> </div> </div> <div class="paragraph"> @@ -904,7 +903,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/040-edit-chosen-file-indicated.png"><img src="images/wicket-viewer/blob-attachments/040-edit-chosen-file-indicated-940.png" alt="040 edit chosen file indicated 940" width="800px"></a> + <a class="image" href="images/blob-attachments/040-edit-chosen-file-indicated.png"><img src="images/blob-attachments/040-edit-chosen-file-indicated-940.png" alt="040 edit chosen file indicated 940" width="800px"></a> </div> </div> </div> @@ -915,7 +914,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/050-ok-if-image-then-rendered.png"><img src="images/wicket-viewer/blob-attachments/050-ok-if-image-then-rendered-940.png" alt="050 ok if image then rendered 940" width="800px"></a> + <a class="image" href="images/blob-attachments/050-ok-if-image-then-rendered.png"><img src="images/blob-attachments/050-ok-if-image-then-rendered-940.png" alt="050 ok if image then rendered 940" width="800px"></a> </div> </div> </div> @@ -926,7 +925,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/060-download.png"><img src="images/wicket-viewer/blob-attachments/060-download-940.png" alt="060 download 940" width="800px"></a> + <a class="image" href="images/blob-attachments/060-download.png"><img src="images/blob-attachments/060-download-940.png" alt="060 download 940" width="800px"></a> </div> </div> </div> @@ -937,7 +936,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/blob-attachments/070-edit-clear.png"><img src="images/wicket-viewer/blob-attachments/070-edit-clear-940.png" alt="070 edit clear 940" width="800px"></a> + <a class="image" href="images/blob-attachments/070-edit-clear.png"><img src="images/blob-attachments/070-edit-clear-940.png" alt="070 edit clear 940" width="800px"></a> </div> </div> </div> @@ -1009,9 +1008,9 @@ </div> <div class="ulist"> <ul> - <li> <p>the <a href="rgsvc.html#_rgsvc_spi_UserRegistrationService">user registration service</a>, which provides an API to create the user account</p> </li> - <li> <p>the <a href="rgsvc.html#_rgsvc_spi_EmailNotificationService">email notification service</a>, which provides an API for to send the verification emails</p> </li> - <li> <p>the <a href="rgsvc.html#_rgsvc_api_EmailService">email service</a>, that is used by the email notification service to actually send the email.</p> </li> + <li> <p>the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_UserRegistrationService">user registration service</a>, which provides an API to create the user account</p> </li> + <li> <p>the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_EmailNotificationService">email notification service</a>, which provides an API for to send the verification emails</p> </li> + <li> <p>the <a href="../rgsvc/rgsvc.html#_rgsvc_api_EmailService">email service</a>, that is used by the email notification service to actually send the email.</p> </li> </ul> </div> <div class="paragraph"> @@ -1037,7 +1036,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/login-page-default.png"><img src="images/wicket-viewer/user-registration/login-page-default.png" alt="login page default" width="300px"></a> + <a class="image" href="images/user-registration/login-page-default.png"><img src="images/user-registration/login-page-default.png" alt="login page default" width="300px"></a> </div> </div> <div class="paragraph"> @@ -1045,7 +1044,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/sign-up-page.png"><img src="images/wicket-viewer/user-registration/sign-up-page.png" alt="sign up page" width="300px"></a> + <a class="image" href="images/user-registration/sign-up-page.png"><img src="images/user-registration/sign-up-page.png" alt="sign up page" width="300px"></a> </div> </div> <div class="paragraph"> @@ -1053,7 +1052,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png"><img src="images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png" alt="sign up login page after sign up" width="300px"></a> + <a class="image" href="images/user-registration/sign-up-login-page-after-sign-up.png"><img src="images/user-registration/sign-up-login-page-after-sign-up.png" alt="sign up login page after sign up" width="300px"></a> </div> </div> <div class="paragraph"> @@ -1061,7 +1060,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png"><img src="images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png" alt="sign up email with verification link" width="500px"></a> + <a class="image" href="images/user-registration/sign-up-email-with-verification-link.png"><img src="images/user-registration/sign-up-email-with-verification-link.png" alt="sign up email with verification link" width="500px"></a> </div> </div> <div class="paragraph"> @@ -1069,7 +1068,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/sign-up-registration-page.png"><img src="images/wicket-viewer/user-registration/sign-up-registration-page.png" alt="sign up registration page" width="300px"></a> + <a class="image" href="images/user-registration/sign-up-registration-page.png"><img src="images/user-registration/sign-up-registration-page.png" alt="sign up registration page" width="300px"></a> </div> </div> <div class="paragraph"> @@ -1077,7 +1076,7 @@ </div> <div class="imageblock"> <div class="content"> - <a class="image" href="images/wicket-viewer/user-registration/sign-up-after-registration.png"><img src="images/wicket-viewer/user-registration/sign-up-after-registration.png" alt="sign up after registration" width="800px"></a> + <a class="image" href="images/user-registration/sign-up-after-registration.png"><img src="images/user-registration/sign-up-after-registration.png" alt="sign up after registration" width="800px"></a> </div> </div> </div> @@ -1088,22 +1087,990 @@ </div> <div class="ulist"> <ul> - <li> <p>register an implementation of the <a href="rgsvc.html#_rgsvc_spi_UserRegistrationService">user registration service</a> (eg by using the <a href="https://github.com/isisaddons/isis-module-security";>Isis addons security module</a>)</p> </li> - <li> <p>configure the <a href="rgsvc.html#_rgsvc_api_EmailService">email service</a></p> </li> + <li> <p>register an implementation of the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_UserRegistrationService">user registration service</a> (eg by using the <a href="https://github.com/isisaddons/isis-module-security";>Isis addons security module</a>)</p> </li> + <li> <p>configure the <a href="../rgsvc/rgsvc.html#_rgsvc_api_EmailService">email service</a></p> </li> </ul> </div> <div class="paragraph"> <p>The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).</p> </div> <div class="paragraph"> - <p>It is also possible to configure the Wicket viewer to suppress <a href="#_ugvw_configuration-properties_suppressing-sign-up">the sign-up page link</a> and/or the <a href="#_ugvw_configuration-properties_suppressing-password-reset">password reset page</a>.</p> + <p>It is also possible to configure the Wicket viewer to suppress <a href="../ugvw/ugvw.html#_ugvw_configuration-properties_suppressing-sign-up">the sign-up page link</a> and/or the <a href="../ugvw/ugvw.html#_ugvw_configuration-properties_suppressing-password-reset">password reset page</a>.</p> </div> </div> </div> </div> </div> <div class="sect1"> - <h2 id="_ugvw_configuration-properties">3. Configuration Properties</h2> + <h2 id="_ugvw_layout">3. Layout</h2> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="sectionbody"> + <div class="paragraph"> + <p>In implementing the <a href="http://en.wikipedia.org/wiki/Naked_objects";>naked objects pattern</a>, Apache Isis aims to infer as much information from the domain classes as possible. Nevertheless, some metadata relating solely to the UI is inevitably required. This chapter describes how this is done both for domain objects using either annotations or using an associated layout file.</p> + </div> + <div class="paragraph"> + <p>It also describes how to layout the application menu items (containing domain service' actions), as more well as more advanced topics such as customising which columns appear in tables.</p> + </div> + <div class="sect2"> + <h3 id="_ugvw_layout_annotation-based">3.1. Annotation-based Layout</h3> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="paragraph"> + <p>Metadata providing UI hints can be specified either using annotations, or using a <a href="../ugvw/ugvw.html#_ugvw_layout_file-based"><code>layout.xml</code></a> file.</p> + </div> + <div class="paragraph"> + <p>In most cases you will probably want to use the file-based approach: changes to file layouts are picked up dynamically, and using a file also allows tabs and tab groups to be specified: this is not supported using annotations.</p> + </div> + <div class="paragraph"> + <p>Nevertheless, annotations are still supported and are sometimes useful for very simple objects or just when prototyping. This section explains how.</p> + </div> + <div class="sect3"> + <h4 id="__code_memberorder_code">3.1.1. <code>@MemberOrder</code></h4> + <div class="paragraph"> + <p>The <a href="../rgant/rgant.html#_rgant-MemberOrder"><code>@MemberOrder</code></a> annotation is used to specify the relative order of domain class properties, collections and actions.</p> + </div> + <div class="paragraph"> + <p>The annotation defines two attributes, <a href="../rgant/rgant.html#_rgant-MemberOrder_name"><code>name()</code></a> and <a href="../rgant/rgant.html#_rgant-MemberOrder_sequence"><code>sequence()</code></a>. Their usage depends on the member type:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>for properties, the <code>name()</code> is used to group properties together into a member group (also called a property group or a fieldset. The <code>sequence()</code> then orders properties within these groups. If no <code>name()</code> is specified then the property is placed in a fallback "General" group, called "General".<br></p> + <div class="paragraph"> + <p>The name of these member groups/fieldsets are then referenced by <a href="../rgant/rgant.html#_rgant-MemberGroupLayout"><code>@MemberGroupLayout</code></a>.</p> + </div> </li> + <li> <p>for collections, the <code>name()</code> attribute is (currently) unused. The <code>sequence()</code> orders collections relative to one another</p> </li> + <li> <p>for actions, the <code>name()</code> attribute associates an action with either a property or with a collection.<br></p> + <div class="ulist"> + <ul> + <li> <p>If the <code>name()</code> attribute matches a property name, then the actionâs button is rendered close to the property, according to <a href="../rgant/rgant.html#_rgant-ActionLayout_position"><code>@ActionLayout#position()</code></a> attribute.<br></p> </li> + <li> <p>On the other hand if the `name() attribute matches a collection name, then the actionâs button is rendered on the collectionâs header.</p> </li> + <li> <p>If there is no <code>name()</code> value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the objectâs icon and title.</p> </li> + </ul> + </div> </li> + </ul> + </div> + <div class="paragraph"> + <p>Within any of these, the <code>sequence()</code> then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing".</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">@MemberOrder</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">String</span> getDescription() { ... } + <span class="annotation">@MemberOrder</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">String</span> getCategory() { ... } + <span class="annotation">@MemberOrder</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">3</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="type">boolean</span> isComplete() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">Detail</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> LocalDate getDueBy() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">Detail</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getCost() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">Detail</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">4</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">String</span> getNotes() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">Misc</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">99</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">Long</span> getVersionSequence() { ... } + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no <code>name</code> attribute is specified. Properties in the same member group are rendered together, as a fieldset.</p> + </div> + <div class="paragraph"> + <p>In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the <code>@MemberOrder</code>'s <a href="../rgant/rgant.html#_rgant-MemberOrder_name"><code>name()</code></a> attribute, holding the value of the property or 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">ToDoItem</span> { + <span class="annotation">@MemberOrder</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">3</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="type">boolean</span> isComplete() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> ToDoItem completed() { ...} + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> ToDoItem notYetCompleted() { ...} + + <span class="annotation">@MemberOrder</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> <span class="predefined-type">SortedSet</span><ToDoItem> getDependencies() { ... } + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> ToDoItem add(ToDoItem t) { ...} + <span class="annotation">@MemberOrder</span>(name=<span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span>, sequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>) + <span class="directive">public</span> ToDoItem remove(ToDoItem t) { ...} + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>will associate the <code>completed()</code> and <code>notYetCompleted()</code> actions with the <code>complete</code> property, and will associate the <code>add()</code> and <code>remove()</code> actions with the <code>dependencies</code> collection.</p> + </div> + <div class="paragraph"> + <p>The value of <a href="../rgant/rgant.html#_rgant-MemberOrder_sequence"><code>sequence()</code></a> is a string. The simplest convention (as shown in the example above) is to use numbersâââ1, 2, 3âââthough it is a better idea to leave gaps in the numbersâââ10, 20, 30 perhapsâââsuch that a new member may be added without having to edit existing numbers.</p> + </div> + <div class="paragraph"> + <p>Even better is to adopt the 'dewey-decimal' notationâââ1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3âââwhich allows for an indefinite amount of future insertion. It also allows subclasses to insert their class members as required.</p> + </div> + </div> + <div class="sect3"> + <h4 id="__code_membergrouplayout_code">3.1.2. <code>@MemberGroupLayout</code></h4> + <div class="paragraph"> + <p>The <a href="../rgant/rgant.html#_rgant-MemberGroupLayout"><code>@MemberGroupLayout</code></a> annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column. The annotation also specifies the relative width of the columns.</p> + </div> + <div class="paragraph"> + <p>The property groups/fieldsets in this case are those that are inferred from the <code>@MemberOrder#name()</code> attribute.</p> + </div> + <div class="admonitionblock tip"> + <table> + <tbody> + <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 combine <code>@MemberOrder</code> with a <a href="../ugvw/ugvw.html#_ugvw_layout_xml">file-based layout</a>. The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does <em>not</em> specify the properties/collections/actions within those grid regions. The <code>@MemberOrder</code> annotation in effect "binds" the properties or collections to those regions of the grid.</p> + </div> + <div class="paragraph"> + <p>When file-based layouts are used this way, the <a href="../rgant/rgant.html#_rgant-MemberGroupLayout"><code>@MemberGroupLayout</code></a> annotation is essentially ignored, but the metadata from the <a href="../rgant/rgant.html#_rgant-MemberOrder"><code>@MemberOrder</code></a> annotation (and the other layout annotations, <a href="../rgant/rgant.html#_rgant-ActionLayout"><code>@ActionLayout</code></a>, <a href="../rgant/rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a> and <a href="../rgant/rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a>) are all still honoured.</p> + </div> </td> + </tr> + </tbody> + </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="annotation">@MemberGroupLayout</span>( + columnSpans={<span class="integer">3</span>,<span class="integer">3</span>,<span class="integer">0</span>,<span class="integer">6</span>}, + left={<span class="string"><span class="delimiter">"</span><span class="content">General</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">Misc</span><span class="delimiter">"</span></span>}, + middle=<span class="string"><span class="delimiter">"</span><span class="content">Detail</span><span class="delimiter">"</span></span> + ) +<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> { + ... +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Four values are given in the <code>columnSpans</code> attribute. The first three are the relative widths of the three columns of property groups. The fourth, meanwhile, indicates the width of a final column that holds all the collections of the object.</p> + </div> + <div class="paragraph"> + <p>The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the <a href="http://getbootstrap.com/2.3.2/";>Bootstrap</a> library).</p> + </div> + <div class="paragraph"> + <p>For example:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>{3,3,0,6}</code> indicates:</p> + <div class="ulist"> + <ul> + <li> <p>a left column of properties taking up 25% of the width</p> </li> + <li> <p>a middle column of properties taking up 25% of the width</p> </li> + <li> <p>a right column of collections taking up 50% of the width</p> </li> + </ul> + </div> </li> + <li> <p><code>{2,6,0,4}</code> indicates:</p> + <div class="ulist"> + <ul> + <li> <p>a left column of properties taking up ~16% of the width</p> </li> + <li> <p>a middle column of properties taking up 50% of the width</p> </li> + <li> <p>a right column of collections taking up ~33% of the width</p> </li> + </ul> + </div> </li> + <li> <p><code>{2,3,3,4}</code> indicates:</p> + <div class="ulist"> + <ul> + <li> <p>a left column of properties taking up ~16% of the width</p> </li> + <li> <p>a middle column of properties taking up 25% of the width</p> </li> + <li> <p>a right column of properties taking up 25% of the width</p> </li> + <li> <p>a far right column of collections taking up ~33% of the width</p> </li> + </ul> + </div> </li> + </ul> + </div> + <div class="paragraph"> + <p>If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>{4,4,4,12} indicates:</p> + <div class="ulist"> + <ul> + <li> <p>a left column of properties taking up ~33% of the width</p> </li> + <li> <p>a middle column of properties taking up ~33% of the width</p> </li> + <li> <p>a right column of properties taking up ~33% of the width</p> </li> + <li> <p>the collections underneath the property columns, taking up the full width</p> </li> + </ul> + </div> </li> + </ul> + </div> + </div> + <div class="sect3"> + <h4 id="_example_layouts">3.1.3. Example Layouts</h4> + <div class="paragraph"> + <p>Below are sketches for the layout of the <a href="https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java";>ToDoItem</a> class of the Isis addons example <a href="https://github.com/isisaddons/isis-app-todoapp/";>todoapp</a> (not ASF):</p> + </div> + <div class="paragraph"> + <p>The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12):</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/reference-layout/6-6-0-12.png"><img src="images/reference-layout/6-6-0-12.png" alt="6 6 0 12" width="720px"></a> + </div> + </div> + <div class="paragraph"> + <p>The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12):</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/reference-layout/4-4-4-12.png"><img src="images/reference-layout/4-4-4-12.png" alt="4 4 4 12" width="720px"></a> + </div> + </div> + <div class="paragraph"> + <p>The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0):</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/reference-layout/4-0-8-0.png"><img src="images/reference-layout/4-0-8-0.png" alt="4 0 8 0" width="720px"></a> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_other_annotations">3.1.4. Other Annotations</h4> + <div class="paragraph"> + <p>As of 1.8.0, all the layout annotations have been consolidated into the various <code>XxxLayout</code> annotations: <a href="../rgant/rgant.html#_rgant-ActionLayout, "><code>@ActionLayout</code></a> <a href="../rgant/rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a>, <a href="../rgant/rgant.html#_rgant-DomainObjectLayout"><code>@DomainObjectLayout</code></a>, <a href="../rgant/rgant.html#_rgant-DomainServiceLayout"><code>@DomainServiceLayout</code></a>, <a href="../rgant/rgant.html#_rgant-ParameterLayout"><code>@ParameterLayout</code></a>, <a href="../rgant/rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a>, and <a href="../rgant/rgant.html#_rgant-ViewModelLayout"><code>@ViewModelLayout</code></a></p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_ugvw_layout_file-based">3.2. File-based Layouts</h3> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="paragraph"> + <p>Metadata providing UI hints can be specified either <a href="../ugvw/ugvw.html#_ugvw_layout_annotation-based">using annotations</a>, or using an <code>Xxx.layout.xml</code> file (where <code>Xxx</code> is the entity or view model object to be rendered).</p> + </div> + <div class="paragraph"> + <p>Using a file-based layout has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app. Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).</p> + </div> + <div class="paragraph"> + <p>Another benefit of file-based layout is that UI hints can be provided for <a href="../ugfun/ugfun.html#_ugfun_how-tos_contributed-members">contributed associations and actions</a> that are synthesised at runtime.</p> + </div> + <div class="paragraph"> + <p>It is also possible to download an initial <code>.layout.xml</code> - capturing any existing layout metadata - using the <a href="../rgsvc/rgsvc.html#_rgsvc_api_LayoutService"><code>LayoutService</code></a> (exposed on the prototyping menu) or using a <a href="../rgcms/rgcms.html#_rgcms_classes_mixins_Object">mixin action</a> contributed to every domain object.</p> + </div> + <div class="paragraph"> + <p>The main downsides of using file-based layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid XML document will result in no metadata for the entire class).</p> + </div> + <div class="paragraph"> + <p>Also, file-based layouts have no notion of inheritance, whereas the dewey-decimal format <code>@MemberOrder</code> annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.</p> + </div> + <div class="paragraph"> + <p>The <code>Xxx.layout.xml</code> file is just the serialized form of a <a href="../rgcms/rgcms.html#_rgcms_classes_layout"><code>Grid</code></a> layout class defined within Apache Isis' applib. These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making iteasy to author such layout files.</p> + </div> + <div class="admonitionblock note"> + <table> + <tbody> + <tr> + <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> + <td class="content"> + <div class="paragraph"> + <p>It is also possible to describe layouts using a <code>.layout.json</code> file. However, <code>.layout.json</code> support is deprecated; the <code>.layout.xml</code> file also enables much more sophisticated layouts than those afforded by <code>.layout.json</code>.</p> + </div> + <div class="paragraph"> + <p>If you have an application with older <code>.layout.json</code> files, then it is possible to download initial <code>.layout.xml</code> files using the <a href="../rgsvc/rgsvc.html#_rgsvc_api_LayoutService"><code>LayoutService</code></a> (exposed as an action on the prototyping menu). The <code>.layout.json</code> file will be ignored once a <code>.layout.xml</code> file is present.</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + <div class="sect3"> + <h4 id="_grids_vs_components">3.2.1. Grids vs Components</h4> + <div class="paragraph"> + <p>The layout file distinguishes between two types of element:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>those that define a grid structure, of: rows, columns, tab groups and tabs.<br></p> + <div class="paragraph"> + <p>The rows and columns are closely modelled on <a href="getbootstrap.com">Bootstrap 3</a> (used in the implementation of the <a href="../ugvw/ugvw.html">Wicket viewer</a>).</p> + </div> </li> + <li> <p>those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>More information about these classes can be found in <a href="../rgcms/rgcms.html#_rgcms_classes_layout">the reference guide</a>. More information on Bootstrap 3âs grid system can be found <a href="http://getbootstrap.com/css/#grid";>here</a>.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_screencast">3.2.2. Screencast</h4> + <div class="paragraph"> + <p>This <a href="https://www.youtube.com/watch?v=MxewC5Pve5k";>screencast</a> describes the feature.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_examples">3.2.3. Examples</h4> + <div class="paragraph"> + <p>Probably the easiest way to understand dynamic XML layouts is by example. For this weâll use the <code>ToDoItem</code> from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp";>Isis addons' todoapp</a>:</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/layout-dynamic-xml/ToDoItem.png"><img src="images/layout-dynamic-xml/ToDoItem.png" alt="ToDoItem" width="940px"></a> + </div> + </div> + <div class="sect4"> + <h5 id="_namespaces">Namespaces</h5> + <div class="paragraph"> + <p>First things first; every <code>.layout.xml</code> file must properly declare the XSD namespaces and schemas. There are two: one for the grid classes, and one for the common component classes:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8" standalone="yes"?></span> +<span class="tag"><bs3:grid</span> + <span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/component</span> <span class="content">http://isis.apache.org/applib/layout/component/component.xsd</span> <span class="content">http://isis.apache.org/applib/layout/grid/bootstrap3</span> <span class="content">http://isis.apache.org/applib/layout/grid/bootstrap3/bootstrap3.xsd</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:bs3</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/grid/bootstrap3</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:c</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/applib/layout/component</span><span class="delimiter">"</span></span> + <span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span><span class="tag">></span> + ... +<span class="tag"></bs3:grid></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>Most IDEs will automatically download the XSD schemas from the specified schema locations, thereby providing "intellisense" help as you edit the file.</p> + </div> + </div> + <div class="sect4"> + <h5 id="_rows_full_width_cols_and_tabs">Rows, full-width cols, and tabs</h5> + <div class="paragraph"> + <p>The example layout consists of three rows: a row for the object/icon, a row containing a properties, and a row containing collections. In all three cases the row contains a single column spanning the full width of the page. For the property and collection rows, the column contains a tab group.</p> + </div> + <div class="paragraph"> + <p>This corresponds to the following XML:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"> <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedActions</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:domainObject</span> <span class="attribute-name">bookmarking</span>=<span class="string"><span class="delimiter">"</span><span class="content">AS_ROOT</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:tabGroup></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Properties</span><span class="delimiter">"</span></span><span class="tag">></span>...<span class="tag"></bs3:tab></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Other</span><span class="delimiter">"</span></span><span class="tag">></span>...<span class="tag"></bs3:tab></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Metadata</span><span class="delimiter">"</span></span><span class="tag">></span>...<span class="tag"></bs3:tab></span> + <span class="tag"></bs3:tabGroup></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:tabGroup</span> <span class="attribute-name">unreferencedCollections</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Similar to</span><span class="delimiter">"</span></span><span class="tag">></span>...<span class="tag"></bs3:tab></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Dependencies</span><span class="delimiter">"</span></span><span class="tag">></span>...<span class="tag"></bs3:tab></span> + <span class="tag"></bs3:tabGroup></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>You will notice that one of the <code>col</code>umns has an <code>unreferencedActions</code> attribute, while one of the <code>tabGroup</code>s has a similar <code>unreferencedCollections</code> attribute. This topic is discussed in more detail <a href="../ugfun/ugfun.html#__ugvw_layout_file-based_unreferenced">below</a>.</p> + </div> + </div> + <div class="sect4"> + <h5 id="_fieldsets">Fieldsets</h5> + <div class="paragraph"> + <p>The first tab containing properties is divided into two columns, each of which holds a single fieldset of multiple properties. Those properties in turn can have associated actions.</p> + </div> + <div class="paragraph"> + <p>This corresponds to the following XML:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"> <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Properties</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">6</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:fieldSet</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">General</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">general</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedProperties</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">duplicate</span><span class="delimiter">"</span></span> <span class="attribute-name">position</span>=<span class="string"><span class="delimiter">"</span><span class="content">PANEL_DROPDOWN</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">delete</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:property</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:property</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">category</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:property</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">subcategory</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">updateCategory</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">analyseCategory</span><span class="delimiter">"</span></span> <span class="attribute-name">position</span>=<span class="string"><span class="delimiter">"</span><span class="content">RIGHT</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></c:property></span> + <span class="tag"><c:property</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">completed</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClassFa</span>=<span class="string"><span class="delimiter">"</span><span class="content">fa-thumbs-up</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">notYetCompleted</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClassFa</span>=<span class="string"><span class="delimiter">"</span><span class="content">fa-thumbs-down</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></c:property></span> + <span class="tag"></c:fieldSet></span> + <span class="tag"></bs3:col></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">6</span><span class="delimiter">"</span></span><span class="tag">></span> + ... + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + <span class="tag"></bs3:tab></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>The tab defines two columns, each span of 6 (meaning half the width of the page).</p> + </div> + <div class="paragraph"> + <p>In the first column there is a single fieldset. Notice how actions - such as <code>duplicate</code> and <code>delete</code> - can be associated with this fieldset directly, meaning that they should be rendered on the fieldsetâs top panel.</p> + </div> + <div class="paragraph"> + <p>Thereafter the fieldset lists the properties in order. Actions can be associated with properties too; here they are rendered underneath or to the right of the field.</p> + </div> + <div class="paragraph"> + <p>Note also the <code>unreferencedProperties</code> attribute for the fieldset; this topic is discussed in more detail <a href="../ugfun/ugfun.html#__ugvw_layout_file-based_unreferenced">below</a>.</p> + </div> + </div> + <div class="sect4"> + <h5 id="_collections">Collections</h5> + <div class="paragraph"> + <p>In the final row the collections are placed in tabs, simply one collection per tab. This corresponds to the following XML:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"> <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Similar to</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:collection</span> <span class="attribute-name">defaultView</span>=<span class="string"><span class="delimiter">"</span><span class="content">table</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">similarTo</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + <span class="tag"></bs3:tab></span> + <span class="tag"><bs3:tab</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">Dependencies</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><bs3:row></span> + <span class="tag"><bs3:col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:collection</span> <span class="attribute-name">defaultView</span>=<span class="string"><span class="delimiter">"</span><span class="content">table</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">dependencies</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">add</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"><c:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">remove</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></c:collection></span> + <span class="tag"></bs3:col></span> + <span class="tag"></bs3:row></span> + <span class="tag"></bs3:tab></span></code></pre> + </div> + </div> + <div class="paragraph"> + <p>As with properties, actions can be associated with collections; this indicates that they should be rendered in the collectionâs header.</p> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="__ugvw_layout_file-based_unreferenced">3.2.4. Unreferenced Members</h4> + <div class="paragraph"> + <p>As noted in the preceding discussion, several of the gridâs regions have either an <code>unreferencedActions</code>, <code>unreferencedCollections</code> or <code>unreferencedProperties</code> attribute.</p> + </div> + <div class="paragraph"> + <p>The rules are:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>unreferencedActions</code> attribute can be specified either on a column or on a fieldset. <br></p> + <div class="paragraph"> + <p>It would normally be typical to use the column holding the <code><domainObject/></code> icon/title, that is as shown in the example. The unreferenced actions then appear as top-level actions for the domain object.</p> + </div> </li> + <li> <p><code>unreferencedCollections</code> attribute can be specified either on a column or on a tabgroup.<br></p> + <div class="paragraph"> + <p>If specified on a column, then that column will contain each of the unreferenced collections, stacked one on top of the other. If specified on a tab group, then a separate tab will be created for each collection, with that tab containing only that single collection.</p> + </div> </li> + <li> <p><code>unreferencedProperties</code> attribute can be specified only on a fieldset.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>The purpose of these attributes is to indicate where in the layout any unreferenced members should be rendered. Every grid <em>must</em> nominate one region for each of these three member types, the reason being that to ensure that the layout can be used even if it is incomplete with respect to the object members inferred from the Java source code. This might be because the developer forgot to update the layout, or it might be because of a new mixin (property, collection or action) contributed to many objects.</p> + </div> + <div class="paragraph"> + <p>The framework ensures that in any given grid exactly one region is specified for each of the three <code>unreferencedâ¦â</code> attributes. If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged. The layout XML will then be ignored.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_more_advanced_features">3.2.5. More advanced features</h4> + <div class="paragraph"> + <p>This section decribes a number of more features useful in more complex layouts.</p> + </div> + <div class="sect4"> + <h5 id="_multiple_references_to_a_feature">Multiple references to a feature</h5> + <div class="paragraph"> + <p>One feature worth being aware of is that it is possible to render a single feature more than once.</p> + </div> + <div class="paragraph"> + <p>For example, the dashboard home page for the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp";>Isis addons' todoapp</a> shows the "not yet complete" collection of todo items twice, once as a table and also as a calendar:</p> + </div> + <div class="imageblock"> + <div class="content"> + <a class="image" href="images/layout-dynamic-xml/ToDoAppDashboard.png"><img src="images/layout-dynamic-xml/ToDoAppDashboard.png" alt="ToDoAppDashboard" width="940px"></a> + </div> + </div> + <div class="paragraph"> + <p>This is accomplished using the following (slightly abbreviated) layout:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><grid</span> <span class="attribute-name">...</span><span class="tag">></span> + <span class="tag"><row></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedActions</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + ... + <span class="tag"></col></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">5</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedCollections</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClass</span>=<span class="string"><span class="delimiter">"</span><span class="content">custom-padding-top-20</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><ns2:collection</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">notYetComplete</span><span class="delimiter">"</span></span> <span class="attribute-name">defaultView</span>=<span class="string"><span class="delimiter">"</span><span class="content">calendar</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="1"></i><b>(1)</b> + <span class="tag"></col></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">5</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClass</span>=<span class="string"><span class="delimiter">"</span><span class="content">custom-padding-top-20</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><ns2:collection</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">notYetComplete</span><span class="delimiter">"</span></span> <span class="attribute-name">defaultView</span>=<span class="string"><span class="delimiter">"</span><span class="content">table</span><span class="delimiter">"</span></span> <span class="attribute-name">paged</span>=<span class="string"><span class="delimiter">"</span><span class="content">5</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="2"></i><b>(2)</b> + <span class="tag"><ns2:collection</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span> <span class="attribute-name">defaultView</span>=<span class="string"><span class="delimiter">"</span><span class="content">table</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></col></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><ns2:fieldSet</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">General</span><span class="delimiter">"</span></span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">general</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedProperties</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></col></span> + <span class="tag"></row></span> +<span class="tag"></grid></span></code></pre> + </div> + </div> + <div class="colist arabic"> + <table> + <tbody> + <tr> + <td><i class="conum" data-value="1"></i><b>1</b></td> + <td>render the collection in "calendar" view</td> + </tr> + <tr> + <td><i class="conum" data-value="2"></i><b>2</b></td> + <td>also render the collection in "table" view</td> + </tr> + </tbody> + </table> + </div> + <div class="paragraph"> + <p>In the middle column the <code>notYetComplete</code> collection is rendered in "calendar" view, while in the right-most column it is rendered in "table" view.</p> + </div> + <div class="paragraph"> + <p>It is also possible to reference object properties and actions more than once. This might be useful for a complex domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the most commonly used info), but also on detail tabs.</p> + </div> + </div> + <div class="sect4"> + <h5 id="_custom_css">Custom CSS</h5> + <div class="paragraph"> + <p>The ToDoAppâs dashboard (above) also shows how custom CSS styles can be associated with specific regions of the layout:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><grid</span> <span class="attribute-name">...</span><span class="tag">></span> + <span class="tag"><row></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedActions</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> + <span class="tag"><ns2:domainObject</span><span class="tag">/></span> + <span class="tag"><row></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">12</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClass</span>=<span class="string"><span class="delimiter">"</span><span class="content">custom-width-100</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> + <span class="tag"><ns2:action</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">exportToWordDoc</span><span class="delimiter">"</span></span><span class="tag">/></span> + <span class="tag"></col></span> + <span class="tag"></row></span> + ... + <span class="tag"></col></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">5</span><span class="delimiter">"</span></span> <span class="attribute-name">unreferencedCollections</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClass</span>=<span class="string"><span class="delimiter">"</span><span class="content">custom-padding-top-20</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> + ... + <span class="tag"></col></span> + <span class="tag"><col</span> <span class="attribute-name">span</span>=<span class="string"><span class="delimiter">"</span><span class="content">5</span><span class="delimiter">"</span></span> <span class="attribute-name">cssClass</span>=<span class="string"><span class="delimiter">"</span><span class="content">custom-padding-top-20</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> + ... + <span class="tag"></col></span> + <span class="tag"></row></span> +<span class="tag"></grid></span></code></pre> + </div> + </div> + <div class="colist arabic"> + <table> + <tbody> + <tr> + <td><i class="conum" data-value="1"></i><b>1</b></td> + <td>Render the column with the <code>custom-width-100</code> CSS class.</td> + </tr> + <tr> + <td><i class="conum" data-value="2"></i><b>2</b></td> + <td>Render the column with the <code>custom-padding-top-20</code> CSS class.</td> + </tr> + <tr> + <td><i class="conum" data-value="3"></i><b>3</b></td> + <td>Ditto</td> + </tr> + </tbody> + </table> + </div> + <div class="paragraph"> + <p>For example the <code>custom-width-100</code> style is used to "stretch" the button for the <code>exportToWordDoc</code> action in the left-most column. This is accomplished with the following CSS in <code>application.css</code>:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="css"><span class="class">.custom-width-100</span> <span class="tag">ul</span>, +<span class="class">.custom-width-100</span> <span class="tag">ul</span> <span class="tag">li</span>, +<span class="class">.custom-width-100</span> <span class="tag">ul</span> <span class="tag">li</span> <span class="tag">a</span><span class="class">.btn</span> { + <span class="key">width</span>: <span class="float">100%</span>; +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Similarly, the middle and right columns are rendered using the <code>custom-padding-top-20</code> CSS class. This shifts them down from the top of the page slightly, using the following CSS:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="css"><span class="class">.custom-padding-top-20</span> { + <span class="key">padding-top</span>: <span class="float">20px</span>; +}</code></pre> + </div> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_migrating_from_earlier_versions">3.2.6. Migrating from earlier versions</h4> + <div class="paragraph"> + <p>As noted earlier on, it is possible to download layout XML files using the <a href="../rgsvc/rgsvc.html#_rgsvc_api_LayoutService"><code>LayoutService</code></a> (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models. Alternatively the layout XML for a single domain object can be downloaded using the <a href="../rgcms/rgcms.html#_rgcms_classes_mixins_Object">mixin action</a> (contributed to every domain object).</p> + </div> + <div class="paragraph"> + <p>There are four "styles":</p> + </div> + <div class="ulist"> + <ul> + <li> <p>current</p> </li> + <li> <p>complete</p> </li> + <li> <p>normalized</p> </li> + <li> <p>minimal</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>Ignorig the "current" style (which merely downloads the currently cached layout), the other three styles allow the developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained elsewhere, either from annotations in the metamodel or from an earlier <code>.layout.json</code> file if present. The table below summarises the choices:</p> + </div> + <table class="tableblock frame-all grid-all spread"> + <caption class="title"> + Table 1. Table caption + </caption> + <colgroup> + <col style="width: 25%;"> + <col style="width: 25%;"> + <col style="width: 25%;"> + <col style="width: 25%;"> + </colgroup> + <thead> + <tr> + <th class="tableblock halign-left valign-bottom">Style</th> + <th class="tableblock halign-center valign-bottom"><a href="../rgant/rgant.html#_rgant-MemberGroupLayout"><code>@MemberGroupLayout</code></a></th> + <th class="tableblock halign-center valign-bottom"><a href="../rgant/rgant.html#_rgant-MemberOrder"><code>@MemberOrder</code></a></th> + <th class="tableblock halign-center valign-bottom"><a href="../rgant/rgant.html#_rgant-ActionLayout"><code>@ActionLayout</code></a>, <a href="../rgant/rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a>, <a href="../rgant/rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a></th> + </tr> + </thead> + <tbody> + <tr> + <td class="tableblock halign-left valign-bottom"><p class="tableblock"><code>COMPLETE</code></p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-bottom"><p class="tableblock"><code>NORMALIZED</code></p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">not in the XML</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-bottom"><p class="tableblock"><code>MINIMAL</code></p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">serialized as XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">not in the XML</p></td> + <td class="tableblock halign-center valign-bottom"><p class="tableblock">not in the XML</p></td> + </tr> + </tbody> + </table> + <div class="paragraph"> + <p>As a developer, you therefore have a choice as to how
<TRUNCATED>
