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></li>
  12       </ul>
  13     </li>
  14     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  15         <li><a href="#Pattern 2: List generated from f"> Pattern 2: List generated from form classification</a></li>
  16         <li><a href="#Pattern 3: Creating lists of TWi"> Pattern 3: Creating lists of TWiki usernames</a></li>
  17       </ul>
  18     </li>
  19     <li><a href="#TWiki Installation Error">TWiki Installation Error</a></li>
  20     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  21         <li><a href="#Pattern 4: Extract the parent of"> Pattern 4: Extract the parent of a given topic</a></li>
  22       </ul>
  23     </li>
  24     <li><a href="#TWiki Installation Error">TWiki Installation Error</a></li>
  25     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  26         <li><a href="#Pattern 5: Show all Children of"> Pattern 5: Show all Children of a given topic</a></li>
  27         <li><a href="#Pattern 6: Search and display th"> Pattern 6: Search and display the home topics of public webs in a list</a></li>
  28       </ul>
  29     </li>
  30     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  31         <li><a href="#Pattern 7: Create a select box w"> Pattern 7: Create a select box with values from a bullet list</a></li>
  32         <li><a href="#Pattern 8: Extract a value from"> Pattern 8: Extract a value from a named bullet list item</a></li>
  33       </ul>
  34     </li>
  35     <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
  36         <li><a href="#Pattern 9: Search for Form and M"> Pattern 9: Search for Form and Meta data: explained</a></li>
  37         <li><a href="#Pattern 10: Search all topics th"> Pattern 10: Search all topics that have been moved</a></li>
  38       </ul>
  39     </li>
  40   </ul>
  41 </div>
  42
  43 <a name="SearchTables"></a>
  44
  45 ## <a name="Pattern 1: Extract values from a"></a> Pattern 1: Extract values from a table
  46
  47 ### <a name="Problem definition"></a> Problem definition
  48
  49 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:
  50
  51     | *Name* | *Type* | *Tooltip message* |
  52     | option1 | option | |
  53     | option2 | option | |
  54     | option3 | option | |
  55
  56 How to extract the 'name' values, i.e. 'option1', 'option2' and 'option3' and put them in a HTML form select input?
  57
  58 ### <a name="Solution"></a> Solution
  59
  60 The following search pattern can be employed:
  61
  62     <form>
  63     <select>
  64     %SEARCH{ "^\|[^\|]*\| *option *\|" topic="%TOPIC%" type="regex" multiple="on" nosearch="on" nototal="on" format="<option>$pattern(^\| *(.*?) *\|.*)</option>" }%
  65     </select>
  66     </form>
  67
  68 which is, in effect:
  69
  70 <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>
  71
  72 <a name="SearchFormClassification"></a>
  73
  74 ## <a name="Pattern 2: List generated from f"></a> Pattern 2: List generated from form classification
  75
  76 ### <a name="Problem"></a> Problem
  77
  78 Imagine a TWiki form-based topic classification, i.e. every page has a form with several fields. How to:
  79
  80 1. create a search to display all topics where one form field is set to a certain value
  81 2. create a search to filter the list above based on the values of a second form field
  82
  83 ### <a name="Test case"></a> Test case
  84
  85 In practice: %BR% Image a TWiki form with two fields:
  86
  87 - TopicClassification = One, Two or Three
  88 - TopicStatus = Test or Final
  89
  90 We will:
  91
  92 1. List all topics where the TopicClassification field is set to 'Two'
  93 2. Enable the user to filter this list based on the values of TopicStatus
  94
  95 ### <a name="Solution"></a> Solution
  96
  97     %SEARCH{"[T]opicClassification.*value\=.*Two;[T]opicStatus.*value\=.*%URLPARAM{type}%"
  98     type="regex" casesensitive="on" nosearch="on"
  99     format="   * $topic - <font face=\"arial,helvetica\" size=\"1\">
 100     _last modified by_ $wikiusername _on_ $date </font> %BR% &nbsp;&nbsp;&nbsp;
 101     <font face=\"arial,helvetica\" size=\"1\"> $formfield(TopicStatus) </font>"
 102     sort="topic"}%
 103
 104 The filtering select dialogue is created as in Pattern 1:
 105
 106     %STARTSIDEBAR%
 107     *Filter:* %BR%
 108     <form name="selectType" action="%SCRIPTURLPATH{"view"}%/%WEB%/" >
 109     <select name="type" size="1" onchange="document.location=this.value;">
 110     %SEARCH{ "^\|[^\|]*\| *option *\|" topic="TopicClassification" web="%WEB%" type="regex"
 111     multiple="on" nosearch="on" nototal="on" format="<option value=%INCLUDINGTOPIC%?type=$pattern(^\| *(.*?) *\|.*)>$pattern(^\| *(.*?) *\|.*)</option>" }%
 112     <option value=%INCLUDINGTOPIC%>All pages</option> </select>
 113     </form>
 114     %STOPSIDEBAR%
 115
 116 This will create similar functionality as TWiki:Plugins.TopicClassificationAddOn
 117
 118 <a name="SearchUsernames"></a>
 119
 120 ## <a name="Pattern 3: Creating lists of TWi"></a> Pattern 3: Creating lists of TWiki usernames
 121
 122 ### <a name="Problem"></a> Problem
 123
 124 How to populate a list box with all usernames of registered TWiki users
 125
 126 ### <a name="Solution 1: Appropriate for Sep"></a><a name="Solution 1: Appropriate for Sep "></a> Solution 1: Appropriate for Sep 2004 TWiki (Cairo)
 127
 128     <form name="testing" action="%SCRIPTURLPATH{"view"}%/%MAINWEB%" method="get">
 129     <select name="topic">
 130     <option>Select user...</option>
 131     %SEARCH{ "Name:;Email:;Country:" web="%MAINWEB%" type="regex" nosearch="on" nototal="on" format="<option>$topic</option>" }%
 132     </select>
 133     <input type="submit" value="Go" />
 134     </form>
 135
 136 Which expands to this: (here limited to all Z\* users because TWiki.org has so many)
 137
 138 <form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select name="topic"><option>Select user...</option>
 139     <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>
 140
 141 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.
 142
 143 ### <a name="Solution 2: As Solution 1, but w"></a> Solution 2: As Solution 1, but with possibility for multi-selecting usernames
 144
 145 The example of Solution 1 produces the list box. Add a MULTIPLE to the _select_ statement, i.e.:
 146
 147     <select name="topic" size="2" MULTIPLE>
 148
 149 Please note that the Search pattern is unchanged compared to Solution 1. The change is in the HTML form element.
 150
 151 The abovementioned modification is, in effect:
 152
 153 <form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select multiple="MULTIPLE" name="topic" size="2"><option>Select user...</option>
 154     <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>
 155
 156 ### <a name="Solution 3: Appropriate for TWik"></a> Solution 3: Appropriate for TWiki 4 (Dakar)
 157
 158 When the User information is stored in a [[UserForm]] (as is default in Dakar) then this list can be generated as follows:
 159
 160     <form name="testing" action="%SCRIPTURLPATH{"view"}%/%MAINWEB%" method="get">
 161     <select name="topic">
 162     <option>Select user...</option>
 163     %SEARCH{"%META:FORM.*[U]serForm" web="%MAINWEB%" type="regex" casesensitive="on" nosearch="on" format="<option>$topic</option>" sort="topic" excludetopic="Test*, TWiki*"}%
 164     </select>
 165     <input type="submit" value="Go" />
 166     </form>
 167
 168 In the above example:
 169
 170 - <code>**META:FORM.\*[U]serForm**</code> will search for all topics with a [[UserForm]] attached - change this if you have a different form where userdata is stored. Please note that this search does not actually extract anything from the form - it just uses it to identify the appropriate pages
 171 - <code>**excludetopic="Test\*, TWiki\*"**</code> allows to skip all topics starting with Test and TWiki, such as TestUser or TWikiAdmin. Use this if you have any special users who you do not want appearing in this list
 172
 173 <a name="SearchTopicParent"></a>
 174
 175 ## <a name="Pattern 4: Extract the parent of"></a> Pattern 4: Extract the parent of a given topic
 176
 177 ### <a name="Problem"></a> Problem
 178
 179 How to get to the parent of the current topic to display on the page?
 180
 181 ### <a name="Solution 1: Using META"></a> Solution 1: Using META
 182
 183 Since TWiki 4.0 you can now use the META variable:
 184
 185 `%META{ "parent" dontrecurse="on" }%`
 186
 187 ### <a name="Solution 2: Using _SpreadSheetPl"></a> Solution 2: Using SpreadSheetPlugin
 188
 189 You might think that the following Search would do the trick:
 190
 191     %SEARCH{ "^%BASETOPIC%$" scope="topic" nosearch="on" type="regex" nonoise="on" format="   * $parent" }%
 192
 193 However, the `$parent` link fails if the topic has no parent set (`$parent` will be empty). You can use some TWiki:Plugins/SpreadSheetPlugin magic to conditionally link to the parent or to `WebHome`:
 194
 195     $percntCALC{$IF($EXACT($parent,),<nop>,$NOP(   * $parent))}$percnt
 196
 197 So the total Search query to find a topic's parent topic is:
 198
 199     %SEARCH{ "^%BASETOPIC%$" scope="topic" type="regex" nonoise="on" format="$percntCALC{$IF($EXACT($parent,),<nop>,$NOP(   * $parent))}$percnt" }%
 200
 201 #### <a name="Test Case"></a> Test Case
 202
 203 The parent topic of this topic is:
 204
 205 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 206
 207 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 208
 209 ### <a name="Solution 3: Using IF statement"></a> Solution 3: Using IF statement
 210
 211 This pattern can be rewritten using `%IF%`, removing the dependency on SpreadSheetPlugin:
 212
 213     %SEARCH{ "^%BASETOPIC%$" web="%BASEWEB%" scope="topic" type="regex" nonoise="on" format="$percntIF{$quot$parent$quot then=$quot   * $parent$quot else=$quot<nop>$quot}$percnt" }%
 214
 215 #### <a name="Test Case"></a> Test Case
 216
 217 The parent topic of this topic is: %BR%
 218
 219 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 220
 221 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 222
 223 <a name="SearchTopicChildren"></a>
 224
 225 ## <a name="Pattern 5: Show all Children of"></a><a name="Pattern 5: Show all Children of "></a> Pattern 5: Show all Children of a given topic
 226
 227 ### <a name="Problem"></a> Problem
 228
 229 How to get to the list of all children of the current topic to display on the page?
 230
 231 ### <a name="Solution"></a> Solution
 232
 233 The parent information is stored in the META:TOPICPARENT meta data. Do a SEARCH to find all topic parent meta data pointing to the current topic:
 234
 235     Children:
 236     %SEARCH{ "META\:TOPICPARENT.*\"%TOPIC%\"" type="regex" nonoise="on" format="[[$topic]]" separator=", " }%
 237
 238 **_Note:_** Replace `%TOPIC%` with `%BASETOPIC%` if you put this SEARCH into the skin or a sidebar.
 239
 240 <a name="SearchPublicWebsList"></a>
 241
 242 ## <a name="Pattern 6: Search and display th"></a> Pattern 6: Search and display the home topics of public webs in a list
 243
 244 ### <a name="Problem"></a> Problem
 245
 246 How to find and display public webs in a drop down list box.
 247
 248 ### <a name="Solution"></a> Solution
 249
 250 _Thanks to TWiki:Main.PeterThoeny for these solutions._
 251
 252     <form>
 253     <select name="topic">
 254     <option value="%TOPIC%">Select...</option>
 255     %SEARCH{ "%HOMETOPIC%" scope="topic" web="all" topic="%HOMETOPIC%" format="<option value=\"$web.$topic\">$web</option>" separator=" " }%
 256     </select>
 257     <input type="submit"  value="Go" />
 258     </form>
 259
 260 ### <a name="Test case"></a> Test case
 261
 262 Public webs of TWiki.
 263
 264 <form><select name="topic"><option value="%TOPIC%">Select...</option>
 265     <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>
 266
 267 %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.
 268
 269 ### <a name="Alternative solution"></a> Alternative solution
 270
 271 This result can also be accomplished with the %WEBLIST% variable.
 272
 273 <form><select name="topic"><option value="%TOPIC%">Select...</option>
 274     <p>
 275     </p></select> <input type="submit" value="Go" /></form>
 276
 277 <a name="SearchBulletList"></a>
 278
 279 ## <a name="Pattern 7: Create a select box w"></a> Pattern 7: Create a select box with values from a bullet list
 280
 281 ### <a name="Problem"></a> Problem
 282
 283 We have a topic with a bullet list with category names. In another topic we want to offer these values in a select box dropdown.
 284
 285 For example, CategoryList has:
 286
 287 - Clients
 288 - People
 289 - Rooms
 290 - Buildings
 291
 292 ### <a name="Solution"></a> Solution
 293
 294 The following search pattern can be employed:
 295
 296     <select name="type">
 297     <option>Select category...</option>
 298     %SEARCH{"   *\s*.*?" topic="CategoryList" type="regex" multiple="on" casesensitive="on" nosummary="on" nosearch="on" noheader="on" nototal="on" format="<option>$pattern(.*   \*\s*([^\n]*).*)</option>"}%
 299     </select>
 300
 301 To render the bullet list as a comma-separated list, use the `separator` parameter:
 302
 303     %SEARCH{"   *\s*.*?" topic="CategoryList" type="regex" multiple="on" casesensitive="on" nosummary="on" nosearch="on" noheader="on" nototal="on" separator="," format="$pattern(.*   \*\s*([^\n]*).*)"}%
 304
 305 <a name="SearchNamedBulletList"></a>
 306
 307 ## <a name="Pattern 8: Extract a value from"></a><a name="Pattern 8: Extract a value from "></a> Pattern 8: Extract a value from a named bullet list item
 308
 309 ### <a name="Problem"></a> Problem
 310
 311 Display the user name in the user's topic title
 312
 313 ### <a name="Solution"></a> Solution
 314
 315 Search for the `Name:` entry.
 316
 317     %SEARCH{"   * [N]ame: " topic="%TOPIC%" type="regex" casesensitive="on" nosummary="on" nosearch="on" noheader="on" nototal="on" format="---+!! $pattern(.*   \* Name: ([^\n]*).*)"}%
 318
 319 ### <a name="Test case"></a> Test case
 320
 321 To create a test case, we will put a name entry here:
 322
 323 - Name: John Doe
 324
 325 Search result:
 326
 327 # <a name="TWiki Installation Error"></a> TWiki Installation Error
 328
 329 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 330
 331 <a name="SearchMetaData"></a>
 332
 333 ## <a name="Pattern 9: Search for Form and M"></a> Pattern 9: Search for Form and Meta data: explained
 334
 335 ### <a name="Problem"></a> Problem
 336
 337 Below is an example of a search that searches form data. The questions are:
 338
 339 - why is this searching the metadata, shouldn't it just search the text?
 340 - what is the meaning of the `td..td` in the search expression?
 341
 342     %SEARCH{ "[S]tatus.*(td..td|value\=).*[W]aiting" casesensitive="on" type="regex"
 343     nosearch="on" nototal="on" format="| [[$topic]]<br /> ($date - $rev -
 344     [[%SCRIPTURLPATH{rdiff}%/$web/$topic][Diffs]]) |"}%
 345
 346 ### <a name="Solution"></a> Solution
 347
 348 %SEARCH depends on grep, and grep searches the whole file, including the meta data.
 349
 350 An example meta data form field is:
 351
 352     %META:FIELD{name="OperatingSystem" title="OperatingSystem" value="OsWin"}%
 353
 354 So a search for a form field could look like:
 355
 356     %SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" type="regex" ... }%
 357
 358 - Using square brackets is a trick to avoid a hit on the topic doing the search.
 359 - The `.*` indicate that there can be any number of any character between `OperatingSystem` and `value` in the (whole) file
 360
 361 Now the original file format of the category table (the predecessor of the TWiki forms) looks like this:
 362
 363     <td valign="top" align="right"> OperatingSystem:  </td><td>  OsWin </td>
 364
 365 The following search finds topics in the old and new format:
 366
 367     %SEARCH{ "[O]peratingSystem.*(td..td|value\=).*[O]sWin" type="regex" ... }%
 368
 369 The `td..td` matches `td<>td`; a simple search on `"[O]peratingSystem.*[O]sWin"` could find a hit in the topic text by coincidence.
 370
 371 A simple `%SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" ...}%` search is sufficient if you do not have topics in the old format.
 372
 373 <a name="MovedTopics"></a>
 374
 375 ## <a name="Pattern 10: Search all topics th"></a> Pattern 10: Search all topics that have been moved
 376
 377 ### <a name="Problem"></a> Problem
 378
 379 How would I go about listing all moved topics ?
 380
 381 ### <a name="Solution"></a> Solution
 382
 383 Search for the META:TOPICMOVED meta data. Type this:
 384
 385 `Moved topics: %SEARCH{ "%META\:TOPICMOVED" type="regex" format="$topic, " nosearch="on" noheader="on" nosummary="on" }%`
 386
 387 to get this (limited to 10 results):
 388
 389 Moved topics:
 390
 391 # TWiki Installation Error
 392
 393 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 394
 395 **_Related Topics:_** [[UserDocumentationCategory]], [[SearchHelp]], [[TWikiVariables#VarSEARCH]], [[FormattedSearch]], [[RegularExpression]]
 396
 397 -- **_Contributors:_** TWiki:Main.AntonAylward, TWiki:Main.ArthurClemens, TWiki:Main.JosMaccabiani, TWiki:Main.PeterThoeny, TWiki:Main.SueLocke