TWiki/FormattedSearch.mdwn

   1 <div>
   2   <ul>
   3     <li><a href="#TWiki Formatted Search Results"> TWiki Formatted Search Results</a><ul>
   4         <li><a href="#Syntax"> Syntax</a></li>
   5         <li><a href="#Nested Search"> Nested Search</a></li>
   6         <li><a href="#Examples"> Examples</a><ul>
   7             <li><a href="#Bullet list showing topic name a"> Bullet list showing topic name and summary</a></li>
   8           </ul>
   9         </li>
  10       </ul>
  11     </li>
  12     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  13         <li>
  14           <ul>
  15             <li><a href="#Table showing form field values"> Table showing form field values of topics with a form</a></li>
  16             <li><a href="#Extract some text from a topic u"> Extract some text from a topic using regular expression</a></li>
  17           </ul>
  18         </li>
  19       </ul>
  20     </li>
  21     <li><a href="#TWiki Installation Error">TWiki Installation Error</a></li>
  22   </ul>
  23 </div>
  24
  25 # <a name="TWiki Formatted Search Results"></a> TWiki Formatted Search Results
  26
  27 _Inline search feature allows flexible formatting of search result_
  28
  29 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 |" }%`).
  30
  31 ## <a name="Syntax"></a> Syntax
  32
  33 Two parameters can be used to specify a customized search result:
  34
  35 1. `header="..."` parameter
  36
  37 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. <br /> Example: `header="| *Topic:* | *Summary:* |"`
  38
  39 2. `format="..."` parameter
  40
  41 Use the format parameter to specify the format of one search hit. <br /> Example: `format="| $topic | $summary |"`
  42
  43 Variables that can be used in the format string:
  44
  45 <table border="1" cellpadding="0" cellspacing="0">
  46   <tr>
  47     <th bgcolor="#99CCCC"><strong> Name: </strong></th>
  48     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
  49   </tr>
  50   <tr>
  51     <td><code>$web</code></td>
  52     <td> Name of the web </td>
  53   </tr>
  54   <tr>
  55     <td><code>$topic</code></td>
  56     <td> Topic name </td>
  57   </tr>
  58   <tr>
  59     <td><code>$topic(20)</code></td>
  60     <td> Topic name, "<tt>- </tt>" hyphenated each 20 characters </td>
  61   </tr>
  62   <tr>
  63     <td><code>$topic(30, -&lt;br /&gt;)</code></td>
  64     <td> Topic name, hyphenated each 30 characters with separator "<tt>-&lt;br /&gt;</tt>" </td>
  65   </tr>
  66   <tr>
  67     <td><code>$topic(40, ...)</code></td>
  68     <td> Topic name, shortended to 40 characters with "<tt>...</tt>" indication </td>
  69   </tr>
  70   <tr>
  71     <td><code>$text</code></td>
  72     <td> Formatted topic text </td>
  73   </tr>
  74   <tr>
  75     <td><code>$locked</code></td>
  76     <td> LOCKED flag (if any) </td>
  77   </tr>
  78   <tr>
  79     <td><code>$date</code></td>
  80     <td> Time stamp of last topic update, like <code>29 Jun 2010 - 15:35</code></td>
  81   </tr>
  82   <tr>
  83     <td><code>$isodate</code></td>
  84     <td> Time stamp of last topic update, like <code>2010-06-29T15:35Z</code></td>
  85   </tr>
  86   <tr>
  87     <td><code>$rev</code></td>
  88     <td> Number of last topic revision, like <code>1.4</code></td>
  89   </tr>
  90   <tr>
  91     <td><code>$wikiusername</code></td>
  92     <td> Wiki user name of last topic update, like <code>Main.JohnSmith</code></td>
  93   </tr>
  94   <tr>
  95     <td><code>$username</code></td>
  96     <td> User name of last topic update, like <code>JohnSmith</code></td>
  97   </tr>
  98   <tr>
  99     <td><code>$summary</code></td>
 100     <td> Topic summary </td>
 101   </tr>
 102   <tr>
 103     <td><code>$formfield(name)</code></td>
 104     <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>
 105   </tr>
 106   <tr>
 107     <td><code>$formfield(name, 10)</code></td>
 108     <td> Form field value, "<tt>- </tt>" hyphenated each 10 characters </td>
 109   </tr>
 110   <tr>
 111     <td><code>$formfield(name, 20, -&lt;br /&gt;)</code></td>
 112     <td> Form field value, hyphenated each 20 characters with separator "<tt>-&lt;br /&gt;</tt>" </td>
 113   </tr>
 114   <tr>
 115     <td><code>$formfield(name, 30, ...)</code></td>
 116     <td> Form field value, shortended to 30 characters with "<tt>...</tt>" indication </td>
 117   </tr>
 118   <tr>
 119     <td><code>$pattern(reg-exp)</code></td>
 120     <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>
 121   </tr>
 122   <tr>
 123     <td><code>$n</code> or <code>$n()</code></td>
 124     <td> New line </td>
 125   </tr>
 126   <tr>
 127     <td><code>$nop</code> or <code>$nop()</code></td>
 128     <td> Is a "no operation". This variable gets removed; useful for nested search </td>
 129   </tr>
 130   <tr>
 131     <td><code>$quot</code></td>
 132     <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
 133   </tr>
 134   <tr>
 135     <td><code>$percnt</code></td>
 136     <td> Percent sign (<code>%</code>) </td>
 137   </tr>
 138   <tr>
 139     <td><code>$dollar</code></td>
 140     <td> Dollar sign (<code>$</code>) </td>
 141   </tr>
 142 </table>
 143
 144 **_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.
 145
 146 ## <a name="Nested Search"></a> Nested Search
 147
 148 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.
 149
 150 Here is an example. We want to search for topics, do a nested search with each hit, and show the result as nested bullets. Parameters like `scope="text" regex="on" nosearch="on" nototal="on"` are omitted for simplicity.
 151
 152 - First search:
 153   - `%SEARCH{ "freedom" format="   * $topic" }%`
 154 - Second search. For each hit we want this search:
 155   - `%SEARCH{ "(topic of first search)" format="      * $topic" }%`
 156 - Now we nest the searches. We need to escape the second search, e.g. the first search will build a valid second search string:
 157   - `%SEARCH{ "freedom" format="   * $topic: $n$percntSEARCH{ \"$topic\" format=\"      * $dollartopic" }$nop%\" }%`
 158
 159 Note that we escape the second search so that it does not get evaluated by the first search:
 160
 161 - `$percnt` to escape the leading percent of the second search
 162 - `\"` to escape the qouble quotes
 163 - `$dollar` to escape the `$` of `$topic`
 164 - `$nop` to escape the `}%` sequence
 165
 166 ## <a name="Examples"></a> Examples
 167
 168 <a name="SearchBulletList"></a>
 169
 170 ### <a name="Bullet list showing topic name a"></a> Bullet list showing topic name and summary
 171
 172 Write this:
 173
 174 `%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header="   * *Topic: Summary:*" format="   * [[$topic]]: $summary" }%`
 175
 176 To get this:
 177
 178 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 179
 180 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 181
 182 ### <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
 183
 184 Write this in the Know web:
 185
 186 `| *Topic:* | *OperatingSystem:* | *OsVersion:* |`<br />`%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%`
 187
 188 To get this:
 189
 190 <table border="1" cellpadding="1" cellspacing="0">
 191   <tr>
 192     <th bgcolor="#99CCCC"><strong>Topic:</strong></th>
 193     <th bgcolor="#99CCCC"><strong>OperatingSystem:</strong></th>
 194     <th bgcolor="#99CCCC"><strong>OsVersion:</strong></th>
 195   </tr>
 196   <tr>
 197     <td><a href="http://www.dementia.org/twiki//view/Know/IncorrectDllVersionW32PTH10DLL">IncorrectDllVersionW32PTH10DLL</a></td>
 198     <td><a href="http://www.dementia.org/twiki//view/Know/OsWin">OsWin</a></td>
 199     <td> 95/98 </td>
 200   </tr>
 201   <tr>
 202     <td><a href="http://www.dementia.org/twiki//view/Know/WinDoze95Crash">WinDoze95Crash</a></td>
 203     <td><a href="http://www.dementia.org/twiki//view/Know/OsWin">OsWin</a></td>
 204     <td> 95 </td>
 205   </tr>
 206 </table>
 207
 208 ### <a name="Extract some text from a topic u"></a> Extract some text from a topic using regular expression
 209
 210 Write this:
 211
 212 `%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%`
 213
 214 To get this:
 215
 216 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 217
 218 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 219
 220 -- [[PeterThoeny]] - 16 May 2002