MULTISEARCH -- perform multiple formatted searches in one efficient macro

The %MULTISEARCH% variable is handled by the MultiSearchPlugin

Parameters

Parameter	Description	Default
"..."	Unnamed parameter is not used in this macro
web	Web in which the search is performed	current web
topic	Limit search to topics e.g. topic="WebPreferences" topic="*Bug" topic="MyTopic,YourTopic" A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names. Adding a topic restriction to a search can greatly improve the search performance.	All topics in a web
excludetopic	Exclude topics from search e.g. excludetopic="Web*" excludetopic="WebHome, WebChanges" A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names.	''
format	Format of the resulting search for each index value of interval. Typically defines a bullet point or a table row	''
header	The header is output just before the formatted search results. Typically used for table headers. See tokens used in headers below
footer	The footer is output just after the formatted search results. Typically used for table footers and for summary texts. See tokens used in headers below
indexmode	Defines the mode of the search. Valid values are index and interval	index
indextype	Defined how to treat the index fields. All index fields are treated as the same type. text is plain text multi means the field has multiple values date means the field is interpreted as a date. The plugin will understand dates in the format described in System/TimeSpecifications and any form field defined as a date field	text
indexformat	Only for date type fields. Defines how the intervals are displayed when showing the start date. Defined by using Time Format Tokens. See below. If this is not defined dates are shown as epoch and text just presented in the original format	undefined
indexstart	For interval searches this defines the start value. For dates this is the date of the first interval. See note 2 about dates below.	undefined
indexend	For interval searches this defines the end value. The actual end of the last interval will depends on the indexstart and indexstep because the plugin assumes you will always want the last interval to be a complete interval. See note 2 about dates below.	undefined
indexstep	The size of each interval. For dates it can be number of seconds or it can be any positive relative time. See note 3 below	1 or 1 week
search#	The # is a number starting from 1. The search syntax is 100% identical with query type searches using standard SEARCH. You cannot jump the number sequency. The number must start with 1 and increment by 1 for each new search option.	''
listformat#	The format that is used for each found topic. These formatted lists are then joined together using the listseparator and output with the $list# (# - the search number) token inside the format parameter	''
listseparator#	The number # must also be used in a search# option. This is the format used for the $list# token used in the format string. Typically this is set to ', ' (comma space) to create a list separated by commas.	''
indexfield#	The name of the form field used for search number #.	''
delay="#"	Number of times the MULTISEARCH will delay its own expansion by changing the first and last %-sign to $percnt and all double quotes (") to $quot. This is used when you use MULTISAVE inside the format parameter of a SEARCH or FORMAT macro and you do not want to expand MULTISEARCH until the outer SEARCH/FORMAT is completed. Set the delay to 1 if it is a single level SEARCH/FORMAT. If you have nested SEARCHes you can set delay to the level of nesting.	0

• Note1: The parameters formats, headers, and footers do not by default put a new line at the end. You must always specify this with a $n if you need a new line (you will need this in most cases)
• Note2: Dates given to indexstart and indexend can be entered in two different formats
  • It will first try the normal Foswiki date/time formats as described in TimeSpecifications.
  • If the above fails it will try and calculate the date based on relative time that the CPAN library Time::ParseDate can handle. E.g. "-3 months" , "last Monday", "+2 days", "next Wednesday", "2 weeks"
• Note3: indexstep relative times is always relative to now. You can use any time format that the CPAN library Time::ParseDate can handle. E.g. "1 month", "7 days", "1 week", "2 weeks"

Parameter Tokens

header="..." parameter, footer="..." parameter

Use the header and footer parameter to specify the header and footer of a search result. It should correspond to the format of the format parameter. Both parameters are optional.

Example header:

header="| *Business* | *Total ($ntotal* | *Open* | *Open A-level* | *List of Opens* |$n"

Example footer:

 footer="| | $ntopics1 | $ntopics2 | $ntopics3 | |$n"

Format tokens that can be used in the header and footer strings:

Name:	Expands To:
$ntopics#	Number of topics found in current web. The total is calculated AFTER all the searches are complete
$calc(...)	Perform simple calculations of numbers inside the ( ). Only numbers and +, -, *, and / is allowed. $calc is evaluated after $ntopics# so you can write $calc($ntopics1 - $ntopics2) to get the difference between the two results

• In addition you can use all the standard format tokens with the header and footer parameters. See below.

listformat#="..." parameter

Example:

listformat1="$formfield(Originator)" listformat2="[[$web.$topic][$topic]]"

Format tokens that can be used in the listformat# string:

Name:	Expands To:
$web	Name of the web
$topic	Name of the found topic
$formfield(name)	Content of any formfield of the given topic. No formatting is done with the formfield content. It may contain characters that needs to be dealt with. (This may be enhanced in later versions of the plugin)

listseparator#="..." parameter

Example:

listseparator2=", "

You can use all the standard format tokens with the listseparator# parameter. See below.

format="..." parameter

Example:

format="| $indexfield | $ntopics1 | $ntopics2 | $list1 | $list2 |$n"

Format tokens that can be used in the format string.

Name:	Expands To:
$indexfield	When indexmode is index $indexfield show the common value of the indexfields When indexmode is interval $indexfield shows the lower value of the interval
$list#	The # is the number of the corresponding search number. $list# displays all the values given by the listformat# parameter which are joined together by the string defined by the listseparator# parameter
$nhits#	The number of topics found by this search number # for this index value or interval.
$ntopics#	$ntopics# is the total of topics found in search# in the accumulated indexes or intervals shown until now. NOTE! For intervals the $ntopics value starts at the number of topics found having an indexfield value below/before the indexstart parameter value
$calc(...)	Perform simple calculations of numbers inside the ( ). Only numbers and +, -, *, and / is allowed. $calc is evaluated after all other tokens are done so you can write $calc($ntopics1 - $ntopics2) to get the difference between the two results

• In addition you can use all the standard format tokens with the format parameter. See below.

indexformat="..." parameter

indexformat is only used when the indextype is date and it accepts these special time format tokens

Token:	Unit:	Example
$seconds	seconds	59
$minutes	minutes	59
$hours	hours	23
$day	day of month	31
$wday	day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat)	Thu
$dow	day of the week (Sun = 0)	2
$week	number of week in year (ISO 8601)	34
$month	short name of month	Dec
$mo	2 digit month	12
$year	4 digit year	1999
$ye	2 digit year	99
$tz	either "GMT" (if set to gmtime), or "Local" (if set to servertime)	GMT
$iso	ISO format timestamp	2024-05-06T13:55:38Z
$rcs	RCS format timestamp	2024/05/06 13:55:38
$http	E-mail & http format timestamp	Mon, 06 May 2024 13:55:38 GMT
$epoch	Number of seconds since 00:00 on 1st January, 1970	1715003738

Tokens can be shortened to 3 characters

Standard Tokens for header, footer, listseparator#, and format parameters

Name:	Expands To:
$n or $n()	New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar Most macros accept parameter strings which are split over multiple lines. This is usually more readable than using $n tokens. If you are familiar with sectional includes, you might also consider nested sectional includes to hold the newline content outside of the parameter string entirely. Note that newline is not a line break. The browser will wrap the lines together. If you require a line break, displaying the results on two lines, use %BR%. Or use two consecutive newlines to create a TML "Paragraph".
$nop or $nop()	Is a "no operation". This token gets removed; useful for nested search
$quot	Double quote (") (\" also works)
$percent	Percent sign (%) ($percnt also works)
$dollar	Dollar sign ($)
$lt	Less than sign (<)
$gt	Greater than sign (>)
$amp	Ampersand (&)
$comma	Comma (,)

Related

MultiSearchPlugin