You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by bu...@apache.org on 2014/11/19 16:48:55 UTC
svn commit: r929786 - in /websites/staging/isis/trunk: cgi-bin/ content/
content/intro/tutorials/ content/more-advanced-topics/
content/reference/recognized-annotations/ content/reference/services/
Author: buildbot
Date: Wed Nov 19 15:48:55 2014
New Revision: 929786
Log:
Staging update by buildbot for isis
Modified:
websites/staging/isis/trunk/cgi-bin/ (props changed)
websites/staging/isis/trunk/content/ (props changed)
websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
websites/staging/isis/trunk/content/more-advanced-topics/ViewModel.html
websites/staging/isis/trunk/content/reference/recognized-annotations/ViewModel.html
websites/staging/isis/trunk/content/reference/services/memento-service.html
Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Nov 19 15:48:55 2014
@@ -1 +1 @@
-1640522
+1640575
Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Nov 19 15:48:55 2014
@@ -1 +1 @@
-1640522
+1640575
Modified: websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
==============================================================================
--- websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html (original)
+++ websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html Wed Nov 19 15:48:55 2014
@@ -817,24 +817,23 @@ mvn clean install
</ul></li>
</ul>
-<h2>Clock Service</h2>
+<h2>CSS UI Hints</h2>
-<p>To ensure testability, there should be no dependencies on system time, for example usage of <code>LocalDate.now()</code>. Instead the domain objects should delegate to the provided <code>ClockService</code>.</p>
+<p>(In 1.8.0-SNAPSHOT), CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
+- the bootstrap "btn" CSS classes can be used using <a href="http://isis.apache.org/reference/recognized-annotations/CssClass.html">@CssClass</a> annotation
+- the <a href="http://fortawesome.github.io/Font-Awesome/icons/">Font Awesome</a> icons can be used using the <a href="http://isis.apache.org/reference/recognized-annotations/CssClassFa.html">@CssClassFa</a> annotation</p>
-<ul>
-<li>remove any dependencies on system time (eg defaults for date/time action parameters)
-<ul>
-<li>inject <a href="http://isis.apache.org/reference/services/ClockService.html">ClockService</a></li>
-<li>call <code>ClockService.now()</code> etc where required.</li>
-</ul></li>
-</ul>
+<p>It's also possible to use Font Awesome icons for the <a href="http://isis.apache.org/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html">domain object icon</a>.</p>
+
+<p>So:
+- for some of the actions of your domain services or entities, annotate using <code>@CssClass</code> or <code>@CssClassFa</code>.</p>
<h2>Dynamic Layout</h2>
-<p>Up to this point we've been using annotations (<code>@MemberOrder</code>, <code>@MemberGroupLayout</code>, <code>@Named</code>, <code>@LabelAt</code> and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding <code>.layout.json</code> file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):</p>
+<p>Up to this point we've been using annotations (<code>@MemberOrder</code>, <code>@MemberGroupLayout</code>, <code>@Named</code>, <code>@LabelAt</code>, <code>@CssClass</code> and <code>@CssClassFa</code> and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding <code>.layout.json</code> file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):</p>
<ul>
-<li>Delete the <code>@MemberOrder</code> and <code>@MemberGroupLayout</code> annotations and instead specify layout hints using a <a href="http://isis.apache.org/components/viewers/wicket/dynamic-layouts.html">.layout.json</a> file.</li>
+<li>Delete the various hint annotations and instead specify layout hints using a <a href="http://isis.apache.org/components/viewers/wicket/dynamic-layouts.html">.layout.json</a> file.</li>
</ul>
<h2>Business rules</h2>
@@ -889,6 +888,18 @@ mvn clean install
<li>Add the <a href="http://isis.apache.org/reference/recognized-annotations/HomePage.html">@HomePage</a> annotation to one (no more) of the domain services' no-arg actions</li>
</ul>
+<h2>Clock Service</h2>
+
+<p>To ensure testability, there should be no dependencies on system time, for example usage of <code>LocalDate.now()</code>. Instead the domain objects should delegate to the provided <code>ClockService</code>.</p>
+
+<ul>
+<li>remove any dependencies on system time (eg defaults for date/time action parameters)
+<ul>
+<li>inject <a href="http://isis.apache.org/reference/services/ClockService.html">ClockService</a></li>
+<li>call <code>ClockService.now()</code> etc where required.</li>
+</ul></li>
+</ul>
+
<h2>Decoupling using Contributions</h2>
<p>One of Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Isis metamodel. In Isis' terminology, we say that the domain service action is contributed to the entity.</p>
@@ -1044,32 +1055,92 @@ mvn clean install
<li>(optional): follow the <a href="https://github.com/isisaddons/isis-module-audit">auditing module</a> README or (the same) <a href="http://youtu.be/g01tK58MxJ8">screencast</a></li>
</ul>
-<h2>CSS</h2>
+<h2>View models</h2>
-<p>TODO</p>
+<p>In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.</p>
-<h2>View models</h2>
+<p>Also, if using Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.</p>
+
+<p>To support these use cases, Isis therefore allows you to write a <a href="http://isis.apache.org/reference/recognized-annotations/ViewModel.html">view model</a>, either by annotating the class with <a href="http://isis.apache.org/reference/recognized-annotations/ViewModel.html">@ViewModel</a> or (for more control) by implementing the <code>ViewModel</code> interface.</p>
<p>TODO</p>
-<h2>Integration tests</h2>
+<h2>Testing</h2>
+
+<p>Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.</p>
+
+<h3>Unit testing</h3>
<p>TODO</p>
-<h2>Composite fixture scripts (a la Estatio)</h2>
+<p>unit</p>
+
+<p>http://isis.apache.org/core/unittestsupport.html</p>
+
+<h3>Integration testing</h3>
<p>TODO</p>
+<p>http://isis.apache.org/core/integtestsupport.html</p>
+
+<p>http://isis.apache.org/reference/services/wrapper-factory.html</p>
+
+<p>reuse the fixture scripts</p>
+
<h2>Customising the REST API</h2>
<p>TODO</p>
+<h1>whether to show only object properties for object members</h1>
+
+<h1>(on the object representation only)</h1>
+
+<h1>Takes precedence over the other 'suppress' below.</h1>
+
+<h1>isis.viewer.restfulobjects.objectPropertyValuesOnly=true</h1>
+
+<p>isis.viewer.restfulobjects.objectPropertyValuesOnly=true</p>
+
+<h1>whether to suppress "describedby" links. Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressDescribedByLinks=true</h1>
+
+<h1>whether to suppress "update" links. Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressUpdateLink=true</h1>
+
+<h1>whether to suppress "id" json-prop for object members. Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressMemberId=true</h1>
+
+<h1>whether to suppress "links" json-prop for object members</h1>
+
+<h1>(on the object representation only). Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressMemberLinks=true</h1>
+
+<h1>whether to suppress "extensions" json-prop for object members</h1>
+
+<h1>(on the object representation only). Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressMemberExtensions=true</h1>
+
+<h1>whether to suppress "disabledReason" json-prop for object members</h1>
+
+<h1>(on the object representation only). Defaults to false.</h1>
+
+<h1>isis.viewer.restfulobjects.suppressMemberDisabledReason=true</h1>
+
+<p>isis.viewer.restfulobjects.suppressMemberDisabledReason=true</p>
+
<h2>Exception Recognizers</h2>
<h2>Configuring to use an external database</h2>
<p>TODO</p>
+<p>update <code>persistor.properties</code></p>
+
<p></div></p>
Modified: websites/staging/isis/trunk/content/more-advanced-topics/ViewModel.html
==============================================================================
--- websites/staging/isis/trunk/content/more-advanced-topics/ViewModel.html (original)
+++ websites/staging/isis/trunk/content/more-advanced-topics/ViewModel.html Wed Nov 19 15:48:55 2014
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
- <title>ViewModel interface
</title>
+ <title>ViewModels
</title>
<meta name="description" content="">
<meta name="author" content="">
@@ -298,7 +298,7 @@
};
function twshare () {
window.open(
- "https://twitter.com/intent/tweet?url="+document.URL+"&text=ViewModel interface
",
+ "https://twitter.com/intent/tweet?url="+document.URL+"&text=ViewModels
",
'Share on Twitter',
'width=800,height=526');
};
@@ -416,16 +416,64 @@
<div class="page-header">
<p><a href="./../documentation.html">Docs</a> » <a href="./../more-advanced-topics/about.html">More Advanced Topics</a></p>
-<h1>ViewModel interface
+<h1>ViewModels
</h1>
</div>
<hr />
-<p>Indicates that a domain object is intended to be used as a view model.</p>
+<p>In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases,
+though, there may be a requirement to bring together data or functionality that spans several entities.</p>
-<h3>API</h3>
+<p>Also, if using Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is owned/deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.</p>
+
+<p>To support these use cases, Isis therefore allows you to write a view model, either by annotating the class with <a href="http://isis.apache.org/reference/recognized-annotations/ViewModel.html">@ViewModel</a> or (for more control) by implementing the <code>ViewModel</code> interface.</p>
+
+<p>View models are immutable; their state is in fact encoded in their identity. Editable view models can be simulated by implementing the <code>ViewModel.Cloneable</code> interface.</p>
+
+<h2>@ViewModel annotation</h2>
+
+<p>The simplest way to create a view model is to annotate the class with <code>@ViewModel</code>:</p>
+
+<pre><code>@ViewModel
+public class MyViewModel {
+
+ public MyViewModel() {}
+
+ ...
+
+}
+</code></pre>
+
+<p>View models must have a no-arg constructor, but there are few other constraints.</p>
+
+<ul>
+<li>if the view model has dependencies on domain services, then either:
+<ul>
+<li>instantiate using <code>DomainObjectContainer#newTransientInstance()</code> or</li>
+<li>instantiate directly and then inject explicitly using <code>DomainObjectContainer#injectServicesInto(.)</code></li>
+</ul></li>
+<li>if the view model has no dependencies on domain services, then just instantiate directly </li>
+</ul>
+
+<p>></p>
+
+<blockquote>
+ <p>Note that there is a <code>DomainObjectContainer#newViewModelInstance(.)</code>; this is for view models that implement <code>ViewModel</code> interface and can be safely ignored.</p>
+</blockquote>
+
+<p>The view model's memento will be derived from the value of the view model object's properties. Any <a href="http://isis.apache.org/reference/recognized-annotations/NotPersistent.html">@NotPersistent</a> properties will be excluded from the memento, as will any <a href="http://isis.apache.org/reference/recognized-annotations/Programmatic.html">@Programmatic</a> properties. Properties that are merely <a href="http://isis.apache.org/reference/recognized-annotations/Hidden.html">@Hidden</a> are included in the memento.</p>
+
+<p>Only properties supported by the configured <a href="../reference/services/memento-service.html">MementoService</a> can be used. The default implementation supports all the value types and persisted entities.</p>
+
+<p>(As of 1.8.0-SNAPSHOT) there are some limitations:
+* view models cannot reference other view models
+* collections (of either view models or entities) are ignored.</p>
+
+<h2>ViewModel interface</h2>
+
+<p>Another way to indicate that a domain object is a view model is by implementing the <code>ViewModel</code> interface:</p>
<pre><code>public interface ViewModel {
@@ -437,7 +485,7 @@
}
</code></pre>
-<p>Where:</p>
+<p>where:</p>
<ul>
<li><code>viewModelMemento()</code></p>
@@ -445,16 +493,12 @@
<p>is called by the framework, to obtain a memento of the view model. Typically this will be the identifier of a backing domain entity, but it could also be an arbitrary string, for example a bunch of JSON.</li>
<li><code>viewModelInit()</code></p>
-<p>is called by the framework so that the view model may recreate its state in a subsequent call (using the memento that the framework obtained from <code>viewModelMemento()</code></li>
+<p>is called by the framework so that the view model may initialize or subsequently recreate its state in a subsequent call (using the memento that the framework obtained from <code>viewModelMemento()</code></li>
</ul>
-<h3>Usage</h3>
-
-<p>Used in the example <a href="https://github.com/apache/isis/tree/quickstart_wicket_restful_jdo-archetype-1.3.1-RC1/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/app">todo app</a>, for example the <a href="https://github.com/apache/isis/blob/quickstart_wicket_restful_jdo-archetype-1.3.1-RC1/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/app/ToDoAppDashboard.java">ToDoAppDashboard</a> that is rendered on the home page.</p>
-
-<h3>Related Services</h3>
+<p>View models implemented this way must be instantiated using <code>DomainObjectContainer#newViewModelInstance(Class,String)</code>, where the second String argument is the memento of the view model, and which is passed to the view model in turn through the <code>viewModelInit(.)</code> method.</p>
-<p>The <a href="../reference/services/memento-service.html">MementoService</a> provides a convenient mechanism for view models to build up and parse memento strings (for the implementation of the <code>viewModelMemento()</code> and <code>viewModelInit()</code> methods.</p>
+<p>The <code>viewModelMemento()</code> and <code>viewModelInit()</code> methods should be reciprocals of each other, but there are no other constraints. The <a href="../reference/services/memento-service.html">MementoService</a> provides a convenient mechanism for view models to build up and parse memento strings. But the methods could do anything; it would even be possible for a view model to store its state in the <code>HttpSession</code> and key that state with a GUID.</p>
Modified: websites/staging/isis/trunk/content/reference/recognized-annotations/ViewModel.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/recognized-annotations/ViewModel.html (original)
+++ websites/staging/isis/trunk/content/reference/recognized-annotations/ViewModel.html Wed Nov 19 15:48:55 2014
@@ -421,13 +421,44 @@
</h1>
</div>
-<p><div class="note">
-This is a stub.
-</div></p>
+<p>The <code>@ViewModel</code> annotation, applied to a class, is the simplest way to indicate that the class is a view model. View models are not persisted to the database, instead their state is encoded within their identity (ultimately represented in the URL). As such, view models are immutable.</p>
-<p>Indicates that the class is a view model whose identity is inferred from the state of its (non-@NotPersisted) properties. </p>
+<p>For example:</p>
-<p>Only properties supported by the configured <a href="../services/memento-service.html">MementoService</a> can be used. The default implementation supports all the value types and persisted entities. However, view models are NOT supported.</p>
+<pre><code>@ViewModel
+public class MyViewModel {
+
+ public MyViewModel() {}
+
+ ...
+
+}
+</code></pre>
+
+<p>View models must have a no-arg constructor, but there are few other constraints.</p>
+
+<ul>
+<li>if the view model has dependencies on domain services, then either:
+<ul>
+<li>instantiate using <code>DomainObjectContainer#newTransientInstance()</code> or</li>
+<li>instantiate directly and then inject explicitly using <code>DomainObjectContainer#injectServicesInto(.)</code></li>
+</ul></li>
+<li>if the view model has no dependencies on domain services, then just instantiate directly </li>
+</ul>
+
+<p>></p>
+
+<blockquote>
+ <p>Note that there is a <code>DomainObjectContainer#newViewModelInstance(.)</code>; this is for view models that implement <code>ViewModel</code> interface and can be safely ignored.</p>
+</blockquote>
+
+<p>The view model's memento will be derived from the value of the view model object's properties. Any <a href="http://isis.apache.org/reference/recognized-annotations/NotPersistent.html">@NotPersistent</a> properties will be excluded from the memento, as will any <a href="http://isis.apache.org/reference/recognized-annotations/Programmatic.html">@Programmatic</a> properties. Properties that are merely <a href="http://isis.apache.org/reference/recognized-annotations/Hidden.html">@Hidden</a> are included in the memento.</p>
+
+<p>Only properties supported by the configured <a href="../reference/services/memento-service.html">MementoService</a> can be used. The default implementation supports all the value types and persisted entities.</p>
+
+<p>(As of 1.8.0-SNAPSHOT) there are some limitations:
+* view models cannot reference other view models
+* collections (of either view models or entities) are ignored.</p>
Modified: websites/staging/isis/trunk/content/reference/services/memento-service.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/services/memento-service.html (original)
+++ websites/staging/isis/trunk/content/reference/services/memento-service.html Wed Nov 19 15:48:55 2014
@@ -457,14 +457,15 @@
<p>In the case of the default implementation provided by the core framework, the types supported are:</p>
<ul>
-<li><code>String</code></li>
-<li><code>boolean,</code>Boolean`</li>
-<li><code>byte</code>, <code>Byte</code></li>
-<li><code>short</code>, <code>Short</code></li>
-<li><code>int</code>, <code>Integer</code></li>
-<li><code>long</code>, <code>Long</code></li>
-<li><code>float</code>, <code>Float</code></li>
-<li><code>double</code>, <code>Double</code></li>
+<li><code>java.lang.String</code></li>
+<li><code>java.lang.Boolean</code>, <code>boolean</code></li>
+<li><code>java.lang.Byte</code>, <code>byte</code></li>
+<li><code>java.lang.Short</code>, <code>short</code></li>
+<li><code>java.lang.Integer</code>, <code>int</code></li>
+<li><code>java.lang.Long</code>, <code>long</code></li>
+<li><code>java.lang.Float</code>, <code>float</code></li>
+<li><code>java.lang.Double</code>, <code>double</code></li>
+<li><code>java.lang.Character</code>, <code>char</code></li>
<li><code>java.math.BigDecimal</code></li>
<li><code>java.math.BigInteger</code></li>
<li><code>org.joda.time.LocalDate</code></li>