You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 10:38:01 UTC
[22/50] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to
ugfun.adoc. Added standard section to each of the guides so can navigate
between each easily.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
deleted file mode 100644
index 0c582d2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_how-tos_ui-hints]]
-= UI Hints
-: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 Apache Isis programming model includes several mechanisms for a domain object to provide UI hints. These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
-
-include::_ug_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
-include::_ug_how-tos_ui_are-you-sure.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index 2bf891d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_how-tos_ui-hints_action-icons-and-css]]
-= Action Icons and CSS
-: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/
-
-
-Apache Isis allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
-
-These UI hint can be applied either to individual actions, or can be applied en-masse using pattern matching.
-
-== Per action
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
-
-
-Alternatively, you can specify these hints dynamically in the xref:ug.adoc#_ug_object-layout[`Xxx.layout.json`] for the entity.
-
-
-== Per pattern matching
-
-Rather than annotating every action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
-
-The xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClassFa.patterns=\
- new.*:fa-plus,\
- add.*:fa-plus-square,\
- create.*:fa-plus,\
- list.*:fa-list, \
- all.*:fa-list, \
- download.*:fa-download, \
- upload.*:fa-upload, \
- execute.*:fa-bolt, \
- run.*:fa-bolt
-----
-
-where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
-
-
-Similarly, the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClass.patterns=\
- delete.*:btn-warning
-----
-
-where (again)the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex.
-
-[TIP]
-====
-We strongly recommend that you use this technique rather than annotating each action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`]. Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index 0e92f5f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_how-tos_ui-hints_eager-rendering]]
-= Eager rendering
-: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/
-
-
-By default, collections all rendered lazily, in other words in a "collapsed" table view:
-
-NOTE: TODO - screenshot here
-
-For the more commonly used collections we want to show the table expanded:
-
-NOTE: TODO - screenshot here
-
-For this we annotate the collection using the `@CollectionLayout(render=RenderType.EAGERLY`; for example
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-@Collection
-@CollectionLayout(
- render = RenderType.EAGERLY
-)
-public Set<ToDoItem> getDependencies() {
- return dependencies;
-}
-----
-
-Alternatively, it can be specified the `Xxx.layout.json` file:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": {
- "render": "EAGERLY"
- },
-}
-----
-
-[WARNING]
-====
-It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", defaultFetchGroup="true")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-...
-----
-
-While this can be done, it's likely to be a bad idea, because doing so will cause DataNucleus to query for more data than required even if the object is being rendered within some referencing object's table.
-
-Of course, your mileage may vary, so don't think you can't experiment.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index 92c0be8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_how-tos_ui-hints_layout]]
-= 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/
-
-
-See the xref:ug.adoc#_ug_object-layout[object layout] chapter.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index dbb56dd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ug_how-tos_ui-hints_names-and-descriptions]]
-= Names and Descriptions
-: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/
-
-NOTE: TODO
-
-
-
-NOTE: see also xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[Internationalization]
-
-== Class (object)
-
-NOTE: TODO - xref:rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
-
-
-== Property
-
-NOTE: TODO - xref:rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
-
-
-
-== Collections
-
-NOTE: TODO - xref:rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
-
-
-
-== Actions
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
-
-
-[TIP]
-====
-If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation. Support for this can be found in the link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF). (In the future we'll fold this into core). See also our guidance on xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading to Java 8].
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 1ec22ed..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_ug_how-tos_ui-hints_object-titles-and-icons]]
-= Object Titles and Icons
-: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/
-
-
-In Apache Isis every object is identified to the user by a title (label) and an icon. This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon. This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-It is also possible for an object to provide a CSS class hint. In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-
-== Object Title
-
-The object title is a label to identify an object to the end-user. Generally the object title is a label to identify an object to the end-user. There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object's likely to be rendered on the same page.
-
-The title is always shown with an icon, so there is generally no need for the title to include information about the object's type. For example the title of a customer object shouldn't include the literal string "Customer"; it can just have the customer's name, reference or some other meaningful business identifier.
-
-
-=== Declarative style
-
-The xref:rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Title(sequence="1", append=" ")
- public String getFirstName() { ... }
- @Title(sequence="2")
- public Product getLastName() { ... }
- ...
-}
-----
-
-might return "Arthur Clarke", while:
-
-[source,java]
-----
-public class CustomerAlt {
- @Title(sequence="2", prepend=", ")
- public String getFirstName() { ... }
-
- @Title(sequence="1")
- public Product getLastName() { ... }
- ...
-}
-----
-
-could return "Clarke, Arthur".
-
-Note that the sequence is in Dewey Decimal Format. This allows a subclass to intersperse information within the title. For example (please forgive this horrible domain modelling (!)):
-
-
-[source,java]
-----
-public class Author extends Customer {
- @Title(sequence="1.5", append=". ")
- public String getMiddleInitial() { ... }
- ...
-}
-----
-
-could return "Arthur C. Clarke".
-
-
-[TIP]
-====
-Titles can sometimes get be long and therefore rather cumbersome in "parented" tables. If `@Title` has been used then the Wicket viewer will automatically exclude portions of the title belonging to the owning object.
-====
-
-
-=== Imperative style
-
-NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
-
-
-
-
-== Object Icon
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon. This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
-
-
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class]. In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
deleted file mode 100644
index 2ce9903..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ug_how-tos_ui_are-you-sure]]
-= 'Are you sure?' idiom
-: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/
-
-
-Sometimes an action might perform irreversible changes. In such a case it's probably a good idea for the UI to require that the
-end-user explicitly confirms that they intended to invoke the action.
-
-== Using action semantics
-
-One way to meet this requirement is using the framework's built-in xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
-
-[source,java]
-----
-@Action(
- semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
-)
-public SimpleObject updateName(
- @Parameter(maxLength = NAME_LENGTH)
- @ParameterLayout(named = "New name")
- final String name) {
- setName(name);
- return this;
-}
-----
-
-
-This will render as:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
-
-
-== Using a checkbox
-
-An alternative approach (for all versions of the framework) is to require the end-user to check a dummy checkbox parameter (and prevent the action from being invoked if the user hasn't checked that parameter).
-
-For example:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
-
-[NOTE]
-====
-Note that these screenshots shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-If the user checks the box:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
-
-then the action will complete.
-
-However, if the user fails to check the box, then a validation message is shown:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
-
-
-
-The code for this is pretty simple:
-
-[source,java]
-----
-public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
- container.removeIfNotAlready(this);
- container.informUser("Deleted " + container.titleOf(this));
- return toDoItems.notYetComplete(); // <1>
-}
-public String validateDelete(boolean areYouSure) {
- return areYouSure? null: "Please confirm you are sure";
-}
-----
-<1> invalid to return `this` (cannot render a deleted object)
-
-Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
deleted file mode 100644
index abd4e99..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_object-layout]]
-= 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/
-
-
-In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis aims to infer as much information from the domain classes as possible. Nevertheless, some metadata relating solely to the UI is inevitably required.
-
-
-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::_ug_object-layout_static.adoc[leveloffset=+1]
-include::_ug_object-layout_dynamic.adoc[leveloffset=+1]
-include::_ug_object-layout_application-menu.adoc[leveloffset=+1]
-include::_ug_object-layout_static-vs-dynamic.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/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
deleted file mode 100644
index 922c3a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-[[_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/1ad82470/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
deleted file mode 100644
index 9bda79a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_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/1ad82470/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
deleted file mode 100644
index b534e57..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_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/1ad82470/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
deleted file mode 100644
index e706944..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-[[_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/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
index 9671be1..9587662 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
@@ -6,7 +6,7 @@
As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
[TIP]
====
@@ -44,13 +44,13 @@ Add the following dependency to the `webapp` project's `pom.xml`:
----
<1> for Isis v1.9.0, use the value shown. for Isis v1.8.0, use 3.2.3.
-In the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
+In the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
== Try it out!
If you want to quickly try out neo4j for yourself:
-* run the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
+* run the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
* build the app:
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
index abf48c8..29a75c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
@@ -15,7 +15,7 @@ singletons, whereas mixins are instantiated as required (by the framework) and t
For more on contributed services:
-* the syntax of writing contributed actions/properties/collections is described in this xref:ug.adoc#_ug_how-tos_contributed-members[how-to]
+* the syntax of writing contributed actions/properties/collections is described in this xref:ug.adoc#_ugfun_how-tos_contributed-members[how-to]
* there's also useful information in the reference guide, discussing the xref:rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index e119bac..b7064a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -110,7 +110,7 @@ However, for an application to be fully internationalized, any validation messag
The first part of the puzzle is tackled by an extension to Apache Isis' programming model. Whereas previously the `disableXxx()` / `validateXxx()` / `title()` methods could only return a `java.lang.String`, they may now optionally return a `TranslatableString` (defined in Isis applib) instead.
-Here's a (silly) example from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's a (silly) example from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
index 214fcd6..a9e523d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
@@ -87,7 +87,7 @@ what the use cases are that those domain entities are trying to support. You ce
domain layer that could support every conceivable use case before starting to think about view models.
Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
-business. Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+business. Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
with the system (perhaps automating several related use cases together).
****
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
index 0af1926..31777f3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
@@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m
[TIP]
====
-Isis' xref:ug.adoc#_ug_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:ug.adoc#_ugfun_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/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 dd5940a..d684ac1 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:ug.adoc#_ug_object-layout_static[statically] and xref:ug.adoc#_ug_object-layout_dynamic[dynamically].
+The metadata for domain objects is obtained both xref:ug.adoc#_ugfun_object-layout_static[statically] and xref:ug.adoc#_ugfun_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/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
new file mode 100644
index 0000000..9c825e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
@@ -0,0 +1,22 @@
+[[_ugfun_core-concepts]]
+= Core Concepts
+: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/
+
+This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
+
+[TIP]
+====
+Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'. We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
+====
+
+
+include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_building-blocks.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_add-ons.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_other-deployment-options.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
new file mode 100644
index 0000000..8c031b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
@@ -0,0 +1,35 @@
+[[_ugfun_core-concepts_add-ons]]
+= Isis Add-ons
+: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 link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into four broad groups:
+
+* modules that provide an implementations of API defined by Apache Isis +
++
+where Apache Isis has hooks to use the service if defined by provides no implementations of its own. The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security] and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects. The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer utilities +
++
+Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use. The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
+
+Each of the modules has a full README and example application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
new file mode 100644
index 0000000..b194875
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
@@ -0,0 +1,335 @@
+[[_ugfun_core-concepts_building-blocks]]
+= Building Blocks
+: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/
+
+In this section we run through the main building blocks that make up an Apache Isis application.
+
+[[_ugfun_core-concepts_building-blocks_metamodel]]
+== A MetaModel
+
+At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
+with optional supporting metadata (eg `Customer.layout.json`).
+
+The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and
+supporting services, as well the members of those classes. The detail of the metamodel is generally explicit, usually
+represented by Java annotations such as `@Title` or `@Action`. Notably the metamodel is
+xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming
+conventions/rules (and conversely to remove those that are built in).
+
+Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the
+`@Title` annotation - which identifies how the framework should derive a human-readable label for each rendered
+domain object - is part of the `org.apache.isis.applib.annotations` package. However the framework also recognizes
+certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
+
+The framework uses DataNucleus for its persistence mechanism. This is an ORM that implements the JDO and JPA APIs, and
+which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J. Apache Isis
+recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowNulls=...)`.
+
+In addition, the framework builds up the metamodel for each domain object using
+xref:ug.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`. These provide metadata such as
+grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the
+application is still running, and are picked up automatically; a useful way to speed up feedback.
+
+[TIP]
+====
+At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
+in the future. We also expect to generalize support for `.layout.json` to be able to read such metadata from other
+sources.
+====
+
+
+[[_ugfun_core-concepts_building-blocks_types-of-domain-objects]]
+== Type of Domain Objects
+
+Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and
+so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
+annotations. From the end-user's perspective the UI displays a single domain object per page; they can then inspect
+and modify its state, and navigate to related objects.
+
+The next type of domain object to discuss is *domain services*. These are (usually) singleton stateless services
+that provide additional functionality. The behaviour of these services is rendered in various ways, though the most
+obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
+
+Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
+object; this includes domain entities as well as other services. This injection of domain services into entities is
+significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
+supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic
+domain model anti-pattern.
+
+As well as domain entities - mapped to a datastore - Apache Isis also supports *view models*. End users interact with
+view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other. However
+view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or
+more underlying entities. Their state is serialized and recreated from their internal identifier; this identifier is
+visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or
+xref:ugvro.adoc#[RestfulObjects viewer].
+
+There's no need though for the view model to aggregate the state of regular domain entities. A view model could also
+be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
+representation of state held in-memory (such as user preferences, for example).
+
+There are also several types of domain services. Most easily described are those domain services (discussed above)
+that are represented as the menu actions on top-level menu bars. Another variation are *contributed services* - domain
+services that contribute behaviour or (derived) state to entities/view models. Finally domain services may also
+simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
+google-maps API.
+
+Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
+being annotated with `@javax.enterprise.context.RequestScoped`. An example of the request-scoped service is the
+xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
+
+The final type of domain object is the *mixin*. These are similar to contributed services in that they also contribute (or rather,
+mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services,
+with a cleaner programming model similar to traits found in other languages.
+
+The diagram below summarizes the various types of domain object:
+
+image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
+
+
+The Apache Isis programming model uses annotations to distinguish these object types:
+
+* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`. Which is used is
+a matter of personal preference. +
++
+It is also possible to implement the `ViewModel` interface, for finer-grained control.
+
+* *domain entities* that are persisted to the database (as the vast majority will) are annotated with
+`@DomainObject(nature=ENTITY)`. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+`@javax.jdo.annotations.PersistenceCapable`. +
++
+In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
+in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
+
+* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`. As for view models, which is
+used is a matter of personal preference.
+
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either
+`VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY`
+(for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).
++
+It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
+This is in fact the default, useful for initial prototyping. A final nature is `VIEW_REST_ONLY` which is for domain
+services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
+
+Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
+stateless. If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be
+`@RequestScoped` so that this state is short-lived and usable only within a single request.
+
+
+
+[[_ugfun_core-concepts_building-blocks_objects-members]]
+== Object Members
+
+Every domain object in Apache Isis consists of (at most) three types of members:
+
+* properties, such as a `Customer`'s `firstName
+
+* collections, such as a `Customer`'s `orders` collection of ``Order``s
+
+* actions, such as a `Customer'`s `placeOrder(...)` method.
+
+Some domain objects - specifically domain services and mixins - only have actions. In the case of contributing services
+and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
+collections on the entity/view model to which they contribute/mix-in.
+
+
+=== Properties
+
+Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
+entity or view model).
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+ private String firstName;
+ public String getFirstName() { return firstName; }
+ public void setFirstName(String firstName) { this.firstName = firstName; }
+ ...
+}
+----
+
+the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
+
+
+=== Collections
+
+Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+ private SortedSet<Order> orders = new TreeSet<Order>();
+ public SortedSet<Order> getOrders() { return orders; }
+ public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
+ ...
+}
+----
+
+the framework infers the `orders` _collection_.
+
+[TIP]
+====
+The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational
+database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
+rendered in the UI they will be ordered "meaningfully" to the end-user.
+====
+
+
+=== Actions
+
+The third type of object member is actions. (To a first approximation), actions are all public methods that do not
+represent properties or collections.
+
+For example:
+
+[source,java]
+----
+public class Customer
+ public Customer placeOrder(Product p, int quantity) { ... }
+ ...
+}
+----
+
+corresponds to the `placeOrder` _action_.
+
+[NOTE]
+====
+The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods
+each of which has its own prefix such as `hide`, `disable` or `validate`. These can be considered as "reserved words"
+in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
+====
+
+
+
+== Entities vs View Models
+
+When developing an Apache Isis application you will most likely start off with the persistent domain entities:
+`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes,
+then you may need to look beyond just domain entities.
+
+To support these use cases we support view models. In the same way that an (RDBMS) database view can aggregate and
+abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
+
+View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain
+entities. Indeed, to a user of the system there is no particular distinction (again, in the same way that when using
+an RDBMS one can use database views and database tables pretty much interchangeably).
+
+View models generally tend to be associated with supporting a particular use case; logically they are part of the
+application layer, not part of the domain layer (where entities live).
+
+We introduce view models here because they do get mentioned quite often within the users and reference guide. However,
+we do consider them a more advanced topic; we generally recommend that you build your applications from the domain
+layer up, rather than from the view model down.
+
+For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[this topic].
+
+
+
+
+[[_ugfun_core-concepts_building-blocks_domain-services]]
+== Domain Services
+
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Apache Isis will automatically inject services into every domain entity that requests them, and into each other.
+
+For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
+
+=== Domain Services vs View Services
+
+NOTE: TODO
+
+`@DomainService(nature=...)`
+
+.Factories, Repositories and Services
+****
+A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], for example.
+
+In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
+****
+
+
+
+[[_ugfun_core-concepts_building-blocks_mixins-and-contributions]]
+== Mixins & Contributions
+
+NOTE: TODO
+
+
+For more information, see xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[this topic on contribution]s, and
+xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[this topic on mixin]s.
+
+
+
+[[_ugfun_core-concepts_building-blocks_domain-events]]
+== Domain Events
+
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
+
+
+
+=== UI Events (`1.11.0-SNAPSHOT`)
+
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
+
+
+
+
+[[_ugfun_core-concepts_building-blocks_oid]]
+== OIDs
+
+As well as defining a xref:ug.adoc#_ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
+classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+
+When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
+object identifier. Fundamentally this is a combination of its type (domain class), along with an identifier. You can think
+of it as its "primary key", except across all domain entity types.
+
+For portability and resilience, though, the object type is generally an alias for the actual domain class: thus
+"customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer". This is derived from an annotation. The
+identifier meanwhile is always converted to a string.
+
+Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by
+a given Apache Isis application. With it, we have the ability to lookup any arbitrary domain objects.
+
+Some examples:
+
+* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
+
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form. When the PDF is
+scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
+
+* as a handle to any object in an audit record (as used by the
+xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`], in fact).
+
+* and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
+xref:ugvw.adoc#[Wicket viewer]
+use the oid tuple to look up, render and allow the user to interact with domain objects.
+
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
+to obtain OIDs. These are represented as `Bookmark`s, obtained from the
+xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`]. Deep links meanwhile can be obtained from
+the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+
+OIDs can also be converted into XML format, useful for integration scenarios. The
+xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+
+
+
+[[_ugfun_core-concepts_building-blocks_value-objects]]
+== Value Objects (Primitives)
+
+NOTE: TODO
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
new file mode 100644
index 0000000..b57e68e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,54 @@
+[[_ugfun_core-concepts_framework-provided-services]]
+= Framework-provided Services
+: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/
+
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+
+General purpose:
+
+* xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`]
+* xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`]
+* xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`]
+* xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`]
+* xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`]
+* xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]
+
+Commands/Background/Auditing:
+
+* xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
+* xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`] (SPI)
+
+Information Sharing:
+
+* xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`]
+* xref:rgsvc.adoc#_rgsvc-api_ActionInvocationContext[`ActionInvocationContext`]
+* xref:rgsvc.adoc#_rgsvc-api_QueryResultsCache[`QueryResultsCache`]
+
+
+UserManagement:
+
+* xref:rgsvc.adoc#_rgsvc-spi_UserProfileService[`UserProfileService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_EmailNotificationService[`EmailNotificationService`] (SPI)
+
+
+Bookmarks and Mementos:
+
+* xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`]
+* xref:rgsvc.adoc#_rgsvc-api_MementoService[`MementoService`]
+* xref:rgsvc.adoc#_rgsvc-api_DeepLinkService[`DeepLinkService`]
+* xref:rgsvc.adoc#_rgsvc-api_XmlSnapshotService[`XmlSnapshotService`]
+
+
+A full list of services can be found in the xref:rgsvc.adoc#_rgsvc-api[Domain Services (API)] and xref:rgsvc.adoc#_rgsvc-spi[Domain Services (SPI)] chapters of the reference guide.
+