ISIS-1521: moves faq from ugfun to dg.adoc, renames to 'hints-n-tips'

Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/0c22c0a3
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/0c22c0a3
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/0c22c0a3

Branch: refs/heads/wip
Commit: 0c22c0a392cce587e6448d438154d8c5063051c7
Parents: add8cef
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:12:14 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:29 2017 +0100

----------------------------------------------------------------------
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  | 23 +++++
 .../dg/_dg_hints-and-tips_enabling-logging.adoc | 41 +++++++++
 .../dg/_dg_hints-and-tips_enhance-only.adoc     | 25 ++++++
 ...nd-tips_how-run-fixtures-on-app-startup.adoc | 24 ++++++
 ...ips_how-to-handle-void-and-null-results.adoc | 79 +++++++++++++++++
 ...nd-tips_how-to-implement-a-spellchecker.adoc | 29 +++++++
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ++++++
 .../dg/_dg_hints-and-tips_per-user-themes.adoc  | 91 ++++++++++++++++++++
 ...g_hints-and-tips_restful-image-property.adoc | 25 ++++++
 ...tips_subtype-entity-not-fully-populated.adoc | 60 +++++++++++++
 .../src/main/asciidoc/guides/dg/dg.adoc         |  3 +-
 .../main/asciidoc/guides/ugfun/_ugfun_faqs.adoc | 21 -----
 .../ugfun/_ugfun_faqs_enabling-logging.adoc     | 41 ---------
 .../guides/ugfun/_ugfun_faqs_enhance-only.adoc  | 25 ------
 ...un_faqs_how-run-fixtures-on-app-startup.adoc | 24 ------
 ...aqs_how-to-handle-void-and-null-results.adoc | 79 -----------------
 ...un_faqs_how-to-implement-a-spellchecker.adoc | 29 -------
 ..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc | 26 ------
 .../ugfun/_ugfun_faqs_per-user-themes.adoc      | 91 --------------------
 .../_ugfun_faqs_restful-image-property.adoc     | 25 ------
 ...faqs_subtype-entity-not-fully-populated.adoc | 60 -------------
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |  2 +-
 22 files changed, 426 insertions(+), 423 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
new file mode 100644
index 0000000..67d89bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -0,0 +1,23 @@
+[[_dg_hints-and-tips]]
+= Hints and Tips
+: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
+
+
+
+This chapter has FAQs (with solutions) for problems we've encountered 
ourselves or have been raised on the
+Apache Isis mailing lists.
+
+See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
+
+include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
new file mode 100644
index 0000000..af3ecc3
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
@@ -0,0 +1,41 @@
+[[_dg_hints-and-tips_enabling-logging]]
+= Enabling Logging
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+Sometimes you just need to see what is going on.
+There are various ways in which logging can be enabled, here are the ones we 
tend to use.
+
+* In Apache Isis +
++
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+* In DataNucleus +
++
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN 
logging page]
+
+* In the JDBC Driver +
++
+Configure `log4jdbc` JDBC rather than the vanilla driver (see 
`WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see 
`WEB-INF/logging.properties`).
+There are examples of both in the 
xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+* In the database +
++
+Details below.
+
+
+Database logging can be configured:
+
+* for HSQLDB +
++
+by adding`;sqllog=3` to the end of the JDBC URL.
+
+* for PostgreSQL: +
++
+Can change `postgresql\9.2\data\postgresql.conf`; see 
link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this 
article] for details.
+
+* for MS SQL Server Logging: +
++
+We like to use the excellent SQL Profiler tool.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
new file mode 100644
index 0000000..aa6bff9
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_enhance-only]]
+= 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/
+
+
+From the Apache Isis mailing list is:
+
+* _Is there a simple way to make a run configuration in IntelliJ for running 
the datanucleus enhancer before running integration test?_
+
+Yes, you can; here's one way:
+
+* 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`
+
+Or, you could just write a small shell script and run from the command line:
+
+[source,bash]
+.enhance.sh
+----
+mvn -pl dom datanucleus:enhance -o
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
new file mode 100644
index 0000000..89a1547
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
@@ -0,0 +1,24 @@
+[[_dg_hints-and-tips_how-run-fixtures-on-app-startup]]
+= How run fixtures on startup?
+: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/
+
+
+From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the 
Apache Isis users mailing list:
+
+* _my fixtures have grown into a couple of files the application needs to read 
in when it starts the first time (and possibly later on when the files content 
change).
+What is the right way to do this?
+Hook up into the webapp start?
+Use events?_
+
+
+The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture 
scripts].
+These can be run in on start-up typically by being specified in the 
xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
+example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp 
archetype].
+
+Alternatively just set "isis.fixtures" and 
"isis.persistor.datanucleus.install-fixtures" properties.
+
+In terms of implementations, you might also want to check out the (non-ASF) 
http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by 
using 
link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`]
 and overriding `ExcelFixtureRowHandler` (same package).
+An example can be found in this (non ASF) 
link:https://github.com/incodehq/contactapp[contactapp], see 
link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
new file mode 100644
index 0000000..76b3a2e
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -0,0 +1,79 @@
+[[_dg_hints-and-tips_how-to-handle-void-and-null-results]]
+= How to handle void/null results
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the 
Apache Isis users mailing list:
+
+* _When using a `void` action, let’s say a remove action, the user is 
redirected to a
+page "no results".
+When clicking the back button in the browser the user sees "Object not found" 
(since you’ve just deleted this object)._
+
+* _You can return a list for example to prevent the user from being redirect 
to a
+  "No results" page, but I think it’s not the responsibility of the 
controllers in
+  the domain model._
+
+* _A solution could be that wicket viewer goes back one page when
+  encountering a deleted object.
+And refresh the current page when receiving a null response or invoking a void 
action.
+But how to implement this?_
+
+One way to implement this idea is to provide a custom implementation of the 
xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not 
null), else the home page (as defined by 
xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
+
+The following custom implementation refines this to use the breadcrumbs 
(available in the Wicket viewer) to return the first non-deleted domain object 
found in the list of breadcrumbs:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@DomainServiceLayout(menuOrder = "1")                                          
 // <1>
+public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
+    @Override
+    public Object route(final Object original) {
+        if(original != null) {                                                 
 // <2>
+            return original;
+        }
+        container.flush();                                                     
 // <3>
+
+        final BreadcrumbModelProvider wicketSession =                          
 // <4>
+            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
+        final BreadcrumbModel breadcrumbModel =
+            wicketSession.getBreadcrumbModel();
+        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
+
+        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
+                breadcrumbs.stream()                                           
 // <5>
+                .filter(entityModel -> entityModel != null)
+                .map(EntityModel::getObject)                                   
 // <6>
+                .filter(objectAdapter -> objectAdapter != null)
+                .map(ObjectAdapter::getObject)                                 
 // <7>
+                .filter(pojo -> !(pojo instanceof Persistable) ||
+                                !((Persistable)pojo).dnIsDeleted())            
 // <8>
+                .findFirst();
+
+        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());         
 // <9>
+    }
+    private Object homePage() {
+        return homePageProviderService.homePage();
+    }
+    @Inject
+    HomePageProviderService homePageProviderService;
+    @Inject
+    DomainObjectContainer container;
+}
+----
+<1> override the default imlpementation
+<2> if a non-null object was returned, then return this
+<3> ensure that any persisted objects have been deleted.
+<4> reach inside the Wicket viewer's internals to obtain the list of 
breadcrumbs.
+<5> loop over all breadcrumbs
+<6> unwrap the Wicket viewer's serializable representation of each domain 
object (`EntityModel`) to the Isis runtime's
+representation (`ObjectAdapter`)
+<7> unwrap the Isis runtime's representation of each domain object 
(`ObjectAdapter`) to the domain object pojo itself
+<8> if object is persistable (not a view model) then make sure it is not 
deleted
+<9> return the first object if any, otherwise the home page object (if any).
+
+Note that the above implementation uses Java 8, so if you are using Java 7 
then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
new file mode 100644
index 0000000..c141366
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -0,0 +1,29 @@
+[[_dg_hints-and-tips_how-to-implement-a-spellchecker]]
+= How to implement a spellchecker?
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the 
Apache Isis users mailing list:
+
+* _What is the easiest way to add a spell checker to the text written in a 
field in
+   a domain object, for instance to check English syntax?_
+
+One way to implement is to use the 
xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
+
+* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] 
xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can 
veto the changes.
+
+* if the change is made through an action, you can use 
xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+
+if if the change is made through an edit, you can use 
xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
+
+You'll need some way to know which fields should be spell checked.  Two ways 
spring to mind:
+
+* either look at the domain event's identifier
+
+* or subclass the domain event (recommended anyway) and have those subclass 
events implement some sort of marker interface, eg a `SpellCheckEvent`.
+
+And you'll (obviously) also need some sort of spell checker implementation to 
call.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
new file mode 100644
index 0000000..22263cd
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -0,0 +1,26 @@
+[[_dg_hints-and-tips_i18n-label-in-wicket-viewer]]
+= How i18n the Wicket viewer?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the 
Apache Isis users mailing list:
+
+* _I am trying to internationalize the label descriptions of form actions, eg 
those in `ActionParametersFormPanel`.
+Referencing those via their message id inside a .po file didn't work either.
+Can this be done?_
+
+
+The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to 
link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now 
possible to internationalize both the Wicket viewer's labels as well as the 
regular translations of the domain object metadata using the `.po` translation 
files as supported by the 
xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+
+Full details of the ``msgId``s that must be added to the `translations.po` 
file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] 
section of the xref:ugbtb.adoc#[beyond the basics] guide.
+
+In prior releases (`1.10.0` and earlier) it was necessary to use 
link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's
 internationalization support], namely resource bundles.  This is still 
supported (as a fallback):
+
+* create a directory structure inside the webapp resource folder following 
that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
+
+* Inside there create an equivalent 
`ActionParametersFormPanel_xx_XX.properties` or 
`ActionParametersFormPanel_xx.properties` file for the various locales that you 
want to support (eg `ActionParametersFormPanel_en_UK.properties`, 
`ActionParametersFormPanel_en_US.properties`, 
`ActionParametersFormPanel_de.properties` and so on).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
new file mode 100644
index 0000000..10a89f1
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
@@ -0,0 +1,91 @@
+[[_dg_hints-and-tips_per-user-themes]]
+= Per-user Themes
+: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/
+
+
+From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the 
Apache Isis users mailing list:
+
+* _Is it possible to have each of our resellers (using our Isis application) 
use there own theme/branding with their own logo and colors?
+Would this also be possible for the login page, possibly depending on the used 
host name?_
+
+
+Yes, you can do this, by installing a custom implementation of the Wicket 
Bootstrap's `ActiveThemeProvider`.
+
+The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] 
(non-ASF) actually 
link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does
 this], storing the info via the 
http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] 
settings modules:
+
+
+[source,java]
+.IActiveThemeProvider implementation
+----
+public class UserSettingsThemeProvider implements ActiveThemeProvider {
+    ...
+    @Override
+    public ITheme getActiveTheme() {
+        if(IsisContext.getSpecificationLoader().isInitialized()) {
+            final String themeName = IsisContext.doInSession(new 
Callable<String>() {
+                @Override
+                public String call() throws Exception {
+                    final UserSettingsService userSettingsService =
+                        lookupService(UserSettingsService.class);
+                    final UserSetting activeTheme = userSettingsService.find(
+                            
IsisContext.getAuthenticationSession().getUserName(),
+                            ACTIVE_THEME);
+                    return activeTheme != null ? activeTheme.valueAsString() : 
null;
+                }
+            });
+            return themeFor(themeName);
+        }
+        return new SessionThemeProvider().getActiveTheme();
+    }
+    @Override
+    public void setActiveTheme(final String themeName) {
+        IsisContext.doInSession(new Runnable() {
+            @Override
+            public void run() {
+                final String currentUsrName =
+                    IsisContext.getAuthenticationSession().getUserName();
+                final UserSettingsServiceRW userSettingsService =
+                        lookupService(UserSettingsServiceRW.class);
+                final UserSettingJdo activeTheme =
+                        (UserSettingJdo) userSettingsService.find(
+                                                currentUsrName, ACTIVE_THEME);
+                if(activeTheme != null) {
+                    activeTheme.updateAsString(themeName);
+                } else {
+                    userSettingsService.newString(
+                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme 
for user", themeName);
+                }
+            }
+        });
+    }
+    private ITheme themeFor(final String themeName) {
+        final ThemeProvider themeProvider = settings.getThemeProvider();
+        if(themeName != null) {
+            for (final ITheme theme : themeProvider.available()) {
+                if (themeName.equals(theme.name()))
+                    return theme;
+            }
+        }
+        return themeProvider.defaultTheme();
+    }
+    ...
+}
+----
+
+and
+
+[source,java]
+.Using the ActiveThemeProvider
+----
+@Override
+protected void init() {
+    super.init();
+
+    final IBootstrapSettings settings = Bootstrap.getSettings();
+    settings.setThemeProvider(new 
BootswatchThemeProvider(BootswatchTheme.Flatly));
+
+    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
new file mode 100644
index 0000000..3084508
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_restful-image-property]]
+= How parse images in RO viewer?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the 
Apache Isis users mailing list:
+
+* _I am trying to display an image in a JavaScript client app, the image comes 
from
+   an Isis RO web service as a string, but it won't show.
+Is there something I should do to change the message?_
+
+
+The RO viewer returns the image as a string, in the form:
+
+    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
+
+This is in the form:
+
+    (filename):(mime type):(binary data in base64)
+
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] 
value type, in string form.
+
+To use, split the parts then format the mime type and base64 data correctly 
before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..d5f5965
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,60 @@
+[[_dg_hints-and-tips_subtype-entity-not-fully-populated]]
+= Subtype not fully populated
+: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/
+
+
+Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on 
the Apache Isis users mailing list...
+
+
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating 
domain entities (ie leaving some properties as `null`), then check that your 
actions are not accessing the fields directly.
+Use getters instead.
+
+
+[WARNING]
+====
+Properties of domain entities should always be accessed using getters.
+The only code that should access to fields should be the getters themselves.
+====
+
+Why so?
+Because DataNucleus will potentially lazy load some properties, but to do this 
it needs to know that the field is being requested.
+This is the purpose of the enhancement phase: the bytecode of the original 
getter method is actually wrapped in code that does the lazy loading checking.
+But hitting the field directly means that the lazy loading code does not run.
+
+This error can be subtle: sometimes "incorrect" code that accesses the fields 
will seem to work.
+But that will be because the field has been populated already, for whatever 
reason.
+
+One case where you will find the issue highlighted is for subtype tables that 
have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SupertypeEntity {
+    ...
+}
+----
+
+and then:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SubtypeEntity extends SupertypeEntity {
+    ...
+}
+----
+
+This will generate two tables in the database, with the primary key of the 
supertype table propagated as a foreign key (also primary key) of the subtype 
table (sometimes called "table per type" strategy).
+This means that DataNucleus might retrieve data from only the supertype table, 
and the lazily load the subtype fields only as required.
+This is preferable to doing a left outer join from the super- to the subtype 
tables to retrieve data that might not be needed.
+
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per 
hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, 
then the problem is less likely to occur because DataNucleus would obtain all 
the data for any given instance from a single table.
+
+Final note: references to other objects (either scalar references or in 
collections) in particular require that getters rather than fields to be used 
to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should 
not and will not resolve such references (otherwise, where to stop... and the 
whole database would be loaded into memory).
+
+In summary, there's just one rule: *always use the getters, never the fields*.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc 
b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
index 5233145..76cd0a5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
@@ -51,9 +51,10 @@ The remaining guides are:
 
 
 
-
 include::_dg_ide.adoc[leveloffset=+1]
 
+include::_dg_hints-and-tips.adoc[leveloffset=+1]
+
 include::_dg_building-isis.adoc[leveloffset=+1]
 
 include::_dg_asciidoc.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
deleted file mode 100644
index 1841474..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_ugfun_faqs]]
-= FAQs
-: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/
-
-
-This chapter has FAQs (with solutions) for problems we've encountered 
ourselves or have been raised on the
-Apache Isis mailing lists.
-
-See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
-
-include::_ugfun_faqs_enabling-logging.adoc[leveloffset=+1]
-include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::_ugfun_faqs_restful-image-property.adoc[leveloffset=+1]
-include::_ugfun_faqs_enhance-only.adoc[leveloffset=+1]
-include::_ugfun_faqs_per-user-themes.adoc[leveloffset=+1]
-include::_ugfun_faqs_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
deleted file mode 100644
index 18e4a1f..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugfun_faqs_enabling-logging]]
-= Enabling Logging
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-Sometimes you just need to see what is going on.
-There are various ways in which logging can be enabled, here are the ones we 
tend to use.
-
-* In Apache Isis +
-+
-Modify `WEB-INF/logging.properties` (a log4j config file)
-
-* In DataNucleus +
-+
-As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN 
logging page]
-
-* In the JDBC Driver +
-+
-Configure `log4jdbc` JDBC rather than the vanilla driver (see 
`WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see 
`WEB-INF/logging.properties`).
-There are examples of both in the 
xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-* In the database +
-+
-Details below.
-
-
-Database logging can be configured:
-
-* for HSQLDB +
-+
-by adding`;sqllog=3` to the end of the JDBC URL.
-
-* for PostgreSQL: +
-+
-Can change `postgresql\9.2\data\postgresql.conf`; see 
link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this 
article] for details.
-
-* for MS SQL Server Logging: +
-+
-We like to use the excellent SQL Profiler tool.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
deleted file mode 100644
index 4af2db6..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_enhance-only]]
-= 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/
-
-
-From the Apache Isis mailing list is:
-
-* _Is there a simple way to make a run configuration in IntelliJ for running 
the datanucleus enhancer before running integration test?_
-
-Yes, you can; here's one way:
-
-* 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`
-
-Or, you could just write a small shell script and run from the command line:
-
-[source,bash]
-.enhance.sh
-----
-mvn -pl dom datanucleus:enhance -o
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
deleted file mode 100644
index 9964d39..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ugfun_faqs_how-run-fixtures-on-app-startup]]
-= How run fixtures on startup?
-: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/
-
-
-From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the 
Apache Isis users mailing list:
-
-* _my fixtures have grown into a couple of files the application needs to read 
in when it starts the first time (and possibly later on when the files content 
change).
-What is the right way to do this?
-Hook up into the webapp start?
-Use events?_
-
-
-The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture 
scripts].
-These can be run in on start-up typically by being specified in the 
xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
-example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp 
archetype].
-
-Alternatively just set "isis.fixtures" and 
"isis.persistor.datanucleus.install-fixtures" properties.
-
-In terms of implementations, you might also want to check out the (non-ASF) 
http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by 
using 
link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`]
 and overriding `ExcelFixtureRowHandler` (same package).
-An example can be found in this (non ASF) 
link:https://github.com/incodehq/contactapp[contactapp], see 
link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
deleted file mode 100644
index b57c453..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ugfun_faqs_how-to-handle-void-and-null-results]]
-= How to handle void/null results
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the 
Apache Isis users mailing list:
-
-* _When using a `void` action, let’s say a remove action, the user is 
redirected to a
-page "no results".
-When clicking the back button in the browser the user sees "Object not found" 
(since you’ve just deleted this object)._
-
-* _You can return a list for example to prevent the user from being redirect 
to a
-  "No results" page, but I think it’s not the responsibility of the 
controllers in
-  the domain model._
-
-* _A solution could be that wicket viewer goes back one page when
-  encountering a deleted object.
-And refresh the current page when receiving a null response or invoking a void 
action.
-But how to implement this?_
-
-One way to implement this idea is to provide a custom implementation of the 
xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
-The default implementation will either return the current object (if not 
null), else the home page (as defined by 
xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
-
-The following custom implementation refines this to use the breadcrumbs 
(available in the Wicket viewer) to return the first non-deleted domain object 
found in the list of breadcrumbs:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@DomainServiceLayout(menuOrder = "1")                                          
 // <1>
-public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
-    @Override
-    public Object route(final Object original) {
-        if(original != null) {                                                 
 // <2>
-            return original;
-        }
-        container.flush();                                                     
 // <3>
-
-        final BreadcrumbModelProvider wicketSession =                          
 // <4>
-            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
-        final BreadcrumbModel breadcrumbModel =
-            wicketSession.getBreadcrumbModel();
-        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
-
-        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
-                breadcrumbs.stream()                                           
 // <5>
-                .filter(entityModel -> entityModel != null)
-                .map(EntityModel::getObject)                                   
 // <6>
-                .filter(objectAdapter -> objectAdapter != null)
-                .map(ObjectAdapter::getObject)                                 
 // <7>
-                .filter(pojo -> !(pojo instanceof Persistable) ||
-                                !((Persistable)pojo).dnIsDeleted())            
 // <8>
-                .findFirst();
-
-        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());         
 // <9>
-    }
-    private Object homePage() {
-        return homePageProviderService.homePage();
-    }
-    @Inject
-    HomePageProviderService homePageProviderService;
-    @Inject
-    DomainObjectContainer container;
-}
-----
-<1> override the default imlpementation
-<2> if a non-null object was returned, then return this
-<3> ensure that any persisted objects have been deleted.
-<4> reach inside the Wicket viewer's internals to obtain the list of 
breadcrumbs.
-<5> loop over all breadcrumbs
-<6> unwrap the Wicket viewer's serializable representation of each domain 
object (`EntityModel`) to the Isis runtime's
-representation (`ObjectAdapter`)
-<7> unwrap the Isis runtime's representation of each domain object 
(`ObjectAdapter`) to the domain object pojo itself
-<8> if object is persistable (not a view model) then make sure it is not 
deleted
-<9> return the first object if any, otherwise the home page object (if any).
-
-Note that the above implementation uses Java 8, so if you are using Java 7 
then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
deleted file mode 100644
index 1c48c0d..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_faqs_how-to-implement-a-spellchecker]]
-= How to implement a spellchecker?
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the 
Apache Isis users mailing list:
-
-* _What is the easiest way to add a spell checker to the text written in a 
field in
-   a domain object, for instance to check English syntax?_
-
-One way to implement is to use the 
xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
-
-* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] 
xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can 
veto the changes.
-
-* if the change is made through an action, you can use 
xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use 
xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
-
-You'll need some way to know which fields should be spell checked.  Two ways 
spring to mind:
-
-* either look at the domain event's identifier
-
-* or subclass the domain event (recommended anyway) and have those subclass 
events implement some sort of marker interface, eg a `SpellCheckEvent`.
-
-And you'll (obviously) also need some sort of spell checker implementation to 
call.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
deleted file mode 100644
index 220c58b..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ugfun_faqs_i18n-label-in-wicket-viewer]]
-= How i18n the Wicket viewer?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the 
Apache Isis users mailing list:
-
-* _I am trying to internationalize the label descriptions of form actions, eg 
those in `ActionParametersFormPanel`.
-Referencing those via their message id inside a .po file didn't work either.
-Can this be done?_
-
-
-The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to 
link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now 
possible to internationalize both the Wicket viewer's labels as well as the 
regular translations of the domain object metadata using the `.po` translation 
files as supported by the 
xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
-
-Full details of the ``msgId``s that must be added to the `translations.po` 
file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] 
section of the xref:ugbtb.adoc#[beyond the basics] guide.
-
-In prior releases (`1.10.0` and earlier) it was necessary to use 
link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's
 internationalization support], namely resource bundles.  This is still 
supported (as a fallback):
-
-* create a directory structure inside the webapp resource folder following 
that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
-
-* Inside there create an equivalent 
`ActionParametersFormPanel_xx_XX.properties` or 
`ActionParametersFormPanel_xx.properties` file for the various locales that you 
want to support (eg `ActionParametersFormPanel_en_UK.properties`, 
`ActionParametersFormPanel_en_US.properties`, 
`ActionParametersFormPanel_de.properties` and so on).
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
deleted file mode 100644
index a9b34d4..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_ugfun_faqs_per-user-themes]]
-= Per-user Themes
-: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/
-
-
-From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the 
Apache Isis users mailing list:
-
-* _Is it possible to have each of our resellers (using our Isis application) 
use there own theme/branding with their own logo and colors?
-Would this also be possible for the login page, possibly depending on the used 
host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket 
Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] 
(non-ASF) actually 
link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does
 this], storing the info via the 
http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] 
settings modules:
-
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
-    ...
-    @Override
-    public ITheme getActiveTheme() {
-        if(IsisContext.getSpecificationLoader().isInitialized()) {
-            final String themeName = IsisContext.doInSession(new 
Callable<String>() {
-                @Override
-                public String call() throws Exception {
-                    final UserSettingsService userSettingsService =
-                        lookupService(UserSettingsService.class);
-                    final UserSetting activeTheme = userSettingsService.find(
-                            
IsisContext.getAuthenticationSession().getUserName(),
-                            ACTIVE_THEME);
-                    return activeTheme != null ? activeTheme.valueAsString() : 
null;
-                }
-            });
-            return themeFor(themeName);
-        }
-        return new SessionThemeProvider().getActiveTheme();
-    }
-    @Override
-    public void setActiveTheme(final String themeName) {
-        IsisContext.doInSession(new Runnable() {
-            @Override
-            public void run() {
-                final String currentUsrName =
-                    IsisContext.getAuthenticationSession().getUserName();
-                final UserSettingsServiceRW userSettingsService =
-                        lookupService(UserSettingsServiceRW.class);
-                final UserSettingJdo activeTheme =
-                        (UserSettingJdo) userSettingsService.find(
-                                                currentUsrName, ACTIVE_THEME);
-                if(activeTheme != null) {
-                    activeTheme.updateAsString(themeName);
-                } else {
-                    userSettingsService.newString(
-                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme 
for user", themeName);
-                }
-            }
-        });
-    }
-    private ITheme themeFor(final String themeName) {
-        final ThemeProvider themeProvider = settings.getThemeProvider();
-        if(themeName != null) {
-            for (final ITheme theme : themeProvider.available()) {
-                if (themeName.equals(theme.name()))
-                    return theme;
-            }
-        }
-        return themeProvider.defaultTheme();
-    }
-    ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
-    super.init();
-
-    final IBootstrapSettings settings = Bootstrap.getSettings();
-    settings.setThemeProvider(new 
BootswatchThemeProvider(BootswatchTheme.Flatly));
-
-    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
deleted file mode 100644
index e5deed8..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_restful-image-property]]
-= How parse images in RO viewer?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the 
Apache Isis users mailing list:
-
-* _I am trying to display an image in a JavaScript client app, the image comes 
from
-   an Isis RO web service as a string, but it won't show.
-Is there something I should do to change the message?_
-
-
-The RO viewer returns the image as a string, in the form:
-
-    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
-
-This is in the form:
-
-    (filename):(mime type):(binary data in base64)
-
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] 
value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly 
before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index 5b02ae0..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_ugfun_faqs_subtype-entity-not-fully-populated]]
-= Subtype not fully populated
-: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/
-
-
-Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on 
the Apache Isis users mailing list...
-
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating 
domain entities (ie leaving some properties as `null`), then check that your 
actions are not accessing the fields directly.
-Use getters instead.
-
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters.
-The only code that should access to fields should be the getters themselves.
-====
-
-Why so?
-Because DataNucleus will potentially lazy load some properties, but to do this 
it needs to know that the field is being requested.
-This is the purpose of the enhancement phase: the bytecode of the original 
getter method is actually wrapped in code that does the lazy loading checking.
-But hitting the field directly means that the lazy loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields 
will seem to work.
-But that will be because the field has been populated already, for whatever 
reason.
-
-One case where you will find the issue highlighted is for subtype tables that 
have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
-    ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
-    ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the 
supertype table propagated as a foreign key (also primary key) of the subtype 
table (sometimes called "table per type" strategy).
-This means that DataNucleus might retrieve data from only the supertype table, 
and the lazily load the subtype fields only as required.
-This is preferable to doing a left outer join from the super- to the subtype 
tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per 
hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, 
then the problem is less likely to occur because DataNucleus would obtain all 
the data for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in 
collections) in particular require that getters rather than fields to be used 
to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should 
not and will not resolve such references (otherwise, where to stop... and the 
whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index f119338..1379b7a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -14,7 +14,7 @@ and tells you how to 
xref:ugfun.adoc#_ugfun_getting-started[get started] with a
 
 It also describes a number of xref:ugfun.adoc#_ugfun_how-tos[how-to]s, 
describes how to influence the
 xref:ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is 
ultimately just a type of metadata), and it
- catalogues various xref:ugfun.adoc#_ugfun_faqs.adoc[FAQ]s.
+ catalogues various xref:dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
 
 === Other Guides
 

Reply via email to