You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/05/01 18:42:30 UTC
isis git commit: ISIS-1133: chipping away at docs.
Repository: isis
Updated Branches:
refs/heads/master cc7ff5324 -> 8d8f64b4c
ISIS-1133: chipping away at docs.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/8d8f64b4
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/8d8f64b4
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/8d8f64b4
Branch: refs/heads/master
Commit: 8d8f64b4cb5ab69fd943c196963df2eb1a04fa75
Parents: cc7ff53
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri May 1 17:42:06 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri May 1 17:42:06 2015 +0100
----------------------------------------------------------------------
.../eclipse/eclipse.adoc | 7 -----
.../documentation/src/main/asciidoc/index.adoc | 11 +++-----
.../_user-guide_appendices_dev-env.adoc | 4 +++
..._user-guide_appendices_dev-env_cmd-line.adoc | 8 ++++++
.../_user-guide_appendices_dev-env_eclipse.adoc | 8 ++++++
.../_user-guide_appendices_migration-notes.adoc | 15 ++++++++++-
.../user-guide/_user-guide_how-tos.adoc | 16 ++++++++----
.../_user-guide_how-tos_bulk-actions.adoc | 8 ++++++
.../_user-guide_how-tos_class-structure.adoc | 27 ++++++++++++--------
.../_user-guide_how-tos_domain-services.adoc | 12 +++++++++
.../_user-guide_how-tos_tips-n-tricks.adoc | 22 +++-------------
...uide_how-tos_tips-n-tricks_are-you-sure.adoc | 2 +-
...uide_how-tos_tips-n-tricks_enhance-only.adoc | 18 +++++++++++++
...ips-n-tricks_overriding-jdo-annotations.adoc | 3 ++-
...-tricks_render-all-properties-in-tables.adoc | 10 ++++++++
...s-n-tricks_suppress-actions-from-the-ui.adoc | 13 ++++++++++
.../_user-guide_how-tos_ui-hints.adoc | 16 +++++++++---
.../_user-guide_how-tos_view-models.adoc | 10 ++++++++
...uide_reference_configuration-properties.adoc | 4 +++
19 files changed, 158 insertions(+), 56 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/getting-started/development-environment/eclipse/eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/getting-started/development-environment/eclipse/eclipse.adoc b/adocs/documentation/src/main/asciidoc/getting-started/development-environment/eclipse/eclipse.adoc
deleted file mode 100644
index 4250a16..0000000
--- a/adocs/documentation/src/main/asciidoc/getting-started/development-environment/eclipse/eclipse.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= Setting up Eclipse
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/index.adoc b/adocs/documentation/src/main/asciidoc/index.adoc
index 69353bd..aba4aa8 100644
--- a/adocs/documentation/src/main/asciidoc/index.adoc
+++ b/adocs/documentation/src/main/asciidoc/index.adoc
@@ -19,12 +19,7 @@ Finding your way around:
* Introducing Isis
** link:introducing-apache-isis/isis-in-pictures/isis-in-pictures.html[Isis in Pictures]
** link:introducing-apache-isis/common-use-cases/common-use-cases.html[Common Use Cases]
-* Getting Started
-** link:getting-started/archetype/simpleapp-archetype.html[SimpleApp Archetype]
-** Development Environments
-*** link:getting-started/development-environment/intellij-idea/intellij-idea.html[Intellij IDEA]
-*** link:getting-started/development-environment/eclipse/eclipse.html[Eclipse]
-*** link:getting-started/development-environment/cmd-line/cmd-line.html[(Maven) Command Line]
-* link:user-guide/user-guide.html[User Guide]
-* link:release-notes/release-notes.html[Release Notes]
+
+* User Guide
+** link:user-guide/user-guide.html[User Guide]
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
index f9347cd..f0add1a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
@@ -5,4 +5,8 @@
IMPORTANT: TODO
+include::_user-guide_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
+
include::_user-guide_appendices_dev-env_intellij.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_dev-env_eclipse.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
new file mode 100644
index 0000000..f1ece55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
@@ -0,0 +1,8 @@
+= Developing from the Command Line
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
new file mode 100644
index 0000000..395719a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
@@ -0,0 +1,8 @@
+= Setting up Eclipse
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
index a93d0ef..ae537a0 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
@@ -5,7 +5,7 @@
-== Upgrading to 1.9.0-SNAPSHOT
+== Upgrading to DataNucleus 4 (in 1.9.0-SNAPSHOT)
Isis 1.9.0 updates to DataNucleus 4.0.0, which requires some changes (simplifications) to the Maven configuration.
@@ -216,6 +216,19 @@ isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
----
+[WARNING]
+====
+Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer. Or even, be careful that they are not doubly enhanced. One of our committers had this situation and it led to all sorts of bizarre issues. The solution, it turned out, was actually just to do a full `mvn clean`.
+
+If you are struggling and suspect you may have misconfigured the enhancer plugin, then you can decompile the bytecode (eg in IntelliJ) and take a look:
+
+* A class enhanced with DataNucleus 3 would implement `javax.jdo.spi.PersistenceCapable` interface
+* A class enhanced with DataNucleus 4 will implement `org.datanucleus.enhancer.Persistable`.
+====
+
+
+
+
== Upgrading to Java 8 (1.9.0-SNAPSHOT and later)
Apache Isis 1.9.0-SNAPSHOT is the first version to support Java 8. You can continue to use Java 7, but if you want to move to Java 8 then there are several small changes to be made.
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
index f0fb5dd..99e5ff0 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
@@ -7,24 +7,30 @@ IMPORTANT: TODO
include::_user-guide_how-tos_class-structure.adoc[leveloffset=+1]
-include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
+include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
+include::_user-guide_how-tos_domain-services.adoc[leveloffset=+1]
include::_user-guide_how-tos_crud.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
+include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
include::_user-guide_how-tos_business-rules.adoc[leveloffset=+1]
+include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
+
include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+include::_user-guide_how-tos_bulk-actions.adoc[leveloffset=+1]
+
include::_user-guide_how-tos_triggering-events.adoc[leveloffset=+1]
include::_user-guide_how-tos_using-modules.adoc[leveloffset=+1]
+include::_user-guide_how-tos_view-models.adoc[leveloffset=+1]
+
include::_user-guide_how-tos_tips-n-tricks.adoc[leveloffset=+1]
include::_user-guide_how-tos_error-handling.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_bulk-actions.adoc
new file mode 100644
index 0000000..9b83333
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_bulk-actions.adoc
@@ -0,0 +1,8 @@
+= Bulk Actions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+ie `@Action(invokeOn=...)`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
index d792b9c..65f88e4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
@@ -83,29 +83,33 @@ The workaround is to mark the collection as `@Programmatic`, as described in <<I
====
-### Optional Action Argument
+## Action Parameters
-## String Length Of Action Parameter
-## BigDecimal Precision Of Action Parameter
+### String Length Of Action Parameter
-### Mapping String (Length)
+### BigDecimal Precision Of Action Parameter
-### Mapping JODA Dates
+### Optional Action Argument
-### Mapping BigDecimals
-### Mapping Blobs
+## Properties vs Parameters
+
+In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`. Ideally we want the surname property and surname action parameter to use the same value type.
+
+Having first-class support for this is a goal of Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal. However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as `java.lang.String`.
+However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters. It is therefore necessary to use Isis' equivalent annotations for action parameters.
+The table below summarises the equivalence of some of the most common cases.
-## Mapping Value Types
-table of:
-.
-|value type
+.Comparing annotations of Properties vs Action Parameters
+[cols="2,3,3", options="header"]
+|===
+|value type/semantic
|property
|action parameter
@@ -124,6 +128,7 @@ table of:
|optional
|`@Column(allowsNull="true")`
|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
+|===
## Ignoring Methods
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
new file mode 100644
index 0000000..7af091d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
@@ -0,0 +1,12 @@
+= 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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+
+## Singleton & request-scoped services
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks.adoc
index 4c0e3c9..0bf528f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks.adoc
@@ -5,28 +5,14 @@
IMPORTANT: TODO
-## Are You Sure? idiom
include::_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
+include::_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_user-guide_how-tos_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
-## To review...
-
-Most of these will move elsewhere, I think:
-
-* Singleton & request-scoped services
-* Decoupling dependencies using contributions
-* How to suppress contributions
-* Bulk actions, acting upon lists
-* Bidirectional relationships
-* View models
-
-
-
-## Overriding JDO Annotations
-
-include::_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_user-guide_how-tos_tips-n-tricks_suppress-actions-from-the-ui.adoc[leveloffset=+1]
+include::_user-guide_how-tos_tips-n-tricks_enhance-only.adoc[leveloffset=+1]
-## Render abstract properties in tables
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc
index d6df7f7..b5b1522 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_are-you-sure.adoc
@@ -1,4 +1,4 @@
-== How Tos: Tips n Tricks: 'Are you sure?' idiom
+= 'Are you sure?' idiom
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:_basedir: ../
:_imagesdir: images/
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_enhance-only.adoc
new file mode 100644
index 0000000..95a0564
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_enhance-only.adoc
@@ -0,0 +1,18 @@
+= Enhance only (IntelliJ)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+== Question:
+
+Is there a simple way to make a run configuratoin in IntelliJ for running the datanucleus enhancer before running integration test?
+
+== Answer:
+
+* Duplicate your run configuration for running the webapp
+** the one where the main class is `org.apache.isis.WebServer`
+** there's a button for this on the run configurations dialog.
+* then, on your copy change the main class to `org.apache.isis.Dummy`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc
index c9dafcb..c528103 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_overriding-jdo-annotations.adoc
@@ -1,5 +1,6 @@
-== How Tos: Tips n Tricks: Overriding JDO Annotations
+= Overriding JDO Annotations
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:_basedir: ../
:_imagesdir: images/
+IMPORTANT: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_render-all-properties-in-tables.adoc
new file mode 100644
index 0000000..4fda8c9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_render-all-properties-in-tables.adoc
@@ -0,0 +1,10 @@
+= Render all Properties in Tables
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+solution: use abstract properties in the supertype
+
+example: audit, command and published event (from isis addons).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_suppress-actions-from-the-ui.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_suppress-actions-from-the-ui.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_suppress-actions-from-the-ui.adoc
new file mode 100644
index 0000000..d074e71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_tips-n-tricks_suppress-actions-from-the-ui.adoc
@@ -0,0 +1,13 @@
+= Suppressing actions from the UI
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+eg if included an addon such as auditing or security.
+
+
+solution is to write a domain event subscriber that vetoes the visibility
+
+All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
index 6b9b7b3..9d94f97 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
@@ -21,16 +21,24 @@ IMPORTANT: TODO
NOTE: see also i18n (TODO: convert to link)
-### Name/descr. of an object
+### Class (object)
-### Name/descr. of a property
+### Property
-### Name/descr. of a collection
+### Collections
-### Name/descr. of an action
+### Actions
### Action Parameters
+Use `@ParameterLayout(named=...)` or `@Named(...)`
+
+[TIP]
+====
+If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation. Support for this can be found in the http://github.com/isisaddons/isis-metamodel-paraname8}[Isis addons' paraname8] metamodel extension (non-ASF). (In the future we'll fold this into core). See also our guidance on <<_upgrading_to_java_8_1_9_0_snapshot_and_later,upgrading to Java 8>>.
+====
+
+
## Layout
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_view-models.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_view-models.adoc
new file mode 100644
index 0000000..2d23d59
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_view-models.adoc
@@ -0,0 +1,10 @@
+= View Models
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+== `@ViewModel`
+
+== `ViewModel` interface
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8d8f64b4/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
index b6ab67c..f2168f4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
@@ -50,6 +50,10 @@ TIP: the default value (if there is one) is shown in _italics_.
| `true`,`_false_`
| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
+|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
+| `true`,`_false_`
+| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
+
|`isis.persistor.datanucleus.impl.*`
|
| Passed through directly to Datanucleus (with prefix stripped)