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 2017/04/20 08:12:43 UTC
[34/58] [abbrv] isis git commit: object titles and icons; fixing links
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
index 8eadadb..ce821b8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
@@ -1,10 +1,68 @@
[[_ugfun_programming-model_view-models_jaxb]]
= JAXB View Models
-
: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/
+Here's a typical example of a JAXB view model, to allow (certain properties of) two ``Customer``s to be compared:
+
+[source,java]
+----
+@XmlRootElement(name = "compareCustomers") // <1>
+@XmlType(
+ propOrder = { // <2>
+ "customer1",
+ "customer2"
+ }
+)
+@XmlAccessorType(XmlAccessType.FIELD) // <3>
+public class CompareCustomers {
+
+ @XmlElement(required = true) // <4>
+ @Getter @Setter
+ Customer customer1;
+
+ @XmlElement(required = true) // <4>
+ @Getter @Setter
+ Customer customer2;
+
+ @XmlTransient // <5>
+ public String getCustomer1Name() {
+ return getCustomer1().getName();
+ }
+
+ @XmlTransient // <5>
+ public String getCustomer1Address() {
+ return getCustomer1().getAddress();
+ }
+
+ ...
+}
+----
+<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
+<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
+<3> Specifying field accessor type allows the Lombok `@Getter` and `@Setter` annotations to be used.
+<4> The `XmlElement` indicates the property is part of the view model's state.
+For collections, the `@XmlElementWrapper` would also typically be used.
+<5> The `@XmlTransient` indicates that the property is derived and should be ignored by JAXB.
+
+Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
+Properties can be ignored (for serialization) using `@XmlTransient`.
+
+The derived properties could also have been implemented using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins].
+
+
+[IMPORTANT]
+====
+Be aware that all the state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
+
+There are limits to the lengths of URLs, however.
+If the URL does exceed limits or contains invalid characters, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
+a URL.
+====
+
+
+include::_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc[leveloffset=+1]
+
-NOTE: FIXME
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
new file mode 100644
index 0000000..1808921
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
@@ -0,0 +1,65 @@
+[[_ugfun_programming-model_view-models_jaxb_referencing-domain-entities]]
+= Referencing Domain Entities
+
+: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/
+
+
+It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
+For example, the `CompareCustomers` view model described above actually references two underlying ``Customer`` entities.
+
+It wouldn't make sense to serialize out the state of a persistent entity (even more so when the view model is also being used as a DTO).
+However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+
+There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
+And this class is similar to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]: it knows how to create an `OidDto` from an object reference.
+
+Thus, in our view model we can legitimately write:
+
+[source,java]
+----
+public class CompareCustomers {
+
+ @XmlElement(required = true)
+ @Getter @Setter
+ Customer customer1;
+ ...
+}
+----
+
+All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class Customer ... {
+ ...
+}
+----
+
+
+It's also possible for a DTO view models to hold collections of objects.
+These can be of any type, either simple properties, or references to other objects.
+The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
+This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
+(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
+
+For example, we could perhaps generalize the view model to hold a set of ``Customer``s to be compared:
+
+[source,java]
+----
+public class CompareCustomers {
+ ...
+ @XmlElementWrapper
+ @XmlElement(name = "customers")
+ @Getter @Setter
+ protected List<Customer> customersToCompare = Lists.newArrayList();
+}
+----
+
+This capability is particularly useful when the JAXB view model is being used as a xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto[DTO].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
index 2069a9a..92c04ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
@@ -6,7 +6,74 @@
:_imagesdir: images/
+Instead of using JAXB to specify a view model, it is also possible to use Apache Isis-specific annotations.
+
+[WARNING]
+====
+As was explained xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models[earlier], the approach is described here is neither as flexible nor as powerful as using the JAXB-style of view models.
+As such, it may be deprecated in the future.
+====
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of defining a view model so that the original intent is not lost.
+They are:
+
+.View model programming model
+[cols="1a,4a,2a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+ public String viewModelMemento() { ... }
+ public void viewModelInit(String memento) { ... }
+}
+|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface. The memento is as defined by the
+interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+
+|===
+
+
-NOTE: FIXME
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
index a1a3301..fe0d4f6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -78,26 +78,264 @@ Titles can sometimes get be long and therefore rather cumbersome in "parented" t
=== Imperative style
-NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+Alternatively, the title can be provided simply by implementing the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method.
+For example:
+
+[source,java]
+----
+public class Author extends Customer {
+
+ public String title() {
+ StringBuilder buf = new StringBuilder();
+ buf.append(getFirstName());
+ if(getMiddleInitial() != null) {
+ buf.append(getMiddleInitial()).append(". ");
+ }
+ buf.append(getLastName();
+ return buf.toString();
+ }
+ ...
+}
+----
+
+A variation on this approach also supports localized names; see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[beyond-the-basics] guide for further details.
+
+
+=== Using a UI subscriber
+
+A third alternative is to move the responsibility for deriving the title into a separate subscriber object.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] attribute to specify:
+
+[source,java]
+----
+@DomainObjectLayout(
+ titleUiEvent = Author.TitleUiEvent.class
+)
+public class Author extends Customer {
+ public static class TitleUiEvent
+ extends org.apache.isis.applib.services.eventbus.TitleUiEvent<Author> {}
+ ...
+}
+----
+The subscriber can then populate this event:
-NOTE: FIXME -
-For more details on the actual UI event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class AuthorSubscriptions extends AbstractSubscriber {
+
+ @org.axonframework.eventhandling.annotation.EventHandler
+ @com.google.common.eventbus.Subscribe
+ public void on(Author.TitleUiEvent ev) {
+ Author author = ev.getSource();
+ ev.setTitle(titleOf(author);
+ }
+
+ private String titleOf(Author author) {
+ StringBuilder buf = new StringBuilder();
+ buf.append(author.getFirstName());
+ if(author.getMiddleInitial() != null) {
+ buf.append(author.getMiddleInitial()).append(". ");
+ }
+ buf.append(author.getLastName();
+ return buf.toString();
+ }
+}
+----
== Object Icon
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon. This could represent the state of that object (eg a shipped order, say, or overdue library book).
+The icon is often the same for all instances of a particular class, and is picked up by convention.
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+It's is also possible for an individual instance to return a custom icon, typically so that some significant state of that domain object is represented.
+For example, a custom icon could be used to represent a shipped order, say, or an overdue library loan.
+=== Declarative style
+
+If there is no requirement to customize the icon (the normal case), then the icon is usually picked up as the `.png` file in the same package as the class.
+For example, the icon for a class `org.mydomain.myapp.Customer` will be `org/mydomain/myapp/Customer.png` (if it exists).
+
+Alternatively, font-awesome icon can be used.
+This is specified using the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClassFa="play" // <1>
+)
+public class InvoiceRun {
+ ...
+}
+----
+<1> will use the "fa-play" icon.
+
+
+
+=== Imperative style
+
+To customise the icon on an instance-by-instance basis, we implement the reserved xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ public String iconName() {
+ return isShipped() ? "shipped": null;
+ }
+ ...
+}
+----
+
+In this case, if the `Order` has shipped then the framework will look for an icon image named "Order-shipped.png" (in the same package as the class).
+Otherwise it will just use "Order.png", as normal.
+
+
+
+=== Using a UI subscriber
+
+As for title, the determination of which image file to use for the icon can be externalized into a UI event subscriber.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] attribute to specify.
+
+For example
+
+[source,java]
+----
+@DomainObjectLayout(
+ iconUiEvent = Author.IconUiEvent.class
+)
+public class Order {
+ public static class IconUiEvent
+ extends org.apache.isis.applib.services.eventbus.IconUiEvent<Order> {}
+ ...
+}
+----
+
+The subscriber can then populate this event:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class OrderSubscriptions extends AbstractSubscriber {
+
+ @org.axonframework.eventhandling.annotation.EventHandler
+ @com.google.common.eventbus.Subscribe
+ public void on(Order.IconUiEvent ev) {
+ Order order = ev.getSource();
+ ev.setIconName(iconNameOf(order);
+ }
+
+ private String iconNameOf(Order order) {
+ StringBuilder buf = new StringBuilder();
+ return order.isShipped() ? "shipped": null;
+ }
+}
+----
+
== Object CSS Styling
+It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].
+In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+In fact, it is also possible to specify additional CSS for an object's members.
+
+
+=== Declarative style
+
+To render an object with a particular CSS, use
+xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`].
+
+When the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`.
+Or, when the domain object is rendered as a row in a collection, then the CSS class will appear in a `<div>` wrapped by the `<tr>` of the row.
+
+One possible use case would be to render the most important object types with a subtle background colour: ``Customer``s shown in light green, or ``Order``s shown in a light pink, for example.
+
+
+Similarly, a CSS class can be specified for object members:
+
+* xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] for actions
+
+* xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`] for properties, and
+
+* xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`] for collections.
+
+Again, this CSS class will be attached to an appropriate containing `<div>` or `<span>` on the rendered page.
+
+Possible use cases for this is to highlight the most important properties of a domain object.
+
+
+=== Imperative style
+
+
+To customise the icon on an instance-by-instance basis, we implement the reserved xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] method.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ public String cssClass() {
+ return isShipped() ? "shipped": null; <1>
+ }
+ ...
+}
+----
+<1> the implementation might well be the same as the `iconName()`.
+
+If non-null value is returned then the CSS class will be rendered _in addition_ to any declarative CSS class also specified.
+
+
+=== Using a UI subscriber
+
+
+As for title and icon, the determination of which CSS class to render can be externalized into a UI event subscriber.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attribute to specify.
+
+For example
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClassUiEvent = Author.CssClassUiEvent.class
+)
+public class Order {
+ public static class CssClassUiEvent
+ extends org.apache.isis.applib.services.eventbus.CssClassUiEvent<Order> {}
+ ...
+}
+----
+
+The subscriber can then populate this event:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class OrderSubscriptions extends AbstractSubscriber {
+
+ @org.axonframework.eventhandling.annotation.EventHandler
+ @com.google.common.eventbus.Subscribe
+ public void on(Order.CssClassUiEvent ev) {
+ Order order = ev.getSource();
+ ev.setIconName(iconNameOf(order);
+ }
+
+ private String cssClassOf(Order order) {
+ StringBuilder buf = new StringBuilder();
+ return order.isShipped() ? "shipped": null;
+ }
+}
+----
+
-It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class]. In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
index 6fead2e..015e8ca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -56,7 +56,7 @@ For example, in writing up the above example we found that writing `schema="
* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_ugbtb_decoupling_db-schemas[using modules].
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_db-schemas[using modules].
* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
index f6a8fa4..8ccc349 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
@@ -49,7 +49,9 @@ Similarly, for those object members that _are_ visible, the viewer also checks i
=== User-registration
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for users to self-register.
+By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session.
+These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
[TIP]
====
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
index daf1226..22980dd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
@@ -6,7 +6,7 @@
-If xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
The 'password reset' link can be suppressed, if required, by setting a configuration flag.
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
index 6d20fea..de3bcde 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
@@ -8,7 +8,7 @@
-If xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
The 'sign up' link can be suppressed, if required, by setting a configuration flag.
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
index 5676d55..9f99703 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
@@ -39,7 +39,7 @@ The layout file distinguishes between two types of element:
* those that define a grid structure, of: rows, columns, tab groups and tabs. +
+
-The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:../ugvw/ugvw.adoc[Wicket viewer]).
+The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:../ugvw/ugvw.adoc#[Wicket viewer]).
* those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
index 261314a..c4d42a4 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
@@ -52,7 +52,7 @@ domain object is a view model rather than an entity (that is, has no id or versi
as top-level actions.
Most of these mixin object members are visible only in prototype mode, though some are visible in production mode and
-so potentially visible to end-users. If you wish to suppress these members from the view, you can either use xref:guides/ugsec.adoc[security],
+so potentially visible to end-users. If you wish to suppress these members from the view, you can either use xref:guides/ugsec.adoc#[security],
or alternatively you can write xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber]s to veto the visibility
of these members by subscribing to their respective domain events.
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
index df56f20..55853a2 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
@@ -70,7 +70,7 @@ the attribute is not set explicitly.
Conversely, neither the xref:guides/rgant.adoc#_rgant_Action_publishingPayloadFactory[`@Action#publishingPayloadFactory()`]
nor the xref:guides/rgant.adoc#_rgant_DomainObject_publishingPayloadFactory[`@DomainObject#publishingPayloadFactory()`] are
supported by `PublisherService`; instead the consumers of the events are expected to callback for any additional
-information, eg using xref:guides/ugvro.adoc[Resful Objects] viewer.
+information, eg using xref:guides/ugvro.adoc#[Resful Objects] viewer.
== Auto-logout
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
index a9475aa..57f2e3d 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
@@ -130,7 +130,6 @@ public class ToDoItem {
== isis-maven-plugin
-The way that the Isis Maven plugin is configured has changed slightly; check out its
-xref:guides/rgmvn.adoc[documentation] for full details.
+The way that the Isis Maven plugin is configured has changed slightly; check out its xref:guides/rgmvn.adoc#[documentation] for full details.
http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index ddcb3c8..b8cb5d5 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -116,7 +116,7 @@ Using the Swagger UI to access the xref:guides/ugvro.adoc#[REST API] automatical
|link:https://www.youtube.com/watch?v=yOh3WphhR1E[010^] +
-Using the xref:guides/rgmvn.adoc[Apache Isis maven plugin] to validate domain object models during the build process (rather than at runtime).
+Using the xref:guides/rgmvn.adoc#[Apache Isis maven plugin] to validate domain object models during the build process (rather than at runtime).
||||||||x|||
@@ -213,20 +213,20 @@ Using xref:guides/ugvw.adoc#_ugvw_layout_file-based[dynamic (XML) layouts] to sp
include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=0d713-V4vrg[019^] +
-Demonstrates how Apache Isis' xref:guides/ugvw.adoc[Wicket viewer] remembers the state of rendered domain objects, and how the end-user of the
+Demonstrates how Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer] remembers the state of rendered domain objects, and how the end-user of the
application can clear these UI hints using the (framework-provided) xref:guides/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"] action.
|||x||||||||
|link:https://www.youtube.com/watch?v=Kqch-XNlBMA[020^] +
-Demonstrates how the end-user can copy and share URLs for domain objects - including UI hints - using Apache Isis' xref:guides/ugvw.adoc[Wicket viewer].
+Demonstrates how the end-user can copy and share URLs for domain objects - including UI hints - using Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer].
|||x||||||||
|link:https://www.youtube.com/watch?v=a0QQLT_16To[021^] +
-Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:guides/ugvw.adoc[Wicket viewer], and how the developer can ensure that xref:guides/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects] and (xref:guides/rgant.adoc#_rgant-Action_semantics[query-only]) xref:guides/rgant.adoc#_rgant-ActionLayout_bookmarking[actions] can be bookmarked.
+Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer], and how the developer can ensure that xref:guides/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects] and (xref:guides/rgant.adoc#_rgant-Action_semantics[query-only]) xref:guides/rgant.adoc#_rgant-ActionLayout_bookmarking[actions] can be bookmarked.
|||x||||||||
@@ -426,7 +426,7 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=esujf_DFeWA[041^] +
-Using BigDecimal as a property within a domain object, also demonstrating the "summary" view within the xref:guides/ugvw.adoc[Wicket viewer].
+Using BigDecimal as a property within a domain object, also demonstrating the "summary" view within the xref:guides/ugvw.adoc#[Wicket viewer].
|||||||x||x|x|
@@ -552,7 +552,7 @@ The (very simple) steps required to rename a domain entity class.
|link:https://www.youtube.com/watch?v=J5xobU6X0ng[057^] +
-How to rename a menu (on the top-level menubar) as rendered in the xref:guides/ugvw.adoc[Wicket viewer].
+How to rename a menu (on the top-level menubar) as rendered in the xref:guides/ugvw.adoc#[Wicket viewer].
|x||||||||||