1 # <a name="Search Pattern Cookbook"></a><a name=" Search Pattern Cookbook"></a> Search Pattern Cookbook
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.
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.
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>
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>
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>
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>
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>
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>
56 <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
59 <li><a href="#Alternative solution"> Alternative solution</a></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>
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>
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>
81 <li><a href="#Contributors"> Contributors</a></li>
87 ## <a name="Pattern 1: Extract values from a"></a> Pattern 1: Extract values from a table
89 ### <a name="Problem definition"></a> Problem definition
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:
93 | *Name* | *Type* | *Tooltip message* |
94 | option1 | option | |
95 | option2 | option | |
96 | option3 | option | |
98 How to extract the 'name' values, i.e. 'option1', 'option2' and 'option3' and put them in a HTML form select input?
100 ### <a name="Solution"></a> Solution
102 The following search pattern can be employed:
106 %SEARCH{ "^\|[^\|]*\| *option *\|" topic="%TOPIC%" regex="on" multiple="on" nosearch="on" nototal="on" format="<option>$pattern(^\| *(.*?) *\|.*)</option>" }%
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>
116 ## <a name="Pattern 2: List generated from f"></a> Pattern 2: List generated from form classification
118 ### <a name="Problem"></a> Problem
120 Imagine a TWiki form-based topic classification, i.e. every page has a form with several fields. How to:
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
125 ### <a name="Test case"></a> Test case
127 In practice: %BR% Image a TWiki form with two fields:
129 - TopicClassification = One, Two or Three
130 - TopicStatus = Test or Final
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
137 ### <a name="Solution"></a> Solution
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%
143 <font face=\"arial,helvetica\" size=\"1\"> $formfield(TopicStatus) </font>"
146 The filtering select dialogue is created as in Pattern 1:
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>
158 This will create similar functionality as TWiki:Plugins.TopicClassificationAddOn %BR%
160 ## <a name="Pattern 3a: listbox with all use"></a> Pattern 3a: listbox with all user names
162 ### <a name="Problem"></a> Problem
164 How to populate a list box with all usernames of registered TWiki users
166 ### <a name="Solution"></a> Solution
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>" }%
173 <input type="submit" value="Go" />
176 Which expands to this: (here limited to all Z\* users because TWiki.org has so many)
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>
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.
183 ## <a name="Pattern 3b: listbox with all use"></a> Pattern 3b: listbox with all user names - select multiple names
185 ### <a name="Problem"></a> Problem
187 Suppose you want to send mail from a form on topic page to a selected list of **_multiple_** [[TWikiUsers]]
189 ### <a name="Solution"></a> Solution
191 The example of Pattern 3a produces the list box. Add a MULTIPLE to the _select_ statement, i.e.:
193 <select name="topic" size="2" MULTIPLE>
195 Please note that the Search pattern is unchanged compared to Pattern 3a. The change is in the HTML form element.
197 ### <a name="Test case"></a> Test case
199 The Search pattern 3a with the abovementioned modification is, in effect:
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>
204 ## <a name="Pattern 4: Extract the parent of"></a> Pattern 4: Extract the parent of a given topic
206 ### <a name="Problem"></a> Problem
208 How to get to the parent of the current topic to display on the page?
210 ### <a name="Solution"></a> Solution
212 You might think that the following Search would do the trick:
214 %SEARCH{ "^%BASETOPIC%$" scope="topic" nosearch="on" type="regex" nototal="on" format="[[$parent][parent_link]]" }%
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]]`
218 So the total Search query to find a topic's parent topic is:
220 %SEARCH{ "^%BASETOPIC%$" scope="topic" nosearch="on" type="regex" nototal="on" format="[<nop>[$percntCALC{$IF($EXACT($parent,), <nop>%HOMETOPIC%, $parent)}$percnt][parent_link]]" }%
222 ### <a name="Test Case"></a> Test Case
224 The parent topic of this topic is:
226 # TWiki Installation Error
228 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
230 ## <a name="Pattern 5: Search and display th"></a> Pattern 5: Search and display the home topics of public webs in a list
232 ### <a name="Problem"></a> Problem
234 How to find and display public webs in a drop down list box.
236 ### <a name="Solution"></a> Solution
238 _Thanks to TWiki:Main.PeterThoeny for these solutions._
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=" " }%
245 <input type="submit" value="Go" />
248 ### <a name="Test case"></a> Test case
250 Public webs of TWiki.
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>
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.
257 ### <a name="Alternative solution"></a> Alternative solution
259 This result can also be accomplished with the %WEBLIST% variable.
261 <form><select name="topic"><option value="%TOPIC%">Select...</option>
263 </p></select> <input type="submit" value="Go" /></form>
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
267 ### <a name="Problem"></a> Problem
269 Display the user name in the user's topic title
271 ### <a name="Solution"></a> Solution
273 Search for the `Name:` entry.
275 %SEARCH{" * [N]ame: " topic="%TOPIC%" regex="on" casesensitive="on" nosummary="on" nosearch="on" noheader="on" nototal="on" format="---+!! $pattern(.* \* Name: ([^\n]*).*)"}%
277 ### <a name="Test case"></a> Test case
279 To create a test case, we will put a name entry here:
285 # <a name="TWiki Installation Error"></a> TWiki Installation Error
287 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
289 ## <a name="Pattern 7: Search for Form and M"></a> Pattern 7: Search for Form and Meta data: explained
291 ### <a name="Problem"></a> Problem
293 Below is an example of a search that searches form data. The questions are:
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?
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]]) |"}%
302 ### <a name="Solution"></a> Solution
304 %SEARCH depends on grep, and grep searches the whole file, including the meta data.
306 An example meta data form field is:
308 %META:FIELD{name="OperatingSystem" title="OperatingSystem" value="OsWin"}%
310 So a search for a form field could look like:
312 %SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" regex="on" ... }%
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
317 Now the original file format of the category table (the predecessor of the TWiki forms) looks like this:
319 <td valign="top" align="right"> OperatingSystem: </td><td> OsWin </td>
321 The following search finds topics in the old and new format:
323 %SEARCH{ "[O]peratingSystem.*(td..td|value\=).*[O]sWin" regex="on" ... }%
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.
327 A simple `%SEARCH{ "[O]peratingSystem.*value\=.*[O]sWin" ...}%` search is sufficient if you do not have topics in the old format.
329 ## <a name="Pattern 8: Search all topics tha"></a> Pattern 8: Search all topics that have been moved
331 ### <a name="Problem"></a> Problem
333 How would I go about listing all moved topics ?
335 ### <a name="Solution"></a> Solution
337 Search for the META:TOPICMOVED meta data. Type this:
339 `Moved topics: %SEARCH{ "%META\:TOPICMOVED" regex="on" format="$topic, " nosearch="on" noheader="on" nosummary="on" }%`
341 to get this (limited to 10 results):
345 # TWiki Installation Error
347 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
349 ## <a name="Contributors"></a> Contributors
351 TWiki:Main.AntonAylward, TWiki:Main.ArthurClemens, TWiki:Main.JosMaccabiani, TWiki:Main.PeterThoeny, TWiki:Main.SueLocke
353 **_Related Topics:_** [[UserDocumentationCategory]]