freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [20/50] incubator-freemarker git commit: Manual: Slightly improved ?api documentation.
Date Sun, 12 Jun 2016 16:54:01 GMT
Manual: Slightly improved ?api documentation.


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

Branch: refs/heads/2.3
Commit: 64a250049fdc1059527aad7b0b44969d451ac787
Parents: b9b554a
Author: ddekany <ddekany@apache.org>
Authored: Wed Jun 1 19:45:41 2016 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Wed Jun 1 19:45:41 2016 +0200

----------------------------------------------------------------------
 src/manual/en_US/book.xml | 61 +++++++++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 25 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/64a25004/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index 516ed4b..30e91b5 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -17591,19 +17591,24 @@ Sorted by name.last:
           <para><literal><replaceable>value</replaceable>?api</literal>
           provides access to the API (usually, the Java API) of
           <literal><replaceable>value</replaceable></literal>, like
-          <literal><replaceable>value</replaceable>?api.<replaceable>someJavaMethod()</replaceable></literal>,
-          if the value itself supports this extra feature. This meant to be
-          used rarely, when you need to call a Java method of an object, but
-          the simplistic view of the value that FreeMarker exposes to the
-          templates hides that, and there's no equivalent built-in either. For
-          example, when you have <literal>Map</literal> that you put into the
+          <literal><replaceable>value</replaceable>?api.<replaceable>someJavaMethod()</replaceable></literal>
+          or
+          <literal><replaceable>value</replaceable>?api.<replaceable>someBeanProperty</replaceable></literal>,
+          if the value itself supports exposing its API. This meant to be used
+          rarely, when you need to call a Java method of an object, but the
+          by-design simplistic view of the value that FreeMarker exposes to
+          the templates hides that, and there's no equivalent built-in either.
+          For example, when you put a <literal>Map</literal> into the
           data-model (and you are using the default object wrapper),
           <literal>myMap.myMethod()</literal> in a template basically
           translates to <literal>((Method)
           myMap.get("myMethod")).invoke(...)</literal> in Java, thus you can't
           call <literal>myMethod</literal>. If, however, you write
           <literal>myMap?api.myMethod()</literal> instead, that means
-          <literal>myMap.myMethod()</literal> in Java.</para>
+          <literal>myMap.myMethod()</literal> in Java. Similarly,
+          <literal>myMap?api.myProperty</literal> translates to
+          <literal>myMap.getMyProperty()</literal> in Java, instead of to
+          <literal>myMap.get("myProperty")</literal>.</para>
 
           <para><emphasis>You should avoid using <literal>api</literal>,
and
           rely on the capabilities of the FTL types and the related built-ins
@@ -17613,7 +17618,7 @@ Sorted by name.last:
           <literal>?api</literal> is more verbose, slower, more easily breaks
           when FreeMarker configuration settings are changed, and most
           importantly, more prone to break as the technical details of the
-          data-model changes. For example, if <literal>users</literal> is
+          data-model change. For example, if <literal>users</literal> is
           changed from a <literal>List</literal> to an array,
           <literal>users?size</literal> will keep working, while
           <literal>users?api.size()</literal> will break.</para>
@@ -17653,16 +17658,18 @@ Sorted by name.last:
                   <literal>DefaultObjectWrapper</literal> with its
                   <literal>incompatibleImprovements</literal> set to 2.3.22 or
                   higher (<link linkend="topic.defaultObjectWrapperIcI">see
-                  how to set it here</link>) (actually, what matters is that
-                  its <literal>useAdaptersForContainer</literal> property is
-                  set to <literal>true</literal>, but that's the default with
-                  said <literal>incompatibleImprovements</literal>), FTL
-                  values made from <literal>Map</literal>-s and
-                  <literal>List</literal>-s support <literal>?api</literal>.
-                  Other <literal>java.util.Collections</literal> also, if
+                  how to set it here</link>), FTL values made from
+                  <literal>Map</literal>-s and <literal>List</literal>-s
+                  support <literal>?api</literal>. (Actually, what matters is
+                  that its <literal>useAdaptersForContainer</literal> property
+                  is set to <literal>true</literal>, but that's the default
+                  with said <literal>incompatibleImprovements</literal>.)
+                  Other <literal>java.util.Collections</literal> (such as
+                  <literal>Set</literal>-s) only support
+                  <literal>?api</literal> if
                   <literal>DefaultObjectWrapper</literal>'s
                   <literal>forceLegacyNonListCollections</literal> property is
-                  set to <literal>false</literal> (default is
+                  set to <literal>false</literal> (the default is
                   <literal>true</literal> for better out-of-the-box backward
                   compatibility).</para>
                 </listitem>
@@ -17670,8 +17677,7 @@ Sorted by name.last:
                 <listitem>
                   <para>When wrapped with pure
                   <literal>BeansWrapper</literal>, all values support
-                  <literal>?api</literal>. But again, avoid using it if
-                  there's another solution.</para>
+                  <literal>?api</literal>.</para>
                 </listitem>
 
                 <listitem>
@@ -27955,19 +27961,24 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
               <literal><replaceable>value</replaceable>?api</literal>
provides
               access to the API (usually, the Java API) of
               <literal><replaceable>value</replaceable></literal>,
like
-              <literal><replaceable>value</replaceable>?api.<replaceable>someJavaMethod()</replaceable></literal>,
-              if the value itself supports this extra feature. This meant to
-              be used rarely, when you need to call a Java method of an
-              object, but the by-design simplistic view of the value that
-              FreeMarker exposes to the templates hides that, and there's no
-              equivalent built-in either. For example, when you put a
+              <literal><replaceable>value</replaceable>?api.<replaceable>someJavaMethod()</replaceable></literal>
+              or
+              <literal><replaceable>value</replaceable>?api.<replaceable>someBeanProperty</replaceable></literal>),
+              if the value itself supports exposing its API. This meant to be
+              used rarely, when you need to call a Java method of an object,
+              but the by-design simplistic view of the value that FreeMarker
+              exposes to the templates hides that, and there's no equivalent
+              built-in either. For example, when you put a
               <literal>Map</literal> into the data-model (and you are using
               the default object wrapper), <literal>myMap.myMethod()</literal>
               in a template basically translates to <literal>((Method)
               myMap.get("myMethod")).invoke(...)</literal> in Java, thus you
               can't call <literal>myMethod</literal>. If, however, you write
               <literal>myMap?api.myMethod()</literal> instead, that means
-              <literal>myMap.myMethod()</literal> in Java.</para>
+              <literal>myMap.myMethod()</literal> in Java. Similarly,
+              <literal>myMap?api.myProperty</literal> translates to
+              <literal>myMap.getMyProperty()</literal> in Java, instead of to
+              <literal>myMap.get("myProperty")</literal>.</para>
 
               <para><emphasis>If you can, rely on the capabilities of the FTL
               types and the related built-ins as far as possible. Using


Mime
View raw message