NOTE: See latest doc at TWiki.FormattedSearch

Formatted Search Using %SEARCH{... format="..."}% Variable

Preface

This is a new feature to have more control on how an embedded %SEARCH{...}%= is formatted.

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 |" }%).

Syntax

Two paramters 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:* |"

2. format="..." parameter

Use the format paramter to specify the format of one search hit. I.e. format="| $topic | $summary |"

Variables that can be used in the format string:

Name:	Expands To:
$web	Name of the web
$topic	Topic name
$locked	LOCKED flag (if any)
$date	Time stamp of last topic update
$rev	Number of last topic revision, i.e. 1.4
$wikiusername	Wiki user name of last topic update, i.e. Main.JohnSmith
$summary	Topic summary
$formfield(name)	The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp)	A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....

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.

Examples

Bullet list showing topic name and summary

Write this:

%SEARCH{ "FAQ" scope="topic" web="TWiki" nosearch="on" nototal="on" header="   * *Topic: Summary:*" format="   * [[$web.$topic]]: $summary" }%

To get this:

• Topic: Summary:
• TWiki.TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of an easily implemented knowledge base solution. To see how it`s done, view the source...
• TWiki.TWikiFaqTemplate: FAQ: Answer: Back to: TWikiFAQ Contributors:
• TWiki.TextFormattingFAQ: Text Formatting FAQ This topics lists frequently asked questions on text formatting. Text formatting applies to people who edit TWiki pages in raw edit mode . TextFormattingRules...

Table showing form field values of topics with a form

Write this in the Know web:

| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%

To get this: (simulated)

Topic:	OperatingSystem:	OsVersion:
IncorrectDllVersionW32PTH10DLL	OsWin	95/98
WinDoze95Crash	OsWin	95

Extract some text from a topic using regular expression

Write this:

%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" web="TWiki" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$web.$topic][Answer...]]" }%

To get this:

TWiki FAQs:

• How can I create a simple TWiki Forms based application? Answer...
• I am a registered user and I have authenticated myself before I edited a topic. But after saving the topic, the left bar and the variable %WIKIUSERNAME% are showing "TWikiGuest" instead of my name. Answer...
• How do I convert a table from HTML to TML? Answer...
• How do I set up cron jobs on Mac OS X? Answer...
• How do I delete or rename a topic? Answer...
• How do I delete or rename a file attachment? Answer...
• Why does the topic revision not increase when I edit a topic? Answer...
• When I try to access TWiki, I get the "Premature end of script headers: ..." error. Answer...
• TWiki has a GPL (GNU General Public License). What is GPL? Answer...
• How can I create a .htpasswd file that is owned by the webserver user? Answer...
• How do you log off? Suppose I log in with the guest username but later I want to use another username, how do I log off from the guest user name? Answer...
• How do I move the form to the top of the page? Answer...
• Answer...
• Need to know which is the best stable version of perl to be used in the End. Answer...
• I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer...
• What happens if two of us try to edit the same topic simultaneously? Answer...
• I would like to install TWiki on my server. Can I get the source? Answer...
• How can I use international (I18N) characters in usernames? Answer...
• What does the "T" in TWiki stand for? Answer...
• So what is this WikiWiki thing exactly? Answer...
• Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...

Feedback

The TWiki.org installation has been updated, also TWikiAlphaRelease.

Feedback is welcomed below.

-- PeterThoeny - 01 Nov 2001

A most excellent feature :-). Any possibility of extending it so that the sort key can be specified in a similar manner (ie sort="$formfield(OperatingSystem)")? This would go part way to making it possible to use forms for a ticket system in our organistation.

• This is now implemented, see SortSearchByMetaField -- PeterThoeny - 16 Feb 2002

-- AdrianLynch - 14 Nov 2001

Sorting is nicely covered by the TablePlugin.

-- PeterThoeny - 14 Nov 2001

Bookview / Include

Regular expression pullout of text is great, but including the body is the whole text in the results is messy. I've patched out local TWiki thus to allow us to use: $topictext to effectively end up with a formatted bookview. Code:

# diff -u2 Search.pm~ Search.pm
--- Search.pm~  Wed Jan 16 18:24:16 2002
+++ Search.pm   Wed Jan 16 18:23:43 2002
@@ -461,4 +461,5 @@
                 $tempVal =~ s/\$n([^a-zA-Z])/\n$1/gos; # expand "$n" to new line
                 $tempVal =~ s/\$web/$thisWebName/gos;
+                $tempVal =~ s/\$topictext/$text/gos;
                 $tempVal =~ s/\$topic/$topic/gos;
                 $tempVal =~ s/\$locked/$locked/gos;

This differs from using a format that uses %INCLUDE% in that %INCLUDE% won't include the stuff between STARTINCLUDE & STOPINCLUDE

-- TWikiGuest - 16 Jan 2001

RSS application

For some interesting applications of FormattedSearch, see WikiRssExtension and MozillaSidebar, which both use this feature to 'syndicate' TWiki WebChanges information.

-- RichardDonkin - 18 Jan 2002

Dynamic data

What seems to me to be missing at the moment is any way to get dynamic data into a formatted search, something like:-

| Topic | Originator | %SEARCH{ "IdeaOriginator.*?value=\"%URLPARAM(originator)%\"" scope="text" regex="on" nosearch="on" nototal="on" format="| $topic | $formfield(IdeaStatus) |" order="modified" reverse="on" limit="10"}%

This would allow me to create a form into which someone can type a name and see just that person's ideas. The best I can do at the moment I think is to use the TablePlugin and sort by the name - but that doesn't cater for multiple originators, which is allowed in my form.

I do use a simple amendment to the search script to build its search string dynamically from multiple query parameters, but that doesn't let me format the result, as I understand it.

-- NigelArmstrong - 23 Jan 2002

(wiki)username

In the doco it states $username is a format option but no such option exists. Or should I say I couldn't find it:

 if( $theFormat ) {
                $tempVal = $theFormat;
                $tempVal =~ s/([^\n])$/$1\n/gos;
                $tempVal =~ s/\$web/$thisWebName/gos;
                $tempVal =~ s/\$topic/$topic/gos;
                $tempVal =~ s/\$locked/$locked/gos;
                $tempVal =~ s/\$date/$revDate/gos;
                $tempVal =~ s/\$rev/1.$revNum/gos;
                $tempVal =~ s/\$wikiusername/$revUser/gos;

            }

Bummer that's exactly what I needed!

Also: AdrianLynch 's idea above about ordering on a formfield value would be awsome (for when you don't want to render search results in a table). And MichaelSparks 's patch above to the topic text to be included is also desireable.

As far as I can see it expanding the capabilties of formatted search results can only be a good thing because it's such a powerful feature. I liken it to a database view from LotusNotes.

There are many applications for storing multiple topics with forms and then listing the form data.

-- AndrewTetlaw - 09 Feb 2002

$username : This is already in TWikiAlphaRelease for some time now.

$topictext : I tried to hack this in but commented it out since there are some "gotchas": Images, links to attachments, variables and possibly other things are broken.

Search with dynamic search string via %URLPARAM{}% : I have not tried this, but this should work because %URLPARAM{}% gets evaluated before %SEARCH{}%.

-- PeterThoeny - 16 Feb 2002

$topictext is now implemented and in TWikiAlphaRelease. Needed to add rendering but exclude the current topic to prevent a loop.

-- PeterThoeny - 16 Feb 2002

Changed name $topictext to $text. This is to make it consistent with scope="text".

-- PeterThoeny - 17 Feb 2002

This is a really powerful feature. I just hacked something together on our internal TWiki that uses this feature. We are using it to track "TODO: xxxx" on our site.

Unfortunately I just noticed something that is a bit off. If I have multiple "TODO: xxxx" within one topic, using FormattedSearch I only get the first one defined. Is there any flag to SEARCH such that I can request all individual instances of a match, even if it returns multiple items within the same topic???

-- JohnCavanaugh - 03 Mar 2002

Is the format option reserved to inline searches or can I make it work with standard searches ? I tried to add a simple format option as a hidden field in the WebSearch form. I has no effect.

-- JeromeBouvattier - 16 Mar 2002

I imagine you can use it in a standard search, but getting the quoting of the URL right is probably quite a challenge. There is a working example of passing a form parameter into a FormattedSearch, which might be another approach to doing what you need - see SherlockAndMozillaSearching.

-- RichardDonkin - 16 Mar 2002

Topic summary length

Is there some way of customizing the length of the text captured and returned by $summary? I'd like to grab 100 words instead of just 30. Or better yet, 300 words or everything up to the first paragraph ending, whichever comes first.

• See patch in AllowDesignationOfSummary, PeterKlausner

-- MattWilkie - 11 Jun 2003

Just adding a note here to say that I've produced a patch that allows you to have named include sections which is in many ways complementary to PeterKlausner's patch. Also the patch allows you to have %INCLUDE%s inside a format - which I thought used to work, but doesn't with default BeijingRelease. (This latter point is a tad "hacky" though IMO)

-- TWikiGuest - 14 Jun 2003

Nest in other variables with $percent or mixed quotes?

SearchWithNoPipe tripped of an old patch of mine: For nesting %FOO{bar}% expressions into format, I added the constant "variable" $percent, so you can write:

%SEARCH{"foobar" format="%INCLUDE{$topic}$percent"}%

This simply prevents %SEARCH from seeing a premature closing }% Is there an easier, more elegant solution to this problem? How does Michaels "hacky" do it?
The trivial patch:

===================================================================
RCS file: /var/cvs/twiki/lib/TWiki/Search.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Search.pm   2002/06/19 13:53:17     1.1
+++ Search.pm   2002/11/12 11:51:00     1.2
@@ -467,6 +467,7 @@
                 $tempVal =~ s/\$rev/1.$revNum/gos;
                 $tempVal =~ s/\$wikiusername/$revUser/gos;
                 $tempVal =~ s/\$username/&TWiki::wikiToUserName($revUser)/geos;
+                $tempVal =~ s/\$percent/%/gos;

             } else {
                 $tempVal = $repeatText;

-- PeterKlausner - 27 Jun 2003

I describe my solution as more hacky because:

• It allows you to use ' where you need " in sub "tags", and \% where you want %
  • you want = Warning: Can't find topic Codev.topic

= as the search format result

• • you write your search format as %INCLUDE{'topic' section='section'}\%

Why not \" it ?

• Doesn't work
• Compare clarity of above with %INCLUDE{\"topic\" section=\"section\"}\%

Why not $quot it then ?

• I've been using python alot recently and anywhere you can put " you can put ' and you can use one for nesting the other, and it's more intuitive in many respects I (personally) feel.
• Compare clarity of above with %INCLUDE{$quottopic$quot section=$quotsection$quot}\%

Why \% not $variable ?

• \escaped thing is one of the simplest most common ways of doing this
• As a result I thought of \% first. (Indeed I thought of \" first, found it didn't work and I know can cause problems so just moved to the next most common idiom I've used)

As noted above patch to do this is included with named include sections.

-- TWikiGuest - 27 Jun 2003

CustomSearchForm discussion (moved)

(Discussion on custom search forms moved to CustomSearchForm.)

I found FormattedSearchinTopics - is it obsolete? If so, delete it? BTW a lot of trash topics all over the place.

-- PeterMasiar - 17 Sep 2003

FormattedSearchAcrossMultipleWebs

-- MartinCleaver - 17 Oct 2003

Is there any chance, that either the $percent or "'nesting'" approach makes it into CairoRelease? I'm doing a test migration with TWikiBetaRelease2004x05x07 and realise, that neither is there

-- PeterKlausner - 03 Jun 2004

$percent was never in the code, but $percnt is. This is aligned with the HTML entity name. See documentation in FormattedSearch.

-- PeterThoeny - 04 Jun 2004