%SEARCH{...}%
is a table consisting of topic names and topic summaries. Use the format="..."
parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as %SEARCH{ "food" format="| $topic | $summary |" }%
. See %SEARCH{...}%
for other search parameters, such as separator=""
.
header="..."
parameter header="| *Topic:* | *Summary:* |"
Variables that can be used in the header string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
format="..."
parameter format="| $topic | $summary |"
Variables that can be used in the format string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$topic |
Topic name |
$topic(20) |
Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) |
Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) |
Topic name, shortened to 40 characters with "..." indication |
$topictitle |
Topic title, in order of sequence defined by: Form field named "Title", topic preference setting named TITLE, topic name |
$parent |
Name of parent topic; empty if not set |
$parent(20) |
Name of parent topic, same hyphenation/shortening like $topic() |
$text |
Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$text(encode:type) |
Same as above, but encoded in the specified type. Possible types are the same as in ENCODE. Though ENCODE can take the extra parameter, $text(encode:type) cannot. Example: $text(encode:html) |
$locked |
LOCKED flag (if any) |
$date |
Time stamp of last topic update, e.g. 2024-02-29 - 10:53 |
$isodate |
Time stamp of last topic update, e.g. 2024-02-29T10:53Z |
$rev |
Number of last topic revision, e.g. 4 |
$username |
Login name of last topic update, e.g. jsmith |
$wikiname |
Wiki user name of last topic update, e.g. JohnSmith |
$wikiusername |
Wiki user name of last topic update, like Main.JohnSmith |
$createdate |
Time stamp of topic revision 1 |
$createusername |
Login name of topic revision 1, e.g. jsmith |
$createwikiname |
Wiki user name of topic revision 1, e.g. JohnSmith |
$createwikiusername |
Wiki user name of topic revision 1, e.g. Main.JohnSmith |
$summary |
Topic summary, just the plain text, all TWiki variables, formatting and line breaks removed; up to 162 characters |
$summary(50) |
Topic summary, up to 50 characters shown |
$summary(showvarnames) |
Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...} |
$summary(expandvar) |
Topic summary, with %ALLTWIKI{...}% variables expanded |
$summary(noheader) |
Topic summary, with leading ---+ headers removedNote: The tokens can be combined, for example $summary(100, showvarnames, noheader) |
$changes |
Summary of changes between latest rev and previous rev |
$changes(n) |
Summary of changes between latest rev and rev n |
$formname |
The name of the form attached to the topic; empty if none |
$formfield(name) |
The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ . This applies only to topics that have a TWikiForm |
$formfield(name, encode:type) |
Form field value, encoded in the specified type. Possible types are the same as in ENCODE: quote , moderate , safe , entity , html , url and csv . The encode:type parameter can be combined with other parameters described below, but it needs to be the last parameter. Example: $formfield(Description, 20, encode:html) |
$formfield(name, render:display) |
Form field value, rendered for display. For example, a form field of type color will render as a colored box. If not specified, the raw value is returned, such as a color value #336699 . The render:display parameter can be combined with other parameters, but must be used after the parameters described below. |
$formfield(name, 10) |
Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) |
Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) |
Form field value, shortened to 30 characters with "..." indication |
$query(query-syntax) |
Access topic meta data using SQL-like QuerySearch syntax. Example: • $query(attachments.arraysize) returns the number of files attached to the current topic • $query(attachments[name~'*.gif'].size) returns an array with size of all .gif attachments, such as 848, 1425, 923 • $query(parent.name) is equivalent to $parent |
$query(query-syntax, quote:") |
Strings in QuerySearch result are quoted with the specified quote. Useful to triple-quote strings for use in SpreadSheetPlugin's CALCULATE, such as $query(attachments.comment, quote:''') which returns a list of triple-quoted attachment comment strings -- the spreadhseet funcions will work properly even if comment strings contain commas and parenthesis |
$query(query-syntax, encode:type) |
QuerySearch result is encoded in the specified type. This is in parallel to $formfield(name, encode:type) mentioned above |
$pattern(reg-exp) |
A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .* , and must end in .* • Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) • Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the e-mail address from a bullet of format * Email: ... • This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag |
$pattern(reg-exp, encode:type) |
A text extracted by reg-exp is encoded in the specified type. This is in parallel to $formfield(name, encode:type) mentioned above |
$count(reg-exp) |
Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp) . Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$ntopics |
Number of topics found in current web. This is the current topic count, not the total number of topics |
$tntopics |
The total number of topics matched |
$nwebs |
The number of webs searched |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
footer="..."
parameter footer="| *Topic* | *Summary* |"
Variables that can be used in the footer string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$ntopics |
Number of topics found in current web |
$tntopics |
The total number of topics matched |
$nwebs |
The number of webs searched |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
default="..."
parameter default="| *Note* | Nothing found in the [[$web.WebHome][$web]] web |"
Variables that can be used in the default string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
%SEARCH{}%
are evaluated once before the search. This is OK for variables that do not change, such as %SCRIPTURLPATH%
. Variables that should be evaluated once per search hit must be escaped. For example, to escape a conditional:
%IF{ "..." then="..." else="..." }%
format="$percntIF{ \"...\" then=\"...\" else=\"...\" }$percnt"
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" footer=" * *Topic: Summary*" }%To get this:
TopicClassification
field, an OperatingSystem
field and an OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" type="regex" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Topic: | OperatingSystem | OsVersion |
---|---|---|
IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
WinDoze95Crash | OsWin | 95 |
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" type="regex" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%To get this: TWiki FAQs:
%WIKIUSERNAME%
are showing "TWikiGuest" instead of my name. Answer...
cron
jobs on Mac OS X? Answer...
%SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
$percnt
to escape the leading percent of the second search
\"
to escape the double quotes
$dollar
to escape the $
of $topic
$nop
to escape the }%
sequence
%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:
$dollarpercntSEARCH{
for level three, $dollardollarpercntSEARCH{
for level four, etc.
Note: Another option, instead of a nested search, is to create a hash. Refer to the blog TWiki:Blog.BlogEntry201603x1. A search using hashes, if possible, may be significantly faster than a nested search.
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" nototal="on" sort="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%=To get this:
WebStatistics | TWikiGuest | 2023-10-03 - 18:15 |
TWikiOnUbuntu | PeterThoeny | 2023-07-15 - 21:08 |
WebHome | PeterThoeny | 2022-08-09 - 03:13 |
ResetPassword | PeterThoeny | 2022-01-05 - 09:13 |
TinyMCEFrequentlyAskedQuestions | PeterThoeny | 2021-09-07 - 17:20 |
TinyMCEQuickHelp | PeterThoeny | 2021-09-07 - 17:17 |
WelcomeGuest | TWikiGuest | 2019-10-31 - 23:12 |
%CALCULATE{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" type="regex" web="Main" nonoise="on" sort="modified" reverse="on" format="$percntCALCULATE{$IF($TIME($date) < $GET(weekold), <nop>, | [[$web.$topic][$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold
variable to the serialized date of exactly one week ago
$percnt
makes sure that the CALCULATE gets executed once for each search hit
weekold
date
<nop>
is returned, which gets removed at the end of the TWiki rendering process
date="..."
paramter in SEARCH to restrict the date.
RakhimSafiullin | TWikiRegistrationAgent | 2024-02-29 - 09:15 | 1 |
TWikiUsers | TWikiAdminUser | 2024-02-29 - 09:15 | 38620 |
SiteStatistics | TWikiAdminGroup | 2024-02-29 - 08:00 | 4769 |
FairouzMalek | PeterThoeny | 2024-02-28 - 13:08 | 3 |
DietmarBeine | TWikiRegistrationAgent | 2024-02-26 - 12:25 | 1 |
IngoMarksteiner | TWikiRegistrationAgent | 2024-02-26 - 10:41 | 1 |
KevinPaquette | TWikiRegistrationAgent | 2024-02-24 - 21:28 | 1 |
RobertSchwarz | TWikiRegistrationAgent | 2024-02-24 - 02:34 | 1 |
SandraAcosta | TWikiRegistrationAgent | 2024-02-23 - 20:53 | 1 |
date=""
parameter as shown in the next example.
%SEARCH{ "." scope="topic" type="regex" web="%USERSWEB%" nonoise="on" sort="modified" reverse="on" format="| [[$web.$topic][$topic]] | $wikiusername | $date | $rev |" limit="100" date="P1w/$today" }%=To get this:
RakhimSafiullin | TWikiRegistrationAgent | 2024-02-29 - 09:15 | 1 |
TWikiUsers | TWikiAdminUser | 2024-02-29 - 09:15 | 38620 |
SiteStatistics | TWikiAdminGroup | 2024-02-29 - 08:00 | 4769 |
FairouzMalek | PeterThoeny | 2024-02-28 - 13:08 | 3 |
DietmarBeine | TWikiRegistrationAgent | 2024-02-26 - 12:25 | 1 |
IngoMarksteiner | TWikiRegistrationAgent | 2024-02-26 - 10:41 | 1 |
KevinPaquette | TWikiRegistrationAgent | 2024-02-24 - 21:28 | 1 |
RobertSchwarz | TWikiRegistrationAgent | 2024-02-24 - 02:34 | 1 |
SandraAcosta | TWikiRegistrationAgent | 2024-02-23 - 20:53 | 1 |
%URLPARAM{"..."}%
variable. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> Find Topics: <input type="text" name="q" size="32" value="%URLPARAM{"q" encode="entity"}%" /> <input type="submit" class="twikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q" encode="quote"}%" type="keyword" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result: Related Topics: UserDocumentationCategory, SearchHelp, VarSEARCH, VarENCODE, SearchResultsPagination, SearchPatternCookbook, RegularExpression, QuerySearch -- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie, TWiki:Main.SopanShewale
%SEARCH{ "^%TOPIC%[A-Za-z0-9]" scope="topic" regex="on" nosearch="on" nototal="on" format=" * [[$topic]]" }%I'm sure I'm not the first to figure this out. I'd like to save the effort of working out common searches for myself and help save other people's efforts by contributing searches I've worked out. -- MitchellModel - 13 Nov 2002 How do you sort results in a search? I don't see it spelled out anywhere I've yet looked. -- GrantBow - 30 Nov 2002 From TWikiVariables: just use the
order
attribute on the embedded search command.
-- RichardDonkin - 30 Nov 2002
This document does not describe the possible values for $scope. It can take 'text' and 'topic'. Text means look in the document whilst topic means look only at the topic name.
-- MartinCleaver - 16 May 2003
$summary and $topic don't seem to work well if a search references another Web - is this easy to fix?
-- JohnTalintyre - 10 Sep 2003
It'd be nice if you could provide a comma separated list of webs to search - it would provide koalaskin the ability to recursively search its child webs.
-- MartinCleaver - 17 Oct 2003
The documentation above is a bit inaccurate for $formfield(name). In fact the code picks up $formfield(title). This can be a problem if the title is not a WikiWord. For example, in the case I was working on, I find the following META tags at the bottom of the topic file:
META:FORM{name="BuyerForm"}% META:FIELD{name="BuyerType" title="BuyerType" value="ComputerHardwareMfg, TeleCom"}% META:FIELD{name="Region" title="[[Region]]" value="NorthAmericaRegion"}% META:FIELD{name="CompanyRevenue2002MilUS" title="Company Revenue 2002 (Mil US$)" value="18915"}% META:FIELD{name="CompanyRevenue2001MilUS" title="Company Revenue 2001 (Mil US$)" value="21790"}%This works for something like
$formfield([[Region]])But blows everything up if you use the more complex
$formfield(Company Revenue 2002 (Mil US$))I think it would be better to use the "name" field above, so that the documentation is correct. It is probably generally improper to use the title of the META field for processing. To fix this, make the following minor change in
Search.pm
:
sub getMetaFormField ...snip... $title = $field->{"title"}; # should change to $title = $field->{"name"}; $value = $field->{"value"}; $value =~ s/^\s*(.*?)\s*$/$1/go; if( $title eq $name ) { $value = breakName( $value, $break ); return $value;See FormattedSearchUsesTitleInsteadOfName -- RaymondLutz - 17 Oct 2003 Added multiple webs, which was implemented in the code but not documented. -- MartinCleaver - 17 Oct 2003 That description for web appears to be for the parameter, not the formatting variable. -- SamHasler - 09 Jan 2004
$pattern(reg-exp) |
A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" 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, $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ... . |
$1
if it exists, or
$0
(whole match) if not
$pattern(\*.*?Email\:\s*([^\n\r]+))
Why the elaborate and unusual requirements for this syntax? I see that pulling out patterns like the above might be a problem due to paren-matching issues, but there are ways around that. Make an exception for $pattern and have it be something like $pattern([[<pattern>]])
and everything is simple again.
-- WalterMundt - 20 Feb 2004
Walter, spec discussions are best done in Codev.
-- PeterThoeny - 17 Mar 2004
I can't seem to generate a table that puts the search results into a grid. I've read over FormattedSearch, TWikiVariables, and TablePlugin and am still lost. Perhaps I'm overlooking something... I can't seem to generate a table that resembles the one below.
Result One One line description. |
Result Two One line description. |
Result Three One line description. |
Result Four One line description. |
format=\"... $dollarpercntPLUGINTAG{attribute=\\"value\\"}$dollarpercnt ...\"-- SteffenPoulsen - 06 Apr 2005 The Syntax section should mention the "separator=" parameter which is required to build certain kinds of search results and is used in several of the examples (nested search). I needed this to create a list of form option values. I wanted them in a table and the table requires the entire cell to be on one "line" thus separator had to be "" or a single space. -- PhilipPokorny - 15 Feb 2006 All SEARCH parameters are documented in TWikiVariables. I added a note accordingly. -- PeterThoeny - 15 Feb 2006 Check out a search app I put together to SearchWithHighlights. I couldn't find anything else out there to do this, so this was a first shot at it. I'll admit it doesn't format things right all the time. And right now it's configured to only search items in the Know web. But it's a nice start anyway. As an example, search for run, and you'll see run in bold and italics within each searched line. (You'll also notice the messed up formatting of the WebStatistics page...) -- BobKocisko - 28 Feb 2006 In the documentation under the heading Table showing form field values of topics with a form you begin the search criteria with:
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" ...What purpose do the open/close brackets perform? There is no documentation covering them. Through experimentation, their presence or absence seem to be insignificant. In any (programming) language, syntax is everything... and I'd hate to accidentally launch missiles at Toledo (Ohio) through a simple coding error. UPDATE: An hour later, after staring at at it while watching S.T. Voyager, it dawned on me to try it as a part of a regular expression. So, I tried:
%SEARCH{ "[Tabcdefg]opicClassif.*?value=\"[P]ublicFAQ\"" ...and it works just fine. Therefore, and please correct me if I'm wrong, the brackets are treated as a set in a Regular Expression, no? -- TerrillBennett - 22 Jun 2007 Yes,
[Tabcdefg]
is a set. [T]
is a "set" with just a single letter, e.g. the letter itself. So why do we need it? In a RegularExpression, [T]opicClassification
and TopicClassification
are identical after all. It is used to avoid a hit on the search term itself. An alternative is to use excludetopic="%TOPIC%"
.
-- PeterThoeny - 23 Jun 2007
Is the default value of the format argument specified anywhere?
-- BryanThale - 15 Oct 2007
There is no default value, e.g. there is no output if no search hit.
-- PeterThoeny - 16 Oct 2007
I want to simplify the "Embedding search forms to return a formatted result" sample above so that the results refresh if you simply choose another option of the select field or at least that the selected option stays selected after pressing the submit button. How can this be done? Here's what I have now:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%" method="get"> Show: <select name="StatusFilter" size="1" onchange="this.form.submit();"><option value="None"> </option><option value="New">New</option><option value="In Work">Active</option><option value="Ready">Ready</option><option value="">All</option></select> </form> Projects Projectstatus: %URLPARAM{"StatusFilter"}% %INCLUDE{"ProjectList" ClientName="%TOPIC%" ProjectStatus="%URLPARAM{"StatusFilter" default=""}%" }%This uses a parametrized INCLUDE to parametrize the search, which works great. The thing that doesn't work properly is the select field, it always jumps back to the first option (here: None resp. an nonbreakable space as workaround). How can I force the view to display the selected option properly? I also did try some javascript, but couldn't get it right cause my javascript sucks. Projects Projectstatus: -- FranzJosefGigler - 18 Oct 2007 The answer to my question above can be found on DynamicSelectedChoiceInSelectList, thanks Peter! -- FranzJosefGigler - 27 Oct 2007 Hi All, Is there any possibility to treat
$summaryas link. I mean that the search result must point to one of the entry in TOC on the page but not to topic which include search result. -- KirillMessel - 08 May 2008 Please ask support questions in the Support web. -- PeterThoeny - 08 May 2008 Thank you JaniHamalainen for adding the helpful note on search performance. It needs some changes before we can take this into the release. This topic is part of the TWiki core release. As such, links to non-core topics do not work, so instead of a TWiki internal link like
[[+Blog.SomeTopic]]
write TWiki:Blog.SomeTopic
, which auto-links. This ensures that links continue to work in TWiki installed somewhere else. Also, from the official docs we do not link to support topics because they tend to have some noise. How about writing a blog post with what you learned? You could add a link in this topic pointing to your blog post on TWiki.org.
-- Peter Thoeny - 2016-03-09
Thanks Peter. I've removed the support topic link and added the newly created blog content to this topic using the proper link.
-- Jani Hamalainen - 2016-03-12