5.12. The Results Page
Once a search has been completed, there needs to be a way of presenting the output. By default, the SpecialPage search is used. It is set to results in the distribution demo, but any number of search pages can be specified by passing the value in the search form specified in the variable mv_search_page.
On the search page, some special Interchange tags are used to format the otherwise standard HTML. Each of the iterative tags is applied to every code returned from the search. This is normally the product code, but could be a key to any of the arbitrary databases. The value placed by the [item-code] tag is set to the first field returned from the search.
The basic structure looks like this:
[search-region] [search-list] your iterating code, once for each match [/search-list] [no-match] Text / tags to be output if no matches found (optional but recommended) [/no-match] [more-list] More / paging area (optional) [/more-list] [/search-region]
Tip for catalogs upgraded from Minivend 3: A [search-list][/search-list] must always be surrounded by a [search-region][/search-region] pair. This is a change from Minivend 3.
[search-list]
-
Starts the representation of a search list. Interchange tags can be embedded in the search list, yielding a table or formatted list of items with part number, description, price, and hyperlinks to order or go to its catalog page.
The example tags shown have an item- prefix, which is the default. Set any prefix desired with the prefix parameter to [search-region]:
[search-region prefix=my] [search-list] SKU: [my-code] Title: [my-data products title] [/search-list] [/search-region]
-
The standard set of Interchange iterative ITL tags are available. They are interpolated in this order:
[item-alternate N] true [else] false [/else] [/item-alternate] [if-item-param named_field] true [else] false [/else] [/if-item-param] [item-param named_field] [if-item-pos N] true [else] false [/else] [/if-item-pos] [item-pos N] [if-item-field products_field] true [else] false [/else] [/if-item-field] [item-field products_column] [item-increment] [item-accessories] [item-code] [item-description] [if-item-data table column] true [else] false [/else] [/if-item-data] [item-data table column] [item-price N* noformat=1*] [item-calc] [/item-calc] [item-change marker] [condition]variable text[/condition] true [else] false [/else] [/item-change marker] [item-last] condition [/item-last] [item-next] condition [/item-next]
Note: those that reference the shopping cart do not apply, i.e., [item-quantity], [item-modifier ...] and friends.
[/search-list]
-
Ends the search list.
[no-match]
-
Starts the region of the search results page that should be returned if there is no match (and no error) for the search. If this is not on the page, the special page nomatch will be displayed instead.
[/no-match]
-
Ends the no match region.
[sort database:field:option* database:field:option*]
-
Sorts the search list return based on database fields. If no options are supplied, sorts according to the return code. See SORTING.
This is slow, and it is far better to pre-sort the return in the search specification.
[item-change marker]
-
Active only within [search-list][/search-list].
Along with the companion [/item-change marker], surrounds a region which should only be output when a field (or other repeating value) changes its value. This allows indented lists similar to database reports to be easily formatted. The repeating value must be a tag interpolated in the search process, such as [item-field field] or [item-data database field].
Of course, this will only work as expected when the search results are properly sorted.
The marker field is mandatory, and is also arbitrary, meaning that any marker can be selected as long as it matches the marker associated with [/item-change marker]. The value to be tested is contained within a [condition]value[/condition] tag pair. The [item-change marker] tag also processes an [else] [/else] pair for output when the value does not change. The tags may be nested as long as the markers are different.
The following is a simple example for a search list that has a field category and subcategory associated with each item:
<TABLE> <TR><TH>Category</TH><TH>Subcategory</TH><TH>Product</TH></TR> [search-list] <TR> <TD> [item-change cat] [condition][item-field category][/condition] [item-field category] [else] [/else] [/item-change cat] </TD> <TD> [item-change subcat] [condition][item-field subcategory][/condition] [item-field subcategory] [else] [/else] [/item-change subcat] </TD> <TD> [item-field name] </TD> [/search-list] </TABLE>
-
The above should output a table that only shows the category and subcategory once, while showing the name for every product. (The will prevent blanked table cells if using a border.)
[/item-change marker]
-
Companion to [item-change marker].
[matches]
-
Replaced with the range of match numbers displayed by the search page. Looks something like "1-50". Make sure to insert this item between a [more-list] and [/more-list] element pair.
[match-count]
-
Replaced with the total number of matches. This tag works even on [query] searches where [value mv_search_match_count] isn't set unless the query is applied to a non-SQL database. Make sure to insert this item between a [more-list] and [/more-list] element pair.
[more-list next_img* prev_img* page_img* border* border_current*]
-
Starts the section of the search page which is only displayed if there are more matches than specified in mv_matchlimit. If there are less matches than the number in mv_matchlimit, all text/html between the [more_list] and [/more_list] elements is stripped.
Use in conjunction with the [more] element to place pointers to additional pages of matches.
If the optional arguments next_img, prev_img, and/or page_img are present, they represent image files that will be inserted instead of the standard 'Next,' 'Previous,' and page number. If prev_img is none, then no previous link will be output. If page_img is none, then no links to pages of matches will be output. These are URLs, are substituted for with ImageDir and friends, and will be encased in IMG tags. Lastly, border is the border number to put.
In addition, if page_img is used, it will be passed an argument of the digit that is to be represented. This would allow an image generator program to be used, generating page numbers on the fly. The border and border_selected values are integers indicating the border that should be put around images in the page_img selection. The <border_selected> is used for the current page if set.
\Examples:
[more-list next.gif prev.gif page_num.cgi 3] causes anchors of:
Previous <IMG SRC="prev.gif" Border=3> Page 1 <IMG SRC="/cgi-bin/page_num.cgi?1"> Page 2 <IMG SRC="/cgi-bin/page_num.cgi?2"> Next <IMG SRC="next.gif" Border=3>
-
[more-list next.gif prev.gif page_num.cgi] causes anchors of:
Previous <IMG SRC="prev.gif"> Page 1 <IMG SRC="/cgi-bin/page_num.cgi?1"> Page 2 <IMG SRC="/cgi-bin/page_num.cgi?2"> Next <IMG SRC="next.gif">
-
[more-list next.gif prev.gif 0 0] causes anchors of:
Previous <IMG SRC="prev.gif" Border=0> Page 1 <IMG SRC="/cgi-bin/page_num.cgi?1"> Page 2 <IMG SRC="/cgi-bin/page_num.cgi?2"> Next <IMG SRC="next.gif" Border=0>
-
To set custom text for the "Previous" and "Next" usually used, define the next_img, prev_img, and page_img with [next-anchor][/next-anchor], [prev-anchor][/prev-anchor], [first-anchor][/first-anchor], [last-anchor][/last-anchor] and [page-anchor][/page-anchor]. The string $PAGE$ will be replaced with the page number in the latter. The same example:
[more-list] [first-anchor] First [/first-anchor] [next-anchor] Forward | [/next-anchor] [prev-anchor] Back [/prev-anchor] [last-anchor] Last [/last-anchor] [page-anchor] Page $PAGE$ (matches $MINPAGE$-$MAXPAGE$) | [/page-anchor] [more] [/more-list]
-
will display Forward | Page 1 (matches 1-50) | Page 2 (matches 51-77) | Back for 2 pages. Note that the following anchors are replaced with the page number, the minimum match on the page, and the maximum match on the page:
$PAGE$ Page number $MINPAGE$ Minimum match on page $MAXPAGE$ Maximum match on page
-
You can customize the HTML hyperlink with [link-template] [/link-template]. This is useful for adding a JavaScript onclick attribute, or setting the link target to a different window, etc.
[link-template]<a href="$URL$" target="_top">$ANCHOR$</a>[/link-template]
-
There are two tokens you can use as many times as needed in [link-template], which will be replaced as follows:
$URL$ The URL for the 'more' page in question $ANCHOR$ The page number or the word "Next" or "Previous" for the link in question.
-
If have many pages of matches and don't wish to have all displayed at once, set [decade-next][/decade-next] and [decade-prev][/decade-prev]. If set them empty, a search with 31 pages will display pages 21-30 like:
Previous 1 2 3 4 5 6 7 8 9 10 [more>>] Next
-
and pages 11-20 like:
Previous [<<more] 11 12 13 14 15 16 17 18 19 20 [more>>] Next
-
If set to [decade-next](higher)[/decade-next] and [decade-prev](lower)[/decade-prev], the following will be displayed:
Previous (lower) 11 12 13 14 15 16 17 18 19 20 (higher) Next
-
Of course, image-based anchors can be used as well.
[/more-list]
-
Companion to [more-list].
[more]
-
Inserts a series of hyperlinks that will call up the next matches in a series. They look like this:
Previous 1 2 3 4 5 6 Next
-
The current page will not be a hyperlink. Every time the new link is pressed, the list is re-built to correspond to the current page. If there is no Next or Previous page, that link will not be shown.
See the search.html file for examples. Make sure to insert this item between a [more-list] and [/more-list] element pair.
[process-search]
-
Outputs the complete URL for a search, including Interchange session tags. Used as the ACTION value for the search form. This is exactly the same as [area search].