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/05/25 09:24:01 UTC

isis git commit: adds pdf link to rendered guides

Repository: isis
Updated Branches:
  refs/heads/master c0db197be -> cdc034710


adds pdf link to rendered guides


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

Branch: refs/heads/master
Commit: cdc034710c933ed48d49131fb069f73cc1166822
Parents: c0db197
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed May 24 17:21:34 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed May 24 17:56:29 2017 +0100

----------------------------------------------------------------------
 adocs/documentation/pom.xml                     |  1 +
 .../src/main/asciidoc/css/customisations.css    |  4 ++
 .../src/main/asciidoc/guides/cgcom/cgcom.adoc   |  2 +-
 .../src/main/asciidoc/guides/dg/dg.adoc         |  1 +
 .../src/main/asciidoc/guides/rgant/rgant.adoc   |  1 +
 .../src/main/asciidoc/guides/rgcfg/rgcfg.adoc   |  1 +
 .../src/main/asciidoc/guides/rgcms/rgcms.adoc   |  1 +
 .../src/main/asciidoc/guides/rgfis/rgfis.adoc   |  1 +
 .../src/main/asciidoc/guides/rgmvn/rgmvn.adoc   |  1 +
 .../src/main/asciidoc/guides/rgsvc/rgsvc.adoc   |  1 +
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |  1 +
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |  1 +
 ...nts-and-tips_overriding-jdo-annotations.adoc | 69 +++++++++++++-------
 .../src/main/asciidoc/guides/ugodn/ugodn.adoc   |  2 +-
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |  1 +
 .../src/main/asciidoc/guides/ugtst/ugtst.adoc   |  1 +
 .../src/main/asciidoc/guides/ugvro/ugvro.adoc   |  1 +
 .../src/main/asciidoc/guides/ugvw/ugvw.adoc     |  1 +
 adocs/template/document.html.erb                |  6 ++
 19 files changed, 70 insertions(+), 27 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/pom.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/pom.xml b/adocs/documentation/pom.xml
index 8e556d2..970a71b 100644
--- a/adocs/documentation/pom.xml
+++ b/adocs/documentation/pom.xml
@@ -159,6 +159,7 @@
 
                                     <sourceDirectory>src/main/asciidoc/</sourceDirectory>
                                     <outputDirectory>${project.reporting.outputDirectory}/</outputDirectory>
+
                                     <!--
                                     <sourceDocumentName>guides/ugvw/ugvw.adoc</sourceDocumentName>
                                     <sourceDocumentName>guides/rgsvc/rgsvc.adoc</sourceDocumentName>

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/css/customisations.css
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/css/customisations.css b/adocs/documentation/src/main/asciidoc/css/customisations.css
index de70282..8f67859 100644
--- a/adocs/documentation/src/main/asciidoc/css/customisations.css
+++ b/adocs/documentation/src/main/asciidoc/css/customisations.css
@@ -43,3 +43,7 @@ table a:not(.btn), .table a:not(.btn) {
 }
 
 
+.pdf-link {
+    float: right;
+    padding-top: 20px;
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
index 3690a30..3c43e70 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
@@ -4,7 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
-
+:generate_pdf:
 
 [[__cgcom]]
 == Committers' Guide

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/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 dbad10f..9694c23 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_dg]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgant/rgant.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/rgant.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/rgant.adoc
index b921d9c..671ea68 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/rgant.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/rgant.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_rgant]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
index 2cd064c..f0c6f3d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_rgcfg]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
index 30372e9..c093ab5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_rgcms]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgfis/rgfis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/rgfis.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/rgfis.adoc
index 68747b6..e927b3c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/rgfis.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/rgfis.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgmvn/rgmvn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/rgmvn.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/rgmvn.adoc
index 3638aed..eaa294d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/rgmvn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/rgmvn.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_rgmvn]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/rgsvc/rgsvc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/rgsvc.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/rgsvc.adoc
index 3952dea..5873d65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/rgsvc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/rgsvc.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/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 5e9c576..4bb7e42 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[_ugbtb]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/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 b548183..bff8c4d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[__ugfun]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/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
index 3430709..1e21319 100644
--- 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
@@ -6,8 +6,28 @@
 
 
 
-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.
+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.
 
+In fact, JDO/DataNucleus provides two different XML files that have slightly different purposes and capabilities:
+
+* first, a `.jdo` file can be provided which - if found - completely replaces the annotations. +
++
+The idea here is simply to use XML as the means by which metadata is specified.
+
+* second, an `.orm` file can be provided which - if found - provides individual overrides for a particular database vendor. +
++
+The idea here is to accommodate for subtle differences in support for SQL between vendors.
+A good example is the default schema for a table: `dbo` for SQL Server, `public` for HSQLDB, `sys` for Oracle, and so on.
+
+If you want to use the first approach (the `.jdo` file), you'll find that you can download the effective XML representation of domain entities using the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Persistable_downloadJdoMetadata[downloadJdoMetadata] mixin action available in prototyping mode.
+This then needs to be renamed and placed in the appropriate location on the classpath; see the link:http://www.datanucleus.org[DataNucleus documentation] for details.
+
+However, using this first approach does create a maintenance effort; if the domain entity's class structure changes over time, then the XML metadata file will need to be updated.
+
+The second approach (using an `.orm` file) is therefore often more useful than the first, because the metadata provided overrides rather than replaces the annotations (and annotations not overridden continue to be honoured).
+
+A typical use case is to change the database schema for an entity.
 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]
@@ -23,42 +43,41 @@ public class AuditEntry {
 
 This will map the `AuditEntry` class to a table `&quot;IsisAddonsAudit&quot;.&quot;AuditEntry&quot;`; that is using a custom schema to own the object.
 
-Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
+Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default.
+Also suppose we are using SQL Server as our target database.
 
+We can override the above annotation using a `AuditEntry-sqlserver.orm` file, placed in the same package as the `AuditEntry` entity.
+For example:
+
+.AuditEntry-sqlserver.orm
 [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">
+<orm xmlns="http://xmlns.jcp.org/xml/ns/jdo/orm"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/orm
+        http://xmlns.jcp.org/xml/ns/jdo/orm_3_0.xsd">
+
     <package name="org.isisaddons.module.audit.dom">
-        <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
+        <class name="AuditEntry"
+               schema="isisaudit"
+               table="AuditEntry">
         </class>
     </package>
-</jdo>
-----
-
-This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
+</orm>
 
-[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.
-====
+----
 
+It's also necessary to tell JDO/DataNucleus about which vendor is being used (`sqlserver` in the example above).
+This is done using a configuration property:
 
-[NOTE]
-====
-* The same approach should work for any other JDO metadata, but some experimentation might be required.+
-+
-For example, in writing up the above example we found that writing `schema=&quot;&quot;` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
 
-* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
+.isis.properties
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.Mapping=sqlserver
+----
 
-* 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/ugbtb.adoc#_ugodn_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/cdc03471/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 85e3071..d90b57e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
@@ -4,7 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
-
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/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 9b17b5c..0edf472 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 [[__ugsec]]

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc
index 2302c81..3b57d97 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
index 8ee10a9..cdb9628 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/ugvro.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
index 4ecfe19..13dab66 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
@@ -4,6 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 :numbered:
+:generate_pdf:
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cdc03471/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index d879f0f..5fe5170 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -61,6 +61,9 @@
        def is_toc?
          not (attributes.has_key?('notoc'))
        end
+       def is_pdf?
+         attributes.has_key?('generate_pdf')
+       end
     %>
 
     <link href="<%= (attr :_basedir) %>css/slick/1.5.0/slick.css" rel="stylesheet">
@@ -206,6 +209,9 @@
                         <a href="#" id="search-results-clear">clear</a>
                     </div>
                 </div>
+                <% if is_pdf? then %>
+                    <span class="pdf-link"><a href="<%= (attr :docname) %>.pdf"><img src="<%= (attr :_basedir) %>images/PDF-50.png"></img></a></span>
+                <% end %>
                 <div class="page-title">
                     <h1><%= document.name %></h1>
                 </div>