Repository: incubator-freemarker-site Updated Branches: refs/heads/asf-site dcbbb53da -> a359f0138
Preview Manual: Added note to help out in the cases where a custom TemplateLoader incorrectly throws IOException at a missing template, instead of returning null. Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/commit/a359f013 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/tree/a359f013 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/diff/a359f013 Branch: refs/heads/asf-site Commit: a359f013834aa1dfe197d948cc5a729a357504c0 Parents: dcbbb53 Author: ddekany <[email protected]> Authored: Tue Mar 27 10:20:28 2018 +0200 Committer: ddekany <[email protected]> Committed: Tue Mar 27 10:20:28 2018 +0200 ---------------------------------------------------------------------- builds/fm2.3.28/ref_directive_include.html | 26 ++++++++++++++++++++++++- builds/fm2.3.28/ref_specvar.html | 19 ++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a359f013/builds/fm2.3.28/ref_directive_include.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_directive_include.html b/builds/fm2.3.28/ref_directive_include.html index c3f3657..92e2a74 100644 --- a/builds/fm2.3.28/ref_directive_include.html +++ b/builds/fm2.3.28/ref_directive_include.html @@ -230,7 +230,31 @@ All rights reserved.</strong></pre></div> ...></code> will print nothing. When <code class="inline-code">false</code>, the template processing will stop with error if the template is missing. If you omit this option, then - it defaults to <code class="inline-code">false</code>.</p> + it defaults to <code class="inline-code">false</code>. A more flexible + approach to handle missing templates (such as if you need to do + something when the template is missing) is using the <a href="ref_specvar.html#ref_specvar_get_optional_template"><code>get_optional_template</code> + special variable</a>.</p> + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>If <code class="inline-code">ignore_missing</code> is + <code class="inline-code">true</code>, yet the <code class="inline-code">include</code> + directive fails with "Template inclusion failed" + error when the template is missing, that's often because your + application uses a custom + <code class="inline-code">freemarker.cache.TemplateLoader</code> + implementation, which incorrectly (against the API + documentation) throws an <code class="inline-code">IOException</code> + instead of returning <code class="inline-code">null</code> if a template is + not found. If it's so, the Java programmers need to fix that. + Another possibility is of course that it was indeed not + possible to tell if the template exists or not due to some + technical issues, in which case stopping with error is the + correct behavior. See the cause <code class="inline-code">IOException</code> + in the Java stack trace to figure out which case it is.</p> + </div> + </li> </ul> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a359f013/builds/fm2.3.28/ref_specvar.html ---------------------------------------------------------------------- diff --git a/builds/fm2.3.28/ref_specvar.html b/builds/fm2.3.28/ref_specvar.html index f9b1c2e..11eb71b 100644 --- a/builds/fm2.3.28/ref_specvar.html +++ b/builds/fm2.3.28/ref_specvar.html @@ -405,6 +405,25 @@ under the License. error if it does exist but still can't be loaded due to syntactical errors in it, or due to some I/O error.</p> + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>If the template fails with "I/O error when trying to + load optional template" when the template is missing, that's + often because your application uses a custom + <code class="inline-code">freemarker.cache.TemplateLoader</code> implementation, + which incorrectly (against the API documentation) throws an + <code class="inline-code">IOException</code> instead of returning + <code class="inline-code">null</code> if a template is not found. If it's so, the + Java programmers need to fix that. Another possibility is of course + that it was indeed not possible to tell if the template exists or + not due to some technical issues, in which case stopping with error + is the correct behavior. See the cause + <code class="inline-code">IOException</code> in the Java stack trace to figure out + which case it is.</p> + </div> + + <p>Example, in which depending on if <code class="inline-code">some.ftl</code> exists, we either print "Template was found:" and the include the template as <code class="inline-code"><#include 'some.ftl'></code>
