You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2014/11/19 16:48:48 UTC
svn commit: r1640575 - in /isis/site/trunk/content:
intro/tutorials/apacheconeu-2014.md more-advanced-topics/ViewModel.md
reference/recognized-annotations/ViewModel.md
reference/services/memento-service.md
Author: danhaywood
Date: Wed Nov 19 15:48:47 2014
New Revision: 1640575
URL: http://svn.apache.org/r1640575
Log:
view models
Modified:
isis/site/trunk/content/intro/tutorials/apacheconeu-2014.md
isis/site/trunk/content/more-advanced-topics/ViewModel.md
isis/site/trunk/content/reference/recognized-annotations/ViewModel.md
isis/site/trunk/content/reference/services/memento-service.md
Modified: isis/site/trunk/content/intro/tutorials/apacheconeu-2014.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/intro/tutorials/apacheconeu-2014.md?rev=1640575&r1=1640574&r2=1640575&view=diff
==============================================================================
--- isis/site/trunk/content/intro/tutorials/apacheconeu-2014.md (original)
+++ isis/site/trunk/content/intro/tutorials/apacheconeu-2014.md Wed Nov 19 15:48:47 2014
@@ -344,23 +344,24 @@ The Wicket UI doesn't allow collections
-## Clock Service
+## CSS UI Hints
-To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
+(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 [@CssClass](http://isis.apache.org/reference/recognized-annotations/CssClass.html) annotation
+- the [Font Awesome](http://fortawesome.github.io/Font-Awesome/icons/) icons can be used using the [@CssClassFa](http://isis.apache.org/reference/recognized-annotations/CssClassFa.html) annotation
+
+It's also possible to use Font Awesome icons for the [domain object icon](http://isis.apache.org/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html).
+
+So:
+- for some of the actions of your domain services or entities, annotate using `@CssClass` or `@CssClassFa`.
-* remove any dependencies on system time (eg defaults for date/time action parameters)
- * inject [ClockService](http://isis.apache.org/reference/services/ClockService.html)
- * call `ClockService.now()` etc where required.
-
-
-
-## Dynamic Layout
-Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@LabelAt` 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 `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):
+## Dynamic Layout
-* Delete the `@MemberOrder` and `@MemberGroupLayout` annotations and instead specify layout hints using a [.layout.json](http://isis.apache.org/components/viewers/wicket/dynamic-layouts.html) file.
+Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@LabelAt`, `@CssClass` and `@CssClassFa` 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 `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):
+* Delete the various hint annotations and instead specify layout hints using a [.layout.json](http://isis.apache.org/components/viewers/wicket/dynamic-layouts.html) file.
@@ -398,7 +399,6 @@ Or, more pithily: "see it, use it, do it
- use the [@MustSatisfy](http://isis.apache.org/reference/recognized-annotations/MustSatisfy.html) annotation to specify an arbitrary constraint
-
## Home page
@@ -410,6 +410,17 @@ The Wicket UI will automatically invoke
+## Clock Service
+
+To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
+
+* remove any dependencies on system time (eg defaults for date/time action parameters)
+ * inject [ClockService](http://isis.apache.org/reference/services/ClockService.html)
+ * call `ClockService.now()` etc where required.
+
+
+
+
## Decoupling using Contributions
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.
@@ -456,7 +467,6 @@ Finally, note that the layout of contrib
-
## Decoupling using the Event Bus
Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
@@ -547,27 +557,42 @@ In addition to providing Wicket viewer e
+## View models
-## CSS
+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.
-TODO
+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.
+To support these use cases, Isis therefore allows you to write a [view model](http://isis.apache.org/reference/recognized-annotations/ViewModel.html), either by annotating the class with [@ViewModel](http://isis.apache.org/reference/recognized-annotations/ViewModel.html) or (for more control) by implementing the `ViewModel` interface.
-## View models
TODO
+## Testing
-## Integration tests
+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.
+
+### Unit testing
TODO
+unit
+
+http://isis.apache.org/core/unittestsupport.html
-## Composite fixture scripts (a la Estatio)
+### Integration testing
TODO
+http://isis.apache.org/core/integtestsupport.html
+
+http://isis.apache.org/reference/services/wrapper-factory.html
+
+
+reuse the fixture scripts
+
+
## Customising the REST API
@@ -575,6 +600,39 @@ TODO
+# whether to show only object properties for object members
+# (on the object representation only)
+# Takes precedence over the other 'suppress' below.
+#isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+
+# whether to suppress "describedby" links. Defaults to false.
+#isis.viewer.restfulobjects.suppressDescribedByLinks=true
+
+# whether to suppress "update" links. Defaults to false.
+#isis.viewer.restfulobjects.suppressUpdateLink=true
+
+# whether to suppress "id" json-prop for object members. Defaults to false.
+#isis.viewer.restfulobjects.suppressMemberId=true
+
+# whether to suppress "links" json-prop for object members
+# (on the object representation only). Defaults to false.
+#isis.viewer.restfulobjects.suppressMemberLinks=true
+
+# whether to suppress "extensions" json-prop for object members
+# (on the object representation only). Defaults to false.
+#isis.viewer.restfulobjects.suppressMemberExtensions=true
+
+# whether to suppress "disabledReason" json-prop for object members
+# (on the object representation only). Defaults to false.
+#isis.viewer.restfulobjects.suppressMemberDisabledReason=true
+isis.viewer.restfulobjects.suppressMemberDisabledReason=true
+
+
+
+
+
+
## Exception Recognizers
@@ -583,5 +641,9 @@ TODO
TODO
+update `persistor.properties`
+
+
+
}
\ No newline at end of file
Modified: isis/site/trunk/content/more-advanced-topics/ViewModel.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/more-advanced-topics/ViewModel.md?rev=1640575&r1=1640574&r2=1640575&view=diff
==============================================================================
--- isis/site/trunk/content/more-advanced-topics/ViewModel.md (original)
+++ isis/site/trunk/content/more-advanced-topics/ViewModel.md Wed Nov 19 15:48:47 2014
@@ -1,9 +1,53 @@
-Title: ViewModel interface
+Title: ViewModels
----------
-Indicates that a domain object is intended to be used as a view model.
+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.
-### API
+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.
+
+To support these use cases, Isis therefore allows you to write a view model, either by annotating the class with [@ViewModel](http://isis.apache.org/reference/recognized-annotations/ViewModel.html) or (for more control) by implementing the `ViewModel` interface.
+
+View models are immutable; their state is in fact encoded in their identity. Editable view models can be simulated by implementing the `ViewModel.Cloneable` interface.
+
+
+## @ViewModel annotation
+
+The simplest way to create a view model is to annotate the class with `@ViewModel`:
+
+ @ViewModel
+ public class MyViewModel {
+
+ public MyViewModel() {}
+
+ ...
+
+ }
+
+View models must have a no-arg constructor, but there are few other constraints.
+
+* if the view model has dependencies on domain services, then either:
+ * instantiate using `DomainObjectContainer#newTransientInstance()` or
+ * instantiate directly and then inject explicitly using `DomainObjectContainer#injectServicesInto(.)`
+* if the view model has no dependencies on domain services, then just instantiate directly
+
+>
+> Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is for view models that implement `ViewModel` interface and can be safely ignored.
+>
+
+The view model's memento will be derived from the value of the view model object's properties. Any [@NotPersistent](http://isis.apache.org/reference/recognized-annotations/NotPersistent.html) properties will be excluded from the memento, as will any [@Programmatic](http://isis.apache.org/reference/recognized-annotations/Programmatic.html) properties. Properties that are merely [@Hidden](http://isis.apache.org/reference/recognized-annotations/Hidden.html) are included in the memento.
+
+Only properties supported by the configured [MementoService](../reference/services/memento-service.html) can be used. The default implementation supports all the value types and persisted entities.
+
+(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.
+
+
+
+## ViewModel interface
+
+Another way to indicate that a domain object is a view model is by implementing the `ViewModel` interface:
public interface ViewModel {
@@ -14,7 +58,7 @@ Indicates that a domain object is intend
public void viewModelInit(String memento);
}
-Where:
+where:
* `viewModelMemento()`
@@ -22,14 +66,12 @@ Where:
* `viewModelInit()`
- 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 `viewModelMemento()`
-
-### Usage
+ 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 `viewModelMemento()`
-Used in the example [todo app](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), for example the [ToDoAppDashboard](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) that is rendered on the home page.
+View models implemented this way must be instantiated using `DomainObjectContainer#newViewModelInstance(Class,String)`, where the second String argument is the memento of the view model, and which is passed to the view model in turn through the `viewModelInit(.)` method.
+
+The `viewModelMemento()` and `viewModelInit()` methods should be reciprocals of each other, but there are no other constraints. The [MementoService](../reference/services/memento-service.html) 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 `HttpSession` and key that state with a GUID.
-### Related Services
-The [MementoService](../reference/services/memento-service.html) provides a convenient mechanism for view models to build up and parse memento strings (for the implementation of the `viewModelMemento()` and `viewModelInit()` methods.
\ No newline at end of file
Modified: isis/site/trunk/content/reference/recognized-annotations/ViewModel.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/recognized-annotations/ViewModel.md?rev=1640575&r1=1640574&r2=1640575&view=diff
==============================================================================
--- isis/site/trunk/content/reference/recognized-annotations/ViewModel.md (original)
+++ isis/site/trunk/content/reference/recognized-annotations/ViewModel.md Wed Nov 19 15:48:47 2014
@@ -1,11 +1,34 @@
Title: @ViewModel
-{note
-This is a stub.
-}
+The `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model. View models are not persisted to the database, instead their state is encoded within their identity (ultimately represented in the URL). As such, view models are immutable.
+For example:
-Indicates that the class is a view model whose identity is inferred from the state of its (non-@NotPersisted) properties.
+ @ViewModel
+ public class MyViewModel {
+
+ public MyViewModel() {}
+
+ ...
+
+ }
-Only properties supported by the configured [MementoService](../services/memento-service.html) can be used. The default implementation supports all the value types and persisted entities. However, view models are NOT supported.
+View models must have a no-arg constructor, but there are few other constraints.
+
+* if the view model has dependencies on domain services, then either:
+ * instantiate using `DomainObjectContainer#newTransientInstance()` or
+ * instantiate directly and then inject explicitly using `DomainObjectContainer#injectServicesInto(.)`
+* if the view model has no dependencies on domain services, then just instantiate directly
+
+>
+> Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is for view models that implement `ViewModel` interface and can be safely ignored.
+>
+
+The view model's memento will be derived from the value of the view model object's properties. Any [@NotPersistent](http://isis.apache.org/reference/recognized-annotations/NotPersistent.html) properties will be excluded from the memento, as will any [@Programmatic](http://isis.apache.org/reference/recognized-annotations/Programmatic.html) properties. Properties that are merely [@Hidden](http://isis.apache.org/reference/recognized-annotations/Hidden.html) are included in the memento.
+
+Only properties supported by the configured [MementoService](../reference/services/memento-service.html) can be used. The default implementation supports all the value types and persisted entities.
+
+(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.
Modified: isis/site/trunk/content/reference/services/memento-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/memento-service.md?rev=1640575&r1=1640574&r2=1640575&view=diff
==============================================================================
--- isis/site/trunk/content/reference/services/memento-service.md (original)
+++ isis/site/trunk/content/reference/services/memento-service.md Wed Nov 19 15:48:47 2014
@@ -35,14 +35,15 @@ The types of objects that are supported
In the case of the default implementation provided by the core framework, the types supported are:
-* `String`
-* `boolean, `Boolean`
-* `byte`, `Byte`
-* `short`, `Short`
-* `int`, `Integer`
-* `long`, `Long`
-* `float`, `Float`
-* `double`, `Double`
+* `java.lang.String`
+* `java.lang.Boolean`, `boolean`
+* `java.lang.Byte`, `byte`
+* `java.lang.Short`, `short`
+* `java.lang.Integer`, `int`
+* `java.lang.Long`, `long`
+* `java.lang.Float`, `float`
+* `java.lang.Double`, `double`
+* `java.lang.Character`, `char`
* `java.math.BigDecimal`
* `java.math.BigInteger`
* `org.joda.time.LocalDate`