PicoSearch FAQ: Template Codes

This FAQ is Part 2 of the series on using template codes to customize the search results page design for PicoSearch Professional and Premium accounts. For the beginning of the series, see Template Codes Overview FAQ

2. Parts Substitution Codes: change default messages and behaviors for the search results page

Here we discuss a list of template codes that replace specific parts of the PicoSearch search results, allowing you to control primarily the standard phrases. They are in the style of HTML commented lines, so that you can develop your template without them being visible. In practice, they will be mined and stripped from your final search results display, so no one will know, even in the source code, that PICO custom codes were utilized. We suggest that you put them in the head of your template, as you would for meta tags.

Language Specifiers: all of the codes below can become language specific by adding language="..." as the first argument. Language of the search results page is set in the account manager, but can also be overridden at runtime from different search boxes by using the setlang argument (see FAQ for details). So for example, you could customize the no results message for different language areas of your site (see Partitions FAQ) by using the _NOTFOUND template code below, but for English say "No answer!" and German say "Keine Antwort!".

PICO_TEMPLATE_NOTFOUND
Message for no results when the user has definitely typed something (compare with PICO_TEMPLATE_EMPTYSEARCH). Default is in the current display language and says "No documents found relating to your query. Try to widen your search and enter more terms related to your topic." A value of 'none' will turn this message off entirely. A nice customization example would be a link to more help or a customer support email, and there is a trick with _FORMQUERY to put the query in the email subject automatically:

PICO_TEMPLATE_ONEFOUND
Message for 1 result, default is in the current display language and says "Found 1 document." A value of 'none' will turn this message off entirely. Example usage:

PICO_TEMPLATE_MULTIFOUND
Message for multiple results, default is in the current display language and says "Found _FORMDOCS_TOTAL documents, shown _FORMDOCS_FROM - _FORMDOCS_TO." Note the use of placeholders for exact counts. A value of 'none' will turn this message off entirely. Example usage:

PICO_TEMPLATE_EMPTYSEARCH
Message for when the user hasn't typed any search terms, and consequently there are no results. This will override the default behavior of acting neutral by saying just the found word label with no terms after (see also PICO_TEMPLATE_FOUNDWORD). This also overrides the one-click entrance message if you're calling the one-click entrance (see that feature in your account manager). Example usage:

PICO_TEMPLATE_ALL_TRY_ANY
Message to override the default statement for when the search in ALL words mode has found no results and ANY words mode has been automatically tried instead. This very handy failover behavior is selected in the account manager's Page Design section, for more comments see FAQ on initializing. Example usage:
PICO_TEMPLATE_SPELL_DIDYOU
This is the message displayed when the search query has spelling errors but still finds some results. Default says "Did you mean?" in bold, italic, and red text, followed by a link to an alternative spell-corrected query to try next. Note: If you use this code, you must include the keyword _ALT_QUERY_LINK as a placeholder that will be filled in with the actual link to the alternate query. You may also include some HTML code such as to specify CSS styles. Example usage:

Or with some CSS styling:

PICO_TEMPLATE_SPELL_CORRFOUND
This is the message displayed when the search query has spelling errors and returns no results, causing PicoSearch to search for an alternative spelling which does find results. Default includes two lines and says:

_BAD_QUERY => returned no results.
_ALT_QUERY => was tried instead, see results below.

Note the use of placeholders for exact values. You may also include some HTML code such as to specify CSS styles or optional line breaks. Example usage:

Or with some CSS styling and a line break:

PICO_TEMPLATE_SPELL_CORRNOTFOUND
This is the message displayed when the search query has spelling errors and returns no results, causing PicoSearch to search for an alternative spelling which does not yield any results either. Default says: "_ALT_QUERY was also tried, no results either." Note the use of a placeholder for the exact value of the alternate query. You may also include _BAD_QUERY for the exact value of the original misspelled query, and some HTML code such as to specify CSS styles. Example usage:

Or with some CSS styling:
PICO_TEMPLATE_BOXSIZE
Search box width, default is 25. Example usage:
PICO_TEMPLATE_BUTTONTEXT
Search button text, default is "Search" in the current language. Example usage:
PICO_TEMPLATE_ANYOPT
The text for the option to Find ANY word. Example usage:
PICO_TEMPLATE_ALLOPT
The text for the option to Find ALL words. Example usage:
PICO_TEMPLATE_EXACTOPT
The text for the option to Find EXACT phrase. Example usage:

PICO_TEMPLATE_WITHINOPT
The text for the option to search Within Results. Example usage:

PICO_TEMPLATE_FOUNDWORD
The default text for the label on the words found. Normally this is the same 'Search' word as in the search button. It can become the Partition name if search was done within a Partition and you selected the 'Say' option in your account manager's Partitions section. This code lets you customize the text of the label, or the entire message if you include _FORMQUERY as a plugin for the words found. A value of 'none' will turn the searched words line off. Here is an example to customize the label only:

And this example customizes the entire message with the added keyword:

PICO_TEMPLATE_IGNORINGWORD
When Stopwords are ignored and reported to the user, this template code sets the label in the message which defaults to "Ignoring" in the current language. If you include the keyword _PICO_IGNORED_WORDS it will set the entire message, and plug in the actual list of words ignored. Here is an example to customize the label only:

And this example customizes the entire message with the added keyword:

PICO_TEMPLATE_SYNONYMWORD
When User Synonyms are reported to the user (as selected in the account manager), this template code sets the label in the message for the added word(s). If you include the keyword _PICO_SYNONYM_WORDS it will set the entire message, and plug in the actual list of synonyms added. Here is an example to customize the label only:

And this example customizes the entire message with the added keyword:
PICO_TEMPLATE_HELPWORD
Help link text, default is "Help" in the current language. Example usage:

PICO_TEMPLATE_HELPBLOCK
Entire help message, default is the PicoSearch help advice in the current display language. Example usage :

PICO_TEMPLATE_STYLE_PAGEBAR
Use this code to change the style for the page bar, which is the cue of links to more results pages when they are available. (Also see PREVCUE and NEXTCUE below to change the default text for "Previous" and "Next" links). The default style is Normal, which shows links in the form of [first - last], like [1-10], [11-20], and so on. Use this to set the Normal style explicitly:

Another popular style is Number-Per-Page, which displays an incremental number for each link based on its order in the cue, starting from 1. Use this to set the Number-Per-Page style:

Or for maximum flexibility you can specify your own Custom List of strings to use, from List1 to as many as you anticipate needing. Each element ListN can be anything, from simple text to graphics and HTML (just no comment tags since that closes the element). Any missing elements use the one before it, so the last element is used for the rest of the links. Example usage:



Also see below PICO_TEMPLATE_MAXLINKS_PAGEBAR and PICO_TEMPLATE_RESULTSPAGES_CUE for more pagebar options.

PICO_TEMPLATE_MAXLINKS_PAGEBAR
Use this to set the maximum number of links to display before the "next" link in the page bar. The default is 5 and you can reset it to any number, or enter ALL to show all links. (The number of results per page is set in the account manager Ranking Options section, or dynamically per search box with the Initializing FAQ). Example usage:

PICO_TEMPLATE_PREVCUE
Previous search cue in the page bar, default is "Previous" in the current display language. Specifying your own value gives you total control including styling, so the value can be any HTML except a comment tag since that closes the element. Example usage:

PICO_TEMPLATE_NEXTCUE
Next search cue in the page bar, default is "Next" in the current display language. Specifying your own value gives you total control including styling, so the value can be any HTML except a comment tag since that closes the element. Example usage:

PICO_TEMPLATE_RESULTSPAGES_CUE
Replace the "Results Pages:" cue that appears before the second page bar at the end of the results list, when there are more results pages available. A value of 'none' will turn the second page bar off entirely. Example usage:
PICO_TEMPLATE_LISTONLY
Turn off search box and status bar, show only raw results list. Example usage:
PICO_TEMPLATE_HR_1
Substitute the following text for the first hard rule line commonly used in the search results. The value 'none' will turn the <hr> tag off. Codes for _HR_2 and _HR_3 work identically for the second and third hard rule lines. Example usage:
PICO_TEMPLATE_SORTBY
When date sorting is offered, use this phrase instead of "Sort by". Example usage:
PICO_TEMPLATE_POSTSORTBY
When date sorting is offered, use this phrase after the phrase "Sort by relevancy/date". Especially needed for languages that require some post-syntax, such as German "Nach datum sortieren". Example usage:
PICO_TEMPLATE_RELEVANCYWORD
When date sorting is offered, use this word(s) instead of the word "relevancy". Example usage:
PICO_TEMPLATE_DATEWORD
When date sorting is offered, use this word(s) instead of the word "date". Example usage:

PICO_TEMPLATE_ELLIPSIS_LEFT, PICO_TEMPLATE_ELLIPSIS_RIGHT
Customize the ellipses (...) that begin and end concordance excerpt lines. Your substitution can include inline CSS, and will include the space between the ellipsis and the text, so use a non-breaking space character as desired. A value of 'none' will turn the ellipsis off entirely. Example usage:

PICO_TEMPLATE_SEP_URL, PICO_TEMPLATE_SEP_STATUS, PICO_TEMPLATE_SEP_HIGHLIGHT
Sets the separator character which defaults to a bullet, and depending on your Configure Results choices will appear next to the URL, status (date) line, and highlight hits link in the search results. Example usage:

PICO_TEMPLATE_ICONPDF
When displaying the icon for PDF documents, use this graphic instead. Be sure to quote the full URL to your icon starting with http. The URL should be the first argument (unless you have a language="..." specifier before that, see above) then additional HTML arguments can optionally follow. The default size for the icons is 16 by 16, so follow the URL height and width if yours differs. If you don't want any icon, use the code with no arguments. Example usage:

Refer to the Additional File Formats section of your account manager for the list of file types and their icons. Template codes for other types work the same way starting with PICO_TEMPLATE plus: _ICONSHOCKWAVE, _ICONXML, _ICONMP3, _ICONMIDI, _ICONMSWORD, _ICONMSEXCEL, _ICONMSPOWERPOINT, _ICONRTF, _ICONPS, and _ICONTEXT

PICO_TEMPLATE_LINKPIC
If you want to show an image next to certain results, you can use the PICOLINKPIC tag in each file that gets the image. But if you have a common image for many files, you can use put the file patterns in your template with each link picture. The syntax is similar to the PICOLINKPIC tag, so read that FAQ first.
 One difference from PICOLINKPIC is just than the = is not required between the PICO_TEMPLATE_LINKPIC and the following image URL, and that's just so an optional language="..." specifier can come before the first argument just like the other PICO_TEMPLATE codes (see above).
 An additional argument PATTERN takes a quoted list of space-separated patterns, similar to the patterns you use for Excluded Paths or Partitions. The patterns are case-insensitive and match left to right with an implied final wildcard, so a directory can match all contents, or if you include any wildcards then the pattern must match the entire url for the image to be displayed. You can have as many as you like in your template, just be aware that a file's own hardcoded PICOLINKPIC will take precedence, and not more than one image will be displayed.
 Here's an example usage with pattern string to match everything in a certain directory plus all of the search engine's pdfs, with the image linking to the particular file in the search results:


 And here's the same example showing the optional attributes for image alt and border style, as well as a forced common href (to a single signup page perhaps) and target:

Continue to: 3. Style Control Codes --->