You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/06/01 09:53:39 UTC
isis git commit: ISIS-1133: more fixing up of references.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 505a311e1 -> 3162bda85
ISIS-1133: more fixing up of references.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/3162bda8
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/3162bda8
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/3162bda8
Branch: refs/heads/ISIS-1133
Commit: 3162bda8582df0a553fe2cdde2b3597162cbfb00
Parents: 505a311
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Jun 1 08:53:35 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Jun 1 08:53:35 2015 +0100
----------------------------------------------------------------------
.../user-guide/_ug_headless-access.adoc | 92 +---
...less-access_AbstractIsisSessionTemplate.adoc | 40 ++
...dless-access_BackgroundCommandExecution.adoc | 68 +++
.../user-guide/_ug_how-tos_class-structure.adoc | 6 +-
...how-tos_class-structure_inject-services.adoc | 77 ++++
...ence-annotations_manpage-Action_command.adoc | 2 +-
...tutorials_stop-scaffolding-start-coding.adoc | 2 +-
...guration-properties_abbreviating-titles.adoc | 2 +-
...ewer_customisation_tweaking-css-classes.adoc | 2 +-
.../user-guide/_ug_wicket-viewer_features.adoc | 445 +------------------
...wicket-viewer_features_bookmarked-pages.adoc | 111 +++++
...et-viewer_features_file-upload-download.adoc | 122 +++++
...cket-viewer_features_hints-and-copy-url.adoc | 80 ++++
..._ug_wicket-viewer_features_recent-pages.adoc | 52 +++
...wicket-viewer_features_titles-in-tables.adoc | 76 ++++
...icket-viewer_features_user-registration.adoc | 81 ++++
.../user-guide/_ug_wicket-viewer_layout.adoc | 4 +-
...t-viewer_layout_application-menu-layout.adoc | 2 +-
...ket-viewer_layout_dynamic-object-layout.adoc | 6 +-
...cket-viewer_layout_static-object-layout.adoc | 28 +-
20 files changed, 741 insertions(+), 557 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
index d8773b0..bd72c8c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
@@ -19,97 +19,9 @@ Note that the calling thread runs in the same process space as the Isis domain o
The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the <<WrapperFactory>> service could be used to enforce such business rules if required.
-== AbstractIsisSessionTemplate
-The `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
+include::_ug_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
+include::_ug_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
-The class itself is intended to be subclassed:
-[source,java]
-----
-public abstract class AbstractIsisSessionTemplate {
- public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
- protected abstract void doExecute(Object context); // <2>
-
- protected ObjectAdapter adapterFor(final Object targetObject) { ... }
- protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
-
- protected PersistenceSession getPersistenceSession() { ... }
- protected IsisTransactionManager getTransactionManager() { ... }
- protected AdapterManager getAdapterManager() { ... }
-}
-----
-<1> `execute(...)` sets up the `IsisSession` and delegates to ...
-<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
-The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
-
-The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
-
-
-[TIP]
-====
-One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
-====
-
-
-
-== BackgroundCommandExecution
-
-The `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
-
-Its signature is:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
- protected void doExecute(Object context) { ... }
- protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
-}
-----
-<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
-
-This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
-
-The diagram below shows the dependencies between these various classes:
-
-.Inheritance Hierarchy for `BackgroundCommandExecution`
-image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
-
-[TIP]
-====
-[source,ini]
-.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f])
-----
-[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
-[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
-----
-
-====
-
-
-
-=== Background Execution using Isis Addons Command Module (not ASF)
-
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of <<BackgroundCommandExecution>>, the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
-
-This implementation queries for ``Command``s persisted by the http://isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of <<CommandService>> and <<BackgroundCommandService>> using the `BackgroundCommandServiceJdoRepository`.
-
-The diagram below shows the inheritance hierarchy for this class:
-
-.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
-image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
-
-
-[TIP]
-====
-[source,java]
-.DSL (http://yuml.me/edit/25343da1[yuml.me/25343da1]):
-----
-[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
-[BackgroundCommandExecution]->injected[BookmarkService|lookup()]
-[BackgroundCommandExecution]->injected[CommandContext|setCommand()]
-----
-
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
new file mode 100644
index 0000000..7402a2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
@@ -0,0 +1,40 @@
+[[_ug_headless-access_AbstractIsisSessionTemplate]]
+= AbstractIsisSessionTemplate
+: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 `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
+
+The class itself is intended to be subclassed:
+
+[source,java]
+----
+public abstract class AbstractIsisSessionTemplate {
+
+ public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
+ protected abstract void doExecute(Object context); // <2>
+
+ protected ObjectAdapter adapterFor(final Object targetObject) { ... }
+ protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
+
+ protected PersistenceSession getPersistenceSession() { ... }
+ protected IsisTransactionManager getTransactionManager() { ... }
+ protected AdapterManager getAdapterManager() { ... }
+}
+----
+<1> `execute(...)` sets up the `IsisSession` and delegates to ...
+<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
+The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
+
+The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
+
+
+[TIP]
+====
+One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
new file mode 100644
index 0000000..76e598a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
@@ -0,0 +1,68 @@
+[[_ug_headless-access_BackgroundCommandExecution]]
+= BackgroundCommandExecution
+: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 `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
+
+Its signature is:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
+ protected void doExecute(Object context) { ... }
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
+}
+----
+<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
+
+This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
+
+The diagram below shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
+
+[TIP]
+====
+[source,ini]
+.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f])
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
+[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
+----
+
+====
+
+
+
+
+
+
+== Background Execution using Isis Addons Command Module (not ASF)
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of <<BackgroundCommandExecution>>, the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+
+This implementation queries for ``Command``s persisted by the http://isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of <<CommandService>> and <<BackgroundCommandService>> using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
+
+[TIP]
+====
+[source,java]
+.DSL (http://yuml.me/edit/25343da1[yuml.me/25343da1]):
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]->injected[BookmarkService|lookup()]
+[BackgroundCommandExecution]->injected[CommandContext|setCommand()]
+----
+
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
index 7d9eeb0..52d013b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
@@ -4,6 +4,7 @@
:_basedir: ../
:_imagesdir: images/
+
Apache Isis works by building a metamodel of the domain objects: entities, view models and services. The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions. The class members of domain services is simpler: just behaviour, ie actions.
In the automatically generated UI a property is rendered as a field. This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity. A collection is generally rendered as a table.
@@ -23,14 +24,11 @@ You can learn more about extending Isis programming model xref:_ug_extending_pro
include::_ug_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-
include::_ug_how-tos_class-structure_properties.adoc[leveloffset=+1]
-
include::_ug_how-tos_class-structure_collections.adoc[leveloffset=+1]
-
include::_ug_how-tos_class-structure_actions.adoc[leveloffset=+1]
-
include::_ug_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
include::_ug_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
new file mode 100644
index 0000000..cc5aa29
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
@@ -0,0 +1,77 @@
+[[how-to-inject-services-into-a-domain-entity-or-other-service]]
+= How to inject services into a domain entity or other service
+: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib `DomainObjectContainer` is also a service, so can be injected in exactly the same manner.
+
+
+
+== Field Injection
+
+Field injection is recommended, using the `@javax.inject.Inject` annotation. For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.inject.Inject
+ OrderRepository orderRepository;
+ ...
+}
+----
+
+
+We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
+
+
+
+== Method Injection
+
+Isis also supports two forms of method injection. All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
+of the method does not matter, only that it is prefixed either `set` or `inject`, is
+public, and has a single parameter of the correct type.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ private OrderRepository orderRepository;
+ public void setOrderRepository(OrderRepository orderRepository) {
+ this.orderRepository = orderRepository;
+ }
+ ...
+}
+----
+
+or alternatively, using 'inject' as the prefix:
+
+[source,java]
+----
+public class Customer {
+ private OrderRepository orderRepository;
+ public void injectOrderRepository(OrderRepository orderRepository) {
+ this.orderRepository = orderRepository;
+ }
+ ...
+}
+----
+
+Note that the method name can be anything; it doesn't need to be related to the type being injected.
+
+
+
+
+== Constructor injection
+
+Simply to note that constructor injection is _not_ supported by Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
+
+
+
+== Qualified services
+
+Isis currently does not support qualified injection of services; the domain service of each type must be distinct from any other.
+
+If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
index d11a446..2cb7693 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
@@ -23,7 +23,7 @@ If an appropriate `CommandService` is configured (for example using (non-ASF) ht
[NOTE]
====
-If background ``Command``s are used, then an external scheduler, using xref:_background_execution_using_isis_addons_command_module_not_asf[headless access], must also be configured.
+If background ``Command``s are used, then an external scheduler, using xref:_ug_headless-access_BackgroundCommandExecution[headless access], must also be configured.
====
[NOTE]
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
index 6a10af4..2a7c361 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
@@ -364,7 +364,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
* Add domain actions to add/remove from the collection
-* to create objects, xref:how_to_inject_srvices_into_a_domain_entity_or_other_service[inject] associated domain service
+* to create objects, xref:_ug_how-tos_class-structure_inject-services[inject] associated domain service
** generally we recommend using the xref:_ug_reference-annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
* the service itself should use xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
* use the xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
index 541ba4c..fdf2878 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
@@ -6,7 +6,7 @@
-Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a xref:_titles_in_tables[mechanism to automatically shorten] the titles of objects specified using `@Title`. As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
+Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a xref:_ug_wicket-viewer_features_titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`. As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
The properties themselves are:
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
index 19959ce..337ea45 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
@@ -94,7 +94,7 @@ div.x-myapp-highlight span.scalarName {
}
----
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:_dynamic_layouts[dynamic layout] JSON file:
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:_ug_wicket-viewer_layout_dynamic-object-layout[dynamic layout] JSON file:
[source,javascript]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
index c8fbd61..0345b5b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
@@ -8,451 +8,18 @@
This section discusses features of the wicket viewer from the perspective of an end-user actually using your Isis application.
+include::_ug_wicket-viewer_features_recent-pages.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_bookmarked-pages.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_hints-and-copy-url.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_titles-in-tables.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_file-upload-download.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_user-registration.adoc[leveloffset=+1]
-== Titles in Tables
-Object titles can often be quite long if the intention is to uniquely identify the object. While this is appropriate for the object view, it can be cumbersome within tables.
-If an object's title is specified with from `@Title` annotation then the Wicket viewer will (for parented collections) automatically "contextualize" a title by excluding the part of the title corresponding to a reference to the owning (parent) object.
-In other words, suppose we have:
-image::{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png[width="579px",link="{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png"]
-so that `Customer` has a collection of `Order`s:
-
-[source,java]
-----
-public class Customer {
- public Set<Order> getOrders() { ... }
- ...
-}
-----
-
-and `Product` also has a collection of `Order`s (please forgive the suspect domain modelling in this example (!)):
-
-[source,java]
-----
-public class Product {
- public Set<Order> getOrders() { ... }
- ...
-}
-----
-
-and where the `Order` class references both `Customer` and `Product`.
-
-The `Order`'s might involve each of these:
-
-[source,java]
-----
-public class Order {
- @Title(sequence="1")
- public Customer getCustomer() { ... }
- @Title(sequence="2")
- public Product getProduct() { ... }
- @Title(sequence="3")
- public String getOtherInfo() { ... }
- ...
-}
-----
-
-In this case, if we view a `Customer` with its collection of `Order`s, then in that parented collection's table the customer's property will be automatically excluded from the title of the `Order` (but it would show the product). Conversely, if a `Product` is viewed then its collection of `Order`s would suppress product (but would show the customer).
-
-[TIP]
-====
-This feature is a close cousin of the `@PropertyLayout(hidden=Where.REFERENCES_PARENT)` annotation, which will cause the property itself to be hidden as a column in the table. An Isis idiom is therefore:
-
-[source,java]
-----
-public class Order {
- @Title(sequence="1")
- @PropertyLayout(hidden=Where.REFERENCES_PARENT)
- public Customer getCustomer() { ... }
- ...
-}
-----
-
-====
-
-The above annotations mean that titles usually "just work", altering according to the context in which they are viewed.
-
-[TIP]
-====
-It is also possible to configure the Wicket viewer to xref:_abbreviating_suppressing_titles_in_tables[abbreviate titles or suppress them] completely.
-====
-
-
-
-== File upload/download
-
-The Isis application library provides the xref:_blob[Blob] value type (binary large objects) and also the xref:_clob[Clob]
-value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
-
-A class can define a property using either of these types, for example:
-
-=== Screenshots
-
-The following screenshots are taken from the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF):
-
-[NOTE]
-====
-TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-==== View mode, empty
-
-`Blob` field rendered as attachment (with no data):
-
-image::{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field.png"]
-
-==== Edit mode
-
-Hit edit; 'choose file' button appears:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file.png"]
-
-==== Choose file
-
-Choose file using the regular browser window:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png[width="520px",link="{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser.png"]
-
-
-Chosen file is indicated:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png"]
-
-==== Image rendered
-
-Back in view mode (ie once hit OK) if the `Blob` is an image, then it is shown:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png"]
-
-==== Download
-
-`Blob` can be downloaded:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/060-download-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/060-download.png"]
-
-==== Clear
-
-Back in edit mode, can choose a different file or clear (assuming property is not mandatory):
-
-image::{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear.png"]
-
-=== Domain Code
-
-To define a `Blob`, use:
-
-[source,java]
-----
-private Blob attachment;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false")
- @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "attachment_name"),
- @javax.jdo.annotations.Column(name = "attachment_mimetype"),
- @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB")
- })
-@Property(
- domainEvent = AttachmentDomainEvent.class,
- optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() { return attachment; }
-public void setAttachment(final Blob attachment) { this.attachment = attachment; }
-----
-
-To define a `Clob`, use:
-
-[source,java]
-----
-private Clob doc;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "doc_name"),
- @javax.jdo.annotations.Column(name = "doc_mimetype"),
- @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
-})
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() { return doc; }
-public void setDoc(final Clob doc) { this.doc = doc; }
-----
-
-The `Blob` and `Clob` types can also be used as parameters to actions.
-
-
-
-
-== Bookmarked pages
-
-The Wicket viewer supports the bookmarking of both domain objects and query-only (xref:_actionsemantics[@ActionSemantics]) actions.
-
-Domain objects, if bookmarkable, can be nested.
-
-Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured.
-
-=== Screenshots
-
-The following screenshot, taken from https://github.com/isisaddons/isis-app-todoapp[Isisaddons example todoapp] (not ASF) shows how the bookmarks are listed in a sliding panel.
-
-image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel.png"]
-
-[NOTE]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-Note how the list contains both domain objects and an action ("not yet complete").
-
-Bookmarks can also form a hierarchy. The following screenshot, also taken from the https://github.com/estatio/estatio[Estatio] application, shows a variety of different bookmarked objects with a nested structure:
-
-image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png"]
-
-[NOTE]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout.
-
-=== Domain Code
-
-To indicate a class is bookmarkable, use the xref:_domainobjectlayout[@DomainObjectLayout] annotation:
-
-[source,java]
-----
-@DomainObjectLayout(
- bookmarking=BookmarkPolicy.AS_ROOT
-)
-public class Lease { ... }
-----
-
-To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy:
-
-[source,java]
-----
-@DomainObjectLayout(
- bookmarking=BookmarkPolicy.AS_CHILD
-)
-public class LeaseItem { ... }
-----
-
-To indicate that a safe (query only) action is bookmarkable, use the xref:_actionlayout[@ActionLayout] annotation:
-
-[source,java]
-----
-public class ToDoItem ... {
- ...
- @ActionLayout(
- bookmarking=BookmarkPolicy.AS_ROOT
- )
- @ActionSemantics(Of.SAFE)
- public List<ToDoItem> notYetComplete() { ... }
- ...
-}
-----
-
-[NOTE]
-====
-The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored.
-====
-
-=== User Experience
-
-The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region).
-
-Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key.
-
-=== Related functionality
-
-The xref:_recent_pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
-
-=== Configuration
-
-By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example:
-
-[source,ini]
-----
-isis.viewer.wicket.bookmarkedPages.maxSize=20
-----
-
-
-
-== Recent pages (drop down)
-
-The Wicket viewer provides a recent pages drop-down that acts as a breadcrumb trail. Using it, the user can quickly open a recently accessed domain object.
-
-=== Screenshots
-
-The following screenshot, taken from the https://github.com/estatio/estatio[Estatio] application, shows the recent pages drop-down after a number of pages have been accessed.
-
-image::{_imagesdir}wicket-viewer/recent-pages/recent-pages.png[width="800px",link="{_imagesdir}wicket-viewer/recent-pages/recent-pages.png"]
-
-
-[NOTE]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-=== Domain Code
-
-The recent pages drop-down is automatically populated; no changes need to be made to the domain classes.
-
-=== User Experience
-
-Selecting the domain object from the list causes the viewer to automatically navigate to the page for the selected object.
-
-=== Related functionality
-
-The xref:_bookmarked_pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
-
-=== Configuration
-
-The number of objects is hard-coded as 10; it cannot currently be configured.
-
-
-
-
-
-== Hints and copy URL
-
-While the user can often copy the URL of a domain object directly from the browser's address bar, the Wicket viewer also allows the URL of domain objects to be easily copied from a dialog.
-
-More interestingly, this URL can also contain hints capturing any sorting or page numbering, or hiding/viewing of collections. End-users can therefore share these URLs as a form of deep linking into a particular view on a domain object.
-
-The copy URL and hinting is automatic.
-
-=== Screenshots
-
-The following screenshots are taken from the [Estatio](https://github.com/estatio/estatio) application.
-
-[NOTE]
-====
-TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-==== Copy URL
-
-This screenshot shows the copy URL button (top right):
-
-image::{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png"]
-
-Clicking on this button brings up a dialog with the URL preselected:
-
-image::{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png"]
-
-
-The URL in this case is something like:
-
- http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0
-
-The user can copy the link (eg `ctrl+C`) into the clipboard, then hit `OK` or `Esc` to dismiss the dialog.
-
-==== Hints
-
-Using the viewer the user can hide/show collection tables, can sort the tables by header columns:
-
-image::{_imagesdir}wicket-viewer/copy-link/030-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/030-hints.png"]
-
-
-Also, if the collection spans multiple pages, then the individual page can be selected.
-
-Once the view has been customised, the URL shown in the copy URL dialog is in an extended form:
-
-image::{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png"]
-
-The URL in this case is something like:
-
- http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0?hint-1:collectionContents-view=3&hint-1:collectionContents:collectionContents-3:table-DESCENDING=value&hint-1:collectionContents:collectionContents-3:table-pageNumber=0&hint-2:collectionContents-view=0&hint-2:collectionContents:collectionContents-2:table-pageNumber=0&hint-3:collectionContents-view=2&hint-3:collectionContents:collectionContents-2:table-pageNumber=0&hint-4:collectionContents-view=3&hint-4:collectionContents:collectionContents-3:table-ASCENDING=exerciseDate&hint-4:collectionContents:collectionContents-3:table-pageNumber=0&hint-5:collectionContents-view=0&hint-5:collectionContents:collectionContents-3:table-pageNumber=0
-
-==== Copy URL from title
-
-When the user invokes an action on the object, the URL (necessarily) changes to indicate that the action was invoked. This URL is specific to the user's session and cannot be shared with others.
-
-A quick way for the user to grab a shareable URL is simply by clicking on the object's title:
-
-image::{_imagesdir}wicket-viewer/copy-link/050-title-url.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/050-title-url.png"]
-
-
-=== User Experience
-
-The copy URL dialog is typically obtained by clicking on the icon.
-
-Alternatively, `alt+]` will also open the dialog. It can be closed with either `OK` or the `Esc` key.
-
-
-
-
-
-
-
-== User Registration
-
-The Wicket viewer provides the ability for users to sign-up by providing a valid email address:
-
-* from the login page the user can instead follow a link to take them to a sign-up page, where they enter their email address.
-* a verification email is sent using this service; the email includes a link back to the running application.
-* the user then completes the registration process by choosing a user name and password.
-* the Wicket viewer then creates an account for them and logs them in.
-
-In a similar way, if the user has forgotten their password then they can request a reset link to be sent to their email, again by providing their email address.
-
-To support this the framework requires three services to be registered and configured:
-
-* the xref:_user_registration_service[user registration service], which provides an API to create the user account
-* the xref:_email_notification_service[email notification service], which provides an API for to send the verification emails
-* the xref:_email_service[email service], that is used by the email notification service to actually send the email.
-
-The Isis core framework provides a default implementation of both the email notification service and the email service. If your application uses the https://github.com/isisaddons/isis-module-security[Isis addons security module] (not ASF) then an implementation is provided by that module; just add to the classpath. Otherwise you will need to provide your own implementation.
-
-[NOTE]
-====
-There is _no_ default implementation of the user registration service in the core framework.
-====
-
-=== Screenshots
-
-The user is presented with a login page:
-
-image::{_imagesdir}wicket-viewer/user-registration/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/login-page-default.png"]
-
-
-Navigate to the sign up page. Complete the page, and verify:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-page.png"]
-
-
-Back to the login page:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png"]
-
-
-Email arrives, with link:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png[width="500px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png"]
-
-
-Follow the link, complete the page:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png"]
-
-
-Automatically logged in:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png[width="800px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png"]
-
-
-=== Configuration
-
-There are two prerequisites:
-
-* register an implementation of the xref:_user_registration_service[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
-
-* configure the xref:_email_service[email service]
-
-The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
-
-It is also possible to configure the Wicket viewer to suppress xref:_suppressing_sign_up[the sign-up page link] and/or the xref:_suppressing_password_reset[password reset page].
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
new file mode 100644
index 0000000..8e6d230
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
@@ -0,0 +1,111 @@
+[[_ug_wicket-viewer_features_bookmarked-pages]]
+= Bookmarked pages
+: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 Wicket viewer supports the bookmarking of both domain objects and query-only (xref:_ug_reference-annotations_manpage-Action_semantics[@Action(semantics=...)]) actions.
+
+Domain objects, if bookmarkable, can be nested.
+
+Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured.
+
+
+
+
+== Screenshots
+
+The following screenshot, taken from https://github.com/isisaddons/isis-app-todoapp[Isisaddons example todoapp] (not ASF) shows how the bookmarks are listed in a sliding panel.
+
+image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel.png"]
+
+[NOTE]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+Note how the list contains both domain objects and an action ("not yet complete").
+
+Bookmarks can also form a hierarchy. The following screenshot, also taken from the https://github.com/estatio/estatio[Estatio] application, shows a variety of different bookmarked objects with a nested structure:
+
+image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png"]
+
+[NOTE]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout.
+
+
+
+
+== Domain Code
+
+To indicate a class is bookmarkable, use the xref:_ug_reference-annotations_manpage-DomainObjectLayout[@DomainObjectLayout] annotation:
+
+[source,java]
+----
+@DomainObjectLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT
+)
+public class Lease { ... }
+----
+
+To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy:
+
+[source,java]
+----
+@DomainObjectLayout(
+ bookmarking=BookmarkPolicy.AS_CHILD
+)
+public class LeaseItem { ... }
+----
+
+To indicate that a safe (query only) action is bookmarkable, use the xref:_ug_reference-annotations_manpage-ActionLayout[@ActionLayout] annotation:
+
+[source,java]
+----
+public class ToDoItem ... {
+ ...
+ @ActionLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT
+ )
+ @ActionSemantics(Of.SAFE)
+ public List<ToDoItem> notYetComplete() { ... }
+ ...
+}
+----
+
+[NOTE]
+====
+The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored.
+====
+
+
+
+
+== User Experience
+
+The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region).
+
+Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key.
+
+=== Related functionality
+
+The xref:_ug_wicket-viewer_features_recent-pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
+
+
+
+
+
+== Configuration
+
+By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example:
+
+[source,ini]
+----
+isis.viewer.wicket.bookmarkedPages.maxSize=20
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
new file mode 100644
index 0000000..d44b045
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
@@ -0,0 +1,122 @@
+[[_ug_wicket-viewer_features_file-upload-download]]
+= File upload/download
+: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 Isis application library provides the xref:_ug_reference-classes_value-types_manpage-Blob[Blob] value type (binary large objects) and also the xref:_ug_reference-classes_value-types_manpage-Clob[Clob]
+value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
+
+A class can define a property using either of these types, for example:
+
+
+
+
+== Screenshots
+
+The following screenshots are taken from the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF):
+
+[NOTE]
+====
+TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+
+
+=== View mode, empty
+
+`Blob` field rendered as attachment (with no data):
+
+image::{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field.png"]
+
+
+
+=== Edit mode
+
+Hit edit; 'choose file' button appears:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file.png"]
+
+
+
+=== Choose file
+
+Choose file using the regular browser window:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png[width="520px",link="{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser.png"]
+
+
+Chosen file is indicated:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png"]
+
+
+
+=== Image rendered
+
+Back in view mode (ie once hit OK) if the `Blob` is an image, then it is shown:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png"]
+
+
+
+=== Download
+
+`Blob` can be downloaded:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/060-download-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/060-download.png"]
+
+
+
+=== Clear
+
+Back in edit mode, can choose a different file or clear (assuming property is not mandatory):
+
+image::{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear.png"]
+
+
+
+
+
+== Domain Code
+
+To define a `Blob`, use:
+
+[source,java]
+----
+private Blob attachment;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false")
+ @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "attachment_name"),
+ @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+ @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB")
+ })
+@Property(
+ domainEvent = AttachmentDomainEvent.class,
+ optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() { return attachment; }
+public void setAttachment(final Blob attachment) { this.attachment = attachment; }
+----
+
+To define a `Clob`, use:
+
+[source,java]
+----
+private Clob doc;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "doc_name"),
+ @javax.jdo.annotations.Column(name = "doc_mimetype"),
+ @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+})
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() { return doc; }
+public void setDoc(final Clob doc) { this.doc = doc; }
+----
+
+The `Blob` and `Clob` types can also be used as parameters to actions.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
new file mode 100644
index 0000000..849360a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
@@ -0,0 +1,80 @@
+[[_ug_wicket-viewer_features_hints-and-copy-url]]
+= Hints and copy URL
+: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/
+
+
+
+While the user can often copy the URL of a domain object directly from the browser's address bar, the Wicket viewer also allows the URL of domain objects to be easily copied from a dialog.
+
+More interestingly, this URL can also contain hints capturing any sorting or page numbering, or hiding/viewing of collections. End-users can therefore share these URLs as a form of deep linking into a particular view on a domain object.
+
+The copy URL and hinting is automatic.
+
+
+
+
+== Screenshots
+
+The following screenshots are taken from the [Estatio](https://github.com/estatio/estatio) application.
+
+[NOTE]
+====
+TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+
+=== Copy URL
+
+This screenshot shows the copy URL button (top right):
+
+image::{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png"]
+
+Clicking on this button brings up a dialog with the URL preselected:
+
+image::{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png"]
+
+
+The URL in this case is something like:
+
+ http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0
+
+The user can copy the link (eg `ctrl+C`) into the clipboard, then hit `OK` or `Esc` to dismiss the dialog.
+
+
+=== Hints
+
+Using the viewer the user can hide/show collection tables, can sort the tables by header columns:
+
+image::{_imagesdir}wicket-viewer/copy-link/030-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/030-hints.png"]
+
+
+Also, if the collection spans multiple pages, then the individual page can be selected.
+
+Once the view has been customised, the URL shown in the copy URL dialog is in an extended form:
+
+image::{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png"]
+
+The URL in this case is something like:
+
+ http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0?hint-1:collectionContents-view=3&hint-1:collectionContents:collectionContents-3:table-DESCENDING=value&hint-1:collectionContents:collectionContents-3:table-pageNumber=0&hint-2:collectionContents-view=0&hint-2:collectionContents:collectionContents-2:table-pageNumber=0&hint-3:collectionContents-view=2&hint-3:collectionContents:collectionContents-2:table-pageNumber=0&hint-4:collectionContents-view=3&hint-4:collectionContents:collectionContents-3:table-ASCENDING=exerciseDate&hint-4:collectionContents:collectionContents-3:table-pageNumber=0&hint-5:collectionContents-view=0&hint-5:collectionContents:collectionContents-3:table-pageNumber=0
+
+
+
+=== Copy URL from title
+
+When the user invokes an action on the object, the URL (necessarily) changes to indicate that the action was invoked. This URL is specific to the user's session and cannot be shared with others.
+
+A quick way for the user to grab a shareable URL is simply by clicking on the object's title:
+
+image::{_imagesdir}wicket-viewer/copy-link/050-title-url.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/050-title-url.png"]
+
+
+
+
+== User Experience
+
+The copy URL dialog is typically obtained by clicking on the icon.
+
+Alternatively, `alt+]` will also open the dialog. It can be closed with either `OK` or the `Esc` key.
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
new file mode 100644
index 0000000..321d00e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
@@ -0,0 +1,52 @@
+[[_ug_wicket-viewer_features_recent-pages]]
+= Recent pages (drop down)
+: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 Wicket viewer provides a recent pages drop-down that acts as a breadcrumb trail. Using it, the user can quickly open a recently accessed domain object.
+
+
+
+== Screenshots
+
+The following screenshot, taken from the https://github.com/estatio/estatio[Estatio] application, shows the recent pages drop-down after a number of pages have been accessed.
+
+image::{_imagesdir}wicket-viewer/recent-pages/recent-pages.png[width="800px",link="{_imagesdir}wicket-viewer/recent-pages/recent-pages.png"]
+
+
+[NOTE]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+
+
+
+== Domain Code
+
+The recent pages drop-down is automatically populated; no changes need to be made to the domain classes.
+
+
+
+
+== User Experience
+
+Selecting the domain object from the list causes the viewer to automatically navigate to the page for the selected object.
+
+
+
+
+== Related functionality
+
+The xref:_ug_wicket-viewer_features_bookmarked-pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
+
+
+
+
+== Configuration
+
+The number of objects is hard-coded as 10; it cannot currently be configured.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
new file mode 100644
index 0000000..2e8f92f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
@@ -0,0 +1,76 @@
+[[_ug_wicket-viewer_features_titles-in-tables]]
+= Titles in Tables
+: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/
+
+
+Object titles can often be quite long if the intention is to uniquely identify the object. While this is appropriate for the object view, it can be cumbersome within tables.
+
+If an object's title is specified with from `@Title` annotation then the Wicket viewer will (for parented collections) automatically "contextualize" a title by excluding the part of the title corresponding to a reference to the owning (parent) object.
+
+In other words, suppose we have:
+
+image::{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png[width="579px",link="{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png"]
+
+so that `Customer` has a collection of `Order`s:
+
+[source,java]
+----
+public class Customer {
+ public Set<Order> getOrders() { ... }
+ ...
+}
+----
+
+and `Product` also has a collection of `Order`s (please forgive the suspect domain modelling in this example (!)):
+
+[source,java]
+----
+public class Product {
+ public Set<Order> getOrders() { ... }
+ ...
+}
+----
+
+and where the `Order` class references both `Customer` and `Product`.
+
+The `Order`'s might involve each of these:
+
+[source,java]
+----
+public class Order {
+ @Title(sequence="1")
+ public Customer getCustomer() { ... }
+ @Title(sequence="2")
+ public Product getProduct() { ... }
+ @Title(sequence="3")
+ public String getOtherInfo() { ... }
+ ...
+}
+----
+
+In this case, if we view a `Customer` with its collection of `Order`s, then in that parented collection's table the customer's property will be automatically excluded from the title of the `Order` (but it would show the product). Conversely, if a `Product` is viewed then its collection of `Order`s would suppress product (but would show the customer).
+
+[TIP]
+====
+This feature is a close cousin of the `@PropertyLayout(hidden=Where.REFERENCES_PARENT)` annotation, which will cause the property itself to be hidden as a column in the table. An Isis idiom is therefore:
+
+[source,java]
+----
+public class Order {
+ @Title(sequence="1")
+ @PropertyLayout(hidden=Where.REFERENCES_PARENT)
+ public Customer getCustomer() { ... }
+ ...
+}
+----
+
+====
+
+The above annotations mean that titles usually "just work", altering according to the context in which they are viewed.
+
+[TIP]
+====
+It is also possible to configure the Wicket viewer to xref:_ug_wicket-viewer_configuration-properties_abbreviating-titles[abbreviate titles or suppress them] completely.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
new file mode 100644
index 0000000..9e64496
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
@@ -0,0 +1,81 @@
+[[_ug_wicket-viewer_features_user-registration]]
+= User Registration
+: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 Wicket viewer provides the ability for users to sign-up by providing a valid email address:
+
+* from the login page the user can instead follow a link to take them to a sign-up page, where they enter their email address.
+* a verification email is sent using this service; the email includes a link back to the running application.
+* the user then completes the registration process by choosing a user name and password.
+* the Wicket viewer then creates an account for them and logs them in.
+
+In a similar way, if the user has forgotten their password then they can request a reset link to be sent to their email, again by providing their email address.
+
+To support this the framework requires three services to be registered and configured:
+
+* the xref:_ug_reference-services-spi_manpage-UserRegistrationService[user registration service], which provides an API to create the user account
+* the xref:_ug_reference-services-spi_manpage-EmailNotificationService[email notification service], which provides an API for to send the verification emails
+* the xref:_ug_reference-services-api_manpage-EmailService[email service], that is used by the email notification service to actually send the email.
+
+The Isis core framework provides a default implementation of both the email notification service and the email service. If your application uses the https://github.com/isisaddons/isis-module-security[Isis addons security module] (not ASF) then an implementation is provided by that module; just add to the classpath. Otherwise you will need to provide your own implementation.
+
+[NOTE]
+====
+There is _no_ default implementation of the user registration service in the core framework.
+====
+
+
+
+== Screenshots
+
+The user is presented with a login page:
+
+image::{_imagesdir}wicket-viewer/user-registration/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/login-page-default.png"]
+
+
+Navigate to the sign up page. Complete the page, and verify:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-page.png"]
+
+
+Back to the login page:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png"]
+
+
+Email arrives, with link:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png[width="500px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png"]
+
+
+Follow the link, complete the page:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png"]
+
+
+Automatically logged in:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png[width="800px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png"]
+
+
+
+
+== Configuration
+
+There are two prerequisites:
+
+* register an implementation of the xref:_user_registration_service[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
+
+* configure the xref:_ug_reference-services-api_manpage-EmailService[email service]
+
+The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
+
+It is also possible to configure the Wicket viewer to suppress xref:_ug_wicket-viewer_configuration-properties_suppressing-sign-up[the sign-up page link] and/or the xref:_ug_wicket-viewer_configuration-properties_suppressing-password-reset[password reset page].
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
index 33a95e7..1ad5a4c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
@@ -19,9 +19,9 @@ include::_ug_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1]
== Static vs Dynamic Layouts
-Using xref:_dynamic_object_layout[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).
+Using xref:_ug_wicket-viewer_layout_dynamic-object-layout[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:_contributed_members[contributed associations and actions] that are synthesised at runtime.
+Another benefit of dynamic layout is that UI hints can be provided for xref:_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.
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
index 2837e62..9abda4b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
@@ -167,5 +167,5 @@ Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module
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:_vetoing_visibility[vetoing subscriber].
+using security or using a xref:_ug_more-advanced_assembling_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
index e626996..0bdaa73 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically, using annotations such as xref:_memberorder[`@MemberOrder`] and xref:_membergrouplayout[`@MemberGroupLayout`]. However, it is also possible to specify the layout data using a JSON file. This brings the advantage that the layout can be refreshed dynamically, without recompiling/redeploying the app.
+Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically, using annotations such as xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`] and xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]. However, it is also possible to specify the layout data using a JSON file. This brings the advantage that the layout can be refreshed dynamically, without recompiling/redeploying the app.
== Screencast
@@ -107,7 +107,7 @@ The format of the file is:
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:_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.
+Note also that the layout file may contain entries for xref:_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.
@@ -119,7 +119,7 @@ The fastest way to get started is to use the http://github.com/isisaddons/isis-m
== Picking up new metadata
-When running in xref:_deployment_types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.
+When running in xref:_ug_runtime_configuration-files_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.
[NOTE]
====
http://git-wip-us.apache.org/repos/asf/isis/blob/3162bda8/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
index e8a6f47..a6b8e51 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
@@ -147,21 +147,21 @@ image::{_imagesdir}wicket-viewer/layouts/4-0-8-0.png[width="720px",link="{_image
As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations:
-* xref:_domainservicelayout[`@DomainServiceLayout`]
-* xref:_domainobjectlayout[`@DomainObjectLayout`]
-* xref:_viewmodellayout[`@ViewModelLayout`]
-* xref:_propertylayout[`@PropertyLayout`]
-* xref:_collectionlayout[`@CollectionLayout`]
-* xref:_actionlayout[`@ActionLayout`]
-* xref:_parameterlayout[`@ParameterLayout`]
+* xref:_ug_reference-annotations_manpage-DomainServiceLayout[`@DomainServiceLayout`]
+* xref:_ug_reference-annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`]
+* xref:_ug_reference-annotations_manpage-ViewModelLayout[`@ViewModelLayout`]
+* xref:_ug_reference-annotations_manpage-PropertyLayout[`@PropertyLayout`]
+* xref:_ug_reference-annotations_manpage-CollectionLayout[`@CollectionLayout`]
+* xref:_ug_reference-annotations_manpage-ActionLayout[`@ActionLayout`]
+* xref:_ug_reference-annotations_manpage-ParameterLayout[`@ParameterLayout`]
Prior to 1.8.0 a variety of annotations (now deprecated) are available, including:
-* xref:_named[`@Named`]
-* xref:_describedas[`@DescribedAs`]
-* xref:_multiline[`@MultiLine`]
-* xref:_typicallength[`@TypicalLength`]
-* xref:_render[`@Render`]
-* xref:_cssclass[`@CssClass`]
-* xref:_cssclassfa[`@CssClassFa`]
+* `@Named`
+* `@DescribedAs`
+* `@MultiLine`
+* `@TypicalLength`
+* `@Render`
+* `@CssClass`
+* `@CssClassFa`