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 2013/07/25 17:57:57 UTC
svn commit: r1507034 - in /isis/site/trunk/content: core/about.md
core/dynamic-layouts.md core/services/about.md
core/services/developer-utilities-service.md documentation.md
Author: danhaywood
Date: Thu Jul 25 15:57:56 2013
New Revision: 1507034
URL: http://svn.apache.org/r1507034
Log:
dynamic layout, dev utilities service
Added:
isis/site/trunk/content/core/dynamic-layouts.md
isis/site/trunk/content/core/services/developer-utilities-service.md
Modified:
isis/site/trunk/content/core/about.md
isis/site/trunk/content/core/services/about.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/core/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/about.md?rev=1507034&r1=1507033&r2=1507034&view=diff
==============================================================================
--- isis/site/trunk/content/core/about.md (original)
+++ isis/site/trunk/content/core/about.md Thu Jul 25 15:57:56 2013
@@ -13,8 +13,10 @@ Title: Core Modules
- [Initializing Services](services/initializing-services.html)
- [Auditing Service](services/auditing-service.html)
- [Bookmark Service](services/bookmark-service.html)
+- [Developer Utilities Service](services/developer-utilities-service.html) [1.3.0-SNAPSHOT]
- [Exception Recognizers](services/exception-recognizers.html)
- [Publishing Service](services/publishing-service.html)
+- [Settings Services](services/settings-services.html) [1.3.0-SNAPSHOT]
### Development
Added: isis/site/trunk/content/core/dynamic-layouts.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/dynamic-layouts.md?rev=1507034&view=auto
==============================================================================
--- isis/site/trunk/content/core/dynamic-layouts.md (added)
+++ isis/site/trunk/content/core/dynamic-layouts.md Thu Jul 25 15:57:56 2013
@@ -0,0 +1,175 @@
+Title: Dynamic Layouts
+
+Because Isis implements the [naked objects pattern](http://en.wikipedia.org/wiki/Naked_objects), the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves.
+
+## Specifying layout using Annotations
+
+### `@MemberOrder`
+
+To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used. For example:
+
+ public class ToDoItem {
+ @MemberOrder(sequence="1")
+ public String getDescription() { ... }
+
+ @MemberOrder(sequence="2")
+ public String getCategory() { ... }
+
+ @MemberOrder(sequence="3")
+ public boolean isComplete() { ... }
+
+ @MemberOrder(name="Detail", sequence="1")
+ public LocalDate getDueBy() { ... }
+
+ @MemberOrder(name="Detail", sequence="2")
+ public BigDecimal getCost() { ... }
+
+ @MemberOrder(name="Detail", sequence="4")
+ public String getNotes() { ... }
+
+ @MemberOrder(name="Misc", sequence="99")
+ public Long getVersionSequence() { ... }
+
+ ...
+
+ }
+
+defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
+
+In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the `@MemberOrder`'s `name` attribute, holding the value of the property or collection.
+
+For example:
+
+ public class ToDoItem {
+
+ @MemberOrder(sequence="3")
+ public boolean isComplete() { ... }
+
+ @MemberOrder(sequence="1")
+ public SortedSet<ToDoItem> getDependencies() { ... }
+
+
+ @MemberOrder(name="complete", sequence="1")
+ public ToDoItem completed() { ...}
+
+ @MemberOrder(name="complete", sequence="2")
+ public ToDoItem notYetCompleted() { ...}
+
+
+ @MemberOrder(name="dependencies", sequence="1")
+ public ToDoItem add(ToDoItem t) { ...}
+
+ @MemberOrder(name="dependencies", sequence="2")
+ public ToDoItem remove(ToDoItem t) { ...}
+
+ }
+
+will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
+
+If the `name` attribute is omitted, then the action is rendered near the header.
+
+Finally, note that the `@MemberOrder`'s `name` attribute has no meaning for collections.
+
+
+### `@MemberGroupLayout`
+
+The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column. It also specifies the relative width:
+
+ @MemberGroupLayout(
+ columnSpans={3,3,0,6}, left={"General", "Misc"}, middle="Detail")
+ public class ToDoItem {
+ ...
+ }
+
+Four values are given in the `columnSpans` 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.
+
+The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the [Bootstrap](http://twitter.github.io/bootstrap/) library).
+
+For example:
+
+* `{3,3,0,6}` indicates:
+ * a left column of properties taking up 25% of the width
+ * a middle column of properties taking up 25% of the width
+ * a right column of collections taking up 50% of the width
+* `{2,6,0,4}` indicates:
+ * a left column of properties taking up ~16% of the width
+ * a middle column of properties taking up 50% of the width
+ * a right column of collections taking up ~33% of the width
+* `{2,3,3,4}` indicates:
+ * a left column of properties taking up ~16% of the width
+ * a middle column of properties taking up 25% of the width
+ * a right column of properties taking up 25% of the width
+ * a far right column of collections taking up ~33% of the width
+
+If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:
+
+* {4,4,4,12} indicates:
+ * a left column of properties taking up ~33% of the width
+ * a middle column of properties taking up ~33% of the width
+ * a right column of properties taking up ~33% of the width
+ * the collections underneath the property columns, taking up the full width
+
+
+
+## Dynamic Layouts
+
+While the use of annotations to specify layout metadata is typesafe, it does have the disadvantage that changing the layout means recompiling the code and redeploying.
+
+So, instead, the layout metadata can be specified using a JSON layout file. The [`DeveloperUtilitiesService`](services/developer-utilities-service.html) can then be used to refresh the layout (rebuilding the metamodel for the domain class in question).
+
+The JSON layout file takes the name `Xxx.layout.json`, where `Xxx` is the class name, and resides in the same package as the class. For example, the layout for the [`ToDoItem`](https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java) class is [`ToDoItem.layout.json`](https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.layout.json)
+
+The format of the `.layout.json` file is:
+
+ {
+ columns: [ // list of columns
+ {
+ span: 6, // span of the left-hand property column
+ memberGroups: { // ordered map of member (property) groups
+ General: { // member group name
+ members: {
+ description: {}, // property, no associated actions
+ category: {},
+ complete: { // property, with associated actions
+ actions: {
+ completed: {}, // associated actions
+ notYetCompleted: {}
+ }
+ }
+ }
+ },
+ Misc: {
+ members: {
+ versionSequence: {}
+ }
+ }
+ }
+ },
+ {
+ span: 6, // span of the middle property column
+ memberGroups: { ... }
+ },
+ {
+ span: 0 // span of the right property column (if any)
+ },
+ {
+ span: 6,
+ collections: { // ordered map of collections
+ dependencies: { // collection, with associated actions
+ actions: {
+ add:{},
+ delete: {}
+ }
+ },
+ similarItems: {} // collection, no associated actions
+ }
+ }
+ ],
+ actions: { // actions not associated with any member
+ delete: {},
+ duplicate: {}
+ }
+ }
+
+
+Although advisable, it is not necessary to list all class members in this file. Any members not listed with be ordered according either to annotations (if present) or fallback/default values.
\ No newline at end of file
Modified: isis/site/trunk/content/core/services/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/about.md?rev=1507034&r1=1507033&r2=1507034&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/about.md (original)
+++ isis/site/trunk/content/core/services/about.md Thu Jul 25 15:57:56 2013
@@ -6,6 +6,7 @@ Title: Applib Services
- [Initializing Services](initializing-services.html)
- [Auditing Service](auditing-service.html)
- [Bookmark Service](bookmark-service.html)
+- [Developer Utilities Service](developer-utilities-service.html) [1.3.0-SNAPSHOT]
- [Exception Recognizers](exception-recognizers.html)
- [Publishing Service](publishing-service.html)
- [Settings Services](settings-services.html) [1.3.0-SNAPSHOT]
Added: isis/site/trunk/content/core/services/developer-utilities-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/developer-utilities-service.md?rev=1507034&view=auto
==============================================================================
--- isis/site/trunk/content/core/services/developer-utilities-service.md (added)
+++ isis/site/trunk/content/core/services/developer-utilities-service.md Thu Jul 25 15:57:56 2013
@@ -0,0 +1,31 @@
+Title: Developer Utilities Service
+
+The `DeveloperUtilitiesService` service is intended to make the developer's job easier in a number of aspects:
+
+* using the `downloadMetaModel()` action, the developer can download a CSV spreadsheet of the Isis metamodel.
+
+ This allows the developer to review the metadata that has Isis has captured about each domain type: for example whether a business rule (hide/disable/validate) has been implemented for each member (also indicating the implementation)
+
+* using the `downloadLayouts()` action, the developer can download a ZIP file of `Xxx.layout.json` files for each domain type in the Isis metamodel.
+
+ This is useful if converting a domain model to use [dynamic layouts](../dynamic-layouts.html).
+
+* using the `downloadLayout()` contributed action, the developer can download the `Xxx.layout.json` for an individual object
+
+* using the `refreshLayout()` contributed action, the developer can reload the current object. The metamodel will be rebuilt and the object's layout may change accordingly.
+
+ > (If using the [Wicket viewer](../../components/viewers/wicket/about.html)) it is necessary to invoke `refreshLayout()` *twice*. This is to do with the relationship between the point at which the metamodel being invalidated, and the point the Wicket viewer builds up its UI.
+
+All of the above actions are annotated as `@Prototype`; they will therefore not appear in a running production application.
+
+### Register the Service
+
+The service is registered, like any other, in `isis.properties`:
+
+<pre>
+isis.services=<i>...other services...</i>,\
+ org.apache.isis.core.metamodel.services.devutils.DeveloperUtilitiesServiceDefault,\
+ ...
+</pre>
+
+
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1507034&r1=1507033&r2=1507034&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Thu Jul 25 15:57:56 2013
@@ -73,9 +73,11 @@ Guidance for committers is at the bottom
- [Initializing Services](core/services/initializing-services.html)
- [Auditing Service](core/services/auditing-service.html)
- [Bookmark Service](core/services/bookmark-service.html)
-- [Exception Recognizers](core/services/exception-recognizers.html)
+- [Developer Utilities Service](core/services/developer-utilities-service.html) [1.3.0-SNAPSHOT]
+- [Exception Recognizers](core/services/exception-recognizers.html)
- [Publishing Service](core/services/publishing-service.html)
-- [Settings Services](core/services/settings-services.html) [1.3.0-SNAPSHOT]
+- [Settings Services](core/services/settings-services.html) [1.3.0-SNAPSHOT]
+
}