TWiki/SearchPatternCookbook.mdwn

   1 # <a name="Search Pattern Cookbook"></a><a name=" Search Pattern Cookbook"></a> Search Pattern Cookbook
   2
   3 The Search function in TWiki is very powerful. Especially searches using a [[RegularExpression]] play an important part of tapping TWiki's full potential. Unfortunately [[RegularExpressions]] can be incredibly obscure to the uninitiated.
   4
   5 Most people not familiar (enough) with Regular Expressions mostly cut and paste (and maybe tweak) from existing examples. This page intends to collect lots of examples together.
   6
   7 <div>
   8   <ul>
   9     <li>
  10       <ul>
  11         <li><a href="#Pattern 1: Extract values from a"> Pattern 1: Extract values from a table</a><ul>
  12             <li><a href="#Problem definition"> Problem definition</a></li>
  13             <li><a href="#Solution"> Solution</a></li>
  14           </ul>
  15         </li>
  16       </ul>
  17     </li>
  18     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  19         <li><a href="#Pattern 2: List generated from f"> Pattern 2: List generated from form classification</a><ul>
  20             <li><a href="#Problem"> Problem</a></li>
  21             <li><a href="#Test case"> Test case</a></li>
  22             <li><a href="#Solution"> Solution</a></li>
  23           </ul>
  24         </li>
  25         <li><a href="#Pattern 3a: listbox with all use"> Pattern 3a: listbox with all user names</a><ul>
  26             <li><a href="#Problem"> Problem</a></li>
  27             <li><a href="#Solution"> Solution</a></li>
  28           </ul>
  29         </li>
  30       </ul>
  31     </li>
  32     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  33         <li><a href="#Pattern 3b: listbox with all use"> Pattern 3b: listbox with all user names - select multiple names</a><ul>
  34             <li><a href="#Problem"> Problem</a></li>
  35             <li><a href="#Solution"> Solution</a></li>
  36             <li><a href="#Test case"> Test case</a></li>
  37           </ul>
  38         </li>
  39       </ul>
  40     </li>
  41     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  42         <li><a href="#Pattern 4: Extract the parent of"> Pattern 4: Extract the parent of a given topic</a><ul>
  43             <li><a href="#Problem"> Problem</a></li>
  44             <li><a href="#Solution"> Solution</a></li>
  45             <li><a href="#Test Case"> Test Case</a></li>
  46           </ul>
  47         </li>
  48         <li><a href="#Pattern 5: Search and display th"> Pattern 5: Search and display the home topics of public webs in a list</a><ul>
  49             <li><a href="#Problem"> Problem</a></li>
  50             <li><a href="#Solution"> Solution</a></li>
  51             <li><a href="#Test case"> Test case</a></li>
  52           </ul>
  53         </li>
  54       </ul>
  55     </li>
  56     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  57         <li>
  58           <ul>
  59             <li><a href="#Alternative solution"> Alternative solution</a></li>
  60           </ul>
  61         </li>
  62         <li><a href="#Pattern 6: Extract a value from"> Pattern 6: Extract a value from a bullet list</a><ul>
  63             <li><a href="#Problem"> Problem</a></li>
  64             <li><a href="#Solution"> Solution</a></li>
  65             <li><a href="#Test case"> Test case</a></li>
  66           </ul>
  67         </li>
  68       </ul>
  69     </li>
  70     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  71         <li><a href="#Pattern 7: Search for Form and M"> Pattern 7: Search for Form and Meta data: explained</a><ul>
  72             <li><a href="#Problem"> Problem</a></li>
  73             <li><a href="#Solution"> Solution</a></li>
  74           </ul>
  75         </li>
  76         <li><a href="#Pattern 8: Search all topics tha"> Pattern 8: Search all topics that have been moved</a><ul>
  77             <li><a href="#Problem"> Problem</a></li>
  78             <li><a href="#Solution"> Solution</a></li>
  79           </ul>
  80         </li>
  81         <li><a href="#Contributors"> Contributors</a></li>
  82       </ul>
  83     </li>
  84   </ul>
  85 </div>
  86
  87 ## <a name="Pattern 1: Extract values from a"></a> Pattern 1: Extract values from a table
  88
  89 ### <a name="Problem definition"></a> Problem definition
  90
  91 Suppose there is a topic with a table defining entries in a TWikiForm. I.e. they define select menu items in a form template. They are then formatted like:
  92
  93     | *Name* | *Type* | *Tooltip message* |
  94     | option1 | option | |
  95     | option2 | option | |
  96     | option3 | option | |
  97
  98 How to extract the 'name' values, i.e. 'option1', 'option2' and 'option3' and put them in a HTML form select input?
  99
 100 ### <a name="Solution"></a> Solution
 101
 102 The following search pattern can be employed:
 103
 104     <form>
 105     <select>
 106     %SEARCH{ "^\|[^\|]*\| *option *\|" topic="%TOPIC%" regex="on" multiple="on" nosearch="on" nototal="on" format="<option>$pattern(^\| *(.*?) *\|.*)</option>" }%
 107     </select>
 108     </form>
 109
 110 which is, in effect:
 111
 112 <form><select><h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select></form>
 113
 114 %BR%
 115
 116 ## <a name="Pattern 2: List generated from f"></a> Pattern 2: List generated from form classification
 117
 118 ### <a name="Problem"></a> Problem
 119
 120 Imagine a TWiki form-based topic classification, i.e. every page has a form with several fields. How to:
 121
 122 1. create a search to display all topics where one form field is set to a certain value
 123 2. create a search to filter the list above based on the values of a second form field
 124
 125 ### <a name="Test case"></a> Test case
 126
 127 In practice: %BR% Image a TWiki form with two fields:
 128
 129 - TopicClassification = One, Two or Three
 130 - TopicStatus = Test or Final
 131
 132 We will:
 133
 134 1. List all topics where the TopicClassification field is set to 'Two'
 135 2. Enable the user to filter this list based on the values of TopicStatus
 136
 137 ### <a name="Solution"></a> Solution
 138
 139     %SEARCH{"[T]opicClassification.*value\=.*Two;[T]opicStatus.*value\=.*%URLPARAM{type}%"
 140     regex="on" casesensitive="on" nosearch="on"
 141     format="   * $topic - <font face=\"arial,helvetica\" size=\"1\">
 142     _last modified by_ $wikiusername _on_ $date </font> %BR% &nbsp;&nbsp;&nbsp;
 143     <font face=\"arial,helvetica\" size=\"1\"> $formfield(TopicStatus) </font>"
 144     sort="topic"}%
 145
 146 The filtering select dialogue is created as in Pattern 1:
 147
 148     %STARTSIDEBAR%
 149     *Filter:* %BR%
 150     <form name="selectType" action="%SCRIPTURLPATH{"view"}%/%WEB%/" >
 151     <select name="type" size="1" onchange="document.location=this.value;">
 152     %SEARCH{ "^\|[^\|]*\| *option *\|" topic="TopicClassification" web="%WEB%" regex="on"
 153     multiple="on" nosearch="on" nototal="on" format="<option value=%INCLUDINGTOPIC%?type=$pattern(^\| *(.*?) *\|.*)>$pattern(^\| *(.*?) *\|.*)</option>" }%
 154     <option value=%INCLUDINGTOPIC%>All pages</option> </select>
 155     </form>
 156     %STOPSIDEBAR%
 157
 158 This will create similar functionality as TWiki:Plugins.TopicClassificationAddOn %BR%
 159
 160 ## <a name="Pattern 3a: listbox with all use"></a> Pattern 3a: listbox with all user names
 161
 162 ### <a name="Problem"></a> Problem
 163
 164 How to populate a list box with all usernames of registered TWiki users
 165
 166 ### <a name="Solution"></a> Solution
 167
 168     <form name="testing" action="%SCRIPTURLPATH{"view"}%/%MAINWEB%" method="get">
 169     <select name="topic">
 170     <option>Select user...</option>
 171     %SEARCH{ "Name:;Email:;Country:" web="%MAINWEB%" type="regex" nosearch="on" nototal="on" format="<option>$topic</option>" }%
 172     </select>
 173     <input type="submit" value="Go" />
 174     </form>
 175
 176 Which expands to this: (here limited to all Z\* users because TWiki.org has so many)
 177
 178 <form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select name="topic"><option>Select user...</option>
 179     <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select> <input type="submit" value="Go" /></form>
 180
 181 This searches all topics in the Main web that contain "Name", "Email" and "Country" bullets. Alternatively, do a [[FormattedSearch]] with `multiple="on"` on the [[Main.TWikiUsers|Main/TWikiUsers]] topic.
 182
 183 ## <a name="Pattern 3b: listbox with all use"></a> Pattern 3b: listbox with all user names - select multiple names
 184
 185 ### <a name="Problem"></a> Problem
 186
 187 Suppose you want to send mail from a form on topic page to a selected list of **_multiple_** [[TWikiUsers]]
 188
 189 ### <a name="Solution"></a> Solution
 190
 191 The example of Pattern 3a produces the list box. Add a MULTIPLE to the _select_ statement, i.e.:
 192
 193     <select name="topic" size="2" MULTIPLE>
 194
 195 Please note that the Search pattern is unchanged compared to Pattern 3a. The change is in the HTML form element.
 196
 197 ### <a name="Test case"></a> Test case
 198
 199 The Search pattern 3a with the abovementioned modification is, in effect:
 200
 201 <form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select multiple="MULTIPLE" name="topic" size="2"><option>Select user...</option>
 202     <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select> <input type="submit" value="Go" /></form>
 203
 204 ## <a name="Pattern 4: Extract the parent of"></a> Pattern 4: Extract the parent of a given topic
 205
 206 ### <a name="Problem"></a> Problem
 207
 208 How to get to the parent of the current topic to display on the page?
 209
 210 ### <a name="Solution"></a> Solution
 211
 212 You might think that the following Search would do the trick:
 213
 214     %SEARCH{ "^%BASETOPIC%$" scope="topic" nosearch="on" type="regex" nototal="on" format="[[$parent][parent_link]]" }%
 215
 216 However, the `[[$parent][parent_link]]` link fails if the topic has no parent set (`$parent` will be empty). You can use some [[SpreadSheetPlugin]] magic to conditionally link to the parent or to `WebHome`: `[[$percntCALC{$IF($EXACT($parent,), %HOMETOPIC%, $parent)}$percnt][parent_link]]`
 217
 218 So the total Search query to find a topic's parent topic is:
 219
 220     %SEARCH{ "^%BASETOPIC%$" scope="topic" nosearch="on" type="regex" nototal="on" format="[<nop>[$percntCALC{$IF($EXACT($parent,), <nop>%HOMETOPIC%, $parent)}$percnt][parent_link]]" }%
 221
 222 ### <a name="Test Case"></a> Test Case
 223
 224 The parent topic of this topic is:
 225
 226 # TWiki Installation Error
 227
 228 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 229
 230 ## <a name="Pattern 5: Search and display th"></a> Pattern 5: Search and display the home topics of public webs in a list
 231
 232 ### <a name="Problem"></a> Problem
 233
 234 How to find and display public webs in a drop down list box.
 235
 236 ### <a name="Solution"></a> Solution
 237
 238 _Thanks to TWiki:Main.PeterThoeny for these solutions._
 239
 240     <form>
 241     <select name="topic">
 242     <option value="%TOPIC%">Select...</option>
 243     %SEARCH{ "%HOMETOPIC%" scope="topic" web="all" topic="%HOMETOPIC%" format="<option value=\"$web.$topic\">$web</option>" separator=" " }%
 244     </select>
 245     <input type="submit"  value="Go" />
 246     </form>
 247
 248 ### <a name="Test case"></a> Test case
 249
 250 Public webs of TWiki.
 251
 252 <form><select name="topic"><option value="%TOPIC%">Select...</option>
 253     <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select> <input type="submit" value="Go" /></form>
 254
 255 %T% For private webs, or any other webs you wish to exclude from the display, use "on" for the `Exclude web from a web="all" search` setting in the relevant web's WebPreferences topic.
 256
 257 ### <a name="Alternative solution"></a> Alternative solution
 258
 259 This result can also be accomplished with the %WEBLIST% variable.
 260
 261 <form><select name="topic"><option value="%TOPIC%">Select...</option>
 262     <p>
 263     </p></select> <input type="submit" value="Go" /></form>
 264
 265 ## <a name="Pattern 6: Extract a value from"></a><a name="Pattern 6: Extract a value from "></a> Pattern 6: Extract a value from a bullet list
 266
 267 ### <a name="Problem"></a> Problem
 268
 269 Display the user name in the user's topic title
 270
 271 ### <a name="Solution"></a> Solution
 272
 273 Search for the `Name:` entry.
 274
 275     %SEARCH{"   * [N]ame: " topic="%TOPIC%" regex="on" casesensitive="on" nosummary="on" nosearch="on" noheader="on" nototal="on" format="---+!! $pattern(.*   \* Name: ([^\n]*).*)"}%
 276
 277 ### <a name="Test case"></a> Test case
 278
 279 To create a test case, we will put a name entry here:
 280
 281 - Name: John Doe
 282
 283 Search result:
 284
 285 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 286
 287 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 288
 289 ## <a name="Pattern 7: Search for Form and M"></a> Pattern 7: Search for Form and Meta data: explained
 290
 291 ### <a name="Problem"></a> Problem
 292
 293 Below is an example of a search that searches form data. The questions are:
 294
 295 - why is this searching the metadata, shouldn't it just search the text?
 296 - what is the meaning of the `td..td` in the search expression?
 297
 298     %SEARCH{ "[S]tatus.*(td..td|value\=).*[W]aiting" casesensitive="on" regex="on"
 299     nosearch="on" nototal="on" format="| [[$topic]]<br /> ($date - $rev -
 300     [[%SCRIPTURLPATH{rdiff}%/$web/$topic][Diffs]]) |"}%
 301
 302 ### <a name="Solution"></a> Solution
 303
 304 %SEARCH depends on grep, and grep searches the whole file, including the meta data.
 305
 306 An example meta data form field is:
 307
 308     %META:FIELD{name="OperatingSystem" title="OperatingSystem" value="OsWin"}%
 309
 310 So a search for a form field could look like:
 311
 312     %SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" regex="on" ... }%
 313
 314 - Using square brackets is a trick to avoid a hit on the topic doing the search.
 315 - The `.*` indicate that there can be any number of any character between `OperatingSystem` and `value` in the (whole) file
 316
 317 Now the original file format of the category table (the predecessor of the TWiki forms) looks like this:
 318
 319     <td valign="top" align="right"> OperatingSystem:  </td><td>  OsWin </td>
 320
 321 The following search finds topics in the old and new format:
 322
 323     %SEARCH{ "[O]peratingSystem.*(td..td|value\=).*[O]sWin" regex="on" ... }%
 324
 325 The `td..td` matches `td<>td`; a simple search on `"[O]peratingSystem.*[O]sWin"` could find a hit in the topic text by coincidence.
 326
 327 A simple `%SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" ...}%` search is sufficient if you do not have topics in the old format.
 328
 329 ## <a name="Pattern 8: Search all topics tha"></a> Pattern 8: Search all topics that have been moved
 330
 331 ### <a name="Problem"></a> Problem
 332
 333 How would I go about listing all moved topics ?
 334
 335 ### <a name="Solution"></a> Solution
 336
 337 Search for the META:TOPICMOVED meta data. Type this:
 338
 339 `Moved topics: %SEARCH{ "%META\:TOPICMOVED" regex="on" format="$topic, " nosearch="on" noheader="on" nosummary="on" }%`
 340
 341 to get this (limited to 10 results):
 342
 343 Moved topics:
 344
 345 # TWiki Installation Error
 346
 347 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 348
 349 ## <a name="Contributors"></a> Contributors
 350
 351 TWiki:Main.AntonAylward, TWiki:Main.ArthurClemens, TWiki:Main.JosMaccabiani, TWiki:Main.PeterThoeny, TWiki:Main.SueLocke
 352
 353 **_Related Topics:_** [[UserDocumentationCategory]]