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/04/15 23:15:53 UTC
isis git commit: ISIS-1133: more outlines for user guide.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133-docs 79ca45f1d -> ad48e0742
ISIS-1133: more outlines for user guide.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ad48e074
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ad48e074
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ad48e074
Branch: refs/heads/ISIS-1133-docs
Commit: ad48e0742c68e001ec75baeab340d458da7f51eb
Parents: 79ca45f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 15 22:15:44 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Apr 15 22:15:44 2015 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/documentation.adoc | 4 +-
...os-tips-n-tricks-are-you-sure-happy-case.png | Bin 0 -> 9993 bytes
...-tos-tips-n-tricks-are-you-sure-sad-case.png | Bin 0 -> 10515 bytes
...guide-how-tos-tips-n-tricks-are-you-sure.png | Bin 0 -> 9312 bytes
.../user-guide-config-and-deployment.adoc | 93 ++++++++++
.../asciidoc/user-guide/user-guide-config.adoc | 46 -----
...ser-guide-core-concepts-building-blocks.adoc | 178 ++++++++++++++++++-
...re-concepts-framework-provided-services.adoc | 73 +++++++-
.../user-guide-extending-programming-model.adoc | 16 ++
.../user-guide/user-guide-extending.adoc | 27 +++
.../user-guide-how-tos-class-members.adoc | 104 -----------
.../user-guide-how-tos-class-structure.adoc | 173 ++++++++++++++++++
.../user-guide-how-tos-error-handling.adoc | 11 ++
.../user-guide/user-guide-how-tos-i18n.adoc | 7 +
.../user-guide-how-tos-multi-tenancy.adoc | 7 +
...ser-guide-how-tos-persistence-lifecycle.adoc | 7 +
...uide-how-tos-tips-n-tricks-are-you-sure.adoc | 47 +++++
...ps-n-tricks-overrriding-jdo-annotations.adoc | 5 +
.../user-guide-how-tos-tips-n-tricks.adoc | 32 ++++
.../user-guide/user-guide-how-tos-ui-hints.adoc | 22 ++-
.../asciidoc/user-guide/user-guide-how-tos.adoc | 35 +++-
...er-guide-integrating-with-other-systems.adoc | 11 ++
.../user-guide/user-guide-isis-addons.adoc | 44 +++++
...-guide-reference-applib-utility-classes.adoc | 8 +
.../user-guide-reference-value-types.adoc | 6 +
.../user-guide/user-guide-reference.adoc | 4 +
.../user-guide/user-guide-restful-viewer.adoc | 35 ++++
.../asciidoc/user-guide/user-guide-testing.adoc | 22 +++
...ide-troubleshooting-datanucleus-logging.adoc | 10 ++
.../user-guide/user-guide-troubleshooting.adoc | 13 ++
.../user-guide/user-guide-wicket-viewer.adoc | 74 ++++++++
.../main/asciidoc/user-guide/user-guide.adoc | 43 ++++-
32 files changed, 994 insertions(+), 163 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 161d619..e6362c1 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -5,8 +5,6 @@
:toc: right
:numbered:
-Finding your way around:
-
ifdef::env-github[]
[TIP]
----
@@ -16,6 +14,8 @@ For the links below, replace the `.html` with `.adoc` to find the original sourc
----
endif::[]
+Finding your way around:
+
* Introducing Isis
** link:introducing-apache-isis/isis-in-pictures/isis-in-pictures.html[Isis in Pictures]
** link:introducing-apache-isis/common-use-cases/common-use-cases.html[Common Use Cases]
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-happy-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-happy-case.png b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-happy-case.png
new file mode 100644
index 0000000..1981c09
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-happy-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-sad-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-sad-case.png b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-sad-case.png
new file mode 100644
index 0000000..6182447
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure-sad-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure.png b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure.png
new file mode 100644
index 0000000..e1a76fe
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/user-guide-how-tos-tips-n-tricks-are-you-sure.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config-and-deployment.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config-and-deployment.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config-and-deployment.adoc
new file mode 100644
index 0000000..ba917c1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config-and-deployment.adoc
@@ -0,0 +1,93 @@
+= User Guide: Configuration and Deployment
+: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
+
+## Configuration Files
+
+Isis' own configuration properties are simple key-value pairs, typically held in in the `WEBINF/isis.properties` file.
+
+## Configuring the Webapp
+
+When running an Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
+
+### Isis configuration
+
+The `WEBINF/isis.properties` file is always read and must exist.
+
+In addition, the following other properties are searched for and if present also read:
+
+* `viewer_wicket.properties` - if the Wicket UI (viewer) is in use
+* `viewer_restfulobjects.properties` - if the Restful Objects REST API (viewer) is in use
+* `viewer.properties` - for any shared UI configuration
+* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
+* `persistor.properties` - for any shared objectstore configuration. This typically is used to hold `JDBC` ``URL``s
+
+### Shiro configuration
+
+`WEB-INF/shiro.ini`
+
+### Configuring Isis to use Shiro
+
+For more on some specific use cases, see <<Configuring Shiro>>
+
+
+### JDO/DataNucleus configuration
+
+Any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
+
+DataNucleus will itself search for additional XML mapping files, eg `mappings.jdo`. These an be used to override any annotations of annotated entities.
+
+## Configuring the Integration Tests
+
+Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
+
+These can be overridden by subclassing `IsisConfigurationForJdoIntegTests`.
+
+
+
+## Isis Configuration Properties
+
+### Deployment Types
+
+
+
+## Configuring Shiro
+
+### Configuring Shiro to use LDAP
+
+### Format of Isis Permissions
+
+
+
+## Configuring DataNucleus
+
+### persistence.xml file
+
+### Eagerly Registering Entity Types
+
+### Disabling persistence-by-reachability
+
+### Transaction Management
+
+
+## Deployment
+
+### Externalized Configuration
+
+### JVM Args
+
+### Using a JNDI Datasource
+
+
+
+## NoSQL Support
+
+### Deploying on the Google App Engine
+
+### Using Neo4J
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config.adoc
deleted file mode 100644
index 9771f4c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-config.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= User Guide: Configuration
-: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
-
-## Configuration
-
-Isis' own configuration properties are simple key-value pairs, typically held in in the `WEBINF/isis.properties` file.
-
-## Configuring the Webapp
-
-When running an Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
-
-### Isis configuration
-
-The `WEBINF/isis.properties` file is always read and must exist.
-
-In addition, the following other properties are searched for and if present also read:
-
-* `viewer_wicket.properties` - if the Wicket UI (viewer) is in use
-* `viewer_restfulobjects.properties` - if the Restful Objects REST API (viewer) is in use
-* `viewer.properties` - for any shared UI configuration
-* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
-* `persistor.properties` - for any shared objectstore configuration. This typically is used to hold `JDBC` ``URL``s
-
-### Shiro configuration
-
-`WEB-INF/shiro.ini`
-
-### JDO/DataNucleus configuration
-
-Any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-
-DataNucleus will itself search for additional XML mapping files, eg `mappings.jdo`. These an be used to override any annotations of annotated entities.
-
-## Configuring the Integration Tests
-
-Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
-
-These can be overridden by subclassing `IsisConfigurationForJdoIntegTests`.
-
-## Reference
-
-### Deployment Types
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-building-blocks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-building-blocks.adoc
index 1122eae..8d015dc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-building-blocks.adoc
@@ -37,12 +37,22 @@ Anything else can be (should be) ignored by annotating with `@Programmatic`.
## 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. 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
`@DomainService(nature=...)`
-### Factories, Repositories, Services
+.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:Domain Driven Design[http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC], 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.
+****
## Value Objects (Primitives)
@@ -56,3 +66,169 @@ Anything else can be (should be) ignored by annotating with `@Programmatic`.
+
+
+
+=== Registering domain services
+
+As noted link:../../how-tos/how-to-09-010-How-to-register-domain-services,-repositories-and-factories.html[elsewhere], domain services (which includes repositories and factories) should be registered in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list):
+
+For example:
+
+[source]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+ com.mycompany.myapp.claim.Claims\,
+ ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+ claim.Claims,\
+ ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) can be found referenced from the main link:../../documentation.html[documentation] page. They include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management.
+
+=== Service scopes
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation `@javax.enterprise.context.RequestScoped` is used to indicate this fact:
+
+[source]
+----
+ @javax.enterprise.context.RequestScoped
+ public class MyService extends AbstractService {
+ ...
+ }
+----
+
+The framework provides a number of request-scoped services; these can be found referenced from the main link:../../documentation.html[documentation] page. They include scratchpad service, query results caching, and support for co-ordinating bulk actions.
+
+=== (Suppressing) contributed actions
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source]
+----
+public interface Library {
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source]
+----
+public class Book implements Loanable { ... }y
+----
+
+and
+
+[source]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+
+This is an important capability because it helps to decouple the concrete classes from the services.
+
+If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotContributed
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
+
+Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+=== (Suppressing) service menu items
+
+By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotInServiceMenu
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+Alternatively, this can be performed using a supporting method:
+
+[source]
+----
+public class LibraryImpl implements Library {
+ public Loan borrow(Loanable l, Borrower b) { ... }
+ public boolean notInServiceMenuBorrow() { ... }
+}
+----
+
+=== (Suppressing) service menus
+
+If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
+
+For example:
+
+[source]
+----
+@Hidden
+public interface EmailService {
+ public void sendEmail(String to, String from, String subject, String body);
+ public void forwardEmail(String to, String from, String subject, String body);
+}
+----
+
+=== Initializing Services
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+==== Initialization
+
+The framework will call any `public` method annotated with `@javax.annotation.PostConstruct` and with either no arguments of an argument of type `Map<String,String>`:
+
+or
+
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+==== Shutdown
+
+Shutdown is similar; the framework will call any method annotated with `@javax.annotation.PreDestroy`:
+
+=== The getId() method
+
+Optionally, a service may provide a `getId()` method:
+
+[source]
+----
+public String getId()
+----
+
+This method returns a logical identifier for a service, independent of its implementation. Currently it used only by perspectives, providing a label by which to record the services that are available for a current user's profile. <!--See ? for more about profiles and perspectives.-->
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-framework-provided-services.adoc
index 5379fa2..57511f5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-framework-provided-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-core-concepts-framework-provided-services.adoc
@@ -3,13 +3,78 @@
:_basedir: ../
:_imagesdir: images/
-## The `DomainObjectContainer` service
-
NOTE: TODO
-## Other Services
+## API vs SPI
+
+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.
+
+## Autoregistration of Domain services
+
+Where a domain service has an implementation, it is (almost always) automatically registered just by virtue of being on the `CLASSPATH`.
+
+The one exception is <<ExceptionRecognizer>>.
+
+It is possible to replacing automatically-registered domain services.
+
+
+## Overview of Domain Services
+
+Unless indicated as SPI, each of the following has an implementation in Isis core.
+
+### `DomainObjectContainer`
+
+### `ClockService`
+
+### `IsisSupportJdo`
+
+### `ExceptionRecognizer`
+
+### `WrapperFactory`
+
+### `EventBusService`
+
+### Commands/Background
+
+#### `CommandContext`
+
+#### `BackgroundService`
+
+### Information Sharing
+
+#### `ScratchPad`
+
+#### `ActionInvocationContext`
+
+#### `QueryResultsCache`
+
+### `EmailService`
+
+### UserManagement
+
+#### `UserProfileService` (SPI)
+
+#### `UserRegistrationService` (SPI)
+
+#### `EmailNotificationService`
+
+
+### Bookmarks and Mementos
+
+#### `BookmarkService`
+
+#### `MementoService`
+
+#### `DeepLinkService`
+
+#### `XmlSnapshotService`
+
+
+
+
-NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending-programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending-programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending-programming-model.adoc
new file mode 100644
index 0000000..8a42fbf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending-programming-model.adoc
@@ -0,0 +1,16 @@
+= User Guide: How-tos: Extending: Programming Model
+: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
+
+## Disallowing deprecated annotations
+
+## Custom validator
+
+## Finetuning the Programming Model
+
+## Layout metadata reader
+
+## Listener to create DB schema objects
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending.adoc
new file mode 100644
index 0000000..9b59717
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-extending.adoc
@@ -0,0 +1,27 @@
+= User Guide: How-tos: Extending
+: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
+
+## Extending the Programming Model
+
+include::user-guide-extending-programming-model.adoc[leveloffset=+1]
+
+
+
+## Extending the Wicket viewer
+
+### Writing a custom theme
+
+### Replacing page elements
+
+### Custom pages
+
+
+
+
+## Extending the Restful viewer
+
+### Custom Representations
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-members.adoc
deleted file mode 100644
index ebb4ae2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-members.adoc
+++ /dev/null
@@ -1,104 +0,0 @@
-= User Guide: How-tos: Class Members
-: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
-
-## Property
-
-
-### Value vs Reference Types
-
-
-The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in <<Mapping Value Types>> provides a handy reference for the each.
-
-### Optional Properties
-
-
-### Mapping String (Length)
-
-### Mapping JODA Dates
-
-### Mapping BigDecimals
-
-### Mapping Blobs
-
-### Mapping Passwords
-
-
-[NOTE]
-.Lazy Loading
-====
-
-====
-
-
-## Collection
-
-
-[NOTE]
-====
-While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
-
-Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
-
-The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
-===
-
-## Actions
-
-[NOTE]
-====
-While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
-
-The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
-====
-
-
-### Optional Action Argument
-
-## String Length Of Action Parameter
-
-## BigDecimal Precision Of Action Parameter
-
-### Mapping String (Length)
-
-### Mapping JODA Dates
-
-### Mapping BigDecimals
-
-### Mapping Blobs
-
-
-
-## Mapping Value Types
-
-table of:
-.
-|value type
-|property
-|action parameter
-
-|string (length)
-|
-|
-
-|big decimal (precision)
-|
-|
-
-|Isis blob
-|
-|
-
-|optional
-|`@Column(allowsNull="true")`
-|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
-
-
-## Ignoring Methods
-
-Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
-
-To exclude such methods, use the `@Programmatic` annotation.
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-structure.adoc
new file mode 100644
index 0000000..f489c6b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-class-structure.adoc
@@ -0,0 +1,173 @@
+= User Guide: How-tos: Class Members
+: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
+
+
+
+
+
+## Class Definition
+
+Classes are defined both to Isis and (if any entity) also to JDO/DataNucleus.
+
+
+
+
+We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+[NOTE]
+====
+As of 1.9.0-SNAPSHOT, all the IsisAddons modules (not ASF) define their own (database) schemas.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+and
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+This results in CREATE TABLE statements such as:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+and
+
+[source,sql]
+----
+CREATE TABLE isisaudit."AuditEntry" (
+ ...
+)
+----
+
+If you don't want to use schemas, then note that you can override the `@PersistenceCapable` annotation by providing XML annotations (`mappings.jdo` files).
+====
+
+
+
+
+## Property
+
+
+### Value vs Reference Types
+
+
+The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in <<Mapping Value Types>> provides a handy reference for the each.
+
+### Optional Properties
+
+
+### Mapping String (Length)
+
+### Mapping JODA Dates
+
+### Mapping BigDecimals
+
+### Mapping Blobs
+
+### Mapping Passwords
+
+
+[NOTE]
+.Lazy Loading
+====
+
+====
+
+
+
+
+## Collection
+
+
+[NOTE]
+====
+While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
+
+Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
+
+The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+===
+
+
+
+## Actions
+
+[NOTE]
+====
+While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
+
+The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+====
+
+
+### Optional Action Argument
+
+## String Length Of Action Parameter
+
+## BigDecimal Precision Of Action Parameter
+
+### Mapping String (Length)
+
+### Mapping JODA Dates
+
+### Mapping BigDecimals
+
+### Mapping Blobs
+
+
+
+
+
+## Mapping Value Types
+
+table of:
+.
+|value type
+|property
+|action parameter
+
+|string (length)
+|
+|
+
+|big decimal (precision)
+|
+|
+
+|Isis blob
+|
+|
+
+|optional
+|`@Column(allowsNull="true")`
+|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
+
+
+## Ignoring Methods
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
+
+To exclude such methods, use the `@Programmatic` annotation.
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-error-handling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-error-handling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-error-handling.adoc
new file mode 100644
index 0000000..356dfdd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-error-handling.adoc
@@ -0,0 +1,11 @@
+= User Guide: How-tos: Error Handling
+: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
+
+## Raise message/errors to users
+
+
+## Exception Recognizers
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-i18n.adoc
new file mode 100644
index 0000000..c6bbdea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-i18n.adoc
@@ -0,0 +1,7 @@
+= User Guide: How-tos: i18n
+: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
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-multi-tenancy.adoc
new file mode 100644
index 0000000..68e2e5e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-multi-tenancy.adoc
@@ -0,0 +1,7 @@
+= User Guide: How-tos: Multi-tenancy
+: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
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-persistence-lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-persistence-lifecycle.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-persistence-lifecycle.adoc
new file mode 100644
index 0000000..c4d39db
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-persistence-lifecycle.adoc
@@ -0,0 +1,7 @@
+= User Guide: How-tos: Persistence Lifecycle
+: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
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-are-you-sure.adoc
new file mode 100644
index 0000000..9f5eaa1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-are-you-sure.adoc
@@ -0,0 +1,47 @@
+== How Tos: Tips n Tricks: '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/
+
+If providing an action that will perform irreversible changes, include a
+mandatory boolean parameter that must be explicitly checked by the end-user
+in order for the action to proceed.
+
+== Screenshots
+
+For example:
+
+image::{_imagesdir}/user-guide-how-tos-tips-n-tricks-are-you-sure.png[]
+
+If the user checks the box:
+
+image::{_imagesdir}/user-guide-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}/user-guide-how-tos-tips-n-tricks-are-you-sure-sad-case.png[]
+
+== Code example
+
+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));
+
+ // invalid to return 'this' (cannot render a deleted object)
+ return toDoItems.notYetComplete();
+}
+public String validateDelete(boolean areYouSure) {
+ return areYouSure? null: "Please confirm you are sure";
+}
+----
+
+Note that the action itself does not use the boolean parameter, it is only
+used by the supporting `validateXxx()` method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-overrriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-overrriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-overrriding-jdo-annotations.adoc
new file mode 100644
index 0000000..c9dafcb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks-overrriding-jdo-annotations.adoc
@@ -0,0 +1,5 @@
+== How Tos: Tips n Tricks: Overriding JDO Annotations
+: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/
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks.adoc
new file mode 100644
index 0000000..072642c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-tips-n-tricks.adoc
@@ -0,0 +1,32 @@
+= User Guide: How-tos: Tips n Tricks
+: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
+
+## Are You Sure? idiom
+
+include::user-guide-how-tos-tips-n-tricks-are-you-sure.adoc[leveloffset=+1]
+
+
+
+## To review...
+
+Most of these will move elsewhere, I think:
+
+* Singleton & request-scoped services
+* Decoupling dependencies using contributions
+* How to suppress contributions
+* Bulk actions, acting upon lists
+* Bidirectional relationships
+* View models
+
+
+
+## Overriding JDO Annotations
+
+include::user-guide-how-tos-tips-n-tricks-overriding-jdo-annotations.adoc[leveloffset=+1]
+
+
+## Render abstract properties in tables
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-ui-hints.adoc
index f313112..82a6a9b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-ui-hints.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-ui-hints.adoc
@@ -17,14 +17,22 @@ NOTE: TODO
### Object CSS Styling
-
## Names and Descriptions
NOTE: see also i18n (TODO: convert to link)
+### Name/descr. of an object
+
+### Name/descr. of a property
+
+### Name/descr. of a collection
+
+### Name/descr. of an action
+
### Action Parameters
+
## Layout
### Layout using annotations
@@ -33,3 +41,15 @@ NOTE: see also i18n (TODO: convert to link)
### Application menu layout
+
+
+## Standardized font-awesome icons and CSS
+
+Use the following settings in isis.properties to apply CSS and font-awesome icons to object members (properties, collections and actions) based on their names.
+
+[source]
+----
+isis.reflector.facet.cssClassFa.patterns=\
+isis.reflector.facet.cssClass.patterns=\
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
index 1e1b387..d86e777 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
@@ -5,9 +5,9 @@
NOTE: TODO
-## Class Members
+## Class Structure
-include::user-guide-how-tos-class-members.adoc[leveloffset=+1]
+include::user-guide-how-tos-class-structure.adoc[leveloffset=+1]
@@ -58,4 +58,35 @@ include::user-guide-how-tos-drop-downs-and-defaults.adoc[leveloffset=+1]
include::user-guide-how-tos-triggering-events.adoc[leveloffset=+1]
+## Idioms and Patterns
+
+include::user-guide-how-tos-patterns.adoc[leveloffset=+1]
+
+
+
+## Error Handling
+
+include::user-guide-how-tos-error-handling.adoc[leveloffset=+1]
+
+
+## i18n
+
+include::user-guide-how-tos-i18n.adoc[leveloffset=+1]
+
+
+## Multi-tenancy
+
+include::user-guide-how-tos-multi-tenancy.adoc[leveloffset=+1]
+
+
+## Persistence Lifecycle
+
+include::user-guide-how-tos-persistence-lifecycle.adoc[leveloffset=+1]
+
+
+## Programming Model
+
+include::user-guide-how-tos-programming-model.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-integrating-with-other-systems.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-integrating-with-other-systems.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-integrating-with-other-systems.adoc
new file mode 100644
index 0000000..f2a0ace
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-integrating-with-other-systems.adoc
@@ -0,0 +1,11 @@
+= User Guide: Integrating with Other Systems
+: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
+
+
+## Non UI Execution
+
+Using `IsisSessionTemplate`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-isis-addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-isis-addons.adoc
new file mode 100644
index 0000000..1843011
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-isis-addons.adoc
@@ -0,0 +1,44 @@
+= User Guide: Isis Addons (not ASF)
+: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
+
+WARNING: Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
+
+## Command Service (persistence)
+
+### API
+### Isis addons implementation (not ASF)
+
+## Background Command Service
+
+### API
+### Background Execution
+### Isis addons implementation (not ASF)
+
+## Auditing
+
+### Auditing API
+### Isis addons implementation (not ASF)
+
+
+## Publishing Service
+
+### API
+### Isis addons implementation (not ASF)
+### Event Serializer per RO Spec (out-of-date)
+
+## Other Isis Addons
+
+### Developer Utilities (not ASF)
+### Docx Mail merge (not ASF)
+### Excel download/upload (not ASF)
+### Fake Data (not ASF)
+### Poly (not ASF)
+### Security (not ASF)
+### Session Logger (not ASF)
+### Settings (not ASF)
+### String interpolator (not ASF)
+### Tags (not ASF)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-applib-utility-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-applib-utility-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-applib-utility-classes.adoc
new file mode 100644
index 0000000..8e84f6f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-applib-utility-classes.adoc
@@ -0,0 +1,8 @@
+= User Guide: Reference: Applib Utility Classes
+: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
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-value-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-value-types.adoc
index 6942d2b..5b2a235 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-value-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference-value-types.adoc
@@ -6,3 +6,9 @@
NOTE: TODO
+## JDK
+
+## JodaTime
+
+## Isis Applib
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference.adoc
index 1dc7ccc..9d7d33b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-reference.adoc
@@ -21,6 +21,10 @@ include::user-guide-reference-domain-services.adoc[leveloffset=+1]
include::user-guide-reference-domain-services.adoc[leveloffset=+1]
+## Applib Utility Classes
+
+include::user-guide-reference-domain-services.adoc[leveloffset=+1]
+
## Convenience Superclasses
include::user-guide-reference-convenience-superclasses.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-restful-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-restful-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-restful-viewer.adoc
new file mode 100644
index 0000000..01a9593
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-restful-viewer.adoc
@@ -0,0 +1,35 @@
+= Restful Viewer
+: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
+
+## Features
+
+### Restful Objects Specification
+### Pretty printing
+
+
+
+## Configuration
+
+### Honor UI hints
+
+### Suppressing elements of the representations
+
+### Simplified object representation
+
+
+
+## Extending the viewer
+
+Discussed in <<Extending the Restful viewer>>
+
+
+
+## Hints and Tips
+
+### Using Chrome Tools
+
+### AngularJS Tips
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-testing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-testing.adoc
new file mode 100644
index 0000000..f1ab535
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-testing.adoc
@@ -0,0 +1,22 @@
+= User Guide: Testing
+: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
+
+## Unit Test Support
+
+## Integration Test Support
+
+## BDD/Integ Test Support
+
+## Fixture Scripts
+
+## SudoService (1.9.0-SNAPSHOT)
+
+## IsisConfigurationForJdoIntegTests
+
+## Isis CmdLine Arguments (for prototyping)
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting-datanucleus-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting-datanucleus-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting-datanucleus-logging.adoc
new file mode 100644
index 0000000..c74c626
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting-datanucleus-logging.adoc
@@ -0,0 +1,10 @@
+= User Guide: How-tos: Trouble Shooting: DataNucleus Logging
+: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
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting.adoc
new file mode 100644
index 0000000..a7365a4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-troubleshooting.adoc
@@ -0,0 +1,13 @@
+= User Guide: How-tos: Trouble Shooting
+: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
+
+## JDO/DataNucleus Logging
+
+include::user-guide-troubleshooting-datanucleus-logging.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-wicket-viewer.adoc
new file mode 100644
index 0000000..bbb16ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-wicket-viewer.adoc
@@ -0,0 +1,74 @@
+= Wicket Viewer
+: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
+
+## Features/end-user usage
+
+### File upload/download
+
+### Bookmarked pages (sliding panel)
+
+### Recent pages (drop down)
+
+### Hints and copy URL
+
+### User Registration
+
+
+
+## Configuration
+
+### Brand logo
+
+### Suppressing 'sign up'
+
+### Suppressing 'password reset'
+
+### Suppressing 'remember me'
+
+### Number of bookmarked pages
+
+### Stripped Wicket tags
+
+### Disabling modal dialogs
+
+### Showing a theme chooser
+
+### Suppressing header and footer (embedded view)
+
+
+
+## Application-specific Customisation
+
+### Customising the Welcome page
+
+### Customising the About page
+
+### Specifying a default theme
+
+### Tweaking CSS classes
+
+### Custom Javascript
+
+### Auto-refresh page
+
+
+
+## Extending the viewer
+
+Discussed in <<Extending the Wicket viewer>>
+
+
+
+## Isis Add-ons (not ASF)
+
+### Excel download
+
+### Fullcalendar2
+
+### Gmap3
+
+### Wicked charts
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ad48e074/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
index ea4aeac..2ad8188 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
@@ -8,16 +8,53 @@
include::user-guide-core-concepts.adoc[leveloffset=+1]
+
+## How-tos
+
+include::user-guide-howtos.adoc[leveloffset=+1]
+
+
## Reference
include::user-guide-reference.adoc[leveloffset=+1]
-## How-tos
-include::user-guide-howtos.adoc[leveloffset=+2]
+## Testing
+
+include::user-guide-testing.adoc[leveloffset=+1]
+
+
+## Wicket Viewer
+
+include::user-guide-wicket-viewer.adoc[leveloffset=+1]
+
+
+## Restful Objects Viewer
+
+include::user-guide-restful-viewer.adoc[leveloffset=+1]
-## Configuration
+
+## Configuration and Deployment
include::user-guide-config.adoc[leveloffset=+1]
+## Isis Addons (Modules)
+
+include::user-guide-isis-addons.adoc[leveloffset=+1]
+
+
+## Integrating with other Systems
+
+include::user-guide-integrating.adoc[leveloffset=+1]
+
+
+## Extending
+
+include::user-guide-extending.adoc[leveloffset=+1]
+
+
+## Trouble Shooting
+
+include::user-guide-trouble-shooting.adoc[leveloffset=+1]
+