You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/04/17 10:32:22 UTC
[28/43] isis git commit: ISIS-1521: adds hints-n-tips sections for
most of the user guides, and distributes out tips from dg.adoc as appropriate
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/7295f71a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/7295f71a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/7295f71a
Branch: refs/heads/wip
Commit: 7295f71a6a78cc0bf4f27f187b6773562c7f5632
Parents: 0b6d175
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:13:05 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Apr 14 16:13:05 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/7295f71a/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/7295f71a/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\u2019s 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\u2019ve 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\u2019s 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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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 \u201caddExcludedProduct()\u201d action, if the user didn\u2019t flush, the following test would fail because the managed
+On the \u201caddExcludedProduct()\u201d 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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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 `"IsisAddonsAudit"."AuditEntry"`; 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=""` (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/7295f71a/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/7295f71a/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/7295f71a/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 `"IsisAddonsAudit"."AuditEntry"`; 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=""` (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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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 `"arguments"` 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/7295f71a/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 `"arguments"` 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/7295f71a/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/7295f71a/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/7295f71a/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/7295f71a/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]\u2019s `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/7295f71a/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]
+
+
+