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`
