-**Formatted Search Using <code>**%SEARCH\{... format="..."\}%**</code> Variable**
-
<div>
<ul>
- <li>
- <ul>
- <li><a href="#Preface"> Preface</a></li>
+ <li><a href="#TWiki Formatted Search Results"> TWiki Formatted Search Results</a><ul>
<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>
-## <a name="Preface"></a> Preface
+# <a name="TWiki Formatted Search Results"></a> TWiki Formatted Search Results
-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 |" }%`).
+_Inline search feature allows flexible formatting of search result_
+
+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. `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. `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:
<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, -<br />)</code></td>
+ <td> Topic name, hyphenated each 30 characters with separator "<tt>-<br /></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 </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, 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>$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([[Main/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, -<br />)</code></td>
+ <td> Form field value, hyphenated each 20 characters with separator "<tt>-<br /></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
### <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 /><code>%SEARCH\{ "[T]opicClassification.\*?value=\\"[P]ublicFAQ\\"" scope="text" regex="on" nosearch="on" nototal="on" format="| \[[$topic]] | $formfield([[OperatingSystem]]) | $formfield([[OsVersion]]) |" \}%</code>
+`| *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>
### <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]] - 24 Oct 2001 <br />
+-- TWiki:Main.PeterThoeny - 16 Mar 2004
git://git.openafs.org / openafs-wiki.git / blobdiff