FREEMARKER-60: Document interaction between lazy import and #global

Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: 
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/96d3971c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/96d3971c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/96d3971c

Branch: refs/heads/2.3
Commit: 96d3971cc6f21974729f4fc0a7dec159b5a4ff42
Parents: 5d81db7
Author: ddekany <ddek...@apache.org>
Authored: Tue Jul 4 21:05:06 2017 +0200
Committer: ddekany <ddek...@apache.org>
Committed: Tue Jul 4 21:05:06 2017 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/Configurable.java | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/96d3971c/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java 
b/src/main/java/freemarker/core/Configurable.java
index 4887dfe..492282a 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -1703,16 +1703,20 @@ public class Configurable {
     /**
      * Specifies if {@code <#import ...>} (and {@link 
Environment#importLib(String, String)}) should delay the loading
      * and processing of the imported templates until the content of the 
imported namespace is actually accessed. This
-     * makes the overhead of <em>unused</em> imports negligible. A drawback is 
that importing a missing or otherwise
-     * broken template will be successful, and the problem will remain hidden 
until (and if) the namespace content is
-     * actually used. Also, you lose the strict control over when the 
namespace initializing code in the imported
-     * template will be executed, though it shouldn't mater for well written 
imported templates anyway. Note that the
-     * namespace initializing code will run with the same {@linkplain 
Configurable#getLocale() locale} as it was at the
-     * point of the {@code <#import ...>} call (other settings won't be 
handled specially like that).
+     * makes the overhead of <em>unused</em> imports negligible. Note that 
turning on lazy importing isn't entirely
+     * transparent, as accessing global variables (usually created with {@code 
<#global ...=...>}) that should be
+     * created by the imported template won't trigger the loading and 
processing of the lazily imported template
+     * (because globals aren't accessed through the namespace variable), so 
the global variable will just be missing.
+     * In general, you lose the strict control over when the namespace 
initializing code in the imported template will
+     * be executed, though it shouldn't mater for most well designed imported 
templates.
+     * Another drawback is that importing a missing or otherwise broken 
template will be successful, and the problem
+     * will remain hidden until (and if) the namespace content is actually 
used. Note that the namespace initializing
+     * code will run with the same {@linkplain Configurable#getLocale() 
locale} as it was at the point of the
+     * {@code <#import ...>} call (other settings won't be handled specially 
like that).
      * 
      * <p>
      * The default is {@code false} (and thus imports are eager) for backward 
compatibility, which can cause
-     * perceivable overhead if you have many imports and only a few of them is 
used.
+     * perceivable overhead if you have many imports and only a few of them is 
actually used.
      * 
      * <p>
      * This setting also affects {@linkplain #setAutoImports(Map) 
auto-imports}, unless you have set a non-{@code null}

Reply via email to