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/12/03 19:15:41 UTC
[23/51] [abbrv] isis git commit: ISIS-1243: moving object-layout
chapter from rg.adoc to ug.adoc
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
new file mode 100644
index 0000000..922c3a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
@@ -0,0 +1,171 @@
+[[_ug_object-layout_application-menu]]
+= Application Menu 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/
+
+
+
+The actions of domain services are made available as an application menu bar. By default each domain service
+corresponds to a single menu on this menu bar, with its actions as the drop-down menu items. This is rarely exactly
+what is required, however. The `@MemberOrder` and `@DomainServiceLayout` annotations can be used to rearrange the
+placement of menu items.
+
+The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management
+application built using Apache Isis.
+
+== @DomainServiceLayout
+
+Menus for domain services can be placed either on a primary, secondary or tertiary menu bar.
+
+image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px",link="{_imagesdir}wicket-viewer/application-menu/layout-menus.png"]
+
+Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services. The Wicket viewer
+automatically adds a divider between each:
+
+image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px",link="{_imagesdir}wicket-viewer/application-menu/dividers.png"]
+
+In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations`
+services. The `Properties` service is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.1"
+)
+public class Properties ... { ... }
+----
+
+while the `Units` service is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.2"
+)
+public class Units ... { ... }
+----
+
+and similarly `FixedAssetRegistrations` is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+ named="Fixed Assets",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "10.3"
+)
+public class FixedAssetRegistrations ... { ... }
+----
+
+Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets"
+and PRIMARY. This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
+
+Meanwhile the value of `menuOrder` attribute is significant for two reasons:
+
+* for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
+* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar.
+
+To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets"
+ because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for
+ "Fixed Assets":
+
+[source,java]
+----
+@DomainServiceLayout(
+ named="Parties",
+ menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+ menuOrder = "20.1"
+)
+public class Parties ... { ... }
+----
+
+Note that only the `menuOrder` of the _first_ domain service is significant in placing the menus along the menu bar;
+thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
+
+== Ordering menu actions
+
+For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation. Thus, for
+the `Units` domain service, its actions are annotated:
+
+[source,java]
+----
+public class Units extends EstatioDomainService<Unit> {
+
+ @MemberOrder(sequence = "1")
+ public Unit newUnit( ... ) { ... }
+
+ @MemberOrder(sequence = "2")
+ public List<Unit> findUnits( ... ) { ... }
+
+ @ActionLayout( prototype = true )
+ @MemberOrder(sequence = "99")
+ public List<Unit> allUnits() { ... }
+ ...
+}
+----
+
+Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
+In the UI it is rendered in italics.
+
+(It is possible to override this place of a given action by specifying `@MemberOrder(name="...")` where the name is
+that of a top-level menu. Prior to 1.8.0 this was the only way of doing things, as of 1.8.0 its use
+is not recommended).
+
+== Tertiary menubar
+
+The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right. This is
+intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
+
+image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px",link="{_imagesdir}wicket-viewer/application-menu/tertiary.png"]
+
+Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation. For
+example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
+
+[source,java]
+----
+@DomainServiceLayout(
+ menuBar = DomainServiceLayout.MenuBar.TERTIARY,
+ menuOrder = "10.1"
+)
+public class EstatioAdministrationService ... {
+
+ @MemberOrder(sequence = "1")
+ public void updateEpochDate( ... ) { ... }
+
+ @MemberOrder(sequence = "2")
+ public List<ApplicationSetting> listAllSettings() { ... }
+ ...
+}
+----
+
+Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the
+viewer does _not_ place dividers between actions from different services on the tertiary menu.
+
+
+== Isis Add-on modules
+
+Some of the (non-ASF) link:http://isisaddons.org[Isis Addons] modules also provide services whose actions appear in top-level menus.
+
+The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three
+top-level menus:
+
+* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and
+ `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the
+ SECONDARY menu bar
+
+* its `SecurityModuleAppFixturesService` domain service, which allows the security modules' fixture scripts to be run,
+ is placed on a "Prototyping" top-level menu, also on the SECONDARY menu bar
+
+* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
+
+Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and
+so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
+
+Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
+using security or using a xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
new file mode 100644
index 0000000..9bda79a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
@@ -0,0 +1,113 @@
+[[_ug_object-layout_dynamic]]
+= Dynamic Object 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.
+
+
+== 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]
+----
+{
+ "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, but with UI hint
+ "propertyLayout": {
+ "typicalLength": 50 // UI hint for size of field (no longer used in ISIS 1.8.0)
+ }
+ },
+ "category": {},
+ "complete": { // property, with associated actions
+ "propertyLayout": {
+ "describedAs": "Whether this todo item has been completed"
+ },
+ "actions": {
+ "completed": {
+ "actionLayout": {
+ "named": "Done", // naming UI hint
+ "cssClass": "x-highlight" // CSS UI hint
+ }
+ },
+ "notYetCompleted": {
+ "actionLayout": {
+ "named": "Not done"
+ }
+ }
+ }
+ }
+ },
+ "Misc": {
+ "members": {
+ "notes": {
+ "propertyLayout": {
+ "multiLine": 5 // UI hint for text area
+ }
+ },
+ "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
+ "collectionLayout": {
+ "paged": 10, // pagination UI hint
+ "render": "EAGERLY" // lazy-loading UI hint
+ },
+ "actions": {
+ "add":{},
+ "delete": {}
+ },
+ },
+ "similarItems": {} // collection, no associated actions
+ }
+ }
+ ],
+ "actions": { // actions not associated with any member
+ "delete": {},
+ "duplicate": {
+ "actionLayout": {
+ "named": {
+ "value": "Clone"
+ }
+ }
+ }
+ }
+}
+----
+
+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.
+
+Note also that the layout file may contain entries for xref:ug.adoc#_ug_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
+
+
+
+== Downloading an initial layout
+
+The fastest way to get started is to use the (non-ASF) link:http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module to download the layout file (derived from any existing static metadata defined by annotations).
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
new file mode 100644
index 0000000..b534e57
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
@@ -0,0 +1,26 @@
+[[_ug_object-layout_static-vs-dynamic]]
+= Static vs Dynamic Layouts
+: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/
+
+
+
+
+Using xref:ug.adoc#_ug_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app. Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
+
+Another benefit of dynamic layout is that UI hints can be provided for xref:ug.adoc#_ug_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
+
+The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class).
+
+Also, dynamic layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
+
+
+
+== Best of both worlds?
+
+Using the (non-ASF) link:http://github.com/isisaddons/isis-jrebel-plugin[Isis addons' jrebel] plugin comes close to getting the best of both words: metadata is specified in a type-safe way using annotations, but can be reloaded automatically.
+
+The downsides are licensing cost, and also the fact that metadata for contributed actions in the contributee class cannot be specified.
+
+Another open source alternative that you might also like to explore is DCEVM; there's a good write-up on the link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
new file mode 100644
index 0000000..e706944
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
@@ -0,0 +1,159 @@
+[[_ug_object-layout_static]]
+= Static Object 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 static approach, using annotations.
+
+
+
+== `@MemberOrder`
+
+The `@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:
+
+* 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". +
++
+The name of these "member groups" 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.
++
+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]
+----
+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() { ... }
+ ...
+}
+----
+
+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.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @MemberOrder(sequence="3")
+ public boolean isComplete() { ... }
+ @MemberOrder(name="complete", sequence="1")
+ public ToDoItem completed() { ...}
+ @MemberOrder(name="complete", sequence="2")
+ public ToDoItem notYetCompleted() { ...}
+
+ @MemberOrder(sequence="1")
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ @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.
+
+
+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.
+
+
+
+
+== `@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 property groups in this case are those that are inferred from the `@MemberOrder#name()` attribute.
+
+For example:
+
+[source,java]
+----
+@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 link:http://getbootstrap.com/2.3.2/[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
+
+== Example Layouts
+
+Below are sketches for the layout of the https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java[ToDoItem] class of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
+
+The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12):
+
+image::{_imagesdir}reference-layout/6-6-0-12.png[width="720px",link="{_imagesdir}reference-layout/6-6-0-12.png"]
+
+The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12):
+
+image::{_imagesdir}reference-layout/4-4-4-12.png[width="720px",link="{_imagesdir}reference-layout/4-4-4-12.png"]
+
+The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0):
+
+image::{_imagesdir}reference-layout/4-0-8-0.png[width="720px",link="{_imagesdir}reference-layout/4-0-8-0.png"]
+
+
+== Other Annotations
+
+As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`], xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`], xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
index 6aecfb2..dd5940a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-The metadata for domain objects is obtained both xref:rg.adoc#_rg_object-layout_static[statically] and xref:rg.adoc#_rg_object-layout_dynamic[dynamically].
+The metadata for domain objects is obtained both xref:ug.adoc#_ug_object-layout_static[statically] and xref:ug.adoc#_ug_object-layout_dynamic[dynamically].
The default implementation for reading dynamic layout metadata is `org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson`, which is responsible for reading from the `Xxx.layout.json` files on the classpath (for each domain entity `Xxx`).
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
index 9f8faa7..b2d0f97 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
}
----
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:rg.adoc#_rg_object-layout_dynamic[dynamic layout] JSON file:
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout] JSON file:
[source,javascript]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
index 491b3ba..fe4c2a9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
@@ -6,7 +6,7 @@
-The wicket viewer has full support for the various methods of specifying the xref:rg.adoc#_rg_object-layout[layout of objects], either statically or dynamically.
+The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ug_object-layout[layout of objects], either statically or dynamically.
Dynamic reloading is automatically supported when running in xref:rg.adoc#_rg_runtime_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered. Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
@@ -46,7 +46,7 @@ And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Is
image::{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png"]
-To learn more about how to configure these types of layout, see the xref:rg.adoc#_rg_object-layout[object layout] chapter.
+To learn more about how to configure these types of layout, see the xref:ug.adoc#_ug_object-layout[object layout] chapter.
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index 1dad8f7..e6199b5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -12,7 +12,7 @@
This reference guide describes in detail the various elements of the Apache Isis Programming Model. Most notably these are the xref:rgant.adoc#_rgant[annotations] (such as `@DomainObject`), and the reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`); it also includes various utility and supporting xref:rg.adoc#_rg_classes[classes].
-Also part of the reference manual are the details of how to influence the xref:rg.adoc#_rg_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it catalogues all the various xref:rg.adoc#_rg_runtime[configuration properties] available that influence the behaviour of the framework and the API domain services.
+Also part of the reference manual are the details of how to influence the xref:ug.adoc#_ug_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it catalogues all the various xref:rg.adoc#_rg_runtime[configuration properties] available that influence the behaviour of the framework and the API domain services.
This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*. The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
@@ -21,7 +21,6 @@ This reference guide does _not_ describe how to actually build an Apache Isis ap
include::_rg_methods.adoc[leveloffset=+1]
include::_rg_classes.adoc[leveloffset=+1]
-include::_rg_object-layout.adoc[leveloffset=+1]
include::_rg_runtime.adoc[leveloffset=+1]
include::_rg_schema.adoc[leveloffset=+1]
include::_rg_web-xml.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/b103f767/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index dcaf539..9a05fec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -30,5 +30,7 @@ include::_ug_core-concepts.adoc[leveloffset=+1]
include::_ug_getting-started.adoc[leveloffset=+1]
include::_ug_how-tos.adoc[leveloffset=+1]
+include::_ug_object-layout.adoc[leveloffset=+1]
+
include::_ug_faqs.adoc[leveloffset=+1]