ISIS-1521: adds hints-n-tips sections for most of the user guides, and 
distributes out tips from dg.adoc as appropriate


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

Branch: refs/heads/wip
Commit: fcf368f0c94cb56f3783d5033477b5f9742379bb
Parents: 4807f4c
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:13:05 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../asciidoc/guides/dg/_dg_hints-and-tips.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 -------------
 .../rgsvc/_rgsvc_api_RepositoryService.adoc     |  2 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     | 27 ++++++
 ...ips_how-to-handle-void-and-null-results.adoc | 79 +++++++++++++++++
 ...nd-tips_how-to-implement-a-spellchecker.adoc | 29 +++++++
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |  1 +
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     | 27 ++++++
 .../ugodn/_ugodn_hints-and-tips_java8.adoc      | 29 +++++++
 ...nts-and-tips_overriding-jdo-annotations.adoc | 64 ++++++++++++++
 ...tips_subtype-entity-not-fully-populated.adoc | 60 +++++++++++++
 .../asciidoc/guides/ugodn/_ugodn_java8.adoc     | 29 -------
 .../_ugodn_overriding-jdo-annotations.adoc      | 64 --------------
 .../src/main/asciidoc/guides/ugodn/ugodn.adoc   |  3 +-
 .../_ugsec_configuring-isis-to-use-bypass.adoc  | 23 -----
 .../guides/ugsec/_ugsec_hints-and-tips.adoc     | 28 ++++++
 ...and-tips_configuring-isis-to-use-bypass.adoc | 23 +++++
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |  3 +-
 .../guides/ugvro/_ugvro_hints-and-tips.adoc     | 87 +++----------------
 .../_ugvro_hints-and-tips_angular-tips.adoc     | 69 +++++++++++++++
 .../_ugvro_hints-and-tips_pretty-printing.adoc  | 13 +++
 ...o_hints-and-tips_restful-image-property.adoc | 25 ++++++
 ...ro_hints-and-tips_using-chrome-devtools.adoc |  9 ++
 .../_ugvw_extending_custom-bootstrap-theme.adoc |  2 +-
 .../guides/ugvw/_ugvw_hints-and-tips.adoc       | 31 +++++++
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ++++++
 .../_ugvw_hints-and-tips_per-user-themes.adoc   | 91 ++++++++++++++++++++
 .../src/main/asciidoc/guides/ugvw/ugvw.adoc     |  2 +-
 33 files changed, 666 insertions(+), 514 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/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
index 78cfee4..26253ea 100644
--- 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
@@ -6,18 +6,24 @@
 :toc: right
 
 
+This chapter provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
 
-This chapter has FAQs (with solutions) for problems we've encountered 
ourselves or have been raised on the
-Apache Isis mailing lists.
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide (this chapter)
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
 
-See also xref:../ugvro/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/fcf368f0/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
deleted file mode 100644
index 373b1e6..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_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/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/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/fcf368f0/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
deleted file mode 100644
index d165a65..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_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/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/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use 
xref:../rgant/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/fcf368f0/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
deleted file mode 100644
index d4d16e0..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_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/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/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/fcf368f0/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
deleted file mode 100644
index 10a89f1..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_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/fcf368f0/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
deleted file mode 100644
index a01564d..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_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/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/fcf368f0/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
deleted file mode 100644
index d5f5965..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_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/fcf368f0/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
index 362cb88..1429962 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
@@ -136,7 +136,7 @@ public abstract class Warehouse extends 
SalesVIPEntity<Marketplace> {
 <2> Needed for updating the managed properties and collections.
 <3> injected services and other methods ommited
 
-On the “addExcludedProduct()” action, if the user didn’t flush, the 
following test would fail because the managed
+On the “addExcludedProduct()” action, if the user didn't flush, the 
following test would fail because the managed
 collection would not containing the given product:
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
new file mode 100644
index 0000000..589802f
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -0,0 +1,27 @@
+[[_ugbtb_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 provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide 
(this chapter).
+
+
+include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
new file mode 100644
index 0000000..c870a51
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -0,0 +1,79 @@
+[[_ugbtb_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/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/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/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
new file mode 100644
index 0000000..eebaa7d
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -0,0 +1,29 @@
+[[_ugbtb_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/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/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+
+if if the change is made through an edit, you can use 
xref:../rgant/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/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index 70276b2..c03eedb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -47,6 +47,7 @@ include::_ugbtb_view-models.adoc[leveloffset=+1]
 include::_ugbtb_decoupling.adoc[leveloffset=+1]
 include::_ugbtb_i18n.adoc[leveloffset=+1]
 include::_ugbtb_headless-access.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips.adoc[leveloffset=+1]
 include::_ugbtb_other-techniques.adoc[leveloffset=+1]
 include::_ugbtb_programming-model.adoc[leveloffset=+1]
 include::_ugbtb_deployment.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
new file mode 100644
index 0000000..7bb687d
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -0,0 +1,27 @@
+[[_ugodn_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/
+
+
+This chapter provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide (this chapter)
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
new file mode 100644
index 0000000..5f1dfed
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
@@ -0,0 +1,29 @@
+[[_ugodn_hints-and-tips_java8]]
+= Java8
+: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/
+
+
+
+DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for 
streams support against collections managed
+by DataNucleus.
+
+Just include within `<dependencies>` of your `dom` module's `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.datanucleus</groupId>
+    <artifactId>datanucleus-java8</artifactId>
+    <version>4.2.0-release</version>t
+</dependency>
+----
+
+[NOTE]
+====
+The DataNucleus website includes a 
link:http://www.datanucleus.org/products/accessplatform/compatibility.html[page]
+listing version compatibility of these extensions vis-a-vis the core 
DataNucleus platform.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
new file mode 100644
index 0000000..6fead2e
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -0,0 +1,64 @@
+[[_ugodn_hints-and-tips_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/
+
+
+
+The JDO Objectstore (or rather, the underlying DataNucleus implementation) 
builds its own persistence metamodel by reading both annotations on the class 
and also by searching for metadata in XML files. The metadata in the XML files 
takes precedence over the annotations, and so can be used to override metadata 
that is "hard-coded" in annotations.
+
+For example, as of 1.9.0 the various http://www.isisaddons.org[Isis addons] 
modules (not ASF) use schemas for each entity. For example, the `AuditEntry` 
entity in the http://github.com/isisaddons/isis-module-audit[audit module] is 
annotated as:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(
+        identityType=IdentityType.DATASTORE,
+        schema = "IsisAddonsAudit",
+        table="AuditEntry")
+public class AuditEntry {
+    ...
+}
+----
+
+This will map the `AuditEntry` class to a table 
`&quot;IsisAddonsAudit&quot;.&quot;AuditEntry&quot;`; that is using a custom 
schema to own the object.
+
+Suppose though that for whatever reason we didn't want to use a custom schema 
but would rather use the default. We can override the above annotation using a 
`package.jdo` file, for example:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo";
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
+        http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd"; version="3.0">
+    <package name="org.isisaddons.module.audit.dom">
+        <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
+        </class>
+    </package>
+</jdo>
+----
+
+This file should be placed can be placed in `src/main/java/META-INF` within 
your application's `dom` module.
+
+[TIP]
+====
+You can use a mixin action on 
xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
+to download the JDO class metadata in XML form.
+====
+
+
+[NOTE]
+====
+* The same approach should work for any other JDO metadata, but some 
experimentation might be required.+
++
+For example, in writing up the above example we found that writing 
`schema=&quot;&quot;` (in an attempt to say, "use the default schema for this 
table") actually caused the original annotation value to be used instead.
+
+* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't 
ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but 
MS SQL Server uses "dbo" as its default).
+
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning 
schema for a given table if it does not exist. This behaviour can be 
customized, as described in the section on 
xref:_ugbtb_decoupling_db-schemas[using modules].
+
+* You may need to override the entire class metadata rather than individual 
elements; the mixin mentioned above can help here.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..90a670d
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,60 @@
+[[_ugodn_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/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
deleted file mode 100644
index 64dc790..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugodn_java8]]
-= Java8
-: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/
-
-
-
-DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for 
streams support against collections managed
-by DataNucleus.
-
-Just include within `<dependencies>` of your `dom` module's `pom.xml`:
-
-[source,xml]
-----
-<dependency>
-    <groupId>org.datanucleus</groupId>
-    <artifactId>datanucleus-java8</artifactId>
-    <version>4.2.0-release</version>t
-</dependency>
-----
-
-[NOTE]
-====
-The DataNucleus website includes a 
link:http://www.datanucleus.org/products/accessplatform/compatibility.html[page]
-listing version compatibility of these extensions vis-a-vis the core 
DataNucleus platform.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
deleted file mode 100644
index fa959f9..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ugodn_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/
-
-
-
-The JDO Objectstore (or rather, the underlying DataNucleus implementation) 
builds its own persistence metamodel by reading both annotations on the class 
and also by searching for metadata in XML files. The metadata in the XML files 
takes precedence over the annotations, and so can be used to override metadata 
that is "hard-coded" in annotations.
-
-For example, as of 1.9.0 the various http://www.isisaddons.org[Isis addons] 
modules (not ASF) use schemas for each entity. For example, the `AuditEntry` 
entity in the http://github.com/isisaddons/isis-module-audit[audit module] is 
annotated as:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(
-        identityType=IdentityType.DATASTORE,
-        schema = "IsisAddonsAudit",
-        table="AuditEntry")
-public class AuditEntry {
-    ...
-}
-----
-
-This will map the `AuditEntry` class to a table 
`&quot;IsisAddonsAudit&quot;.&quot;AuditEntry&quot;`; that is using a custom 
schema to own the object.
-
-Suppose though that for whatever reason we didn't want to use a custom schema 
but would rather use the default. We can override the above annotation using a 
`package.jdo` file, for example:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo";
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
-        http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd"; version="3.0">
-    <package name="org.isisaddons.module.audit.dom">
-        <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
-        </class>
-    </package>
-</jdo>
-----
-
-This file should be placed can be placed in `src/main/java/META-INF` within 
your application's `dom` module.
-
-[TIP]
-====
-You can use a mixin action on 
xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
-to download the JDO class metadata in XML form.
-====
-
-
-[NOTE]
-====
-* The same approach should work for any other JDO metadata, but some 
experimentation might be required.+
-+
-For example, in writing up the above example we found that writing 
`schema=&quot;&quot;` (in an attempt to say, "use the default schema for this 
table") actually caused the original annotation value to be used instead.
-
-* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't 
ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but 
MS SQL Server uses "dbo" as its default).
-
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning 
schema for a given table if it does not exist. This behaviour can be 
customized, as described in the section on 
xref:_ugbtb_decoupling_db-schemas[using modules].
-
-* You may need to override the entire class metadata rather than individual 
elements; the mixin mentioned above can help here.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
index f10d3cd..03887c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
@@ -59,6 +59,5 @@ The remaining guides are:
 
 include::_ugodn_configuring.adoc[leveloffset=+1]
 include::_ugodn_jdo-mappings.adoc[leveloffset=+1]
-include::_ugodn_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugodn_java8.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
deleted file mode 100644
index 734e0e3..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugsec_configuring-isis-to-use-bypass]]
-= Bypassing security
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-The bypass security component consists of an implementation of both the 
`AuthenticationManager` and `AuthorizationManager` APIs, and are intended for 
prototyping use only.
-
-The authentication manager allows access with any credentials (in a sense, 
"bypassing" authentication), while the authorization manager provides access to 
all class members (in a sense, "bypassing" authorization).
-
-
-To tell Apache Isis to bypass security, just update the 
`WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=bypass
-isis.authorization=bypass
-----
-
-This installs the appropriate no-op implementations for both authentication 
and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.PNG[width="600px"]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
new file mode 100644
index 0000000..94eb956
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
@@ -0,0 +1,28 @@
+[[_ugsec_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 provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide (this 
chapter)
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+
+include::_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
new file mode 100644
index 0000000..9f297c8
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
@@ -0,0 +1,23 @@
+[[_ugsec_hints-and-tips_configuring-isis-to-use-bypass]]
+= Bypassing security
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The bypass security component consists of an implementation of both the 
`AuthenticationManager` and `AuthorizationManager` APIs, and are intended for 
prototyping use only.
+
+The authentication manager allows access with any credentials (in a sense, 
"bypassing" authentication), while the authorization manager provides access to 
all class members (in a sense, "bypassing" authorization).
+
+
+To tell Apache Isis to bypass security, just update the 
`WEB-INF/isis.properties` file:
+
+[source,ini]
+----
+isis.authentication=bypass
+isis.authorization=bypass
+----
+
+This installs the appropriate no-op implementations for both authentication 
and authorization:
+
+image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.PNG[width="600px"]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index b12e3c7..449abb5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -92,7 +92,8 @@ include::_ugsec_shiro-jdbc-realm.adoc[leveloffset=+1]
 
 include::_ugsec_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
 
-include::_ugsec_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+
+include::_ugsec_hints-and-tips.adoc[leveloffset=+1]
 
 include::_ugsec_api-for-applications.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index ac454f9..a53db8a 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -5,92 +5,33 @@
 :_imagesdir: images/
 
 
+This chapter provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
 
-Since the Restful Objects viewer is designed for computer programs to interact 
with (rather than human beings), it can be a little difficult to explore and 
generally "grok" how it works.
-
-This section provides a few hints-and-tips to help you on your way.
-
-
-
-
-== Using Chrome Tools
-
-This link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to 
explore the Restful API using Chrome plugins/extensions, and how we use them to 
write end-2-end (TCK) tests for the Restful Objects viewer.
-
-
-
-
+See also hints-n-tips chapters in the:
 
-== Angular Tips
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
 
-The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended 
be support both bespoke custom-written viewers as well as generic viewers. 
Indeed, we expect most clients consuming the API will be bespoke, not generic.
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 
-This page captures one or two tips on using Angular to write such a bespoke 
client.
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide (this chapter)
 
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide
 
-=== Invoking a GET link (eg invoking a query action)
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 
-Suppose you have a `CustomerService` providing a `findCustomer` action:
-
-[source,java]
-----
-public class CustomerService {
-    public String id() { return "customers"; }
-    @Action(semantics=SemanticsOf.SAFE)
-    public Customer findCustomer(
-            @ParameterLayout(named="customerName")
-            final String customerName) {
-        ...
-    }
-}
-----
-
-Restful Objects will expose this as action with the following link that looks 
something like:
-
-[source,javascript]
-----
-{
-  "rel" : "urn:org.restfulobjects:rels/invoke",
-  "href" : 
"http://localhost:8080/restful/services/customers/actions/findCustomer/invoke";,
-  "method" : "GET",
-  "type" : 
"application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
-  "arguments" : {
-    "customerName" : {
-      "value" : null
-    }
-  }
-}
-----
-
-You can then invoke this using Angular' `$resource` service as follows.
-
-[source,javascript]
-----
-var findCustomer = 
$resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString";);
-var findCustomerArgs = {
-  "customerName": {
-      "value": "Fred"
-    }
-};
-findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, 
function(data) { ... } )
-----
-
-Here the `:queryString` placeholder in the initial `$resource` constructor is 
expanded with a stringified version of the JSON object representing the args. 
Note how the `findCustomerArgs` is the same as the `&quot;arguments&quot;` 
attribute in the original link (with a value provided instead of `null`).
-
-
-=== Invoking a PUT or POST link
-
-If the method is a PUT or a POST, then no `:queryString` placeholder is 
required in the URL, and the args are instead part of the body.
-
-Use `$resource.put(...)` or `$resource.post(...)` instead.
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
 
 
+Since the Restful Objects viewer is designed for computer programs to interact 
with (rather than human beings), it can be a little difficult to explore and 
generally "grok" how it works.
 
-== Pretty printing
+This section provides a few hints-and-tips to help you on your way.
 
-The JSON representations generated by the Restful Objects viewer are in 
compact form if the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment 
type] is SERVER (ie production), but will automatically be "pretty printed" (in 
other words indented) if the deployment type is PROTOTYPE.
 
 
+include::_ugvro_hints-and-tips_using-chrome-devtools.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_angular-tips.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_pretty-printing.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
new file mode 100644
index 0000000..1ad8f1e
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
@@ -0,0 +1,69 @@
+[[_ugvro_hints-and-tips_angular-tips]]
+= Angular 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/
+
+
+
+The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended 
be support both bespoke custom-written viewers as well as generic viewers. 
Indeed, we expect most clients consuming the API will be bespoke, not generic.
+
+This page captures one or two tips on using Angular to write such a bespoke 
client.
+
+
+== Invoking a GET link (eg invoking a query action)
+
+Suppose you have a `CustomerService` providing a `findCustomer` action:
+
+[source,java]
+----
+public class CustomerService {
+    public String id() { return "customers"; }
+    @Action(semantics=SemanticsOf.SAFE)
+    public Customer findCustomer(
+            @ParameterLayout(named="customerName")
+            final String customerName) {
+        ...
+    }
+}
+----
+
+Restful Objects will expose this as action with the following link that looks 
something like:
+
+[source,javascript]
+----
+{
+  "rel" : "urn:org.restfulobjects:rels/invoke",
+  "href" : 
"http://localhost:8080/restful/services/customers/actions/findCustomer/invoke";,
+  "method" : "GET",
+  "type" : 
"application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
+  "arguments" : {
+    "customerName" : {
+      "value" : null
+    }
+  }
+}
+----
+
+You can then invoke this using Angular' `$resource` service as follows.
+
+[source,javascript]
+----
+var findCustomer = 
$resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString";);
+var findCustomerArgs = {
+  "customerName": {
+      "value": "Fred"
+    }
+};
+findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, 
function(data) { ... } )
+----
+
+Here the `:queryString` placeholder in the initial `$resource` constructor is 
expanded with a stringified version of the JSON object representing the args. 
Note how the `findCustomerArgs` is the same as the `&quot;arguments&quot;` 
attribute in the original link (with a value provided instead of `null`).
+
+
+== Invoking a PUT or POST link
+
+If the method is a PUT or a POST, then no `:queryString` placeholder is 
required in the URL, and the args are instead part of the body.
+
+Use `$resource.put(...)` or `$resource.post(...)` instead.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
new file mode 100644
index 0000000..22108b4
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
@@ -0,0 +1,13 @@
+[[_ugvro_hints-and-tips_pretty-printing]]
+= Pretty printing
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The JSON representations generated by the Restful Objects viewer are in 
compact form if the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment 
type] is SERVER (ie production), but will automatically be "pretty printed" (in 
other words indented) if the deployment type is PROTOTYPE.
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
new file mode 100644
index 0000000..898df04
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
@@ -0,0 +1,25 @@
+[[_ugvro_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/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/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
new file mode 100644
index 0000000..74eb6b8
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
@@ -0,0 +1,9 @@
+[[_ugvro_hints-and-tips_using-chrome-devtools]]
+= Using Chrome Dev Tools
+: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 link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to 
explore the Restful API using Chrome plugins/extensions, and how we use them to 
write end-2-end (TCK) tests for the Restful Objects viewer.

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
index e52d7d5..b837fa6 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
@@ -10,7 +10,7 @@ The Apache Isis Wicket viewer uses 
http://getbootstrap.com/[Bootstrap] styles an
 
 By default the viewer uses the default bootstrap theme. It is possible to 
configure the Wicket viewer to allow the user to 
xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[select
 other themes] provided by http://bootswatch.com[bootswatch.com], and if 
required one of these can be 
xref:../ugvw/ugvw.adoc#_ugvw_customisation_default-theme[set as the default].
 
-However, you may instead want to write your own custom theme, for example to 
fit your company's look-n-feel/interface guidelines. This is done by 
implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket 
Bootstrap]’s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
+However, you may instead want to write your own custom theme, for example to 
fit your company's look-n-feel/interface guidelines. This is done by 
implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]'s 
`de.agilecoders.wicket.core.settings.ITheme` class. This defines:
 
 * the name of the theme
 * the resources it needs (the CSS and optional JS and/or fonts), and

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
new file mode 100644
index 0000000..c736afb
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
@@ -0,0 +1,31 @@
+[[_ugvro_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/
+
+
+
+This chapter provides some solutions for problems we've encountered ourselves 
or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide (this 
chapter)
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] 
guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] 
guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+
+include::_ugvw_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
+include::_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
+
+
+

Reply via email to