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 2020/03/24 19:15:23 UTC
[isis] 02/04: ISIS-2062: flattens user guide
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2062
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 08d427abf236e824d88b67935162bf747707017d
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 24 18:54:26 2020 +0000
ISIS-2062: flattens user guide
---
.../ROOT/pages/landing-page/components.adoc | 4 ++--
.../what-is-apache-isis/powered-by/contactapp.adoc | 2 +-
.../powered-by/gesconsultor-grc.adoc | 2 +-
.../pages/what-is-apache-isis/screencasts.adoc | 16 +++++++--------
api/adoc/userguide/modules/ROOT/pages/about.adoc | 15 ++++++++++----
.../btb/pages/hints-and-tips/pushing-changes.adoc | 2 +-
api/adoc/userguide/modules/fun/pages/about.adoc | 6 ------
.../modules/fun/pages/business-rules.adoc | 4 ++--
.../{core-concepts.adoc => concepts-patterns.adoc} | 0
.../apache-isis-vs-cqrs-and-event-sourcing.adoc | 6 +++---
.../fun/pages/core-concepts/architecture.adoc | 7 ++++---
.../fun/pages/core-concepts/core-values.adoc | 6 +++---
api/adoc/userguide/modules/fun/pages/crud.adoc | 4 ++--
.../userguide/modules/fun/pages/crud/deleting.adoc | 2 +-
.../userguide/modules/fun/pages/crud/finding.adoc | 2 +-
.../modules/fun/pages/crud/instantiating.adoc | 4 ++--
.../modules/fun/pages/crud/persisting.adoc | 2 +-
.../userguide/modules/fun/pages/crud/updating.adoc | 2 +-
.../pages/domain-entities-and-services.adoc} | 12 ++++-------
.../domain-entities.adoc | 1 +
.../domain-services.adoc | 9 +++++----
.../inject-services.adoc | 3 ++-
.../{programming-model => }/meta-annotations.adoc | 0
.../fun/pages/{programming-model => }/mixins.adoc | 2 +-
.../fun/pages/{programming-model => }/modules.adoc | 2 +-
.../about.adoc => fun/pages/object-members.adoc} | 14 ++++---------
.../actions.adoc | 16 +++++++--------
.../collections.adoc | 6 +++---
.../properties.adoc | 4 ++--
.../pages/{building-blocks.adoc => overview.adoc} | 16 +++++++--------
.../business-rules.adoc | 0
.../{building-blocks => overview}/events.adoc | 7 ++++---
.../{building-blocks => overview}/identifiers.adoc | 2 +-
.../{building-blocks => overview}/modules.adoc | 12 +++++------
.../object-members.adoc | 10 +++++-----
.../programming-model.adoc | 8 ++++----
.../types-of-domain-objects.adoc | 18 ++++++++---------
.../modules/fun/pages/programming-model.adoc | 11 -----------
api/adoc/userguide/modules/fun/pages/ui-hints.adoc | 2 --
.../pages/{ui-hints/layout.adoc => ui-layout.adoc} | 5 +++--
.../pages/{programming-model => }/view-models.adoc | 10 +++++-----
.../UNUSED-dto.adoc | 12 +++++------
.../userguide/modules/fun/partials/module-nav.adoc | 23 ++++++++++++----------
.../applib-ant/pages/Action/restrictTo.adoc | 1 +
.../applib-ant/pages/DomainObject/nature.adoc | 4 ++--
.../pages/DomainObjectLayout/cssClassUiEvent.adoc | 5 +++--
.../pages/DomainObjectLayout/iconUiEvent.adoc | 4 ++--
.../pages/DomainObjectLayout/layoutUiEvent.adoc | 1 +
.../pages/DomainObjectLayout/titleUiEvent.adoc | 4 ++--
.../main/adoc/modules/applib-ant/pages/Mixin.adoc | 2 +-
.../adoc/modules/applib-ant/pages/ViewModel.adoc | 2 +-
.../applib-ant/pages/XmlJavaTypeAdapter.adoc | 2 +-
.../modules/applib-ant/pages/XmlRootElement.adoc | 6 +++---
.../modules/applib-cm/pages/classes/mixins.adoc | 2 +-
.../applib-cm/pages/classes/mixins/Dto.adoc | 2 +-
.../applib-cm/pages/methods/prefixes/choices.adoc | 2 +-
.../applib-cm/pages/methods/prefixes/default.adoc | 2 +-
.../applib-cm/pages/methods/prefixes/disable.adoc | 2 --
.../applib-cm/pages/methods/prefixes/hide.adoc | 2 --
.../adoc/modules/applib-svc/pages/JaxbService.adoc | 2 +-
.../adoc/modules/applib-svc/pages/Scratchpad.adoc | 2 +-
.../modules/applib-svc/pages/SwaggerService.adoc | 2 +-
.../applib-svc/pages/UrlEncodingService.adoc | 2 +-
.../src/main/adoc/modules/schema/pages/common.adoc | 2 +-
.../src/main/adoc/modules/config/pages/about.adoc | 2 +-
.../pages/ContentNegotiationService.adoc | 2 +-
.../adoc/modules/starters/pages/helloworld.adoc | 2 +-
.../adoc/modules/starters/pages/simpleapp.adoc | 2 +-
.../adoc/modules/ROOT/pages/layout/file-based.adoc | 2 +-
69 files changed, 170 insertions(+), 184 deletions(-)
diff --git a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
index 271e117..755680e 100644
--- a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
+++ b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
@@ -26,9 +26,9 @@ The xref:security:ROOT:about.adoc[Security Guide] describes how to configure eac
== Persistence
-The framework allows xref:userguide:fun:building-blocks.adoc#domain-entities[domain entities] to be persisted using the xref:pjdo:ROOT:about.adoc[JDO/DataNucleus object store], for use with the JDO API.
+The framework allows xref:userguide:fun:overview.adoc#domain-entities[domain entities] to be persisted using the xref:pjdo:ROOT:about.adoc[JDO/DataNucleus object store], for use with the JDO API.
-Alternatively, if you restrict yourself to xref:userguide:fun:building-blocks.adoc#view-models[view models] then these can be persisted with any data persistence technology that is supported by Spring Boot.
+Alternatively, if you restrict yourself to xref:userguide:fun:overview.adoc#view-models[view models] then these can be persisted with any data persistence technology that is supported by Spring Boot.
== Extensions
diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/contactapp.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/contactapp.adoc
index 4bb6054..30f1980 100644
--- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/contactapp.adoc
+++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/contactapp.adoc
@@ -24,7 +24,7 @@ image:https://github.com/incodehq/contactapp/blob/master/docs/contactapp-fronten
As our first Apache Isis app making use of mobile technologies it opens the doors for more to follow.
Ionic has proven easy to learn and build apps with, and has a helpful community.
-Meanwhile we've used Apache Isis' support for xref:userguide:fun:programming-model.adoc#jaxb[JAXB view models]
+Meanwhile we've used Apache Isis' support for xref:userguide:fun:view-models.adoc#jaxb[JAXB view models]
and in particular the xref:vro:ROOT:simplified-representations.adoc[simplified REST representations] introduced in v1.12.0. The result is code that is easy to follow and enhance.
We expect that the scope of _Contact App_ will expand and new features added, these will (almost certainly) remain open source.
diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/gesconsultor-grc.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/gesconsultor-grc.adoc
index 4097e07..378fdb2 100644
--- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/gesconsultor-grc.adoc
+++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/powered-by/gesconsultor-grc.adoc
@@ -79,7 +79,7 @@ We chose http://wavemaker.com[Wavemaker] for implementing the viewer, also lever
Even so, while GRC does (as the figures above show) include custom views, the majority of the views exposed by GRC are automatically generated from the underlying domain entities; the GRC viewer is a proprietary version of Isis' own xref:vw:ROOT:about.adoc[Wicket viewer].
At the last count more than 400 domain entities, across 6 different Bounded Contexts, are surfaced in the UI in this this way.
-At the Domain level, we also extensively use the xref:userguide:fun:building-blocks.adoc#domain-events[domain events] functionality available in Apache Isis, along with many of the (non-ASF) link:https://platform.incode.org[Incode Platform^] (such as audit, security and excel modules).
+At the Domain level, we also extensively use the xref:userguide:fun:overview.adoc#domain-events[domain events] functionality available in Apache Isis, along with many of the (non-ASF) link:https://platform.incode.org[Incode Platform^] (such as audit, security and excel modules).
The GRC platform currently has more than 5600 automated tests, about 2000 being xref:testing:specsupport:about.adoc[BDD tests] and 3600 xref:testing:integtestsupport:about.adoc[integration tests], all leveraging Apache Isis' extensive testing capabilities.
diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
index 888dd3b..525fc39 100644
--- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
+++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
@@ -64,7 +64,7 @@ Importing the generated app into an xref:setupguide:ROOT:ide.adoc[IDE] +
|link:https://www.youtube.com/watch?v=xVTjtiJM8XM[003^] +
-Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel`xref:userguide:fun:programming-model.adoc#view-models[view model] and `SimpleObjects` domain service (repository).
+Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel`xref:userguide:fun:view-models.adoc[view model] and `SimpleObjects` domain service (repository).
||||x|||||||
@@ -240,19 +240,19 @@ include::screencasts/playlists.adoc[]
|link:https://www.youtube.com/watch?v=Wn5215K7_Jg[022^] +
-Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:userguide:fun:building-blocks.adoc#mixins[mixin] (useful for decoupling).
+Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:userguide:fun:overview.adoc#mixins[mixin] (useful for decoupling).
|x|||||x|||||
|link:https://www.youtube.com/watch?v=m633OEBpWqQ[023^] +
-Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:userguide:fun:building-blocks.adoc#mixins[mixin].
+Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:userguide:fun:overview.adoc#mixins[mixin].
||||||x|||||
|link:https://www.youtube.com/watch?v=-AQJb9GtIqI[024^] +
-Using a domain event subscriber to xref:userguide:fun:building-blocks.adoc#domain-events[decouple] and abstract business rules (xref:refguide:applib-cm:methods.adoc#validate[validation]).
+Using a domain event subscriber to xref:userguide:fun:overview.adoc#domain-events[decouple] and abstract business rules (xref:refguide:applib-cm:methods.adoc#validate[validation]).
||||||x|||||
@@ -514,22 +514,22 @@ include::screencasts/playlists.adoc[]
|link:https://www.youtube.com/watch?v=puG-pzxRSd0[052^] +
-How to write a xref:userguide:fun:programming-model.adoc#jaxb[(JAXB) view model], holding references to two domain objects.
+How to write a xref:userguide:fun:view-models.adoc#jaxb[(JAXB) view model], holding references to two domain objects.
|x||||||||x||
|link:https://www.youtube.com/watch?v=tdBkmA2CCZY[053^] +
-Updating the title, icon and layout of a xref:userguide:fun:programming-model.adoc#jaxb[(JAXB) view model].
+Updating the title, icon and layout of a xref:userguide:fun:view-models.adoc#jaxb[(JAXB) view model].
||||x|||||||
|link:https://www.youtube.com/watch?v=TKF0FB_od00[054^] +
-How to expose information from underlying domain entities referenced by a xref:userguide:fun:programming-model.adoc#jaxb[(JAXB) view model] using derived properties
+How to expose information from underlying domain entities referenced by a xref:userguide:fun:view-models.adoc#jaxb[(JAXB) view model] using derived properties
||||||||||x|
|link:https://www.youtube.com/watch?v=TMMeVhRNi8A[055^] +
-Adding an action to a xref:userguide:fun:programming-model.adoc#jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
+Adding an action to a xref:userguide:fun:view-models.adoc#jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
||||x|||||||
diff --git a/api/adoc/userguide/modules/ROOT/pages/about.adoc b/api/adoc/userguide/modules/ROOT/pages/about.adoc
index 4db27d7..20d0843 100644
--- a/api/adoc/userguide/modules/ROOT/pages/about.adoc
+++ b/api/adoc/userguide/modules/ROOT/pages/about.adoc
@@ -3,12 +3,19 @@
: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 ag [...]
-The user guide breaks into two main sections:
-* xref:userguide:fun:about.adoc[Fundamentals]
-* xref:userguide:btb:about.adoc[Beyond the Basics]
+This guide introduces the xref:userguide:fun:concepts-patterns.adoc[core concepts] and the an xref:userguide:fun:overview.adoc[overview] of the building blocks of Apache Isis applications.
-It also includes some extensions:
+It goes on to describe the basics of the Apache Isis' programming model: xref:userguide:fun:domain-entities-and-services.adoc[domain entities and services], xref:userguide:fun:object-members.adoc[object members], xref:userguide:fun:ui-layout.adoc[UI layout] and xref:userguide:fun:ui-hints.adoc[UI hints], xref:userguide:fun:business-rules.adoc[business rules] and xref:userguide:fun:drop-downs-and-defaults.adoc[drop downs and defaults].
+
+It moves on to discuss some slightly more advanced areas of the programming model: xref:userguide:fun:meta-annotations.adoc[meta-annotations], xref:userguide:fun:view-models.adoc[view models] and xref:userguide:fun:mixins.adoc[mixins].
+These all allow you to develop more sophisticated applications, while remaining maintainable and elegant.
+
+To finish up, there is a chapter on xref:userguide:fun:crud.adoc[CRUD] which runs through these basic operations, and a chapter explaining how to structure your application using xref:userguide:fun:modules.adoc[modules].
+
+There is one further chapter, xref:userguide:btb:about.adoc[Beyond the Basics], which tackles more advanced topics.
+
+As an appendix, the guide also references some of the extensions that you are likely to use often and routinely:
* xref:userguide:flyway:about.adoc[Flyway]
diff --git a/api/adoc/userguide/modules/btb/pages/hints-and-tips/pushing-changes.adoc b/api/adoc/userguide/modules/btb/pages/hints-and-tips/pushing-changes.adoc
index bebd239..3a9d236 100644
--- a/api/adoc/userguide/modules/btb/pages/hints-and-tips/pushing-changes.adoc
+++ b/api/adoc/userguide/modules/btb/pages/hints-and-tips/pushing-changes.adoc
@@ -7,7 +7,7 @@
[NOTE]
====
-This technique is much less powerful than using xref:userguide:fun/building-blocks.adoc#domain-events[the event bus] or an SPI service.
+This technique is much less powerful than using xref:userguide:fun:overview.adoc#domain-events[the event bus] or an SPI service.
We present it mostly for completeness.
====
diff --git a/api/adoc/userguide/modules/fun/pages/about.adoc b/api/adoc/userguide/modules/fun/pages/about.adoc
index e1d5414..01be009 100644
--- a/api/adoc/userguide/modules/fun/pages/about.adoc
+++ b/api/adoc/userguide/modules/fun/pages/about.adoc
@@ -2,12 +2,6 @@
: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 ag [...]
-This guide introduces the xref:userguide:fun:core-concepts.adoc[core concepts] and the building blocks of Apache Isis applications, and describes the conventions of Apache Isis' xref:userguide:fun:programming-model.adoc[programming model].
-
-It goes on to explain the ideas of providing xref:userguide:fun:ui-hints.adoc[UI hints] such as titles and icons (though note that this is covered in more detail in the xref:vw:ROOT:layout.adoc[layout] chapter of the xref:vw:ROOT:about.adoc[Wicket Viewer] guide).
-
-There is also a chapter on xref:userguide:fun:crud.adoc[CRUD] operations, and a more interesting chapter on implementing xref:userguide:fun:business-rules.adoc[business rules].
-It finishes with a short chapter on implementing xref:userguide:fun:drop-downs-and-defaults.adoc[drop downs and defaults], important for actions that involve the interaction between several objects (in other words, most of them).
diff --git a/api/adoc/userguide/modules/fun/pages/business-rules.adoc b/api/adoc/userguide/modules/fun/pages/business-rules.adoc
index 49340f4..63c765c 100644
--- a/api/adoc/userguide/modules/fun/pages/business-rules.adoc
+++ b/api/adoc/userguide/modules/fun/pages/business-rules.adoc
@@ -4,7 +4,7 @@
:page-partial:
-As explained xref:building-blocks.adoc#business-rules[earlier], when a domain object is rendered in the UI or the end-user interacts with the domain object through the UI, the framework applies a series of precondition business rules to each object member.
+As explained xref:overview.adoc#business-rules[earlier], when a domain object is rendered in the UI or the end-user interacts with the domain object through the UI, the framework applies a series of precondition business rules to each object member.
These can be summarised as "see it, use it, do it".
.See it, use it, do it
@@ -18,7 +18,7 @@ These can be summarised as "see it, use it, do it".
****
The framework provides a multitude of ways to implement these business rules.
-One decoupled approach is using xref:userguide:fun:building-blocks.adoc#domain-events[domain events]; the checks above correspond to the phases of the domain event.
+One decoupled approach is using xref:userguide:fun:overview.adoc#domain-events[domain events]; the checks above correspond to the phases of the domain event.
A simpler approach is to just implement the business rules imperatively in the domain object, or in a mixin for the object.
diff --git a/api/adoc/userguide/modules/fun/pages/core-concepts.adoc b/api/adoc/userguide/modules/fun/pages/concepts-patterns.adoc
similarity index 100%
rename from api/adoc/userguide/modules/fun/pages/core-concepts.adoc
rename to api/adoc/userguide/modules/fun/pages/concepts-patterns.adoc
diff --git a/api/adoc/userguide/modules/fun/pages/core-concepts/apache-isis-vs-cqrs-and-event-sourcing.adoc b/api/adoc/userguide/modules/fun/pages/core-concepts/apache-isis-vs-cqrs-and-event-sourcing.adoc
index 67c1fdf..7e7b775 100644
--- a/api/adoc/userguide/modules/fun/pages/core-concepts/apache-isis-vs-cqrs-and-event-sourcing.adoc
+++ b/api/adoc/userguide/modules/fun/pages/core-concepts/apache-isis-vs-cqrs-and-event-sourcing.adoc
@@ -38,7 +38,7 @@ But then again, having a separate read model just so that the querying is very s
It is possible though to use Apache Isis in a CQRS style.
The entities would have no behaviour in and of themselves to modify their state, they would just be data structures.
-The behaviour (commands) would instead be implemented as xref:userguide:fun:programming-model.adoc#mixins[mixins] that act upon those commands.
+The behaviour (commands) would instead be implemented as xref:userguide:fun:mixins.adoc[mixins] that act upon those commands.
In the UI (surfaced by the xref:vw:ROOT:about.adoc[Wicket viewer]) or in the REST API (surfaced by the xref:vro:ROOT:about.adoc[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait), only at runtime.
However, this wouldn't be true CQRS because those mixins would modify those entities which would then be flushed back to the single database.
@@ -62,7 +62,7 @@ With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` acti
== Event Sourcing
-The xref:userguide:fun:core-concepts.adoc#cqrs[CQRS architecture] is often combined with _Event Sourcing_ pattern, though they are separate ideas.
+The xref:userguide:fun:concepts-patterns.adoc#cqrs[CQRS architecture] is often combined with _Event Sourcing_ pattern, though they are separate ideas.
With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly.
For example, if a customer places an order then this might emit the `OrderPlacedEvent`.
@@ -85,7 +85,7 @@ To use Apache Isis with event sourcing would require disregarding the inbuild su
Because Apache Isis runs on top of Spring Boot, such an integration ought to be comparatively easy to do.
But in any case the roadmap is to support JPA as well as JDO, indeed as you read this the framework may already support this, and so in the future there are likely be additional SPIs to enable this trivially).
-As with a CQRS architecture, Apache xref:userguide:fun:programming-model.adoc#mixins[mixins] would be the obvious way to associate behaviour with an event sourced entity.
+As with a CQRS architecture, Apache xref:userguide:fun:mixins.adoc[mixins] would be the obvious way to associate behaviour with an event sourced entity.
These mixins would most likely delegate to an event sourcing framework such as link:https://axoniq.io/[Axon] to do the work.
Also, in Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`], and can optionally also be published through the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
These features could also have a role to play in an event sourced system.
diff --git a/api/adoc/userguide/modules/fun/pages/core-concepts/architecture.adoc b/api/adoc/userguide/modules/fun/pages/core-concepts/architecture.adoc
index ccd97f0..965c941 100644
--- a/api/adoc/userguide/modules/fun/pages/core-concepts/architecture.adoc
+++ b/api/adoc/userguide/modules/fun/pages/core-concepts/architecture.adoc
@@ -5,6 +5,7 @@
This section describes some of the architectural patterns upon which Apache Isis builds.
+[#hexagonal-architecture]
== Hexagonal Architecture
One of the patterns that Evans discusses in his book is that of a *layered architecture*.
@@ -37,7 +38,7 @@ Here Apache Isis delegates most of the heavy lifting to an ORM (DataNucleus or s
[[aop]]
== Aspect Oriented
-Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:userguide:fun:core-concepts.adoc#naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name).
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:userguide:fun:concepts-patterns.adoc#naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name).
It's certainly true that to develop an Apache Isis application you will reasonably good object oriented modelling skills.
But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
@@ -86,11 +87,11 @@ Mixins can also contribute read-only properties or collections: effectively the
In other words, we can dissociate behaviour from data.
That's not always the right thing to do of course.
-In Richard Pawson's description of the xref:userguide:fun:core-concepts.adoc#naked-objects-pattern.adoc[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulates the data.
+In Richard Pawson's description of the xref:userguide:fun:concepts-patterns.adoc#naked-objects-pattern.adoc[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulates the data.
But on the other hand sometimes the behaviour and data structures change at different rates.
The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.
Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.
And again, to loop back to the topic of this section, it's an AOP concept that being implemented by the framework.
The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially - just focus on implementing your domain object.
-Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for xref:userguide:fun:building-blocks.adoc#mixins[mixins] and interceptors (using the xref:refguide:applib-svc:EventBusService.adoc[event bus]) to ensure that your codebase remains maintainable.
+Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for xref:userguide:fun:overview.adoc#mixins[mixins] and interceptors (using the xref:refguide:applib-svc:EventBusService.adoc[event bus]) to ensure that your codebase remains maintainable.
diff --git a/api/adoc/userguide/modules/fun/pages/core-concepts/core-values.adoc b/api/adoc/userguide/modules/fun/pages/core-concepts/core-values.adoc
index a440129..36e0473 100644
--- a/api/adoc/userguide/modules/fun/pages/core-concepts/core-values.adoc
+++ b/api/adoc/userguide/modules/fun/pages/core-concepts/core-values.adoc
@@ -78,7 +78,7 @@ The framework encourages splitting this functionality into modules; each such mo
This architecture means that it's impossible for business logic to leach out into the adjacent presentation layer because the developer doesn't (can't) write any code for presentation layer.
We in effect have a "firewall" between the two layers.
-To support the business domain being split into separate modules, the framework provides various features, the most important of which are the dependency injection of xref:building-blocks.adoc#domain-services[domain services], xref:building-blocks.adoc#mixins[mixins], and in-memory xref:building-blocks.adoc#events[events].
+To support the business domain being split into separate modules, the framework provides various features, the most important of which are the dependency injection of xref:overview.adoc#domain-services[domain services], xref:overview.adoc#mixins[mixins], and in-memory xref:overview.adoc#events[events].
For those cases where a module needs to interact with other modules but does not know about their implementations, the module can either define its own link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] domain services or it can define custom domain events and fire them.
This technique is also used extensively by the framework itself.
@@ -94,7 +94,7 @@ For further discussion on modular monoliths, check out Dan Haywood's article on
== Easing the road to DDD
-The case for xref:core-concepts.adoc#domain-driven-design[domain driven design] might be compelling, but that doesn't necessarily make it easy to do.
+The case for xref:concepts-patterns.adoc#domain-driven-design[domain driven design] might be compelling, but that doesn't necessarily make it easy to do.
Let's take a look at some of the challenges that _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
=== DDD takes a conscious effort
@@ -166,7 +166,7 @@ All the validation logic *must* be in the domain model because there is nowhere
Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework.
That means it is very possible to take your domain model prototyped in Apache Isis and then deploy it on some other _J(2)EE_ architecture, with a custom _UI_ if you want.
-This is discussed later on, in xref:core-concepts.adoc#deployment-options[deployment options].
+This is discussed later on, in xref:concepts-patterns.adoc#deployment-options[deployment options].
=== Extending the reach of DDD
diff --git a/api/adoc/userguide/modules/fun/pages/crud.adoc b/api/adoc/userguide/modules/fun/pages/crud.adoc
index 36597dc..20e74f9 100644
--- a/api/adoc/userguide/modules/fun/pages/crud.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud.adoc
@@ -4,10 +4,10 @@
:page-partial:
-This chapter shows the idioms for creating, reading, updating and deleting xref:userguide:fun:building-blocks.adoc#domain-entities[domain entities].
+This chapter shows the idioms for creating, reading, updating and deleting xref:userguide:fun:overview.adoc#domain-entities[domain entities].
The main domain services used for this are xref:refguide:applib-svc:RepositoryService.adoc[`RepositoryService`] and xref:refguide:applib-svc:FactoryService.adoc[`FactoryService`].
-It also shows how to instantiate xref:userguide:fun:building-blocks.adoc#view-models[view models] and how to programmatically instantiate xref:userguide:fun:building-blocks.adoc#mixins[mixins] (useful primarily for xref:testing:integtestsupport:about.adoc[integration testing]).
+It also shows how to instantiate xref:userguide:fun:overview.adoc#view-models[view models] and how to programmatically instantiate xref:userguide:fun:overview.adoc#mixins[mixins] (useful primarily for xref:testing:integtestsupport:about.adoc[integration testing]).
diff --git a/api/adoc/userguide/modules/fun/pages/crud/deleting.adoc b/api/adoc/userguide/modules/fun/pages/crud/deleting.adoc
index fd87293..2adbfc4 100644
--- a/api/adoc/userguide/modules/fun/pages/crud/deleting.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud/deleting.adoc
@@ -26,6 +26,6 @@ repositoryService.removeAndFlush(customer);
to eagerly perform the object deletion from the database.
-When an object is deleted the framework will emit `ObjectRemovingEvent` xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle event].
+When an object is deleted the framework will emit `ObjectRemovingEvent` xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle event].
diff --git a/api/adoc/userguide/modules/fun/pages/crud/finding.adoc b/api/adoc/userguide/modules/fun/pages/crud/finding.adoc
index 6b1210e..929ed51 100644
--- a/api/adoc/userguide/modules/fun/pages/crud/finding.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud/finding.adoc
@@ -59,7 +59,7 @@ Whenever a query is submitted, the framework will automatically "flush" any pend
This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved.
-When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle event].
+When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle event].
== Type-safe queries
diff --git a/api/adoc/userguide/modules/fun/pages/crud/instantiating.adoc b/api/adoc/userguide/modules/fun/pages/crud/instantiating.adoc
index 5f9d161..6ba159d 100644
--- a/api/adoc/userguide/modules/fun/pages/crud/instantiating.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud/instantiating.adoc
@@ -22,7 +22,7 @@ Dashboard dashboardVM = factoryService.instantiate(Dashboard.class);
----
For this to work the target class _must_ have a no-arg constructor.
-When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle event] will also be emitted.
+When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle event] will also be emitted.
However, you may prefer for your domain objects to have regular constructor defining their minimum set of mandatory properties.
@@ -51,7 +51,7 @@ serviceRegister.injectServicesInto(customer);
Note though that this does _not_ raise any lifecycle event.
-To instantiate a xref:userguide:fun:building-blocks.adoc#mixins[mixin], a different API of `FactoryService` is used:
+To instantiate a xref:userguide:fun:overview.adoc#mixins[mixin], a different API of `FactoryService` is used:
[source,java]
----
diff --git a/api/adoc/userguide/modules/fun/pages/crud/persisting.adoc b/api/adoc/userguide/modules/fun/pages/crud/persisting.adoc
index b63aedf..f96f3dc 100644
--- a/api/adoc/userguide/modules/fun/pages/crud/persisting.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud/persisting.adoc
@@ -56,7 +56,7 @@ Nevertheless, if you want to ensure that the persist command is flushed immediat
repositoryService.persistAndFlush(customer);
----
-When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle events].
+When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle events].
== Persistence by Reachability
diff --git a/api/adoc/userguide/modules/fun/pages/crud/updating.adoc b/api/adoc/userguide/modules/fun/pages/crud/updating.adoc
index ed38a50..5a88896 100644
--- a/api/adoc/userguide/modules/fun/pages/crud/updating.adoc
+++ b/api/adoc/userguide/modules/fun/pages/crud/updating.adoc
@@ -16,7 +16,7 @@ That said, it is possible to "flush" pending changes:
* using xref:pjdo:ROOT:services/IsisJdoSupport.adoc[`IsisJdoSupport`] it is possible to reach down to the underlying JDO API, and perform a flush of pending object updates also.
-When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle events].
+When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle events].
diff --git a/api/adoc/userguide/modules/ROOT/pages/about.adoc b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services.adoc
similarity index 74%
copy from api/adoc/userguide/modules/ROOT/pages/about.adoc
copy to api/adoc/userguide/modules/fun/pages/domain-entities-and-services.adoc
index 4db27d7..66ecfe1 100644
--- a/api/adoc/userguide/modules/ROOT/pages/about.adoc
+++ b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services.adoc
@@ -1,14 +1,10 @@
-= User Guides
-:page-role: -toc
+= Domain Entities and Services
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-The user guide breaks into two main sections:
-* xref:userguide:fun:about.adoc[Fundamentals]
-* xref:userguide:btb:about.adoc[Beyond the Basics]
-It also includes some extensions:
-
-* xref:userguide:flyway:about.adoc[Flyway]
+include::domain-entities-and-services/domain-entities.adoc[leveloffset=+1]
+include::domain-entities-and-services/domain-services.adoc[leveloffset=+1]
+include::domain-entities-and-services/inject-services.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/domain-entities.adoc b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-entities.adoc
similarity index 99%
rename from api/adoc/userguide/modules/fun/pages/programming-model/domain-entities.adoc
rename to api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-entities.adoc
index e7023e5..0f8affe 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/domain-entities.adoc
+++ b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-entities.adoc
@@ -1,3 +1,4 @@
+[#domain-entities]
= 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 ag [...]
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-services.adoc
similarity index 98%
rename from api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc
rename to api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-services.adoc
index 963cb11..4ad5c61 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc
+++ b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/domain-services.adoc
@@ -1,3 +1,4 @@
+[#domain-services]
= Domain Services
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
@@ -142,9 +143,9 @@ There's no need to name the action parameters if the code is compiled using the
<.> the action implementation delegates to an injected repository.
The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:userguide:fun:programming-model.adoc#inject-services[below].
+There is further discussion of service injection xref:userguide:fun:domain-entities-and-services.adoc#injecting-services[below].
-<.> xref:refguide:applib-ant:Action.adoc#restrictTo[Prototype] actions are rendered only in prototyping mode.
+<.> xref:refguide:applib-ant:Action.adoc#restrictto[Prototype] actions are rendered only in prototyping mode.
A "list all" action such as this can be useful when exploring the domain with a small dataset.
<.> Menu services typically delegate to an underlying repository/ies specific to the domain (rather than use `RepositoryService` directly, for example).
@@ -155,7 +156,7 @@ An alternative perspective is that the duplication is just unnecessary boilerpla
== Event Subscribers
-Domain services acting as event subscribers can subscribe to xref:userguide:fun:building-blocks.adoc#lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
+Domain services acting as event subscribers can subscribe to xref:userguide:fun:overview.adoc#lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
Behind the scenes this uses Spring's (in-memory) link:https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/core.html#context-functionality-events-annotation[event bus].
[source,java]
@@ -274,7 +275,7 @@ val prohibitedCharacters =
----
For this configuration property service to be discovered and managed by Spring, we need to use the link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/context/properties/EnableConfigurationProperties.html[`EnableConfigurationProperties`] annotation.
-This normally would reside on the owning module (discussed in more detail xref:programming-model.adoc#modules[later]):
+This normally would reside on the owning module (discussed in more detail xref:modules.adoc[later]):
[source,java]
.SimpleModule.java
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/inject-services.adoc b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/inject-services.adoc
similarity index 96%
rename from api/adoc/userguide/modules/fun/pages/programming-model/inject-services.adoc
rename to api/adoc/userguide/modules/fun/pages/domain-entities-and-services/inject-services.adoc
index a2123aa..da9b4c8 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/inject-services.adoc
+++ b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/inject-services.adoc
@@ -1,3 +1,4 @@
+[#injecting-services]
= Injecting services
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
@@ -17,7 +18,7 @@ It is also possible to use Spring's own link:https://docs.spring.io/spring-frame
Since the two annotations are effectively equivalent, we recommend using the JEE standard.
====
-However, not only does Apache Isis use Spring to autowire domain services into other services, the framework _also_ ensures that services are injected into any domain object (eg xref:building-blocks.adoc#domain-entities[entity], xref:building-blocks.adoc#view-models[view model], xref:building-blocks.adoc#mixins[mixins], xref:testing:fixtures:about.adoc#fixture-scripts[fixture script], xref:refguide:applib-cm:classes.adoc#specification[specification] etc).
+However, not only does Apache Isis use Spring to autowire domain services into other services, the framework _also_ ensures that services are injected into any domain object (eg xref:overview.adoc#domain-entities[entity], xref:overview.adoc#view-models[view model], xref:overview.adoc#mixins[mixins], xref:testing:fixtures:about.adoc#fixture-scripts[fixture script], xref:refguide:applib-cm:classes.adoc#specification[specification] etc).
This is key enabler to place functionality in the "right place", eg in a domain entity/view model itself, or in a mixin.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/meta-annotations.adoc b/api/adoc/userguide/modules/fun/pages/meta-annotations.adoc
similarity index 100%
rename from api/adoc/userguide/modules/fun/pages/programming-model/meta-annotations.adoc
rename to api/adoc/userguide/modules/fun/pages/meta-annotations.adoc
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/mixins.adoc b/api/adoc/userguide/modules/fun/pages/mixins.adoc
similarity index 98%
rename from api/adoc/userguide/modules/fun/pages/programming-model/mixins.adoc
rename to api/adoc/userguide/modules/fun/pages/mixins.adoc
index d094d9a..a693279 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/mixins.adoc
+++ b/api/adoc/userguide/modules/fun/pages/mixins.adoc
@@ -4,7 +4,7 @@
:page-partial:
-A xref:userguide:fun:building-blocks.adoc#mixins[mixin] acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object.
+A xref:userguide:fun:overview.adoc#mixins[mixin] acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object.
Under the covers, all mixins are basically actions that use the mixee as one of their arguments.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc b/api/adoc/userguide/modules/fun/pages/modules.adoc
similarity index 98%
rename from api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc
rename to api/adoc/userguide/modules/fun/pages/modules.adoc
index db559ee..a5122a8 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc
+++ b/api/adoc/userguide/modules/fun/pages/modules.adoc
@@ -10,7 +10,7 @@ Spring's link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/o
TIP: See Spring documentation on link:https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/core.html#beans-annotation-config[annotation-based container configuration], link:https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/core.html#beans-classpath-scanning[classpath scanning] and link:https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/core.html#beans-java[java-based configuration] for much more on this topic.
By convention, we have one Spring "logical" module in each Maven "physical" module, meaning that Maven itself can be used to enforce acyclic dependencies.
-(See xref:building-blocks.adoc#modules[previous chapter] for more discussion on the alternatives).
+(See xref:overview.adoc#modules[previous chapter] for more discussion on the alternatives).
Thus, there will be a single top-level package corresponding to the module, and this will be aligned with the `<groupId>` and `<artifactId>` of the Maven module in which it resides.
diff --git a/api/adoc/userguide/modules/ROOT/pages/about.adoc b/api/adoc/userguide/modules/fun/pages/object-members.adoc
similarity index 75%
copy from api/adoc/userguide/modules/ROOT/pages/about.adoc
copy to api/adoc/userguide/modules/fun/pages/object-members.adoc
index 4db27d7..9c1177a 100644
--- a/api/adoc/userguide/modules/ROOT/pages/about.adoc
+++ b/api/adoc/userguide/modules/fun/pages/object-members.adoc
@@ -1,14 +1,8 @@
-= User Guides
-:page-role: -toc
+= Object Members
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-The user guide breaks into two main sections:
-
-* xref:userguide:fun:about.adoc[Fundamentals]
-* xref:userguide:btb:about.adoc[Beyond the Basics]
-
-It also includes some extensions:
-
-* xref:userguide:flyway:about.adoc[Flyway]
+include::object-members/properties.adoc[leveloffset=+1]
+include::object-members/collections.adoc[leveloffset=+1]
+include::object-members/actions.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/actions.adoc b/api/adoc/userguide/modules/fun/pages/object-members/actions.adoc
similarity index 92%
rename from api/adoc/userguide/modules/fun/pages/programming-model/actions.adoc
rename to api/adoc/userguide/modules/fun/pages/object-members/actions.adoc
index be71667..fbb7989 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/actions.adoc
+++ b/api/adoc/userguide/modules/fun/pages/object-members/actions.adoc
@@ -5,7 +5,7 @@
:page-partial:
-An action is a public method that is presented as a prompt form, and invoked upon a target object (or on a xref:building-blocks.adoc#mixins[mixin] contributing to the target object).
+An action is a public method that is presented as a prompt form, and invoked upon a target object (or on a xref:overview.adoc#mixins[mixin] contributing to the target object).
They allow the user to perform complex interactions with the domain object, and so raise the level of abstraction compared to requiring the user than simple CRUD-style operations.
@@ -13,11 +13,11 @@ For example, imagine a lease management system, where a lease is extended by cre
There are three operations here: set the end date of the original lease term, create the new lease term with relevant details copied over from the original lease term, and set the start date of the lease term correctly.
Instead, all of these operations can be combined into a single action, "renew".
-Through such means the xref:core-concepts.adoc#ubiquitous-language[ubiquitous language] grows.
+Through such means the xref:concepts-patterns.adoc#ubiquitous-language[ubiquitous language] grows.
-TIP: This is the reason why Apache Isis' default is xref:programming-model.adoc#editable-properties[non-editable properties]: to encourage this sort of "knowledge crunching".
+TIP: This is the reason why Apache Isis' default is xref:object-members.adoc#editable-properties[non-editable properties]: to encourage this sort of "knowledge crunching".
-You can find further discussion on when and why you should write actions xref:building-blocks.adoc#actions[earlier].
+You can find further discussion on when and why you should write actions xref:overview.adoc#actions[earlier].
== Defining actions
@@ -164,7 +164,7 @@ public List<Product> autoComplete0AddToBasket( // <.>
}
----
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:refguide:applib-ant:DomainObject.adoc[`@DomainObject`] on the referenced type (described xref:userguide:fun:programming-model.adoc#reference-parameter-types[above]).
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:refguide:applib-ant:DomainObject.adoc[`@DomainObject`] on the referenced type (described xref:userguide:fun:object-members.adoc#reference-parameter-types[above]).
== Optional Parameters
@@ -201,7 +201,7 @@ private LocalDate shipBy;
+
Note that this uses an ORM-specific mechanism to specify the same semantics (in this case, using JDO/DataNucleus' `@Column#allowsNull()`.)
-See also xref:userguide:fun:programming-model.adoc#properties-vs-parameters[properties vs parameters].
+See also xref:userguide:fun:meta-annotations.adoc#properties-vs-parameters[properties vs parameters].
== ``String`` Parameters (Length)
@@ -247,7 +247,7 @@ Incidentally, note in the above example that the new value is assigned to the pr
This is important, because it allows the ORM to keep track that this instance variable is "dirty" and so needs writing to the database table before the transaction completes.
====
-See also xref:userguide:fun:programming-model.adoc#properties-vs-parameters[properties vs parameters].
+See also xref:userguide:fun:meta-annotations.adoc#properties-vs-parameters[properties vs parameters].
== ``BigDecimal``s (Precision)
@@ -278,7 +278,7 @@ private BigDecimal discountRate;
+
Note that this uses an ORM-specific annotation (in this case, xref:refguide:applib-ant:Column.adoc#lengthscale-for-bigdecimals[`@Column#scale`]
-See also xref:userguide:fun:programming-model.adoc#properties-vs-parameters[properties vs parameters].
+See also xref:userguide:fun:meta-annotations.adoc#properties-vs-parameters[properties vs parameters].
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/collections.adoc b/api/adoc/userguide/modules/fun/pages/object-members/collections.adoc
similarity index 94%
rename from api/adoc/userguide/modules/fun/pages/programming-model/collections.adoc
rename to api/adoc/userguide/modules/fun/pages/object-members/collections.adoc
index 12504ac..b044736 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/collections.adoc
+++ b/api/adoc/userguide/modules/fun/pages/object-members/collections.adoc
@@ -8,7 +8,7 @@
A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
For example, a `Customer` may have a collection of ``Order``s).
-It's ok for a xref:userguide:fun:programming-model.adoc#view-models[view model] to reference both view model and domain entities.
+It's ok for a xref:userguide:fun:view-models.adoc[view model] to reference both view model and domain entities.
However, it _isn't_ valid for a domain entity to hold a reference to view model, because the ORM will not know how to persist the view model object.
Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
@@ -26,8 +26,8 @@ Other annotations can be used to specify if the association is bidirectional, an
Apache Isis may recognise some of these annotations from the persistence layer infers some domain semantics from them.
-Unlike xref:userguide:fun:programming-model.adoc#properties[properties], the framework does not allow collections to be "edited".
-Instead, xref:userguide:fun:programming-model.adoc#actions[action]s can be written that will modify the contents of the collection as a side-effect.
+Unlike xref:userguide:fun:object-members.adoc#properties[properties], the framework does not allow collections to be "edited".
+Instead, xref:userguide:fun:object-members.adoc#actions[action]s can be written that will modify the contents of the collection as a side-effect.
For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc b/api/adoc/userguide/modules/fun/pages/object-members/properties.adoc
similarity index 98%
rename from api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
rename to api/adoc/userguide/modules/fun/pages/object-members/properties.adoc
index 767e4b1..2017165 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
+++ b/api/adoc/userguide/modules/fun/pages/object-members/properties.adoc
@@ -5,7 +5,7 @@
:page-partial:
-A property is an instance variable of a domain object, of a scalar type, that holds some state in either a xref:userguide:fun:programming-model.adoc#domain-entities[domain entity] or a xref:userguide:fun:programming-model.adoc#view-models[view model].
+A property is an instance variable of a domain object, of a scalar type, that holds some state in either a xref:userguide:fun:domain-entities-and-services.adoc#domain-entities[domain entity] or a xref:userguide:fun:view-models.adoc[view model].
For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
@@ -73,7 +73,7 @@ import lombok.Setter;
private Customer customer;
----
-It's ok for a xref:userguide:fun:programming-model.adoc#view-models[view model] to reference other view models and also to reference domain entities.
+It's ok for a xref:userguide:fun:view-models.adoc[view model] to reference other view models and also to reference domain entities.
However, it _isn't_ valid for a domain entity to hold a reference to view model, because the ORM will not know how to persist the view model object.
[TIP]
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks.adoc b/api/adoc/userguide/modules/fun/pages/overview.adoc
similarity index 66%
rename from api/adoc/userguide/modules/fun/pages/building-blocks.adoc
rename to api/adoc/userguide/modules/fun/pages/overview.adoc
index fffd7b4..9ceb580 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview.adoc
@@ -1,16 +1,16 @@
-= Building Blocks
+= Overview
: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 ag [...]
In this section we run through the main building blocks that make up an Apache Isis application.
-include::building-blocks/types-of-domain-objects.adoc[leveloffset=+1]
-include::building-blocks/identifiers.adoc[leveloffset=+1]
-include::building-blocks/object-members.adoc[leveloffset=+1]
-include::building-blocks/business-rules.adoc[leveloffset=+1]
-include::building-blocks/events.adoc[leveloffset=+1]
-include::building-blocks/modules.adoc[leveloffset=+1]
-include::building-blocks/programming-model.adoc[leveloffset=+1]
+include::overview/types-of-domain-objects.adoc[leveloffset=+1]
+include::overview/identifiers.adoc[leveloffset=+1]
+include::overview/object-members.adoc[leveloffset=+1]
+include::overview/business-rules.adoc[leveloffset=+1]
+include::overview/events.adoc[leveloffset=+1]
+include::overview/modules.adoc[leveloffset=+1]
+include::overview/programming-model.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/business-rules.adoc b/api/adoc/userguide/modules/fun/pages/overview/business-rules.adoc
similarity index 100%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/business-rules.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/business-rules.adoc
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/events.adoc b/api/adoc/userguide/modules/fun/pages/overview/events.adoc
similarity index 92%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/events.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/events.adoc
index af79462..6eeac35 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/events.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/events.adoc
@@ -12,6 +12,7 @@ To receive the events, the domain service should subscribe to the xref:refguide:
The framework has several categories of events: domain events, UI events and lifecycle events.
These are explored in the sections below.
+[#domain-events]
== Domain Events
Domain events are fired -- through the internal xref:refguide:applib-svc:EventBusService.adoc[event bus] -- for every user interaction with each object member (property, collection or action).
@@ -45,7 +46,7 @@ For more details on the actual domain event classes, see the xref:refguide:appli
== UI Events
-As explained xref:userguide:fun:building-blocks.adoc#title-and-icon-and-css-class[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+As explained xref:userguide:fun:overview.adoc#title-and-icon-and-css-class[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
xref:userguide:fun:ui-hints.adoc#object-titles-and-icons[Normally] the code to return title and icon of an object is part of the domain object's implementation.
However, UI events allow this title and icon to be provided instead by a subscriber.
@@ -59,9 +60,9 @@ There are two use cases where this feature is useful:
* the first is to override the title/icon/CSS class/layout of 3rd party library code, for example as provided by the xref:security:secman:about.adoc[SecMan] extension.
-* the second is for xref:userguide:fun:programming-model.adoc#jaxb[JAXB-style view models] which are code generated from XSDs and so cannot have any dependencies on the rest of the Apache Isis framework.
+* the second is for xref:userguide:fun:view-models.adoc#jaxb[JAXB-style view models] which are code generated from XSDs and so cannot have any dependencies on the rest of the Apache Isis framework.
-In this second case a subscriber on the default events can provide a title and icon for such an object, with the behaviour provided using xref:userguide:fun:building-blocks.adoc#mixins[mixins].
+In this second case a subscriber on the default events can provide a title and icon for such an object, with the behaviour provided using xref:userguide:fun:overview.adoc#mixins[mixins].
== Lifecycle Events
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/identifiers.adoc b/api/adoc/userguide/modules/fun/pages/overview/identifiers.adoc
similarity index 95%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/identifiers.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/identifiers.adoc
index 3716a4f..9297563 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/identifiers.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/identifiers.adoc
@@ -38,7 +38,7 @@ Details on how to actually write titles and icons (the programming model) can be
[[oid]]
== OIDs
-As well as defining a xref:userguide:fun:core-concepts.adoc#metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+As well as defining a xref:userguide:fun:concepts-patterns.adoc#metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
Fundamentally this is a combination of its type (domain class), along with an identifier.
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc b/api/adoc/userguide/modules/fun/pages/overview/modules.adoc
similarity index 92%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/modules.adoc
index 0b30c3d..d9fa0e5 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/modules.adoc
@@ -3,7 +3,7 @@
: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 ag [...]
:page-partial:
-As described xref:core-concepts.adoc#modular[previously], enabling and ensuring modularity is an key principle for Apache Isis frameworks.
+As described xref:concepts-patterns.adoc#modular[previously], enabling and ensuring modularity is an key principle for Apache Isis frameworks.
Modularity is the only way to ensure that a complex application domain does not overwhelm and result in unmaintainable software.
Modules chunk up the overall application into smaller pieces, usually a pacakge and subpackages.
@@ -35,11 +35,11 @@ Both xref:refguide:applib-svc:about.adoc[framework-defined] domain services and
By "everywhere", we mean not just into domain services, but _also_ injected into domain entities and view models.
This enables us to implement behaviourally complete domain objects (if we so wish).
-* xref:building-blocks.adoc#mixins[mixins] that allow functionality defined in one module to appear (in the UI) to be provided by some other module.
+* xref:overview.adoc#mixins[mixins] that allow functionality defined in one module to appear (in the UI) to be provided by some other module.
+
For example, a _Document_ module might allow `Document` objects to be attached to any arbitrary domain object (such as `Order` or `Customer`) in other modules.
A mixin would allow the UI for a `Customer` to also display these attached ``Document``s, even though the _Customer_ module would have no knowledge of/dependency on the _Workflow_ module.
-(More on this example xref:building-blocks.adoc#inverting-dependencies[below]).
+(More on this example xref:overview.adoc#inverting-dependencies[below]).
+
Dependencies are also injected into mixins.
A common technique is to factor out from domain objects into mixins and then generalise.
@@ -47,7 +47,7 @@ A common technique is to factor out from domain objects into mixins and then gen
* the internal xref:refguide:applib-svc:EventBusService.adoc[event bus] allows modules to influence other modules.
+
A subscriber in one module can subscribe to events emitted by domain objects in another module.
-These events can affect both the UI (eg hiding or disabling xref:building-blocks.adoc#object-members[object members], or allowing or vetoing interactions).
+These events can affect both the UI (eg hiding or disabling xref:overview.adoc#object-members[object members], or allowing or vetoing interactions).
A good example of this last is supporting (what in an RDBMS we would call) referential integrity.
Suppose the `customers` module has a `Customer` object and a `EmailAddress` object, with a customer having a collection of email addresses.
@@ -67,7 +67,7 @@ If we get the dependencies wrong (that is, our initial guess on stability is pro
* use the link:https://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to introduce an abstraction representing the dependency.
-* move functionality, eg by factoring it out into xref:building-blocks.adoc#mixins[mixins] into the other module or into a third module which depends on the other modules that had a bidirectional relationship
+* move functionality, eg by factoring it out into xref:overview.adoc#mixins[mixins] into the other module or into a third module which depends on the other modules that had a bidirectional relationship
Mixins in particular allow dependencies to be inverted, so that the dependencies between modules can be kept acyclic and under control.
@@ -146,7 +146,7 @@ We can therefore rely on Maven to ensure there are no cyclic dependencies: the a
[TIP]
====
-Details on how to actually define modules can be found xref:userguide:fun:programming-model.adoc#modules[here].
+Details on how to actually define modules can be found xref:userguide:fun:modules.adoc[here].
====
If the above convention is too officious,then you could choose to have multiple Spring modules per Maven module, but you will need to watch out for cycles.
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/object-members.adoc b/api/adoc/userguide/modules/fun/pages/overview/object-members.adoc
similarity index 92%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/object-members.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/object-members.adoc
index 07292ee..b211ed5 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/object-members.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/object-members.adoc
@@ -55,7 +55,7 @@ Whether it is present or not depends to some extent on your preferred style: the
[TIP]
====
-Details on how to actually write properties in practice (the programming model) can be found xref:userguide:fun:programming-model.adoc#properties[here].
+Details on how to actually write properties in practice (the programming model) can be found xref:userguide:fun:object-members.adoc#properties[here].
====
@@ -91,21 +91,21 @@ Whether it is present or not depends to some extent on your preferred style: the
[TIP]
====
-Details on how to actually write collections in practice (the programming model) can be found xref:userguide:fun:programming-model.adoc#collections[here].
+Details on how to actually write collections in practice (the programming model) can be found xref:userguide:fun:object-members.adoc#collections[here].
====
[#actions]
== Actions
-While xref:userguide:fun:programming-model.adoc#properties[properties] and xref:userguide:fun:programming-model.adoc#collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+While xref:userguide:fun:object-members.adoc#properties[properties] and xref:userguide:fun:object-members.adoc#collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
An application that consists only of domain entities with just "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
Such applications are often called CRUD applications (create/read/update/delete).
In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
Actions allow those business rules to be encoded programmatically.
-Those actions can either be defined in the domain class itself, or can be contributed by way of a xref:building-blocks.adoc#mixins[mixin].
+Those actions can either be defined in the domain class itself, or can be contributed by way of a xref:overview.adoc#mixins[mixin].
The general philosophy for an Apache Isis (naked objects) application is _not_ to constrain the end-user in how they interact with the UI: it doesn't attempt to define a rigid business process.
However, it _does_ aim to ensure that business rule invariants are maintained, that is that domain objects aren't allowed to enter into an invalid state.
@@ -153,5 +153,5 @@ Note though that UI hints for parameters _cannot_ be specified in the layout fil
[TIP]
====
-Details on how to actually write actions in practice (the programming model) can be found xref:userguide:fun:programming-model.adoc#actions[here].
+Details on how to actually write actions in practice (the programming model) can be found xref:userguide:fun:object-members.adoc#actions[here].
====
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/programming-model.adoc b/api/adoc/userguide/modules/fun/pages/overview/programming-model.adoc
similarity index 67%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/programming-model.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/programming-model.adoc
index 26d3cde..0ee9b13 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/programming-model.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/programming-model.adoc
@@ -3,11 +3,11 @@
: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 ag [...]
-Apache Isis works by building a xref:core-concepts.adoc#metamodel[metamodel] of the domain objects: entities, domain services, view models and mixins.
-Dependent on the xref:building-blocks.adoc#type-of-domain-objects[sort of domain object], the class methods represent both state -- (single-valued) xref:building-blocks.adoc#properties[properties] and (multi-valued) xref:building-blocks.adoc#collections[collections] -- and behaviour -- xref:building-blocks.adoc#actions[actions].
+Apache Isis works by building a xref:concepts-patterns.adoc#metamodel[metamodel] of the domain objects: entities, domain services, view models and mixins.
+Dependent on the xref:overview.adoc#type-of-domain-objects[sort of domain object], the class methods represent both state -- (single-valued) xref:overview.adoc#properties[properties] and (multi-valued) xref:overview.adoc#collections[collections] -- and behaviour -- xref:overview.adoc#actions[actions].
-More specifically, both xref:building-blocks.adoc#domain-entities[entities] and xref:building-blocks.adoc#view-models[view models] can have properties, collections and actions, while xref:building-blocks.adoc#domain-services[domain services] have just actions.
-xref:building-blocks.adoc#mixins[Mixins] also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
+More specifically, both xref:overview.adoc#domain-entities[entities] and xref:overview.adoc#view-models[view models] can have properties, collections and actions, while xref:overview.adoc#domain-services[domain services] have just actions.
+xref:overview.adoc#mixins[Mixins] also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
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.
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/types-of-domain-objects.adoc b/api/adoc/userguide/modules/fun/pages/overview/types-of-domain-objects.adoc
similarity index 96%
rename from api/adoc/userguide/modules/fun/pages/building-blocks/types-of-domain-objects.adoc
rename to api/adoc/userguide/modules/fun/pages/overview/types-of-domain-objects.adoc
index 29045ec..d006f48 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/types-of-domain-objects.adoc
+++ b/api/adoc/userguide/modules/fun/pages/overview/types-of-domain-objects.adoc
@@ -61,7 +61,7 @@ This isn't a hard-n-fast rule, but it is a good rule of thumb.
[TIP]
====
Details on how to actually write a domain entity (the programming model for domain entities) is
-xref:userguide:fun:programming-model.adoc#domain-entities[here].
+xref:userguide:fun:domain-entities-and-services.adoc#domain-entities[here].
====
[#domain-services]
@@ -86,7 +86,7 @@ Domain services can also be used for a number of other purposes:
* to provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API, or to perform some calculation, or attach a barcode, send an email etc
* to act as a subscribers to the event bus, potentially influencing events fired by some other module (a key technique for decoupling large applications) +
-+ This is discussed in more detail below, in the section on xref:userguide:fun:building-blocks.adoc#events[events].
++ This is discussed in more detail below, in the section on xref:userguide:fun:overview.adoc#events[events].
* to implement an link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] of the Apache Isis framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
@@ -99,12 +99,12 @@ Domain services are instantiated once and once only by the framework, and are us
[TIP]
====
Details on how to actually write a domain service (the programming model for domain services) is
-xref:userguide:fun:programming-model.adoc#domain-services[here].
+xref:userguide:fun:domain-entities-and-services.adoc#domain-services[here].
====
=== Hexagonal Architecture
-It's worth extending the xref:userguide:fun:core-concepts.adoc#hexagonal-architecture[Hexagonal Architecture] to show where domain services fit in:
+It's worth extending the xref:userguide:fun:concepts-patterns.adoc#hexagonal-architecture[Hexagonal Architecture] to show where domain services fit in:
.The hexagonal architecture with API and SPI implementations
image::core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px",link="{imagesdir}/core-concepts/philosophy/hexagonal-architecture-addons.png"]
@@ -136,7 +136,7 @@ We explore these use cases in more detail below.
[TIP]
====
-Details on how to actually write a view model (the programming model for view models) can be found xref:userguide:fun:programming-model.adoc#view-models[here].
+Details on how to actually write a view model (the programming model for view models) can be found xref:userguide:fun:view-models.adoc[here].
====
=== Externally-managed entities
@@ -211,11 +211,11 @@ This is done by annotating the class using JAXB annotations; this allows the con
//[TIP]
//====
-//Details of how to consume such DTOs, eg within an ESB such as link:http://camel.apache.org[Apache Camel(TM)], can be found xref:userguide:fun:programming-model.adoc#dto-consumers[here].
+//Details of how to consume such DTOs, eg within an ESB such as link:http://camel.apache.org[Apache Camel(TM)], can be found xref:userguide:fun:view-models.adoc#dto-consumers[here].
//====
These DTOs are still usable as "regular" view models; they will render in the xref:vw:ROOT:about.adoc[Wicket viewer] just like any other.
-In fact (as the xref:userguide:fun:programming-model.adoc#jaxb[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
+In fact (as the xref:userguide:fun:view-models.adoc#jaxb[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
The view model simply needs to implement the xref:refguide:applib-cm:classes/mixins.adoc#Dto[`Dto`] marker interface; the framework has xref:refguide:applib-cm:classes/mixins.adoc#Dto[mixins] that contribute the download actions to the view model.
@@ -262,7 +262,7 @@ A mixin object allows one class to contribute behaviour - actions, (derived) pro
Or rather, the mixin _appears_ to contribute the behaviour/state in the UI; the underlying domain class being "decorated" does not know this is happening.
This is therefore a key technique to allow the app to stay decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
-There's a lot more discussion on this topic in xref:building-blocks.adoc#modules[modules], below.
+There's a lot more discussion on this topic in xref:overview.adoc#modules[modules], below.
Mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
@@ -288,7 +288,7 @@ There are also commercial products such as JRebel.
[TIP]
====
Details on how to actually write a mixin (the programming model for mixins) is
-xref:userguide:fun:programming-model.adoc#mixins[here].
+xref:userguide:fun:mixins.adoc[here].
====
.DCI Architecture
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model.adoc b/api/adoc/userguide/modules/fun/pages/programming-model.adoc
index 91239fb..dc0b910 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model.adoc
@@ -4,16 +4,5 @@
-include::programming-model/domain-entities.adoc[leveloffset=+1]
-include::programming-model/domain-services.adoc[leveloffset=+1]
-include::programming-model/modules.adoc[leveloffset=+1]
-include::programming-model/properties.adoc[leveloffset=+1]
-include::programming-model/collections.adoc[leveloffset=+1]
-include::programming-model/actions.adoc[leveloffset=+1]
-include::programming-model/meta-annotations.adoc[leveloffset=+1]
-include::programming-model/inject-services.adoc[leveloffset=+1]
-include::programming-model/view-models.adoc[leveloffset=+1]
-include::programming-model/mixins.adoc[leveloffset=+1]
-
diff --git a/api/adoc/userguide/modules/fun/pages/ui-hints.adoc b/api/adoc/userguide/modules/fun/pages/ui-hints.adoc
index 98e517d..139ade7 100644
--- a/api/adoc/userguide/modules/fun/pages/ui-hints.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui-hints.adoc
@@ -8,8 +8,6 @@ The Apache Isis programming model includes several mechanisms for a domain objec
These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
-
-include::ui-hints/layout.adoc[leveloffset=+1]
include::ui-hints/object-titles-and-icons.adoc[leveloffset=+1]
include::ui-hints/action-icons-and-css.adoc[leveloffset=+1]
include::ui-hints/names-and-descriptions.adoc[leveloffset=+1]
diff --git a/api/adoc/userguide/modules/fun/pages/ui-hints/layout.adoc b/api/adoc/userguide/modules/fun/pages/ui-layout.adoc
similarity index 90%
rename from api/adoc/userguide/modules/fun/pages/ui-hints/layout.adoc
rename to api/adoc/userguide/modules/fun/pages/ui-layout.adoc
index acd1160..e024811 100644
--- a/api/adoc/userguide/modules/fun/pages/ui-hints/layout.adoc
+++ b/api/adoc/userguide/modules/fun/pages/ui-layout.adoc
@@ -1,14 +1,15 @@
-[#layout-file]
-= Layout File
+= UI Layout
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
+
The most significant aspect of the UI is the layout of the object's members: its properties, collections and actions.
These can be organized into columns, rows and tabs.
This can be accomplished using either annotations or through a separate file-based layout.
Since this is a large topic, it has its own xref:vw:ROOT:layout.adoc[layout chapter] in the Wicket viewer guide.
+WARNING: TODO: v2 - move this material here, since it applies to any viewer, not just the Wicket viewer.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/view-models.adoc b/api/adoc/userguide/modules/fun/pages/view-models.adoc
similarity index 94%
rename from api/adoc/userguide/modules/fun/pages/programming-model/view-models.adoc
rename to api/adoc/userguide/modules/fun/pages/view-models.adoc
index 5674cf6..aadbabb 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/view-models.adoc
+++ b/api/adoc/userguide/modules/fun/pages/view-models.adoc
@@ -5,7 +5,7 @@
:page-partial:
-As described in the xref:userguide:fun:building-blocks.adoc#view-models[introduction], view models are domain objects like domain entities, with behaviour and state.
+As described in the xref:userguide:fun:overview.adoc#view-models[introduction], view models are domain objects like domain entities, with behaviour and state.
However, unlike domain entities, their state is _not_ persisted to a database but is instead serialized into its identifier (in effect, its URL).
In other words, the framework will automatically manage the view model's state.
@@ -73,7 +73,7 @@ This is an all-or-nothing affair: either all properties must be listed, or else
For collections, the `@XmlElementWrapper` would also typically be used.
<.> The `@XmlTransient` indicates that the property is derived and should be ignored by JAXB. +
-The derived properties could also have been implemented using xref:userguide:fun:building-blocks.adoc#mixins[mixins].
+The derived properties could also have been implemented using xref:userguide:fun:overview.adoc#mixins[mixins].
[IMPORTANT]
====
@@ -88,7 +88,7 @@ a URL.
=== Referencing Domain Entities
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 xref:userguide:fun:programming-model.adoc#jaxb[above] actually references two underlying ``Customer`` entities.
+For example, the `CompareCustomers` view model described xref:userguide:fun:view-models.adoc#jaxb[above] actually references two underlying ``Customer`` entities.
It wouldn't make sense to serialize out the state of a persistent entity.
However, the identity of the underlying entity is well defined; Apache Isis defines the xref:refguide:schema:common.adoc[common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
@@ -139,7 +139,7 @@ public class CompareCustomers {
}
----
-This capability is particularly useful when the JAXB view model is being used as a xref:userguide:fun:programming-model.adoc#dto[DTO].
+// This capability is particularly useful when the JAXB view model is being used as a xref:userguide:fun:view-models.adoc#dto[DTO].
[[joda-datatypes]]
=== JODA Time Datatypes
@@ -217,7 +217,7 @@ Double check that view models are implicitly cloned even in this fashion.
Instead of using JAXB to specify a view model, it is also possible to use Apache Isis-specific annotations.
-As was explained xref:userguide:fun:programming-model.adoc#view-models[earlier], the approach is described here is neither as flexible nor as powerful as using the JAXB-style of view models.
+As was explained xref:userguide:fun:view-models.adoc[earlier], the approach is described here is neither as flexible nor as powerful as using the JAXB-style of view models.
It is however likely to be faster.
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.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/UNUSED-dto.adoc b/api/adoc/userguide/modules/fun/pages/view-models/UNUSED-dto.adoc
similarity index 95%
rename from api/adoc/userguide/modules/fun/pages/programming-model/UNUSED-dto.adoc
rename to api/adoc/userguide/modules/fun/pages/view-models/UNUSED-dto.adoc
index d3f23f5..2c4c057 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/UNUSED-dto.adoc
+++ b/api/adoc/userguide/modules/fun/pages/view-models/UNUSED-dto.adoc
@@ -47,16 +47,16 @@ public class ToDoItemV1_1 implements Dto { // <.>
protected List<ToDoItem> similarItems = Lists.newArrayList();
}
----
-<.> package name encodes major version; see discussion on xref:userguide:fun:programming-model.adoc#versioning[versioning]
+<.> package name encodes major version; see discussion on xref:userguide:fun:view-models.adoc#versioning[versioning]
<.> identifies this class as a view model and defines the root element for JAXB serialization
<.> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
<.> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:refguide:applib-ant:DomainObjectLayout.adoc#titleuievent[`@DomainObjectLayout#titleUiEvent()`].
-<.> class name encodes (major and) minor version; see discussion on xref:userguide:fun:programming-model.adoc#versioning[versioning]
-<.> again, see discussion on xref:userguide:fun:programming-model.adoc#versioning[versioning]
-<.> again, see discussion on xref:userguide:fun:programming-model.adoc#versioning[versioning]
+<.> class name encodes (major and) minor version; see discussion on xref:userguide:fun:view-models.adoc#versioning[versioning]
+<.> again, see discussion on xref:userguide:fun:view-models.adoc#versioning[versioning]
+<.> again, see discussion on xref:userguide:fun:view-models.adoc#versioning[versioning]
<.> simple scalar properties
-<.> reference to a persistent entity; discussed xref:userguide:fun:programming-model.adoc#referencing-domain-entities[here]
-<.> reference to a collection of persistent entities; again discussed xref:userguide:fun:programming-model.adoc#referencing-domain-entities[here]
+<.> reference to a persistent entity; discussed xref:userguide:fun:view-models.adoc#referencing-domain-entities[here]
+<.> reference to a collection of persistent entities; again discussed xref:userguide:fun:view-models.adoc#referencing-domain-entities[here]
diff --git a/api/adoc/userguide/modules/fun/partials/module-nav.adoc b/api/adoc/userguide/modules/fun/partials/module-nav.adoc
index 98c76f7..44f438a 100644
--- a/api/adoc/userguide/modules/fun/partials/module-nav.adoc
+++ b/api/adoc/userguide/modules/fun/partials/module-nav.adoc
@@ -1,14 +1,17 @@
-
-
-* xref:userguide:fun:about.adoc[Fundamentals]
-** xref:userguide:fun:core-concepts.adoc[Core Concepts]
-** xref:userguide:fun:building-blocks.adoc[Building Blocks]
-** xref:userguide:fun:programming-model.adoc[Programming Model]
-** xref:userguide:fun:ui-hints.adoc[UI Hints]
-** xref:userguide:fun:crud.adoc[CRUD]
-** xref:userguide:fun:business-rules.adoc[Business Rules]
-** xref:userguide:fun:drop-downs-and-defaults.adoc[Drop downs and Defaults]
+* xref:userguide:fun:concepts-patterns.adoc[Concepts & Patterns]
+* xref:userguide:fun:overview.adoc[Overview]
+* xref:userguide:fun:domain-entities-and-services.adoc[Domain Entities & Services]
+* xref:userguide:fun:object-members.adoc[Object Members]
+* xref:userguide:fun:ui-layout.adoc[UI Layout]
+* xref:userguide:fun:ui-hints.adoc[UI Hints]
+* xref:userguide:fun:business-rules.adoc[Business Rules]
+* xref:userguide:fun:drop-downs-and-defaults.adoc[Drop downs and Defaults]
+* xref:userguide:fun:meta-annotations.adoc[Meta-annotations]
+* xref:userguide:fun:view-models.adoc[View Models]
+* xref:userguide:fun:mixins.adoc[Mixins]
+* xref:userguide:fun:crud.adoc[CRUD]
+* xref:userguide:fun:modules.adoc[Modules]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
index 05386fa..e2d33f1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
@@ -1,3 +1,4 @@
+[#restrictto]
= `restrictTo`
: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 ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
index dffb748..6a9cf8f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
@@ -49,7 +49,7 @@ The framework will automatically recreate the domain object each time it is inte
indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
+
Equivalent to annotating with xref:refguide:applib-ant:Mixin.adoc[`@Mixin`].
-For further discussion on using mixins, see xref:userguide:fun:building-blocks.adoc#mixins[mixins] in the user guide.
+For further discussion on using mixins, see xref:userguide:fun:overview.adoc#mixins[mixins] in the user guide.
* `VIEW_MODEL` +
@@ -73,7 +73,7 @@ The benefit of `nature()` is that it allows the developer to properly characteri
====
On the other hand, view models defined in this way do have some limitations; see xref:refguide:applib-ant:ViewModel.adoc[`@ViewModel`] for further discussion.
-These limitations do _not_ apply to xref:userguide:fun:programming-model.adoc#jaxb[JAXB] view models.
+These limitations do _not_ apply to xref:userguide:fun:view-models.adoc#jaxb[JAXB] view models.
If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
index 6aac47d..89f7198 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
@@ -1,3 +1,4 @@
+[#cssclassuievent]
= cssClassUiEvent
: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 ag [...]
@@ -13,8 +14,8 @@ From this they can, if they wish, specify a CSS class for the domain object usin
[NOTE]
====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `CssClassUiEvent.Default`.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
index ee89863..5d6d3df 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
@@ -14,8 +14,8 @@ From this they can, if they wish, specify an icon name for the domain object usi
[NOTE]
====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `IconUiEvent.Default`.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
index aabecc8..074eb91 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
@@ -1,3 +1,4 @@
+[#layoutuievent]
= layoutUiEvent
: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 ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
index b5cba8f..d044c39 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
@@ -15,8 +15,8 @@ From this they can, if they wish, specify a title for the domain object using th
[NOTE]
====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `TitleUiEvent.Default`.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
index 50430be..1d4b13a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
@@ -9,7 +9,7 @@ The `@Mixin` annotation indicates that the class acts as a mixin, contributing b
Mixins were originally introduced as a means of allowing contributions from one module to the types of another module; in such cases the mixin type is often an interface type (eg `DocumentHolder`) that might be implemented by numerous different concrete types.
However, mixins are also a convenient mechanism for grouping functionality even for a concrete type.
-For further discussion on using mixins, see xref:userguide:fun:building-blocks.adoc#mixins[mixins] in the user guide.
+For further discussion on using mixins, see xref:userguide:fun:overview.adoc#mixins[mixins] in the user guide.
[source,java]
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
index 29c1fa6..e06674e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
@@ -58,7 +58,7 @@ View models, as defined by `@ViewModel` (or `@DomainObject(nature=VIEW_MODEL)` f
* collections (of either view models or entities) are ignored.
* not every data type is supported,
-However, these limitations do _not_ apply to xref:userguide:fun:programming-model.adoc#jaxb[JAXB] view models.
+However, these limitations do _not_ apply to xref:userguide:fun:view-models.adoc#jaxb[JAXB] view models.
If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
[NOTE]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
index 95ba023..2829efc 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
@@ -21,6 +21,6 @@ public class ToDoItem ... {
This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom.
-For a more complete discussion of writing JAXB view models/DTOs, see xref:userguide:fun:building-blocks.adoc#view-models[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:userguide:fun:overview.adoc#view-models[this topic]
in the user guide.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
index 1862fd6..48f9833 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
@@ -3,7 +3,7 @@
: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 ag [...]
-The `@XmlRootElement` annotation provides an alternative way to define a xref:userguide:fun:building-blocks.adoc#view-models[view model], in particular one intended to act as a DTO for use within xref:vro:ROOT:about.adoc[RestfulObjects viewer], or which contains arbitrarily complex state.
+The `@XmlRootElement` annotation provides an alternative way to define a xref:userguide:fun:overview.adoc#view-models[view model], in particular one intended to act as a DTO for use within xref:vro:ROOT:about.adoc[RestfulObjects viewer], or which contains arbitrarily complex state.
A view model is a non-persisted domain object whose state is converted to/from a string memento.
In the case of a JAXB-annotated object this memento is its XML representation.
@@ -56,7 +56,7 @@ public class ToDoItemDto implements Dto {
Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep the DTO "clean", just focused on specifying the data contract.
-Behaviour can therefore be provided using xref:userguide:fun:building-blocks.adoc#mixins[mixins] (annotated with xref:refguide:applib-ant:Mixin.adoc[`@Mixin`]), while xref:refguide:applib-cm:classes/uievent.adoc[UI events] can be used to obtain title, icons and so on.
+Behaviour can therefore be provided using xref:userguide:fun:overview.adoc#mixins[mixins] (annotated with xref:refguide:applib-ant:Mixin.adoc[`@Mixin`]), while xref:refguide:applib-cm:classes/uievent.adoc[UI events] can be used to obtain title, icons and so on.
-For a more complete discussion of writing JAXB view models/DTOs, see xref:userguide:fun:building-blocks.adoc#view-models[this topic] in the user guide.
+For a more complete discussion of writing JAXB view models/DTOs, see xref:userguide:fun:overview.adoc#view-models[this topic] in the user guide.
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins.adoc
index b11dc5d..d3ddaf8 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins.adoc
@@ -8,7 +8,7 @@ This chapter defines a number of role interfaces that definea contract for some
[TIP]
====
-See the xref:userguide:fun:building-blocks.adoc#mixins[fundamentals user guide] for a discussion of mixins.
+See the xref:userguide:fun:overview.adoc#mixins[fundamentals user guide] for a discussion of mixins.
====
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Dto.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Dto.adoc
index 662ba4a..00569ac 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Dto.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/mixins/Dto.adoc
@@ -7,7 +7,7 @@
The `Dto` role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using
xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`].
-It enables the ability to download the XML and XSD schema of those objects using two xref:userguide:fun:building-blocks.adoc#mixins[mixins], `Dto_downloadXml` and `Dto_downloadXsd`.
+It enables the ability to download the XML and XSD schema of those objects using two xref:userguide:fun:overview.adoc#mixins[mixins], `Dto_downloadXml` and `Dto_downloadXsd`.
The interface is just a marker interface (with no members), and is defined as:
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
index 588b914..b6b3143 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
@@ -59,7 +59,7 @@ image::reference-methods/prefixes/choices/dependent.png[width="800px",link="{ima
-This functionality is actually implemented as a xref:userguide:fun:programming-model.adoc#contributed-action[contributed action], so the code for this is:
+This functionality is actually implemented as a xref:userguide:fun:mixins.adoc#contributed-action[contributed action], so the code for this is:
[source,java]
----
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
index cec80e5..426ab1d 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
@@ -60,7 +60,7 @@ public class ShoppingCartItem {
-Defaults are also supported (of course) for xref:userguide:fun:programming-model.adoc#contributed-action[contributed actions].
+Defaults are also supported (of course) for xref:userguide:fun:mixins.adoc#contributed-action[contributed actions].
For example, here is a contributed action for updating category/subcategory of the http://github.com/apache/isis-app-todoapp[TodoApp]:
[source,java]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/disable.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/disable.adoc
index 128a124..9d49bca 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/disable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/disable.adoc
@@ -87,8 +87,6 @@ public class Customer {
In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
-
-Note that enabling this configuration property in effect means that xref:userguide:fun:building-blocks.adoc#mixins[mixins] must be used instead of xref:userguide:fun:programming-model.adoc#contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/hide.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/hide.adoc
index 01d368b..494135b 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/hide.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/hide.adoc
@@ -91,8 +91,6 @@ However, if they check the first boolean parameter (ie, to ship the `Order` to t
====
In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
-
-Note that enabling this configuration property in effect means that xref:userguide:fun:building-blocks.adoc#mixins[mixins] must be used instead of xref:userguide:fun:programming-model.adoc#contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/JaxbService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/JaxbService.adoc
index fdb9d47..55c0ddc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/JaxbService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/JaxbService.adoc
@@ -35,6 +35,6 @@ Apache Isis provides a default implementation of the service, `o.a.i.applib.serv
== Usage within the framework
This service is provided as a convenience for applications, but is also used internally by the framework to marshall xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated
-xref:userguide:fun:building-blocks.adoc#view-models[view models].
+xref:userguide:fun:overview.adoc#view-models[view models].
The functionality to download XML and XSD schemas is also exposed in the UI through mixins of the xref:refguide:applib-cm:classes/mixins.adoc#Dto[`Dto`] interface.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/Scratchpad.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/Scratchpad.adoc
index 7e9eaaa..2b00098 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/Scratchpad.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/Scratchpad.adoc
@@ -53,7 +53,7 @@ public BigDecimal totalCost() {
Scratchpad scratchpad;
----
-A more complex example could use a xref:userguide:fun:building-blocks.adoc#view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
+A more complex example could use a xref:userguide:fun:overview.adoc#view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
[source,java]
----
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/SwaggerService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/SwaggerService.adoc
index 42bfd0e..bf0e816 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/SwaggerService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/SwaggerService.adoc
@@ -30,7 +30,7 @@ include::refguide:applib-svc:example$services/swagger/SwaggerService.java[tags="
<.> Produces a limited spec for use by third-party clients, ie public use.
This specification is restricted only to
-xref:userguide:fun:building-blocks.adoc#view-models[view model]s and to domain services with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY`.
+xref:userguide:fun:overview.adoc#view-models[view model]s and to domain services with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY`.
<.> Produces a more complete spec, for internally-managed clients, ie private internal use.
This specification includes domain entities and all menu domain services (as well as any view models).
<.> Ditto, but also including any xref:refguide:applib-ant:Action.adoc#restrictTo[prototype] actions.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/UrlEncodingService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/UrlEncodingService.adoc
index 37885a1..6aa8f85 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/UrlEncodingService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/UrlEncodingService.adoc
@@ -7,7 +7,7 @@ WARNING: TODO - to review for v2.
The `UrlEncodingService` defines a consistent way to convert strings to/from a form safe for use within a URL.
-The service is used by the framework to map xref:userguide:fun:building-blocks.adoc#view-models[view model] mementos (derived from the state of the view model itself) into a form that can be used as a view model.
+The service is used by the framework to map xref:userguide:fun:overview.adoc#view-models[view model] mementos (derived from the state of the view model itself) into a form that can be used as a view model.
When the framework needs to recreate the view model (for example to invoke an action on it), this URL is converted back into a view model memento, from which the view model can then be hydrated.
Defining this functionality as an SPI has two use cases:
diff --git a/api/schema/src/main/adoc/modules/schema/pages/common.adoc b/api/schema/src/main/adoc/modules/schema/pages/common.adoc
index 11bbf31..af593d7 100644
--- a/api/schema/src/main/adoc/modules/schema/pages/common.adoc
+++ b/api/schema/src/main/adoc/modules/schema/pages/common.adoc
@@ -14,7 +14,7 @@ This is basically a formal XML equivalent to the `Bookmark` object obtained from
Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by a given Apache Isis application.
With it, we have the ability to lookup any arbitrary object.
-Further discussion and examples can be found xref:userguide:fun:building-blocks.adoc#oid[here].
+Further discussion and examples can be found xref:userguide:fun:overview.adoc#oid[here].
The `oidDto` complex type is defined as:
diff --git a/core/config/src/main/adoc/modules/config/pages/about.adoc b/core/config/src/main/adoc/modules/config/pages/about.adoc
index bf2f50a..636a059 100644
--- a/core/config/src/main/adoc/modules/config/pages/about.adoc
+++ b/core/config/src/main/adoc/modules/config/pages/about.adoc
@@ -144,7 +144,7 @@ public class AppManifest {
<2> Enables the Shiro security mechanism.
There are several security implementations, precisely one must be selected
<3> Enables JDO/DataNucleus for persistence.
-Optional (though if omitted then only xref:userguide:fun:building-blocks.adoc#view-models[view models] may be used, with hand-rolled persistence).
+Optional (though if omitted then only xref:userguide:fun:overview.adoc#view-models[view models] may be used, with hand-rolled persistence).
<4> Enables the xref:vro:ROOT:about.adoc[Restful Objects viewer] (ie REST API).
<5> Enables the xref:vw:ROOT:about.adoc[Wicket viewer]
<6> References the application's module(s), in this case just the one, `ApplicationModule`. +
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ContentNegotiationService.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ContentNegotiationService.adoc
index 2bdb762..48248d1 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ContentNegotiationService.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ContentNegotiationService.adoc
@@ -12,7 +12,7 @@ Another use case is to support "third party" REST clients over which you have no
Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:
-* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:userguide:fun:building-blocks.adoc#view-models[view model]. This is then surfaced over the RO viewer. +
+* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:userguide:fun:overview.adoc#view-models[view model]. This is then surfaced over the RO viewer. +
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
diff --git a/starters/adoc/modules/starters/pages/helloworld.adoc b/starters/adoc/modules/starters/pages/helloworld.adoc
index d616430..1813dfc 100644
--- a/starters/adoc/modules/starters/pages/helloworld.adoc
+++ b/starters/adoc/modules/starters/pages/helloworld.adoc
@@ -330,7 +330,7 @@ public class AppManifest {
<2> Enables the Shiro security mechanism.
There are several security implementations, precisely one must be selected
<3> Enables JDO/DataNucleus for persistence.
-Optional (though if omitted then only xref:userguide:fun:building-blocks.adoc#view-models[view models] may be used, with hand-rolled persistence).
+Optional (though if omitted then only xref:userguide:fun:overview.adoc#view-models[view models] may be used, with hand-rolled persistence).
<4> Enables the xref:vro:ROOT:about.adoc[Restful Objects viewer] (ie REST API).
<5> Enables the xref:vw:ROOT:about.adoc[Wicket viewer]
<6> Enables the H2 Console (menu from the "Prototyping" menu), applicable only if running against h2 in-memory database.
diff --git a/starters/adoc/modules/starters/pages/simpleapp.adoc b/starters/adoc/modules/starters/pages/simpleapp.adoc
index c7ad1ad..4293c74 100644
--- a/starters/adoc/modules/starters/pages/simpleapp.adoc
+++ b/starters/adoc/modules/starters/pages/simpleapp.adoc
@@ -673,7 +673,7 @@ public class AppManifest {
<2> Enables the Shiro security mechanism.
There are several security implementations, precisely one must be selected
<3> Enables JDO/DataNucleus for persistence.
-Optional (though if omitted then only xref:userguide:fun:building-blocks.adoc#view-models[view models] may be used, with hand-rolled persistence).
+Optional (though if omitted then only xref:userguide:fun:overview.adoc#view-models[view models] may be used, with hand-rolled persistence).
<4> Enables the xref:vro:ROOT:about.adoc[Restful Objects viewer] (ie REST API).
<5> Enables the xref:vw:ROOT:about.adoc[Wicket viewer]
<6> Enables the H2 Console (menu from the "Prototyping" menu), applicable only if running against h2 in-memory database.
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
index 20d8de6..8e3e885 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
@@ -13,7 +13,7 @@ File-based layouts offer a number of benefits:
* 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).
-* UI hints can be provided for contributed xref:userguide:fun:programming-model.adoc#contributed-action[actions] that are synthesised at runtime.
+* UI hints can be provided for xref:userguide:fun:mixins.adoc[mixin] contributions that are synthesised at runtime.
It is also possible to download an initial `.layout.xml` - capturing any existing layout metadata - using the xref:refguide:applib-svc:LayoutService.adoc[`LayoutService`] (exposed on the prototyping menu) or using a xref:refguide:applib-cm:classes/mixins.adoc#Object[mixin action] contributed to every domain object.