Repository: incubator-freemarker Updated Branches: refs/heads/2.3-gae cd5b68c2f -> b5c374210
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/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/b5c37421 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/b5c37421 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/b5c37421 Branch: refs/heads/2.3-gae Commit: b5c3742100ac3ee868852d70c1b50b5bf51156b6 Parents: cd5b68c Author: ddekany <[email protected]> Authored: Tue Mar 27 10:17:33 2018 +0200 Committer: ddekany <[email protected]> Committed: Tue Mar 27 10:17:33 2018 +0200 ---------------------------------------------------------------------- src/manual/en_US/book.xml | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/b5c37421/src/manual/en_US/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml index 2670fde..3fcef11 100644 --- a/src/manual/en_US/book.xml +++ b/src/manual/en_US/book.xml @@ -20593,7 +20593,29 @@ All rights reserved.</emphasis></programlisting> ...></literal> will print nothing. When <literal>false</literal>, the template processing will stop with error if the template is missing. If you omit this option, then - it defaults to <literal>false</literal>.</para> + it defaults to <literal>false</literal>. A more flexible + approach to handle missing templates (such as if you need to do + something when the template is missing) is using the <link + linkend="ref_specvar_get_optional_template"><literal>get_optional_template</literal> + special variable</link>.</para> + + <note> + <para>If <literal>ignore_missing</literal> is + <literal>true</literal>, yet the <literal>include</literal> + directive fails with <quote>Template inclusion failed</quote> + error when the template is missing, that's often because your + application uses a custom + <literal>freemarker.cache.TemplateLoader</literal> + implementation, which incorrectly (against the API + documentation) throws an <literal>IOException</literal> + instead of returning <literal>null</literal> 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 <literal>IOException</literal> + in the Java stack trace to figure out which case it is.</para> + </note> </listitem> </itemizedlist> @@ -23866,6 +23888,22 @@ There was no specific handler for node y error if it does exist but still can't be loaded due to syntactical errors in it, or due to some I/O error.</para> + <note> + <para>If the template fails with <quote>I/O error when trying to + load optional template</quote> when the template is missing, that's + often because your application uses a custom + <literal>freemarker.cache.TemplateLoader</literal> implementation, + which incorrectly (against the API documentation) throws an + <literal>IOException</literal> instead of returning + <literal>null</literal> 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 + <literal>IOException</literal> in the Java stack trace to figure out + which case it is.</para> + </note> + <para>Example, in which depending on if <literal>some.ftl</literal> exists, we either print <quote>Template was found:</quote> and the include the template as <literal><#include 'some.ftl'></literal>
