%META:TOPICINFO{author="ProjectContributor" date="1655899072" format="1.1" version="1"}%
%META:TOPICPARENT{name="UserDocumentationCategory"}%
---+!! Search Pattern Cookbook

The Search function is very powerful. Searches using a RegularExpression play an important part of tapping Foswiki's full potential. Unfortunately RegularExpressions can be incredibly obscure to the uninitiated. 

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.

%TOC{ depth="2" }%

<!-- ============================== -->
#SearchTables
---++ Pattern 1: Extract values from a table

---+++ Problem definition

Suppose there is a topic with a table defining entries in a [[DataForms][data form]]. I.e. they define select menu items in a form definition. They are then formatted like:

<verbatim class="tml">
| *Name*  | *Type* | *Description* |
| option1 | option |               |
| option2 | option |               |
| option3 | option |               |
</verbatim>

How to extract the 'name' values, i.e. 'option1', 'option2' and 'option3' and put them in a HTML form select input?

---+++ Solution 1
The following search pattern can be employed:

<verbatim class="tml">
%STARTSECTION{"solution1"}%
<form>
    <select>
        %SEARCH{
            "^\|[^\|]*\| *option *\|"
            topic="%TOPIC%"
            type="regex"
            multiple="on"
            nonoise="on"
            format="<option>$pattern(^\| *(.*?) *\|.*)</option>"
        }%
    </select>
</form>
%ENDSECTION{"solution1"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution1"}%

---+++ Solution 2
If your table has this format:
<verbatim class="tml">
| *Country*      |
|                |
| Afghanistan    |
| Aland Islands  |
| Albania        |
| Algeria        |
| American Samoa |
| Andorra        |
</verbatim>

You need to skip the header row. Use this search:
<verbatim class="tml">
%STARTSECTION{"solution2"}%
<select>
    %SEARCH{
        "^\|[^\*\|]*\|"
        topic="CountryList"
        type="regex"
        multiple="on"
        nonoise="on"
        format="<option>$pattern(^\| *(.*?) *\|.*)</option>"
    }%
</select>
%ENDSECTION{"solution2"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution2"}%

---+++ Solution 3
If you want to grab the complete row for each occurrence of a string in a table, for instance the word "Marketing":
<verbatim class="tml">
| a | b | c | d | e |
| Marketing | b | c | d | e|
| a | b | c | d | e |
| a | marketing | c | d | e | 
| a | b | c | d | marketing | 
</verbatim>

use this query:
<verbatim class="tml">
%STARTSECTION{"solution3"}%
%SEARCH{
    "^\|.*?Marketing.*"
    type="regex"
    topic="%TOPIC%"
    multiple="on"
    nonoise="on"
    format="| $pattern(^\| *(.*?) *|.*)"
}%
%ENDSECTION{"solution3"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution3"}%

<!-- ============================== -->
#SearchFormClassification
---++ Pattern 2: List generated from form classification

---+++ Problem

Imagine a form-based topic classification, i.e. every page has a form with several fields. How to:
   1. create a search to display all topics where one form field is set to a certain value
   1. create a search to filter the list above based on the values of a second form field

---+++ Test case

In practice: %BR%
Image a form with two fields:
   * !TopicClassification = One, Two or Three
   * !TopicStatus = Test or Final

We will:
   1. List all topics where the !TopicClassification field is set to 'Two'
   2. Enable the user to filter this list based on the values of !TopicStatus

---+++ Solution

<verbatim class="tml">
%STARTSECTION{"solution4"}%
%SEARCH{
    "TopicClassification='%URLPARAM{"type" default="FrequentlyAskedQuestion"}%'"
    type="query"
    nonoise="on"
    sort="topic"
    format="   * [[$topic]] - <span class='foswikiGrayText'>$date, [[$wikiusername]]</span>"
}%
%ENDSECTION{"solution4"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution4"}%

The filtering select dialogue is created as in Pattern 1:

<verbatim class="tml">
%STARTSECTION{"solution5"}%
*Filter:* 
<form name="selectType" action="%SCRIPTURLPATH{"view"}%/%WEB%/" >
    <select name="type" size="1" onchange="document.location=this.value;"> 
        %SEARCH{
            "^\|[^\|]*\| *option *\|"
            topic="TopicClassification"
            type="regex" 
            nonoise="on"
            format="<option value='%BASETOPIC%?type=$pattern(^\| *(.*?) *\|.*)'>
                $pattern(^\| *(.*?) *\|.*)</option>"
        }% 
        <option value='%BASETOPIC%'>All pages</option>
    </select>
</form>
%ENDSECTION{"solution5"}%
</verbatim>

This will create similar functionality as Foswiki:Extensions.TopicClassificationAddOn

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution5"}%

<!-- ============================== -->
#SearchTopicParent
---++ Pattern 3: Extract the parent of a given topic

---+++ Problem

How to get to the parent of the current topic to display on the page?

---+++ Solution 1: Using QUERY

Use the QUERY macro:

<verbatim class="tml">
%STARTSECTION{"solution6"}%
Parent of [[%TOPIC%]] is [[%QUERY{ "parent.name" }%]]
%ENDSECTION{"solution6"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution6"}%

<!-- ============================== -->
#SearchTopicChildren
---++ Pattern 4: Show all Children of a given topic

---+++ Problem

How to get to the list of all children of the current topic to display on the page?

---+++ Solution

The parent information is stored in the topic meta data. Do a SEARCH to find all topic parent meta data pointing to the current topic:

<verbatim class="tml">
%STARTSECTION{"solution7"}%
%SEARCH{
    "parent.name='%HOMETOPIC%'"
    type="query"
    nonoise="on"
    header="*Children:* "
    format="[[$topic]]"
    separator=", "
}%
%ENDSECTION{"solution7"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution7"}%

See also [[HierarchicalNavigation]] for an elaborate example.

<!-- ============================== -->
#SearchPublicWebsList
---++ Pattern 5: Search and display the home topics of public webs in a list

---+++ Problem

How to find and display public webs in a drop down list box.

---+++ Solution

<verbatim class="tml">
%STARTSECTION{"solution8"}%
<form>
    <select name="topic">
        <option value="%TOPIC%">Select...</option>
            %SEARCH{
                "%HOMETOPIC%"
                scope="topic"
                web="all"
                topic="%HOMETOPIC%"
                format="<option value='$web.$topic'>$web</option>"
                separator=" "
            }%
    </select>
    <input type="submit" class="foswikiSubmit" value="Go" />
</form>
%ENDSECTION{"solution8"}%
</verbatim>

Public webs can be found with the %<nop>WEBLIST% macro.

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution8"}%

<!-- ============================== -->
#SearchBulletList
---++ Pattern 6: Create a select box with values from a bullet list

---+++ Problem

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.

For example, !CategoryList has:
   * Clients
   * People
   * Rooms
   * Buildings

---+++ Solution

The following search pattern can be employed:

<verbatim class="tml">
%STARTSECTION{"solution9"}%
<select name="type">
    <option>Select category...</option>
    %SEARCH{
        "   *\s*.*?"
        topic="CategoryList"
        type="regex"
        multiple="on"
        casesensitive="on"
        nonoise="on"
        format="<option>$pattern(.*   \*\s*([^\n]*).*)</option>"
    }%
</select>
%ENDSECTION{"solution9"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution9"}%

To render the bullet list as a comma-separated list, use the =separator= parameter:
<verbatim class="tml">
%STARTSECTION{"solution10"}%
%SEARCH{
    "   *\s*.*?"
    topic="CategoryList"
    type="regex"
    multiple="on"
    casesensitive="on"
    nonoise="on"
    separator=","
    format="$pattern(.*   \*\s*([^\n]*).*)"
}%
%ENDSECTION{"solution10"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution10"}%

<!-- ============================== -->
#MovedTopics
---++ Pattern 7: Search all topics that have been moved

---+++ Problem

How would I go about listing all moved topics ?

---+++ Solution

Search for the 'moved' meta data. 

<verbatim class="tml">
%STARTSECTION{"solution11"}%
*Moved topics*: %SEARCH{
    "moved.from=~'\w+'"
    web="all"
    type="query"
    separator=", "
    format="[[$web.$topic]]"
    nonoise="on"
}%
%ENDSECTION{"solution11"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution11"}%

---++ Pattern 8: Extract level-1 headings

---+++ How do I go about extracting the first occurance of a level-1 heading?

---+++ Solution
Use the =$pattern()= token. 

%STARTSECTION{"Headings"}%
<verbatim class="tml">
%STARTSECTION{"solution12"}%
%SEARCH{
    "^---[+][^+][^\r\n]+[\r\n]"
    type="regex"
    nonoise="on"
    header="Headings:"
    limit="5"
    format="   * [[$topic][$pattern([\r\n\-+!]+([^\r\n]*?)[\r\n].*)]]"
    footer="Found $ntopics topics with level-1 headings"
}%
%ENDSECTION{"solution12"}%
</verbatim>

%INCLUDE{"%WEB%.%TOPIC%" section="click2exec" id="solution12"}%
%ENDSECTION{"Headings"}%

---
*Related Topics:* UserDocumentationCategory, SearchHelp, [[Macros]], FormattedSearch, RegularExpression

<verbatim class="foswikiHidden">
%STARTSECTION{"click2exec"}%
%BUTTON{"Click to execute" onclick="jQuery('#%id%').trigger('refresh')"}%

<div class="jqLoader" data-mode="manual" data-web="%INCLUDINGWEB%" data-topic="%INCLUDINGTOPIC%" data-section="%id%" id="%id%"></div>
%JQREQUIRE{"loader"}%
%ENDSECTION{"click2exec"}%
</verbatim>
