Repository: isis Updated Branches: refs/heads/master 4f3932d38 -> fa4c9c1f7
ISIS-993: documentation on XML layouts. Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/fa4c9c1f Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/fa4c9c1f Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/fa4c9c1f Branch: refs/heads/master Commit: fa4c9c1f71766e31171935dc40c0f528359bd09b Parents: 4f3932d Author: Dan Haywood <d...@haywood-associates.co.uk> Authored: Fri Mar 4 17:42:56 2016 +0000 Committer: Dan Haywood <d...@haywood-associates.co.uk> Committed: Fri Mar 4 17:42:56 2016 +0000 ---------------------------------------------------------------------- .../asciidoc/guides/_ugfun_object-layout.adoc | 1 + .../guides/_ugfun_object-layout_dynamic.adoc | 15 ++++++- .../_ugfun_object-layout_dynamic_xml.adoc | 28 +++++++++++++ .../guides/_ugfun_object-layout_static.adoc | 44 +++++++++++++------- 4 files changed, 70 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/fa4c9c1f/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc index add6b42..7347e0e 100644 --- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc @@ -11,6 +11,7 @@ In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pat This chapter describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions). include::_ugfun_object-layout_static.adoc[leveloffset=+1] +include::_ugfun_object-layout_dynamic_xml.adoc[leveloffset=+1] include::_ugfun_object-layout_dynamic.adoc[leveloffset=+1] include::_ugfun_object-layout_application-menu.adoc[leveloffset=+1] include::_ugfun_object-layout_static-vs-dynamic.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/fa4c9c1f/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc index 53c488c..e2379c8 100644 --- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc @@ -1,17 +1,28 @@ [[_ugfun_object-layout_dynamic]] -= Dynamic Object Layout += Dynamic (JSON) Layout :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. :_basedir: ../ :_imagesdir: images/ -Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file. This section describes the dynamic approach, using the file. +Metadata providing UI hints can be specified either xref:ugfun.adoc#_ugfun_object-layout_static[statically], using annotations, or dynamically, using either a xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[``layout.xml``] file or (as described here) a `.layout.json` file. +[IMPORTANT] +==== +(As of `1.12.0-SNAPSHOT`), the use of dynamic layouts through the `.layout.json` is DEPRECATED. + +The `.layout.json` file will be ignored if a `.layout.xml` file is present. It is possible to download initial `.layout.xml` files - which will capture all the metadata originally in the `.layout.json` file - using the xref:rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`] (exposed on the prototyping menu). + +The ``.layout.xml`` file also allows enables much more sophisticated custom layouts than those afforded by ``.layout.json``, and the layout files are easier to write due to the presence of an XSD schema file which ensures that the file is syntactically correct. +==== + == JSON layout file The JSON layout file for class `Xxx` takes the name `Xxx.layout.json`, and resides in the same package as the class. + + The format of the file is: [source,javascript] http://git-wip-us.apache.org/repos/asf/isis/blob/fa4c9c1f/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc new file mode 100644 index 0000000..32ee071 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc @@ -0,0 +1,28 @@ +[[_ugfun_object-layout_dynamic_xml]] += Dynamic (XML) Layout (`1.12.0-SNAPSHOT`) +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +:_basedir: ../ +:_imagesdir: images/ + + + +Metadata providing UI hints can be specified either xref:ugfun.adoc#_ugfun_object-layout_static[statically], using annotations, or dynamically using an `Xxx.layout.xml` file (where `Xxx` is the entity or view model object to be rendered). + +A corresponding XSD schema for the XML file makes it easy to author such layout files. It is also possible to download an initial `.layout.xml` - capturing any existing layout metadata using the xref:rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`] (exposed on the prototyping menu). + +[TIP] +==== +It is also possible to describe dynamic layouts using a `.layout.json` file, as discussed xref:ugfun.adoc#_ugfun_object-layout_dynamic[here]. As of `1.12.0-SNAPSHOT` the `.layout.json` file should be considered as deprecated: the ``.layout.xml`` file also allows enables much more sophisticated custom layouts than those afforded by ``.layout.json``, and the layout files are easier to write due to the presence of an XSD schema file which ensures that the file is syntactically correct. +==== + +== Grids vs Components + +The XML file distinguishes between two types of element: + +* those that define a grid structure, of: rows, columns, tabgroups and tabs. + ++ +The rows and columns are closely modelled on link:getbootstrap.com[bootstrap 3] (used in the implementation of the xref:ugvw.adoc[Wicket viewer]). + +* those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself. + +These two different element types have their own XSD namespaces. In principle this allows the layout engine \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/fa4c9c1f/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc index 487abb8..79b3b4d 100644 --- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc @@ -5,33 +5,36 @@ :_imagesdir: images/ -Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file. This section describes the static approach, using annotations. +Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using either a `layout.xml` file (`1.12.0-SNAPSHOT`) or a `.layout.json` file. + +This section describes the static approach, using annotations. == `@MemberOrder` -The `@MemberOrder` annotation is used to specify the relative order of domain class properties, collections and actions. +The xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation is used to specify the relative order of domain class properties, collections and actions. -The annotation defines two attributes, `name()` and `sequence()`. Their usage depends on the member type: +The annotation defines two attributes, xref:rgant.adoc#_rgant_MemberOrder_name[`name()`] and xref:rgant.adoc#_rgant_MemberOrder_sequence[`sequence()`]. Their usage depends on the member type: -* for properties, the `name()` is used to group properties together. The `sequence()` then orders properties within these groups. If no `name()` is specified then the property is placed in a fallback "General" group, called "General". + +* for properties, the `name()` is used to group properties together into a member group (also called a property group or (in `1.12.0-SNAPSHOT`) a fieldset. The `sequence()` then orders properties within these groups. If no `name()` is specified then the property is placed in a fallback "General" group, called "General". + + -The name of these "member groups" are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]. +The name of these member groups/fieldsets are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]. * for collections, the `name()` attribute is (currently) unused. The `sequence()` orders collections relative to one another * for actions, the `name()` attribute associates an action with either a property or with a collection. + -+ -If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. + -+ -On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header. + -+ -If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title. -+ + +** If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. + + +** On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header. + +** If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title. + Within any of these, the `sequence()` then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing". + For example: [source,java] @@ -57,7 +60,7 @@ public class ToDoItem { This 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. +In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:rgant.adoc#_rgant_MemberOrder_name[`name()`] attribute, holding the value of the property or collection. For example: @@ -84,16 +87,25 @@ public class ToDoItem { will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection. -The value of `sequence()` is a string. The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers. A useful alternative is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion. It also allows subclasses to insert their class members as required. +The value of xref:rgant.adoc#_rgant_MemberOrder_sequence[`sequence()`] is a string. The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers. + +Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion. It also allows subclasses to insert their class members as required. == `@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. The annotation also specifies the relative width of the columns. +The xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column. The annotation also specifies the relative width of the columns. + +The property groups/fieldsets in this case are those that are inferred from the `@MemberOrder#name()` attribute. + +[TIP] +==== +It is also possible to combine `@MemberOrder` with dynamic layouts, either using xref:ugfun.adoc#_ugfun_object-layout_xml[XML] (`1.12.0-SNAPSHOT`) or xref:ugfun.adoc#_ugfun_object-layout_dynamic[JSON]. The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions. The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid. -The property groups in this case are those that are inferred from the `@MemberOrder#name()` attribute. +When dynamic layouts are used this way, the xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]) are all still honoured. +==== For example:
