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 2015/06/01 19:24:08 UTC
isis git commit: ISIS-1133: working on the annotations.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 6192bae99 -> a4d2c55c4
ISIS-1133: working on the annotations.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/a4d2c55c
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/a4d2c55c
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/a4d2c55c
Branch: refs/heads/ISIS-1133
Commit: a4d2c55c48b9950a4852664395ad930d53a4efed
Parents: 6192bae
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Jun 1 18:24:03 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Jun 1 18:24:03 2015 +0100
----------------------------------------------------------------------
...erence-annotations_manpage-ActionLayout.adoc | 6 +-
...ce-annotations_manpage-CollectionLayout.adoc | 26 ++++---
...-annotations_manpage-DomainObjectLayout.adoc | 28 ++++---
...nce-annotations_manpage-ParameterLayout.adoc | 10 ++-
...ence-annotations_manpage-PropertyLayout.adoc | 82 ++++++++++----------
...ns_manpage-PropertyLayout_labelPosition.adoc | 25 ++++++
...nce-annotations_manpage-ViewModelLayout.adoc | 35 +++++----
.../_ug_runtime_configuring-core.adoc | 44 ++++++++++-
8 files changed, 167 insertions(+), 89 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
index 24dcaa6..d20a718 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
@@ -34,7 +34,7 @@ For a domain service action to be contributed, the domain services must have a x
|xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`cssClass()`]
|Any string valid as a CSS class
-|an additional CSS class around the HTML that represents for the action, to allow additional styling. +
+|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]. +
Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
@@ -43,8 +43,6 @@ Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by
|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
|specify a font awesome icon for the action's menu link or icon. +
-Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-
|`cssClassFaPosition()`
|`LEFT`, `RIGHT` +
@@ -58,7 +56,7 @@ Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by
|xref:_ug_reference-annotations_manpage-ActionLayout_hidden[`hidden()`]
-|`EVERYWHERE`,`NOWHERE` +
+|`EVERYWHERE`, `NOWHERE` +
(`NOWHERE`)
|indicates where (in the UI) the action should be hidden from the user.
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
index 2d19314..c93603d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
@@ -20,23 +20,26 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[`cssClass()`]
-|
+|Any string valid as a CSS class
|the css class that a collection should have, to allow more targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]
|xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[`describedAs()`]
-|
+|String.
|description of this collection, eg to be rendered in a tooltip.
|xref:_ug_reference-annotations_manpage-CollectionLayout_hidden[`hidden()`]
-|
-|indicates where in the UI the collection should _not_ be visible in the UI (only NOWHERE or EVERWHERE/ANYWHERE)
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
|xref:_ug_reference-annotations_manpage-CollectionLayout_named[named()]
-|
-|the name of this collection (overriding the name derived from its name in code)
+|String.
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
|namedEscaped()
@@ -45,18 +48,19 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-CollectionLayout_paged[`paged()`]
-|
+|Positive integer
|the page size for instances of this class when rendered within a table.
|xref:_ug_reference-annotations_manpage-CollectionLayout_render[`render()`]
-|
-|that the rendering of a collection should be performed LAZILY or EAGERLY
+|`EAGERLY`, `LAZILY` +
+(`LAZILY`)
+|whether the collection should be (eagerly) rendered open or (lazily) rendered closed
|xref:_ug_reference-annotations_manpage-CollectionLayout_sortedBy[`sortedBy()`]
-|
-|indicates that the elements in a ({@link java.util.SortedSet}) collection should be sorted according to a different order than the natural sort order, as defined by the specified `Comparator`.
+|Subclass of `java.util.Comparator` for element type
+|indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
index 77363fc..55f0b60 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
@@ -21,43 +21,47 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking[`bookmarking()`]
-|
-|
+|`AS_ROOT`, `AS_CHILD`, `NEVER` +
+(`NEVER`)
+|whether (and how) this domain object should be automatically bookmarked
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssclass[`cssClass()`]
-|
+|Any string valid as a CSS class
|the css class that a domain class (type) should have, to allow more targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`cssClassFa()`]
-|
-|the name of this class (overriding the name derived from its name in code)
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
|`cssClassFaPosition()`
-|
-|the name of this class (overriding the name derived from its name in code)
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Currently unused.
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
-|
+|String.
|description of this class, eg to be rendered in a tooltip.
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[`named()`]
-|
-|
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[`paged()`]
-|
+|Positive integer
|the page size for instances of this class when rendered within a table.
|xref:_ug_reference-annotations_manpage-DomainObjectLayout_plural[`plural()`]
-|
+|String.
|the plural name of the class
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
index 5276c61..736055f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
@@ -20,7 +20,7 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[`cssClass()`]
-|
+|Any string valid as a CSS class
|the css class that a parameter should have, to allow more targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]
@@ -41,12 +41,14 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-ParameterLayout_named[`named()`]
|
-|the name of this parameter. For Java 7 this is generally required. For Java 8, the name can be inferred from the code so this attribute allows the name to be overridden.
+|the name of this parameter. +
+
+For Java 7 this is generally required. For Java 8, the name can often be inferred from the code so this attribute allows the name to be overridden. A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
|`namedEscaped()`
-|
-|whether to HTML escape the name of this parameter. Defaults to true.
+|`true`, `false` (`true`)
+|whether to HTML escape the name of this parameter.
|xref:_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
index b0d44c2..097203b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
@@ -20,42 +20,67 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[`cssClass()`]
-|
+|Any string valid as a CSS class
|the css class that a property should have, to allow more targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]
|xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[`describedAs()`]
-|
+|String
|description of this property, eg to be rendered in a tooltip.
+|xref:_ug_reference-annotations_manpage-PropertyLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
+
+
|xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition()`]
-|
-|in forms, the positioning of the label (LEFT, TOP or NONE) relative to the property value. For boolean properties it is also possible to specify RIGHT. Defaults to LEFT unless `multiLine` also specified (see below)
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Defaults is `LEFT`, unless xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[`multiLine`] in which case `TOP`. The value `RIGHT` is only supported for boolean properties. +
+
+It is also possible to change the default through a xref:_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
|xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[`multiLine()`]
-|
-|for string propertys, render as a text area over multiple lines. If set >1, then `labelPosition` defaults to TOP unless otherwise specified.
+|Positive integer
+|for string propertys, render as a text area over multiple lines. +
+
+If set >1, then xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
|xref:_ug_reference-annotations_manpage-PropertyLayout_named[`named()`]
-|
-|the name of this property. For Java 7 this is generally required. For Java 8, the name can be inferred from the code so this attribute allows the name to be overridden.
+|String
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
|`namedEscaped()`
-|
-|whether to HTML escape the name of this property. Defaults to true.
+|`true`, `false` +
+(`true`)
+|whether to HTML escape the name of this property.
|xref:_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
-|
-|for date propertys only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
+|`true`, `false` +
+(`false`)
+|for date propertys only, render the date as one day prior to the actually stored date. +
+
+Useful for persisting an open interval, eg: +
+
+`[1-Apr-2015, 1-Jun-2015)` +
+
+but presenting the data as if a closed interval +
+
+`[1-Apr-2015, 31-May-2015]`.
|xref:_ug_reference-annotations_manpage-PropertyLayout_typicalLength[`typicalLength()`]
-|
+|Positive integer.
|the typical entry length of a field, use to determine the optimum width for display
|===
@@ -68,14 +93,14 @@ For example:
[source,java]
----
public class ToDoItem {
-
@PropertyLayout(
cssClass="x-key",
named="Description of this <i>item</i>",
namedEscaped=false,
describedAs="What needs to be done",
labelPosition=LabelPosition.LEFT,
- typicalLength=80)
+ typicalLength=80
+ )
public String getDescription() { ... }
@PropertyLayout(
@@ -83,7 +108,6 @@ public class ToDoItem {
labelPosition=LabelPosition.TOP,
multiLine=8)
public String getNotes() { ... }
-
...
}
----
@@ -125,32 +149,6 @@ As an alternative to using the `@PropertyLayout` annotation, a dynamic layout us
}
----
-[TIP]
-.Specifying a default setting for label positions
-====
-If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
-frustrating to have to annotate every property.
-
-Instead, a default can be specified in `isis.properties`:
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=LEFT
-----
-
-If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
-====
-
-
-IMPORTANT: TODO - ensure these properties are in the runtime config chapter
-
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
index 6dbc574..6e8e266 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
@@ -15,3 +15,28 @@ can be used instead, eg:
[source,javascript]
----
----
+
+
+
+[TIP]
+.Specifying a default setting for label positions
+====
+If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
+
+Instead, a default can be specified in `isis.properties`:
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=TOP
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
index a7cbd9a..fb07d64 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
@@ -20,39 +20,44 @@ The table below summarizes the annotation's attributes.
| Description
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[`cssClass()`]
-|
-|
+|xref:_ug_reference-annotations_manpage-ViewModelLayout_cssclass[`cssClass()`]
+|Any string valid as a CSS class
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:_ug_runtime_application-specific_application-css[`application.css`]
|xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[`cssClassFa()`]
-|
-|
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
|`cssClassFaPosition()`
-|
-|
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Currently unused.
|xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[`describedAs()`]
-|
-|
+|String.
+|description of this class, eg to be rendered in a tooltip.
+
|xref:_ug_reference-annotations_manpage-ViewModelLayout_named[`named()`]
-|
-|
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
|xref:_ug_reference-annotations_manpage-ViewModelLayout_paged[`paged()`]
-|
-|
+|Positive integer
+|the page size for instances of this class when rendered within a table.
|xref:_ug_reference-annotations_manpage-ViewModelLayout_plural[`plural()`]
-|
-|
+|String.
+|the plural name of the class
+
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/a4d2c55c/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
index 1061659..4969544 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
@@ -112,12 +112,31 @@ See xref:_ug_extending_programming-model_custom-validator[Custom Validator] to l
See xref:_ug_extending_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
+|`isis.viewers.` +
+`propertyLayout.labelPosition`
+|`TOP`, `LEFT` +
+(`LEFT`)
+|Default for label position for all properties if not explicitly specified using xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
+
|===
+[source,ini]
+----
+
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+
[[_ug_runtime_configuring-core_isis-objects-editing]]
-== `isis.objects.editing`
+== `objects.editing`
This configuration property in effect allows editing to be disabled globally for an application:
@@ -128,3 +147,26 @@ isis.objects.editing=false
We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+
+
+[[_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition]]
+== `propertyLayout.labelPosition`
+
+If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
+frustrating to have to annotate every property.
+
+Instead, a default can be specified in `isis.properties`:
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=TOP
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.