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/20 08:12:25 UTC
[16/58] [abbrv] isis git commit: ISIS-1521: moves faq from ugfun to
dg.adoc, renames to 'hints-n-tips'
ISIS-1521: moves faq from ugfun to dg.adoc, renames to 'hints-n-tips'
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/0c22c0a3
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/0c22c0a3
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/0c22c0a3
Branch: refs/heads/wip
Commit: 0c22c0a392cce587e6448d438154d8c5063051c7
Parents: add8cef
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:12:14 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:29 2017 +0100
----------------------------------------------------------------------
.../asciidoc/guides/dg/_dg_hints-and-tips.adoc | 23 +++++
.../dg/_dg_hints-and-tips_enabling-logging.adoc | 41 +++++++++
.../dg/_dg_hints-and-tips_enhance-only.adoc | 25 ++++++
...nd-tips_how-run-fixtures-on-app-startup.adoc | 24 ++++++
...ips_how-to-handle-void-and-null-results.adoc | 79 +++++++++++++++++
...nd-tips_how-to-implement-a-spellchecker.adoc | 29 +++++++
...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ++++++
.../dg/_dg_hints-and-tips_per-user-themes.adoc | 91 ++++++++++++++++++++
...g_hints-and-tips_restful-image-property.adoc | 25 ++++++
...tips_subtype-entity-not-fully-populated.adoc | 60 +++++++++++++
.../src/main/asciidoc/guides/dg/dg.adoc | 3 +-
.../main/asciidoc/guides/ugfun/_ugfun_faqs.adoc | 21 -----
.../ugfun/_ugfun_faqs_enabling-logging.adoc | 41 ---------
.../guides/ugfun/_ugfun_faqs_enhance-only.adoc | 25 ------
...un_faqs_how-run-fixtures-on-app-startup.adoc | 24 ------
...aqs_how-to-handle-void-and-null-results.adoc | 79 -----------------
...un_faqs_how-to-implement-a-spellchecker.adoc | 29 -------
..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc | 26 ------
.../ugfun/_ugfun_faqs_per-user-themes.adoc | 91 --------------------
.../_ugfun_faqs_restful-image-property.adoc | 25 ------
...faqs_subtype-entity-not-fully-populated.adoc | 60 -------------
.../src/main/asciidoc/guides/ugfun/ugfun.adoc | 2 +-
22 files changed, 426 insertions(+), 423 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
new file mode 100644
index 0000000..67d89bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -0,0 +1,23 @@
+[[_dg_hints-and-tips]]
+= Hints and Tips
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+
+This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
+Apache Isis mailing lists.
+
+See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
+
+include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
new file mode 100644
index 0000000..af3ecc3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
@@ -0,0 +1,41 @@
+[[_dg_hints-and-tips_enabling-logging]]
+= Enabling Logging
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+Sometimes you just need to see what is going on.
+There are various ways in which logging can be enabled, here are the ones we tend to use.
+
+* In Apache Isis +
++
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+* In DataNucleus +
++
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
+
+* In the JDBC Driver +
++
+Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
+There are examples of both in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+* In the database +
++
+Details below.
+
+
+Database logging can be configured:
+
+* for HSQLDB +
++
+by adding`;sqllog=3` to the end of the JDBC URL.
+
+* for PostgreSQL: +
++
+Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
+
+* for MS SQL Server Logging: +
++
+We like to use the excellent SQL Profiler tool.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
new file mode 100644
index 0000000..aa6bff9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_enhance-only]]
+= Enhance only (IntelliJ)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+From the Apache Isis mailing list is:
+
+* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
+
+Yes, you can; here's one way:
+
+* Duplicate your run configuration for running the webapp
+** the one where the main class is `org.apache.isis.WebServer`
+** there's a button for this on the run configurations dialog.
+* then, on your copy change the main class to `org.apache.isis.Dummy`
+
+Or, you could just write a small shell script and run from the command line:
+
+[source,bash]
+.enhance.sh
+----
+mvn -pl dom datanucleus:enhance -o
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
new file mode 100644
index 0000000..89a1547
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
@@ -0,0 +1,24 @@
+[[_dg_hints-and-tips_how-run-fixtures-on-app-startup]]
+= How run fixtures on startup?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the Apache Isis users mailing list:
+
+* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change).
+What is the right way to do this?
+Hook up into the webapp start?
+Use events?_
+
+
+The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
+These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
+example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+Alternatively just set "isis.fixtures" and "isis.persistor.datanucleus.install-fixtures" properties.
+
+In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package).
+An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
new file mode 100644
index 0000000..76b3a2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -0,0 +1,79 @@
+[[_dg_hints-and-tips_how-to-handle-void-and-null-results]]
+= How to handle void/null results
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
+
+* _When using a `void` action, let\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.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
+
+The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@DomainServiceLayout(menuOrder = "1") // <1>
+public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
+ @Override
+ public Object route(final Object original) {
+ if(original != null) { // <2>
+ return original;
+ }
+ container.flush(); // <3>
+
+ final BreadcrumbModelProvider wicketSession = // <4>
+ (BreadcrumbModelProvider) AuthenticatedWebSession.get();
+ final BreadcrumbModel breadcrumbModel =
+ wicketSession.getBreadcrumbModel();
+ final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
+
+ final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
+ breadcrumbs.stream() // <5>
+ .filter(entityModel -> entityModel != null)
+ .map(EntityModel::getObject) // <6>
+ .filter(objectAdapter -> objectAdapter != null)
+ .map(ObjectAdapter::getObject) // <7>
+ .filter(pojo -> !(pojo instanceof Persistable) ||
+ !((Persistable)pojo).dnIsDeleted()) // <8>
+ .findFirst();
+
+ return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage()); // <9>
+ }
+ private Object homePage() {
+ return homePageProviderService.homePage();
+ }
+ @Inject
+ HomePageProviderService homePageProviderService;
+ @Inject
+ DomainObjectContainer container;
+}
+----
+<1> override the default imlpementation
+<2> if a non-null object was returned, then return this
+<3> ensure that any persisted objects have been deleted.
+<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
+<5> loop over all breadcrumbs
+<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
+representation (`ObjectAdapter`)
+<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
+<8> if object is persistable (not a view model) then make sure it is not deleted
+<9> return the first object if any, otherwise the home page object (if any).
+
+Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
new file mode 100644
index 0000000..c141366
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -0,0 +1,29 @@
+[[_dg_hints-and-tips_how-to-implement-a-spellchecker]]
+= How to implement a spellchecker?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
+
+* _What is the easiest way to add a spell checker to the text written in a field in
+ a domain object, for instance to check English syntax?_
+
+One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
+
+* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
+
+* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+
+if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
+
+You'll need some way to know which fields should be spell checked. Two ways spring to mind:
+
+* either look at the domain event's identifier
+
+* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
+
+And you'll (obviously) also need some sort of spell checker implementation to call.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
new file mode 100644
index 0000000..22263cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -0,0 +1,26 @@
+[[_dg_hints-and-tips_i18n-label-in-wicket-viewer]]
+= How i18n the Wicket viewer?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
+
+* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
+Referencing those via their message id inside a .po file didn't work either.
+Can this be done?_
+
+
+The above FAQ was raised against `1.10.0`. As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+
+Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
+
+In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles. This is still supported (as a fallback):
+
+* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
+
+* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
new file mode 100644
index 0000000..10a89f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
@@ -0,0 +1,91 @@
+[[_dg_hints-and-tips_per-user-themes]]
+= Per-user Themes
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
+
+* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
+Would this also be possible for the login page, possibly depending on the used host name?_
+
+
+Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
+
+The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
+
+
+[source,java]
+.IActiveThemeProvider implementation
+----
+public class UserSettingsThemeProvider implements ActiveThemeProvider {
+ ...
+ @Override
+ public ITheme getActiveTheme() {
+ if(IsisContext.getSpecificationLoader().isInitialized()) {
+ final String themeName = IsisContext.doInSession(new Callable<String>() {
+ @Override
+ public String call() throws Exception {
+ final UserSettingsService userSettingsService =
+ lookupService(UserSettingsService.class);
+ final UserSetting activeTheme = userSettingsService.find(
+ IsisContext.getAuthenticationSession().getUserName(),
+ ACTIVE_THEME);
+ return activeTheme != null ? activeTheme.valueAsString() : null;
+ }
+ });
+ return themeFor(themeName);
+ }
+ return new SessionThemeProvider().getActiveTheme();
+ }
+ @Override
+ public void setActiveTheme(final String themeName) {
+ IsisContext.doInSession(new Runnable() {
+ @Override
+ public void run() {
+ final String currentUsrName =
+ IsisContext.getAuthenticationSession().getUserName();
+ final UserSettingsServiceRW userSettingsService =
+ lookupService(UserSettingsServiceRW.class);
+ final UserSettingJdo activeTheme =
+ (UserSettingJdo) userSettingsService.find(
+ currentUsrName, ACTIVE_THEME);
+ if(activeTheme != null) {
+ activeTheme.updateAsString(themeName);
+ } else {
+ userSettingsService.newString(
+ currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
+ }
+ }
+ });
+ }
+ private ITheme themeFor(final String themeName) {
+ final ThemeProvider themeProvider = settings.getThemeProvider();
+ if(themeName != null) {
+ for (final ITheme theme : themeProvider.available()) {
+ if (themeName.equals(theme.name()))
+ return theme;
+ }
+ }
+ return themeProvider.defaultTheme();
+ }
+ ...
+}
+----
+
+and
+
+[source,java]
+.Using the ActiveThemeProvider
+----
+@Override
+protected void init() {
+ super.init();
+
+ final IBootstrapSettings settings = Bootstrap.getSettings();
+ settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
+
+ settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
new file mode 100644
index 0000000..3084508
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_restful-image-property]]
+= How parse images in RO viewer?
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
+
+* _I am trying to display an image in a JavaScript client app, the image comes from
+ an Isis RO web service as a string, but it won't show.
+Is there something I should do to change the message?_
+
+
+The RO viewer returns the image as a string, in the form:
+
+ "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/ ...."
+
+This is in the form:
+
+ (filename):(mime type):(binary data in base64)
+
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
+
+To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..d5f5965
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,60 @@
+[[_dg_hints-and-tips_subtype-entity-not-fully-populated]]
+= Subtype not fully populated
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
+
+
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
+Use getters instead.
+
+
+[WARNING]
+====
+Properties of domain entities should always be accessed using getters.
+The only code that should access to fields should be the getters themselves.
+====
+
+Why so?
+Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
+This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
+But hitting the field directly means that the lazy loading code does not run.
+
+This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
+But that will be because the field has been populated already, for whatever reason.
+
+One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SupertypeEntity {
+ ...
+}
+----
+
+and then:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SubtypeEntity extends SupertypeEntity {
+ ...
+}
+----
+
+This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
+This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
+This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
+
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
+
+Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
+
+In summary, there's just one rule: *always use the getters, never the fields*.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
index 5233145..76cd0a5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
@@ -51,9 +51,10 @@ The remaining guides are:
-
include::_dg_ide.adoc[leveloffset=+1]
+include::_dg_hints-and-tips.adoc[leveloffset=+1]
+
include::_dg_building-isis.adoc[leveloffset=+1]
include::_dg_asciidoc.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
deleted file mode 100644
index 1841474..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_ugfun_faqs]]
-= FAQs
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
-Apache Isis mailing lists.
-
-See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
-
-include::_ugfun_faqs_enabling-logging.adoc[leveloffset=+1]
-include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::_ugfun_faqs_restful-image-property.adoc[leveloffset=+1]
-include::_ugfun_faqs_enhance-only.adoc[leveloffset=+1]
-include::_ugfun_faqs_per-user-themes.adoc[leveloffset=+1]
-include::_ugfun_faqs_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
deleted file mode 100644
index 18e4a1f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugfun_faqs_enabling-logging]]
-= Enabling Logging
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-Sometimes you just need to see what is going on.
-There are various ways in which logging can be enabled, here are the ones we tend to use.
-
-* In Apache Isis +
-+
-Modify `WEB-INF/logging.properties` (a log4j config file)
-
-* In DataNucleus +
-+
-As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
-
-* In the JDBC Driver +
-+
-Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
-There are examples of both in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-* In the database +
-+
-Details below.
-
-
-Database logging can be configured:
-
-* for HSQLDB +
-+
-by adding`;sqllog=3` to the end of the JDBC URL.
-
-* for PostgreSQL: +
-+
-Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
-
-* for MS SQL Server Logging: +
-+
-We like to use the excellent SQL Profiler tool.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
deleted file mode 100644
index 4af2db6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_enhance-only]]
-= Enhance only (IntelliJ)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-From the Apache Isis mailing list is:
-
-* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
-
-Yes, you can; here's one way:
-
-* Duplicate your run configuration for running the webapp
-** the one where the main class is `org.apache.isis.WebServer`
-** there's a button for this on the run configurations dialog.
-* then, on your copy change the main class to `org.apache.isis.Dummy`
-
-Or, you could just write a small shell script and run from the command line:
-
-[source,bash]
-.enhance.sh
-----
-mvn -pl dom datanucleus:enhance -o
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
deleted file mode 100644
index 9964d39..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ugfun_faqs_how-run-fixtures-on-app-startup]]
-= How run fixtures on startup?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the Apache Isis users mailing list:
-
-* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change).
-What is the right way to do this?
-Hook up into the webapp start?
-Use events?_
-
-
-The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
-These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
-example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-Alternatively just set "isis.fixtures" and "isis.persistor.datanucleus.install-fixtures" properties.
-
-In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package).
-An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
deleted file mode 100644
index b57c453..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ugfun_faqs_how-to-handle-void-and-null-results]]
-= How to handle void/null results
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
-
-* _When using a `void` action, let\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.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
-The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
-
-The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@DomainServiceLayout(menuOrder = "1") // <1>
-public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
- @Override
- public Object route(final Object original) {
- if(original != null) { // <2>
- return original;
- }
- container.flush(); // <3>
-
- final BreadcrumbModelProvider wicketSession = // <4>
- (BreadcrumbModelProvider) AuthenticatedWebSession.get();
- final BreadcrumbModel breadcrumbModel =
- wicketSession.getBreadcrumbModel();
- final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
-
- final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
- breadcrumbs.stream() // <5>
- .filter(entityModel -> entityModel != null)
- .map(EntityModel::getObject) // <6>
- .filter(objectAdapter -> objectAdapter != null)
- .map(ObjectAdapter::getObject) // <7>
- .filter(pojo -> !(pojo instanceof Persistable) ||
- !((Persistable)pojo).dnIsDeleted()) // <8>
- .findFirst();
-
- return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage()); // <9>
- }
- private Object homePage() {
- return homePageProviderService.homePage();
- }
- @Inject
- HomePageProviderService homePageProviderService;
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> override the default imlpementation
-<2> if a non-null object was returned, then return this
-<3> ensure that any persisted objects have been deleted.
-<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
-<5> loop over all breadcrumbs
-<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
-representation (`ObjectAdapter`)
-<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
-<8> if object is persistable (not a view model) then make sure it is not deleted
-<9> return the first object if any, otherwise the home page object (if any).
-
-Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
deleted file mode 100644
index 1c48c0d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_faqs_how-to-implement-a-spellchecker]]
-= How to implement a spellchecker?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
-
-* _What is the easiest way to add a spell checker to the text written in a field in
- a domain object, for instance to check English syntax?_
-
-One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
-
-* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
-
-* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
-
-You'll need some way to know which fields should be spell checked. Two ways spring to mind:
-
-* either look at the domain event's identifier
-
-* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
-
-And you'll (obviously) also need some sort of spell checker implementation to call.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
deleted file mode 100644
index 220c58b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ugfun_faqs_i18n-label-in-wicket-viewer]]
-= How i18n the Wicket viewer?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
-
-* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
-Referencing those via their message id inside a .po file didn't work either.
-Can this be done?_
-
-
-The above FAQ was raised against `1.10.0`. As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
-
-Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
-
-In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles. This is still supported (as a fallback):
-
-* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
-
-* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
deleted file mode 100644
index a9b34d4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_ugfun_faqs_per-user-themes]]
-= Per-user Themes
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
-
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
-Would this also be possible for the login page, possibly depending on the used host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
-
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
- ...
- @Override
- public ITheme getActiveTheme() {
- if(IsisContext.getSpecificationLoader().isInitialized()) {
- final String themeName = IsisContext.doInSession(new Callable<String>() {
- @Override
- public String call() throws Exception {
- final UserSettingsService userSettingsService =
- lookupService(UserSettingsService.class);
- final UserSetting activeTheme = userSettingsService.find(
- IsisContext.getAuthenticationSession().getUserName(),
- ACTIVE_THEME);
- return activeTheme != null ? activeTheme.valueAsString() : null;
- }
- });
- return themeFor(themeName);
- }
- return new SessionThemeProvider().getActiveTheme();
- }
- @Override
- public void setActiveTheme(final String themeName) {
- IsisContext.doInSession(new Runnable() {
- @Override
- public void run() {
- final String currentUsrName =
- IsisContext.getAuthenticationSession().getUserName();
- final UserSettingsServiceRW userSettingsService =
- lookupService(UserSettingsServiceRW.class);
- final UserSettingJdo activeTheme =
- (UserSettingJdo) userSettingsService.find(
- currentUsrName, ACTIVE_THEME);
- if(activeTheme != null) {
- activeTheme.updateAsString(themeName);
- } else {
- userSettingsService.newString(
- currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
- }
- }
- });
- }
- private ITheme themeFor(final String themeName) {
- final ThemeProvider themeProvider = settings.getThemeProvider();
- if(themeName != null) {
- for (final ITheme theme : themeProvider.available()) {
- if (themeName.equals(theme.name()))
- return theme;
- }
- }
- return themeProvider.defaultTheme();
- }
- ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
- super.init();
-
- final IBootstrapSettings settings = Bootstrap.getSettings();
- settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-
- settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
deleted file mode 100644
index e5deed8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_restful-image-property]]
-= How parse images in RO viewer?
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
-
-* _I am trying to display an image in a JavaScript client app, the image comes from
- an Isis RO web service as a string, but it won't show.
-Is there something I should do to change the message?_
-
-
-The RO viewer returns the image as a string, in the form:
-
- "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/ ...."
-
-This is in the form:
-
- (filename):(mime type):(binary data in base64)
-
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index 5b02ae0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_ugfun_faqs_subtype-entity-not-fully-populated]]
-= Subtype not fully populated
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
-
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
-Use getters instead.
-
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters.
-The only code that should access to fields should be the getters themselves.
-====
-
-Why so?
-Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
-This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
-But hitting the field directly means that the lazy loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
-But that will be because the field has been populated already, for whatever reason.
-
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
- ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
- ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
-This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
-This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index f119338..1379b7a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -14,7 +14,7 @@ and tells you how to xref:ugfun.adoc#_ugfun_getting-started[get started] with a
It also describes a number of xref:ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
xref:ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:ugfun.adoc#_ugfun_faqs.adoc[FAQ]s.
+ catalogues various xref:dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
=== Other Guides