Changeset 9329

Timestamp:

09/25/10 09:12:13 (20 months ago)

Author:

PaulHarvey

Message:

Item9415: Doc updates, new animated example of nested (delayed) macro

• Invented some terminology: 'Standard' and 'delayed' form of macros
• Macros & FormattedSearch updates
• More fixes for CompleteDocumentation
• Removed &vbar; which isn't a real HTML entity, from VarENCODE

Location:

branches/Release01x01/core/data/System

Files:

• FormattedSearch.txt (modified) (10 diffs)
• Macros.txt (modified) (12 diffs)
• VarENCODE.txt (modified) (1 diff)

branches/Release01x01/core/data/System/FormattedSearch.txt

@@ -41 +41 @@
 | =$nhits= | Number of hits if =multiple="on"=. Cumulative across all topics in current web. Identical to =$ntopics= unless =multiple="on"= |
 | =$pager= | pager control - can be optionally customised using the =pagerformat= below |
-%INCLUDE{FormatTokens}%
+%INCLUDE{"FormatTokens"}%
 
 <blockquote class="foswikiHelp">%X% Note that if the separator parameter for SEARCH is not defined a newline is added after the last search result.</blockquote>
@@ -64 +64 @@
 | =$previousbutton= | skin template (SEARCH:pager_previous) html for the full URL to the previous page - _IF_ using the built in pager system |
 | =$nextbutton= | skin template (SEARCH:pager_next) html for the full URL to the previous page - _IF_ using the built in pager system |
-%INCLUDE{FormatTokens}%
+%INCLUDE{"FormatTokens"}%
 
 ---+++ 4. =format="..."= parameter
@@ -113 +113 @@
 | =$nhits= | Number of hits if =multiple="on"=. Cumulative across all topics in current web. Identical to =$ntopics= unless =multiple="on"= |
 | =$pager= | pager control - can be optionally customised using the =pagerformat= below |
-%INCLUDE{FormatTokens}%
+%INCLUDE{"FormatTokens"}%
 
 ---++ Examples
@@ -187 +187 @@
 #NestedSearch
 ---+++ Nested Search
-
-[[VarSEARCH][SEARCH]], as with many TML macros, may be nested. For example: search for some topics in an initial (outer) search, and for each of them apply a second (inner) search. The idea is to use the outer search to build a series of inner seraches.
-
-%INCLUDE{"Macros" section="insideoutlefttoright" THETOPIC="%SYSTEMWEB%.FAQWhatIsWikiWiki" THEFIELD="TopicClassification"}%
+[[VarSEARCH][SEARCH]] is one of many [[Macros][macros]] that produce output which may be controlled with =format=, =header= and =footer= parameters, among others. To make use of _additional_ macros in the output, familiarity with [[#InsideOutLeftToRight][inside-out, left-to-right]] order of expansion rules is required. There are two forms:
+   1 Standard: Use =%<nop>INNERMACRO%= to build the parameter string *before* =%<nop>OUTERMACRO%= is expanded
+   <verbatim class="tml"> %OUTERMACRO{
+   format="%INNERMACRO%"
+ }%</verbatim>
+   1 Delayed: Use the parameter string to incorporate =%<nop>INNERMACRO%= into the output of =%<nop>OUTERMACRO%=
+   <verbatim class="tml"> %OUTERMACRO{
+   format="$percentINNERMACRO$percent"
+ }%</verbatim>
+ <blockquote class="foswikiHelp">%T% When working with a given [[Macros][macro]], consult its documentation to determine which paramters support the =$percent/$percnt= [[FormatTokens][format tokens]]</blockquote>
+
+%INCLUDE{"Macros"
+  section="insideoutlefttoright"
+  THETOPIC="%SYSTEMWEB%.FAQWhatIsWikiWiki"
+  THEFIELD="TopicClassification"
+  PARENT="UserDocumentationCategory"
+}%
+
+---++++ Worked example
+*Problem:* search for some topics in an initial (outer) search, and for each of them apply a second (inner) search. The idea is to use the outer search to build a series of inner seraches.
 
 #NestedSearchExample
@@ -216 +232 @@
 Now let's nest the two.
 #NestingWithEscapes
----++++ Method 1 (nesting with escapes)
+---+++++ Method 1 (nesting with escapes)
 The inner search cannot be placed directly into the format string of the outer, because of the "inside-out, left-to-right" macro expansion behaviour [[#InsideOutLeftToRight][discussed earlier]]. It must be delayed so that the outer search is evaluated first. To do this, we need to escape the inner search, i.e. let the outer search build a series of searches comprised of the inner search.
    * Use =$percent= to escape (delay) the inner search's [[VarSEARCH][SEARCH]] macro
@@ -254 +270 @@
 }%
 
+<blockquote class="foswikiHelp">
+%X% When nesting with escapes, each new nesting level must "escape the escapes", e.g. write =$dollarpercentSEARCH{= for level three, =$dollardollarpercentSEARCH{= for level four, etc.
+</blockquote>
+
 #NestedSectionalInclude
----++++ Method 2 (nesting with sectional includes)
-Nested expressions can be difficult to write correctly, and are difficult to troubleshoot when they go wrong.
-
-The recommended approach is to make use of the [[VarSTARTSECTION][STARTSECTION]]/[[VarENDSECTION][ENDSECTION]] feature of the [[VarINCLUDE][INCLUDE]] macro. Instead of nesting the inner search expression directly inside the format string of the outer, the inner search is written as a separate stand-alone section of a topic which is INCLUDEd into the format string of the outer.
+---+++++ Method 2 (nesting with sectional includes)
+Nested expressions with delayed macros can be difficult to write: care must be taken to escape all the quotes of the inner delayed macro, and it may become confusing whether to use =$topic=, =$dollartopic= or =$dollardollartopic=.
+
+If you find yourself using escaped tokens like =$dollartopic=, another approach is to use the [[VarSTARTSECTION][STARTSECTION]]/[[VarENDSECTION][ENDSECTION]] feature of [[VarINCLUDE][INCLUDE]]. Instead of nesting the inner search expression directly inside the format string of the outer, the inner search is written as a separate stand-alone section of a topic which is INCLUDEd into the format string of the outer.
 
 *Write this:*
@@ -288 +308 @@
 <blockquote class="foswikiHelp">%H% Output will be the same as for the first method
 
-%X% Nested search can be slow, especially if you nest more than 3 levels deep. Nesting is limited to 16 levels.
-
-When nesting with escapes, each new nesting level must "escape the escapes", e.g. write =$dollarpercentSEARCH{= for level three, =$dollardollarpercentSEARCH{= for level four, etc.
-
-Therefore the sectional include method is strongly recommended to avoid this kind of difficult syntax.</blockquote>
+%X% Nested search can be slow, especially if you nest more than 3 levels deep. Nesting is limited to 16 levels.</blockquote>
 
 ---+++ Most recently changed pages
@@ -319 +335 @@
 }%
 
+#ConditionalOutputExample
 ---+++ Search with conditional output
 
@@ -341 +358 @@
 <blockquote class="foswikiHelp">
 %ICON{"info"}% *Details:*
-   * The SEARCH has a deferred [[VarICON][ICON]]. The =$percent= ensures that ICON is evaluated once for each search hit
-   * The [[VarICON][ICON]] contains an [[VarIF][IF]], which again is deferred with the =$percent= token and will also be evaluated for each SEARCH hit. Additionally, the "inside-out, left-to-right" rule discussed earlier means that this IF expression will be evaluated before [[VarICON][ICON]].
+   * The SEARCH has a delayed [[VarICON][ICON]]. The =$percent= ensures that ICON is evaluated once for each search hit
+   * The [[VarICON][ICON]] contains an [[VarIF][IF]], which again is delayed with the =$percent= token and will also be evaluated for each SEARCH hit. Additionally, the [[#InsideOutLeftToRight][inside-out, left-to-right]] rule discussed earlier means that this IF expression will be evaluated before [[VarICON][ICON]].
    * If =$topic= is a child of UserDocumentationCategory, the =info= icon is used; otherwise, =gear=.
 </blockquote>
@@ -366 +383 @@
 <verbatim class="tml">
 <form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
-Find Topics: 
+Find Topics:
 <input type="text" name="q" size="32"\
   value="%URLPARAM{"q" encode="entity"}%" />&nbsp;<input\

branches/Release01x01/core/data/System/Macros.txt

@@ -23 +23 @@
 To use a macro type its name. For example,
    * type =%<nop>T%= to get %T% (a [[%SYSTEMWEB%.PreferenceSettings][preference settings]])
-   * type =%<nop>TOPIC%= to get =%TOPIC%= (a predefined [[macro]])
-   * type =%<nop>CALC{ "$UPPER(Text)" }%= to get =TEXT= ([[VarCALC][CALC]] is a macro defined by SpreadSheetPlugin)
+   * type =%<nop>TOPIC%= to get =%TOPIC%= (a predefined [[VarTOPIC][macro]])
+   * type =%<nop>CALC{ "$UPPER(Text)" }%= to get =TEXT= ([[VarCALC][CALC]] is a macro defined by [[SpreadSheetPlugin]])
 
 *Note:*
@@ -34 +34 @@
 ---+++ Order of expansion
 The following describes only these types of macros:
-   * Most built-in Foswiki macros. The following are notable exceptions: [[VarCALC][CALC]], [[VarSTARTSECTION][STARTSECTION]]/ENDSECTION, [[VarSTARTINCLUDE][STARTINCLUDE]]/STOPINCLUDE
-   * Preference variables
-   * Macros registered by most plugins, using the so-called [[PerlDoc?module=Foswiki::Func#registerTagHandler][registerTagHandler()]]
-
-But *not* plugins which rely on [[PerlDoc?module=Foswiki::Func#commonTagsHandler][commonTagsHandler()]]
+   * [[PreferenceSettings][Preference settings]]
+   * Most macros provided by plugins (those that use [[PerlDoc?module=Foswiki::Func#registerTagHandler][registerTagHandler()]])
+   <blockquote class="foswikiHelp">%X% *Not* those that use [[PerlDoc?module=Foswiki::Func#commonTagsHandler][commonTagsHandler()]]</blockquote>
+   * Most built-in Foswiki macros
+   <blockquote class="foswikiHelp">%X% Notable exceptions include: [[VarCALC][CALC]], [[VarSTARTSECTION][STARTSECTION]]/ENDSECTION, [[VarSTARTINCLUDE][STARTINCLUDE]]/STOPINCLUDE</blockquote>
 
 %STARTSECTION{"insideoutlefttoright"}%
+#StandardForm
+---++++ Standard form
 #InsideOutLeftToRight
-The key to understanding nested expressions in Foswiki is to understand that macros are expanded "inside-out, left-to-right". For example:
+The key to understanding nested expressions in Foswiki is to understand that macros are expanded "inside-out, left-to-right". *Example:*
+
 <verbatim class="tml">
 %MACRO1{
@@ -50 +53 @@
 }%
 </verbatim>
-
 The macros are expanded in this order: MACRO3, MACRO4, MACRO2, MACRO1.
 
----++++ Animated Example
+#AnimatedExample
+---+++++ Animated Example
 %JQREQUIRE{"CYCLE,EASING,CHILI"}%<!-- ids are appended with %INCLUDINGTOPIC%
 to avoid duplicates in System.CompleteDocumentation -->%ADDTOZONE{"script"
@@ -72 +75 @@
   requires="JQUERYPLUGIN::CYCLE"
 }%%ADDTOZONE{"head"
-  id="NestedSlideshow/css"
+  id="NestedSlideshow%INCLUDINGTOPIC%/css"
   text="<style type='text/css'>
-    #NestedSlideshow%INCLUDINGTOPIC% { width: 440px; height: 249px; }
-    #NestedSlideshowNav%INCLUDINGTOPIC%  { z-index: 50; position: absolute; bottom: 10px; }
     #NestedSlideshowNav%INCLUDINGTOPIC%  a { margin: 0 10px 0 0; padding: 3px 5px; border: 1px solid #ddd; background: #fff; text-decoration: none }
     #NestedSlideshowNav%INCLUDINGTOPIC%  a.activeSlide,
@@ -81 +82 @@
     #NestedSlideshowNav%INCLUDINGTOPIC%  a:focus { outline: none; }
   </style>"
-}%<div id="NestedSlideshow%INCLUDINGTOPIC%">
-    <div id="NestedSlideshowNav%INCLUDINGTOPIC%"></div>
+}%<div id="NestedSlideshowNav%INCLUDINGTOPIC%"></div>
+<div id="NestedSlideshow%INCLUDINGTOPIC%">
 <pre class="tml">
 %<nop>INCLUDE{
@@ -106 +107 @@
 %<nop>INCLUDE{
     "%<nop>QUERY{
-        "'%<nop>SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
+        "'%<nop>SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
     }%"
     section="Summary"
@@ -116 +117 @@
 %<nop>INCLUDE{
     "%<nop>QUERY{
-        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
+        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
     }%"
     section="Summary"
@@ -126 +127 @@
 %<nop>INCLUDE{
     "%QUERY{
-        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
+        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
     }%"
     section="Summary"
@@ -136 +137 @@
 %INCLUDE{
     "%QUERY{
-        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
+        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
     }%"
     section="Summary"
@@ -146 +147 @@
 %INCLUDE{
     "%QUERY{
-        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
+        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
     }%"
     section="Summary"
@@ -152 +153 @@
    * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
    * Set THEFIELD = TopicClassification
+</pre>
+</div>
+
+#DelayedForm
+---++++ Delayed form
+[[#StandardForm][Standard form]] macros can nearly always be used to build the parameter string of another macro; however, sometimes it is desirable to bypass the [[#InsideOutLeftToRight][inside-out]] expansion order and delay the inner macro until after the outer macro has finished expansion. This is accomplished by using the [[FormatTokens][$percent]] format token instead of =%=, and escaping any ="= character it uses (becomes =\"=)
+
+<blockquote class="foswikiHelp">%T% When working with a given [[Macros][macro]], consult its documentation to determine which paramters support the =$percent/$percnt= [[FormatTokens][format tokens]]. Generally only _output parameters_ like =header=, =format= and =footer= support [[FormatTokens][format tokens]].</blockquote>
+*Example:*
+<verbatim class="tml">
+%MACRO1{
+   format="$percentMACRO2{
+      format=\"%MACRO3%, %MACRO4%\"
+   }$percent"
+}%
+</verbatim>
+The macros are expanded in this order: MACRO3, MACRO4, MACRO1, *MACRO2*.
+#AnimatedDelayedExample
+---+++++ Animated Example
+From the [[FormattedSearch#ConditionalOutputExample][conditional output example]]:
+
+%JQREQUIRE{"CYCLE,EASING,CHILI"}%<!-- ids are appended with %INCLUDINGTOPIC%
+to avoid duplicates in System.CompleteDocumentation -->%ADDTOZONE{"script"
+  id="DelayedSlideshow%INCLUDINGTOPIC%"
+  text="<script type='text/javascript'>
+jQuery(document).ready(function($) {
+    $('#DelayedSlideshow%INCLUDINGTOPIC%').cycle({
+        fx:     'fade',
+        speed:  'slow',
+        timeout: 5000,
+        pager:  '#DelayedSlideshowNav%INCLUDINGTOPIC%',
+        slideExpr: 'pre',
+        pause:  true,
+        pauseOnPagerHover: true
+    });
+});
+</script>"
+  requires="JQUERYPLUGIN::CYCLE"
+}%%ADDTOZONE{"head"
+  id="DelayedSlideshow%INCLUDINGTOPIC%/css"
+  text="<style type='text/css'>
+    #DelayedSlideshowNav%INCLUDINGTOPIC%  a { margin: 0 10px 0 0; padding: 3px 5px; border: 1px solid #ddd; background: #fff; text-decoration: none }
+    #DelayedSlideshowNav%INCLUDINGTOPIC%  a.activeSlide,
+    #DelayedSlideshowNav%INCLUDINGTOPIC%  a:hover { background: #cff }
+    #DelayedSlideshowNav%INCLUDINGTOPIC%  a:focus { outline: none; }
+  </style>"
+}%<div id="DelayedSlideshowNav%INCLUDINGTOPIC%"></div>
+<div id="DelayedSlideshow%INCLUDINGTOPIC%">
+<verbatim class="tml">
+%SEARCH{
+  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
+  type="query"
+  limit="2"
+  nonoise="on"
+  format="   * $percentICON{
+    \"$percentIF{
+      \"'$topic'/parent.name='%PARENT%'\"
+      then=\"info\" else=\"gear\"
+    }$percent\"
+  }$percent [[$topic]]"
+}%
+----
+   * Set PARENT = UserDocumentationCategory
+</verbatim>
+<pre class="tml">
+%<nop>SEARCH{
+  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
+  type="query"
+  limit="2"
+  nonoise="on"
+  format="   * $percentICON{
+    \"$percentIF{
+      \"'$topic'/parent.name='UserDocumentationCategory'\"
+      then=\"info\" else=\"gear\"
+    }$percent\"
+  }$percent [[$topic]]"
+}%
+----
+   * Set PARENT = UserDocumentationCategory
+</pre>
+<pre class="tml">
+%SEARCH{
+  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
+  type="query"
+  limit="2"
+  nonoise="on"
+  format="   * $percent<nop>ICON{
+    \"$percent<nop>IF{
+      \"'$topic'/parent.name='UserDocumentationCategory'\"
+      then=\"info\" else=\"gear\"
+    }$percent\"
+  }$percent [[$topic]]"
+}%
+----
+   * Set PARENT = UserDocumentationCategory
+</pre>
+<pre class="tml">
+%SEARCH{
+  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
+  type="query"
+  limit="2"
+  nonoise="on"
+  format="   * $percent<nop>ICON{
+    \"$percentIF{
+      \"'$topic'/parent.name='UserDocumentationCategory'\"
+      then=\"info\" else=\"gear\"
+    }$percent\"
+  }$percent [[$topic]]"
+}%
+----
+   * Set PARENT = UserDocumentationCategory
+</pre>
+<pre class="tml">
+%SEARCH{
+  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
+  type="query"
+  limit="2"
+  nonoise="on"
+  format="   * &lt;img src=\"$percentICONURL{
+    \"$percentIF{
+      \"'$topic'/parent.name='UserDocumentationCategory'\"
+      then=\"info\" else=\"gear\"
+    }$percent\"
+  }$percent\"/&gt; [[$topic]]"
+}%
+----
+   * Set PARENT = UserDocumentationCategory
 </pre>
 </div>
@@ -217 +345 @@
 *Related Topics:* UserDocumentationCategory
 <!-- %JQREQUIRE{"chili"}% -->
-
-%META:FILEATTACHMENT{name="nested_macros.gif" attr="h" version="1.1"}%

branches/Release01x01/core/data/System/VarENCODE.txt

@@ -25 +25 @@
    %<nop>ENCODE{"spaced name"}%= expands to
       %ENCODE{"spaced name"}%
-   %<nop>ENCODE{"| Blah | | More blah |" old="|,$n" new="&vbar;,&lt;br /&gt;"}% expands to
-      %ENCODE{"| Blah | | More blah |" old="|,$n" new="&vbar;,<br />"}%
+   %<nop>ENCODE{"| Blah | | More blah |" old="|,$n" new="&amp;#124;,&lt;br /&gt;"}% expands to
+      %ENCODE{"| Blah | | More blah |" old="|,$n" new="&#124;,<br />"}%
       - this encoding is useful to protect special TML characters in tables.
    %<nop>ENCODE{"10xx1x01x" old="1,x,0" new="A,,B"}% expands to