You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2020/08/04 23:43:15 UTC
[freemarker-docgen] branch master updated: Added feature to pass
custom variables to Docgen that then can be referred in DocBook text like
[docgen.customVariables.myVariable].
This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/freemarker-docgen.git
The following commit(s) were added to refs/heads/master by this push:
new 575718e Added feature to pass custom variables to Docgen that then can be referred in DocBook text like [docgen.customVariables.myVariable].
575718e is described below
commit 575718e92c6a23f5a1995b5a49ddf7d4b70e6028
Author: ddekany <dd...@apache.org>
AuthorDate: Wed Aug 5 01:33:29 2020 +0200
Added feature to pass custom variables to Docgen that then can be referred in DocBook text like [docgen.customVariables.myVariable].
---
.../java/org/freemarker/docgen/core/Transform.java | 28 ++++++++++++++++++++++
.../freemarker/docgen/core/templates/footer.ftlh | 2 +-
.../docgen/core/templates/node-handlers.ftlh | 4 +++-
.../org/freemarker/docgen/core/templates/util.ftl | 19 +++++++++++++++
.../org/freemarker/docgen/maven/TransformMojo.java | 7 ++++++
5 files changed, 58 insertions(+), 2 deletions(-)
diff --git a/freemarker-docgen-core/src/main/java/org/freemarker/docgen/core/Transform.java b/freemarker-docgen-core/src/main/java/org/freemarker/docgen/core/Transform.java
index 53bfe16..ee6eb6f 100644
--- a/freemarker-docgen-core/src/main/java/org/freemarker/docgen/core/Transform.java
+++ b/freemarker-docgen-core/src/main/java/org/freemarker/docgen/core/Transform.java
@@ -143,6 +143,7 @@ public final class Transform {
static final String SETTING_MAX_MAIN_TOF_DISPLAY_DEPTH
= "maxMainTOFDisplayDepth";
static final String SETTING_NUMBERED_SECTIONS = "numberedSections";
+ static final String SETTING_CUSTOM_VARIABLES = "customVariables";
static final String SETTING_VALIDATION_PROGRAMLISTINGS_REQ_ROLE
= "programlistingsRequireRole";
@@ -219,6 +220,7 @@ public final class Transform {
= SETTING_MAX_TOF_DISPLAY_DEPTH;
private static final String VAR_NUMBERED_SECTIONS
= SETTING_NUMBERED_SECTIONS;
+ private static final String VAR_CUSTOM_VARIABLES = SETTING_CUSTOM_VARIABLES;
private static final String VAR_INDEX_ENTRIES
= "indexEntries";
private static final String VAR_PAGE_TYPE = "pageType";
@@ -404,6 +406,8 @@ public final class Transform {
private LinkedHashMap<String, String> externalBookmarks = new LinkedHashMap<>();
private Map<String, Map<String, String>> footerSiteMap;
+ private Map<String, Object> customVariables = new HashMap<>();
+
private LinkedHashMap<String, String> tabs = new LinkedHashMap<>();
private Map<String, Map<String, String>> secondaryTabs;
@@ -594,6 +598,13 @@ public final class Transform {
null, SETTING_SEO_META_KEYS);
seoMeta.put(k, v);
}
+ } else if (settingName.equals(SETTING_CUSTOM_VARIABLES)) {
+ Map<String, Object> m = castSettingToMapWithStringKeys(
+ cfgFile, settingName, settingValue);
+ Map<String, Object> newCustomVariables = new HashMap<>(m);
+ // Values set with setCustomVariables(Map) has precedence.
+ newCustomVariables.putAll(customVariables);
+ customVariables = newCustomVariables;
} else if (settingName.equals(SETTING_TABS)) {
Map<String, Object> m = castSettingToMapWithStringKeys(
cfgFile, settingName, settingValue);
@@ -1029,6 +1040,8 @@ public final class Transform {
VAR_INTERNAL_BOOKMARDS, internalBookmarks);
fmConfig.setSharedVariable(
VAR_ROOT_ELEMENT, doc.getDocumentElement());
+ fmConfig.setSharedVariable(
+ VAR_CUSTOM_VARIABLES, customVariables);
// Calculated data:
{
@@ -2819,6 +2832,21 @@ public final class Transform {
this.generateEclipseTOC = eclipseToC;
}
+ public Map<String, Object> getCustomVariables() {
+ return customVariables;
+ }
+
+ /**
+ * Sets the {@link Map} of custom variables, that will be available in templates with variable name
+ * {@link #VAR_CUSTOM_VARIABLES}. When the Docgen settings file loaded ({@link #FILE_SETTINGS}) during
+ * {@link #execute()}, it adds further custom variables, but by creating a new {@link Map}, and not by modifying
+ * the parameter {@link Map}. In case the same custom variable is set in both places, the value of the variable in
+ * this map will win. So this method can be used to override variables set in the settings file.
+ */
+ public void setCustomVariables(Map<String, Object> customVariables) {
+ this.customVariables = customVariables;
+ }
+
// -------------------------------------------------------------------------
/**
diff --git a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/footer.ftlh b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/footer.ftlh
index ca6d9cd..8c51f7b 100644
--- a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/footer.ftlh
+++ b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/footer.ftlh
@@ -62,7 +62,7 @@
</time><#t>
<#local book = .node?root.*>
<#if book.info.productname?hasContent>
- , for ${book.info.productname}<#t>
+ , for <@u.printWithResolvedPlaceholders book.info.productname /><#t>
</#if>
</p>
</#macro>
diff --git a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/node-handlers.ftlh b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/node-handlers.ftlh
index c3e9827..30a5252 100644
--- a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/node-handlers.ftlh
+++ b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/node-handlers.ftlh
@@ -31,7 +31,9 @@
>
<#assign footnotes = []>
-<#macro @text>${.node}</#macro>
+<#macro @text>
+ <@u.printWithResolvedPlaceholders .node /><#t>
+</#macro>
<#macro @element>
<#stop "This DocBook element is not supported by the Docgen transformer, "
diff --git a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/util.ftl b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/util.ftl
index d3ceacf..8f28676 100644
--- a/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/util.ftl
+++ b/freemarker-docgen-core/src/main/resources/org/freemarker/docgen/core/templates/util.ftl
@@ -118,3 +118,22 @@
<#macro invisible1x1Img>
<img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/><#t>
</#macro>
+
+<#macro printWithResolvedPlaceholders text>
+ <#if text?contains(r"[docgen.customVariables.")>
+ <#local s = text>
+ <#list text?matches(r"\[docgen\.customVariables\.(.+?)\]") as match>
+ <#local replaced = match?groups[0]>
+ <#local customVarName = match?groups[1]>
+ <#attempt>
+ <#local customVarValue = customVariables[customVarName]>
+ <#recover>
+ <#stop "Failed to resolve custom variable \"${customVarName}\" in text \"${replaced}\": ${.error}">
+ </#attempt>
+ <#local s = s?replace(replaced, customVarValue)>
+ </#list>
+ ${s}<#t>
+ <#else>
+ ${text}<#t>
+ </#if>
+</#macro>
diff --git a/freemarker-docgen-maven/src/main/java/org/freemarker/docgen/maven/TransformMojo.java b/freemarker-docgen-maven/src/main/java/org/freemarker/docgen/maven/TransformMojo.java
index 7103c67..343f3ca 100644
--- a/freemarker-docgen-maven/src/main/java/org/freemarker/docgen/maven/TransformMojo.java
+++ b/freemarker-docgen-maven/src/main/java/org/freemarker/docgen/maven/TransformMojo.java
@@ -19,6 +19,7 @@
package org.freemarker.docgen.maven;
import java.io.File;
+import java.util.Map;
import java.util.TimeZone;
import org.apache.maven.plugin.AbstractMojo;
@@ -55,6 +56,9 @@ public class TransformMojo extends AbstractMojo {
@Parameter()
private boolean printProgress = true;
+ @Parameter()
+ private Map<String, Object> customVariables;
+
@Override
public void execute() throws MojoExecutionException, MojoFailureException {
Transform transform = new Transform();
@@ -76,6 +80,9 @@ public class TransformMojo extends AbstractMojo {
transform.setOffline(offline);
}
transform.setPrintProgress(printProgress); // TODO Use Maven logging for this
+ if (customVariables != null) {
+ transform.setCustomVariables(customVariables);
+ }
try {
transform.execute();
} catch (Exception e) {