none
[openafs-wiki.git] / TWiki / FormattedSearch.mdwn
index 9812904..d9d9f6f 100644 (file)
@@ -1,7 +1,6 @@
 <div>
   <ul>
     <li><a href="#TWiki Formatted Search Results"> TWiki Formatted Search Results</a><ul>
-        <li><a href="#Overview"> Overview</a></li>
         <li><a href="#Syntax"> Syntax</a></li>
         <li><a href="#Examples"> Examples</a><ul>
             <li><a href="#Bullet list showing topic name a"> Bullet list showing topic name and summary</a></li>
         </li>
       </ul>
     </li>
+    <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
+        <li>
+          <ul>
+            <li><a href="#Nested Search"> Nested Search</a></li>
+          </ul>
+        </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>
 
 _Inline search feature allows flexible formatting of search result_
 
-## <a name="Overview"></a> Overview
-
-By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the `format="..."` parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. `%SEARCH{ "food" format="| $topic | $summary |" }%`).
+The `%SEARCH{...}%` variable documented in [[TWikiVariables]] has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the `format="..."` parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as `%SEARCH{ "food" format="| $topic | $summary |" }%`).
 
 ## <a name="Syntax"></a> Syntax
 
-Two paramters can be used to specify a customized search result:
+Two parameters can be used to specify a customized search result:
 
 1. `header="..."` parameter
 
-Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e. <br />`header="| *Topic:* | *Summary:* |"`
+Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. <br /> Example: `header="| *Topic:* | *Summary:* |"`
 
 2. `format="..."` parameter
 
-Use the format paramter to specify the format of one search hit. I.e. <br />`format="| $topic | $summary |"`
+Use the format parameter to specify the format of one search hit. <br /> Example: `format="| $topic | $summary |"`
 
 Variables that can be used in the format string:
 
@@ -50,10 +79,6 @@ Variables that can be used in the format string:
     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
   </tr>
   <tr>
-    <td><code>$n</code></td>
-    <td> New line </td>
-  </tr>
-  <tr>
     <td><code>$web</code></td>
     <td> Name of the web </td>
   </tr>
@@ -62,54 +87,128 @@ Variables that can be used in the format string:
     <td> Topic name </td>
   </tr>
   <tr>
+    <td><code>$topic(20)</code></td>
+    <td> Topic name, "<tt>- </tt>" hyphenated each 20 characters </td>
+  </tr>
+  <tr>
+    <td><code>$topic(30, -&lt;br /&gt;)</code></td>
+    <td> Topic name, hyphenated each 30 characters with separator "<tt>-&lt;br /&gt;</tt>" </td>
+  </tr>
+  <tr>
+    <td><code>$topic(40, ...)</code></td>
+    <td> Topic name, shortended to 40 characters with "<tt>...</tt>" indication </td>
+  </tr>
+  <tr>
+    <td><code>$text</code></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>
     <td> LOCKED flag (if any) </td>
   </tr>
   <tr>
     <td><code>$date</code></td>
-    <td> Time stamp of last topic update, i.e. <code>29 Jun 2010 - 15:31</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, i.e. <code>2010-06-29T15:31Z</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, i.e. <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, e.g. <code>jsmith</code></td>
+  </tr>
+  <tr>
+    <td><code>$wikiname</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, i.e. <code>Main.JohnSmith</code></td>
+    <td> Wiki user name of last topic update, like <code>Main.JohnSmith</code></td>
   </tr>
   <tr>
-    <td><code>$username</code></td>
-    <td> User name of last topic update, i.e. <code>JohnSmith</code></td>
+    <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, i.e. <code>$formfield(TopicClassification)</code> would get expanded to <code>PublicFAQ</code>. This applies only to topics that have a [[Main/TWikiForms]]</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>
+  <tr>
+    <td><code>$formfield(name, 10)</code></td>
+    <td> Form field value, "<tt>- </tt>" hyphenated each 10 characters </td>
+  </tr>
+  <tr>
+    <td><code>$formfield(name, 20, -&lt;br /&gt;)</code></td>
+    <td> Form field value, hyphenated each 20 characters with separator "<tt>-&lt;br /&gt;</tt>" </td>
+  </tr>
+  <tr>
+    <td><code>$formfield(name, 30, ...)</code></td>
+    <td> Form field value, shortended to 30 characters with "<tt>...</tt>" indication </td>
   </tr>
   <tr>
     <td><code>$pattern(reg-exp)</code></td>
-    <td> A regular expression pattern to extract some text from a topic, i.e. <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>
+    <td> New line </td>
+  </tr>
+  <tr>
+    <td><code>$nop</code> or <code>$nop()</code></td>
+    <td> Is a "no operation". This variable gets removed; useful for nested search </td>
+  </tr>
+  <tr>
+    <td><code>$quot</code></td>
+    <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
+  </tr>
+  <tr>
+    <td><code>$percnt</code></td>
+    <td> Percent sign (<code>%</code>) </td>
+  </tr>
+  <tr>
+    <td><code>$dollar</code></td>
+    <td> Dollar sign (<code>$</code>) </td>
   </tr>
 </table>
 
-**_Note:_** For `$pattern(reg-exp)`, specify a [[RegularExpression]] that scans from start to end and contains the text you want to keep in parenthesis, i.e. `$pattern(.*?(from here.*?to here).*)`. You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
+**_Note:_** For `$pattern(reg-exp)`, specify a [[RegularExpression]] that scans from start to end and contains the text you want to keep in parenthesis, like `$pattern(.*?(from here.*?to here).*)`. You need to make sure that the integrity of a web page is not compromised; for example, if you include a table make sure to include everything including the table end tag.
 
 ## <a name="Examples"></a> Examples
 
+<a name="SearchBulletList"></a>
+
 ### <a name="Bullet list showing topic name a"></a> Bullet list showing topic name and summary
 
-Write this:
+**Write this:**
 
 `%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header="   * *Topic: Summary:*" format="   * [[$topic]]: $summary" }%`
 
-To get this:
+**To get this:**
 
 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 
@@ -117,11 +216,11 @@ Incorrect format of searchformat template (missing sections? There should be 4 %
 
 ### <a name="Table showing form field values"></a><a name="Table showing form field values "></a> Table showing form field values of topics with a form
 
-Write this in the Know web:
+**Write this in the Know web:**
 
 `| *Topic:* | *OperatingSystem:* | *OsVersion:* |`<br />`%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%`
 
-To get this:
+**To get this:**
 
 <table border="1" cellpadding="1" cellspacing="0">
   <tr>
@@ -143,14 +242,103 @@ To get this:
 
 ### <a name="Extract some text from a topic u"></a> Extract some text from a topic using regular expression
 
-Write this:
+**Write this:**
 
 `%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%`
 
-To get this:
+**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="Nested Search"></a> Nested Search
+
+Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.
+
+Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).
+
+- 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" 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
+  - Use `$dollar` to escape the `$` of `$topic`
+  - Use `$nop` to escape the `}%` sequence
+
+**Write this:**
+
+`%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:**
+
+# <a name="TWiki Installation Error"></a> TWiki Installation Error
+
+Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
+
+### <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)
 
--- [[PeterThoeny]] - 28 Nov 2001 <br />
+-- TWiki:Main.PeterThoeny - 16 Mar 2004