none
[openafs-wiki.git] / TWiki / FormattedSearch.mdwn
index f3da535..d9d9f6f 100644 (file)
         </li>
       </ul>
     </li>
+    <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
+        <li>
+          <ul>
+            <li><a href="#Most recently changed pages"> Most recently changed pages</a></li>
+          </ul>
+        </li>
+      </ul>
+    </li>
+    <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
+        <li>
+          <ul>
+            <li><a href="#Search with conditional output"> Search with conditional output</a></li>
+          </ul>
+        </li>
+      </ul>
+    </li>
+    <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
+        <li>
+          <ul>
+            <li><a href="#Embedding search forms to return"> Embedding search forms to return a formatted result</a></li>
+          </ul>
+        </li>
+      </ul>
+    </li>
     <li><a href="#TWiki Installation Error">TWiki Installation Error</a></li>
   </ul>
 </div>
@@ -76,7 +100,7 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$text</code></td>
-    <td> Formatted topic text </td>
+    <td> Formatted topic text. In case of a <code>multiple="on"</code> search, it is the line found for each search hit. </td>
   </tr>
   <tr>
     <td><code>$locked</code></td>
@@ -84,33 +108,53 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$date</code></td>
-    <td> Time stamp of last topic update, like <code>29 Jun 2010 - 15:42</code></td>
+    <td> Time stamp of last topic update, e.g. <code>29 Jun 2010 - 15:45</code></td>
   </tr>
   <tr>
     <td><code>$isodate</code></td>
-    <td> Time stamp of last topic update, like <code>2010-06-29T15:42Z</code></td>
+    <td> Time stamp of last topic update, e.g. <code>2010-06-29T15:45Z</code></td>
   </tr>
   <tr>
     <td><code>$rev</code></td>
-    <td> Number of last topic revision, like <code>1.4</code></td>
+    <td> Number of last topic revision, e.g. <code>1.4</code></td>
   </tr>
   <tr>
     <td><code>$username</code></td>
-    <td> Login name of last topic update, like <code>jsmith</code></td>
+    <td> Login name of last topic update, e.g. <code>jsmith</code></td>
   </tr>
   <tr>
     <td><code>$wikiname</code></td>
-    <td> Wiki user name of last topic update, like <code>JohnSmith</code></td>
+    <td> Wiki user name of last topic update, e.g. <code>JohnSmith</code></td>
   </tr>
   <tr>
     <td><code>$wikiusername</code></td>
     <td> Wiki user name of last topic update, like <code>Main.JohnSmith</code></td>
   </tr>
   <tr>
+    <td><code>$createdate</code></td>
+    <td> Time stamp of topic revision 1.1 </td>
+  </tr>
+  <tr>
+    <td><code>$createusername</code></td>
+    <td> Login name of topic revision 1.1, e.g. <code>jsmith</code></td>
+  </tr>
+  <tr>
+    <td><code>$createwikiname</code></td>
+    <td> Wiki user name of topic revision 1.1, e.g. <code>JohnSmith</code></td>
+  </tr>
+  <tr>
+    <td><code>$createwikiusername</code></td>
+    <td> Wiki user name of topic revision 1.1, e.g. <code>Main.JohnSmith</code></td>
+  </tr>
+  <tr>
     <td><code>$summary</code></td>
     <td> Topic summary </td>
   </tr>
   <tr>
+    <td><code>$formname</code></td>
+    <td> The name of the form attached to the topic; empty if none </td>
+  </tr>
+  <tr>
     <td><code>$formfield(name)</code></td>
     <td> The field value of a form field; for example, <code>$formfield(TopicClassification)</code> would get expanded to <code>PublicFAQ</code>. This applies only to topics that have a [[Main/TWikiForms]]</td>
   </tr>
@@ -128,7 +172,7 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$pattern(reg-exp)</code></td>
-    <td> A regular expression pattern to extract some text from a topic. For example, <code>$pattern(.*?\*.*?Email\:\s*([^\n\r]+).*)</code> extracts the email address from a bullet of format <code>* Email: ...</code>. </td>
+    <td> A regular expression pattern to extract some text from a topic (does not search meta data; use <code>$formfield</code> instead). In case of a <code>multiple="on"</code> search, the pattern is applied to the line found in each search hit. The pattern must cover the whole text (topic or line). For example, <code>$pattern(.*?\*.*?Email\:\s*([^\n\r]+).*)</code> extracts the email address from a bullet of format <code>* Email: ...</code>. This example has non-greedy <code>.*?</code> patterns to scan for the first occurance of the Email bullet; use greedy <code>.*</code> patterns to scan for the last occurance. </td>
   </tr>
   <tr>
     <td><code>$n</code> or <code>$n()</code></td>
@@ -217,7 +261,7 @@ Here is an example. Let's search for all topics that contain the word "culture"
 - First search:
   - `%SEARCH{ "culture" format="   * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%`
 - Second search. For each hit we want this search:
-  - `%SEARCH{ "(topic found in first search)" format="   $topic" nosearch="on" nototal="on" }%`
+  - `%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%`
 - Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:
   - Use `$percnt` to escape the leading percent of the second search
   - Use `\"` to escape the double quotes
@@ -226,7 +270,46 @@ Here is an example. Let's search for all topics that contain the word "culture"
 
 **Write this:**
 
-`%SEARCH{ "culture" format="   * $topic is referenced by:$n      * $percntSEARCH{ \"$topic\" format=\"   $dollartopic\" nosearch=\"on\" nototal=\"on\" }$nop%" nosearch="on" nototal="on" }%`
+`%SEARCH{ "culture" format="   * $topic is referenced by:$n      * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%`
+
+**To get this:**
+
+# <a name="TWiki Installation Error"></a> TWiki Installation Error
+
+Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
+
+### <a name="Most recently changed pages"></a> Most recently changed pages
+
+**Write this:**
+
+`%SEARCH{ "\.*" scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on"  format="| [[$topic]] | $wikiusername  | $date |" limit="7" }%`
+
+**To get this:**
+
+# <a name="TWiki Installation Error"></a> TWiki Installation Error
+
+Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
+
+### <a name="Search with conditional output"></a> Search with conditional output
+
+A regular expression search is flexible, but there are limitations. For example, you cannot show all topics that are up to exactly one week old, or create a report that shows all records with invalid form fields or fields within a certain range, etc. You need some additional logic to format output based on a condition:
+
+1. Specify a search which returns more hits then you need
+2. For each search hit apply a spreadsheet formula to determine if the hit is needed
+3. If needed, format and output the result
+4. Else supress the search hit
+
+This requires the TWiki:Plugins.SpreadSheetPlugin. The following example shows all topics that are up to exactly one week old.
+
+**Write this:**
+
+`%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%` %BR% `%SEARCH{ "." scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%`
+
+- The first line sets the `weekold` variable to the serialized date of exactly one week ago
+- The SEARCH has a deferred CALC. The `$percnt` makes sure that the CALC gets executed once for each search hit
+- The CALC compares the date of the topic with the `weekold` date
+- If topic is older, a `<nop>` is returned, which gets removed at the end of the TWiki rendering process
+- Otherwise, the search hit is formatted and returned
 
 **To get this:**
 
@@ -234,4 +317,28 @@ Here is an example. Let's search for all topics that contain the word "culture"
 
 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 
--- [[PeterThoeny]] - 16 May 2002
+### <a name="Embedding search forms to return"></a> Embedding search forms to return a formatted result
+
+Use an HTML form and an embedded formatted search on the same topic. You can link them together with an `%URLPARAM{"..."}%` variable. Example:
+
+**Write this:**
+
+    <form action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
+    Find Topics:
+    <input type="text" name="q" size="32" value="%URLPARAM{"q"}%" />
+    <input type="submit" value="Search" />
+    </form>
+    Result:
+    %SEARCH{ search="%URLPARAM{"q"}%" format="   * $web.$topic: %BR% $summary" nosearch="on" }%
+
+**To get this:**
+
+<form action="http://www.dementia.org/twiki//view/%WEB%/%TOPIC%"> Find Topics: <input name="q" size="32" type="text" value="" /> <input type="submit" value="Search" /></form>
+
+Result:
+
+# <a name="TWiki Installation Error"></a> TWiki Installation Error
+
+Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
+
+-- TWiki:Main.PeterThoeny - 16 Mar 2004