\& Search in title \& artist \& .Ve Once again, this does not conduct a search on an \s-1SQL\s0 database, but formats a corresponding text-based search. Parentheses will have no effect, and an \s-1OR\s0 condition will cause all conditions to be \s-1OR\s0. The searches above would be similar to: .PP .Vb 11 \& [page search=" \& co=yes \& sf=artist \& op=rm \& se=[value artist] \& sf=title \& op=rm \& se=[value title] \& " ] \& Search for [value artist], [value title] \& .Ve .Vb 9 \& [page search=" \& co=yes \& sf=[value column] \& op=rm \& se=[value searchstring] \& " ] \& Search for [value searchstring] \& in [value column] \& .Ve .Sh "One-Click Searches" .IX Subsection "One-Click Searches" Interchange allows a search to be passed in a \s-1URL\s0, as shown above. Just specify the search with the special page parameter search or special page scan. Here is an example: .PP .Vb 6 \& [page search=" \& se=Impressionists \& sf=category \& "] \& Impressionist Paintings \& .Ve This is the same: .PP .Vb 3 \& [page scan se=Impressionists/sf=category] \& Impressionist Paintings \& .Ve Here is the same thing from a home page (assuming /cgi-bin/vlink is the \s-1CGI\s0 path for Interchange's vlink): .PP .Vb 3 \& \& Impressionist Paintings \& .Ve The two-letter abbreviations are mapped with these letters: .PP .Vb 62 \& ac mv_all_chars \& bd mv_base_directory \& bs mv_begin_string \& ck mv_cache_key \& co mv_coordinate \& cs mv_case \& cv mv_verbatim_columns \& de mv_dict_end \& df mv_dict_fold \& di mv_dict_limit \& dl mv_dict_look \& DL mv_raw_dict_look \& do mv_dict_order \& dr mv_record_delim \& em mv_exact_match \& er mv_spelling_errors \& ff mv_field_file \& fi mv_search_file \& fm mv_first_match \& fn mv_field_names \& hs mv_head_skip \& ix mv_index_delim \& lb mv_search_label \& lf mv_like_field \& lo mv_list_only \& lr mv_search_line_return \& ls mv_like_spec \& ma mv_more_alpha \& mc mv_more_alpha_chars \& md mv_more_decade \& ml mv_matchlimit \& mm mv_max_matches \& MM mv_more_matches \& mp mv_profile \& ms mv_min_string \& ne mv_negate \& ng mv_negate \& np mv_nextpage \& nu mv_numeric \& op mv_column_op \& os mv_orsearch \& pf prefix \& ra mv_return_all \& rd mv_return_delim \& rf mv_return_fields \& rn mv_return_file_name \& rr mv_return_reference \& rs mv_return_spec \& se mv_searchspec \& sf mv_search_field \& sg mv_search_group \& si mv_search_immediate \& sm mv_start_match \& sp mv_search_page \& sq mv_sql_query \& sr mv_search_relate \& st mv_searchtype \& su mv_substring_match \& tf mv_sort_field \& to mv_sort_option \& un mv_unique \& va mv_value .Ve These can be treated just the same as form variables on the page, except that they can't contain a new line. If using the multi-line method of specification, the characters will automatically be escaped for a \s-1URL\s0. .PP \&\s-1IMPORTANT\s0 \s-1NOTE:\s0 An incompatibility in earlier Interchange catalogs is specifying [page scan/se=searchstring]. This is interpreted by the parser as [page scan/se=\*(L"searchstring\*(R"] and will cause a bad \s-1URL\s0. Change this to [page scan se=searchstring], or perhaps better yet: .PP .Vb 3 \& [page search=" \& se=searchstring \& "] .Ve A one-click search may be specified in three different ways. .Ip "Original" 4 .IX Item "Original" To do an \s-1OR\s0 search on the fields category and artist for the strings \&\*(L"Surreal\*(R" and \*(L"Gogh,\*(R" while matching substrings, do: .Sp .Vb 2 \& [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=cat Van Gogh -- compare to surrealists \& .Ve gory] .Sp In this method of specification, to replace a / (slash) in a file name (for the sp, bd, or fi parameter), the shorthand of :: must be used, i.e., sp=results::standard. (This may not work for some browsers, so put the page in the main pages directory or define the page in a search profile.) .Ip "Multi-Line" 4 .IX Item "Multi-Line" Specify parameters one to a line, as well. .Sp .Vb 7 \& [pag se="Van Gogh" \& sp=lists/surreal \& os=yes \& su=yes \& sf=artist \& sf=category \& ] Van Gogh -- compare to surrealists .Ve .Vb 1 \& scan .Ve Any \*(L"unsafe\*(R" characters will be escaped. To search for trailing spaces (unlikely), quote. .Ip "Ampersand" 4 .IX Item "Ampersand" Substitute & for / in the specification and be able to use / and quotes and spaces in the specification. .Sp .Vb 2 \& [page href=scan se="Van Gogh"&sp=lists/surreal&os=yes&su=yes&sf=a Van Gogh -- compare to surrealists \& .Ve tist] .Sp Any \*(L"unsafe\*(R" characters will be escaped. .Sh "Setting Display Options with mv_value" .IX Subsection "Setting Display Options with mv_value" A value can be specified that will be set in the link with the mv_value parameter. It takes an argument of var=value, just as setting a normal variable in an Interchange profile. Actually mv_value is a misnomer, it will almost never be used in a form where variable values can be set. Always specify it in a one-click search with va=var=value. Example: .PP .Vb 5 \& [page href=scan \& arg="se=Renaissance \& se=Impressionists \& va=category_name=Renaissance and Impressionist Paintings \& os=yes"]Renaissance and Impressionist Paintings .Ve Display the appropriate category on the search results page with [value category_name]. .Sh "In-Page Searches" .IX Subsection "In-Page Searches" To specify a search inside a page with the [search-region parameters*] tag. The parameters are the same as the one-click search, and the output is always a newline-separated list of the return objects, by default, a series of item codes. .PP The [loop ...] tag directly accepts a search parameter. To search for all products in the categories \*(L"Americana\*(R" and \*(L"Contemporary,\*(R" do: .PP .Vb 9 \& [loop search=" \& se=Americana \& se=Contemporary \& os=yes \& sf=category9 \& "] \& Artist: [loop-field artist]
\& Title: [loop-field title]
\& [/loop] .Ve The advantage of the in-page search is that searches can be embedded within searches, and there can be straight unchanging links from static \s-1HTML\s0 pages. .PP To place an in-page search with the full range of display in a normal results page, use the [search-region] tag the same as above, except that [search-list], [more-list], and [more] tags can be placed within it. Use them to display and format the results, including paging. For example: .PP .Vb 15 \& [search-region more=1 \& search=" \& se=Americana \& sf=category \& ml=2 \& "] \& [more-list][more][/more-list] \& [search-list] \& [page [item-code]] \& [item-field title], by [item-field artist] \& [/search-list] \& [no-match] \& Sorry, no matches for [value mv_searchspec]. \& [/no-match] \& [/search-region] .Ve \&\fBNote: \fRThe [item-code] above does not need to be quoted because it is replaced before the [page ...] tag is interpolated. If building large lists, this is worth doing because unquoted tags are twice as fast to parse. .PP To use the same page for search paging, make sure to set the sp=page parameter. .Sh "Search Profiles" .IX Subsection "Search Profiles" An unlimited number of search profiles can be predefined that reside in a file or files. To use this, make up a series of lines like: .PP .Vb 3 \& mv_search_field=artist \&mv_search_field=category \&mv_orsearch=yes .Ve These correspond to the Interchange search variables that can be set on a form. Set it right on the page that contains the search. .PP .Vb 5 \& [set artist_profile] \&mv_search_field=artist \&mv_search_field=category \&mv_orsearch=yes \&[/set] .Ve This is the same: .PP .Vb 5 \& [set artist_profile] \&sf=artist \&sf=category \&os=yes \&[/set] .Ve Then, in the search form, set a variable with the name of the profile: .PP .Vb 1 \& .Ve In a one-click search, use the mp modifier: .PP .Vb 1 \& [page scan se=Leonardo/mp=artist_profile]A left-handed artist .Ve They can also be placed in a file. Define the file name in the SearchProfile directive. The catalog must be reconfigured for Interchange to read it. The profile is named by placing a name following a _\|_NAME_\|_ pragma: .PP .Vb 1 \& __NAME__ title_search .Ve The _\|_NAME_\|_ must begin the line, and be followed by whitespace and the name. .PP The special variable mv_last stops interpretation of search variables. The following variables are always interpreted: .PP .Vb 2 \& mv_dict_look \& mv_searchspec .Ve Other than that, if mv_last is set in a search profile, and there are other variables on the search form, they will not be interpreted. .PP To place multiple search profiles in the same file, separate them with _\|_END_\|_, which must be on a line by itself. .Sh "Search Reference" .IX Subsection "Search Reference" The supplied simple/srchform.html and simple/results.html pages show example search forms. Modify them to present the search in any way desired. Be careful to use the proper variable names for passing to Interchange. It is also necessary to copy the hidden variables as-is. They are required to interpret the request as a search. .PP \&\fBNote: \fRThe following definitions frequently refer to field name and column and column number. All are the references to the columns of a searched text file as separated by delimiter characters. .PP The field names can be specified in several ways. .Ip "ProductFiles" 4 .IX Item "ProductFiles" If the file to be searched is left empty in the search form or definition (it is set with mv_search_file (fi)), the text files associated with the products databases will be searched, and field names are already available as named in the first line of the \fIfile\fR\|(s). This is defined to be products.txt in the Interchange demo catalogs. .Sp Be careful if using \s-1SQL\s0! If the database is changed and not exported with [tag export products][/tag], searches will not be successful. .Ip "Other database files" 4 .IX Item "Other database files" If the file or files to be searched are \s-1ASCII\s0 delimited files, and have field names specified on the first line of the file, Interchange will read the first line (of the first file) and determine the field names. .Ip "Other files" 4 .IX Item "Other files" If the file or files to be searched are \s-1ASCII\s0 delimited files, but don't have field names specified on the first line of the file, set the variable mv_field_names to a comma-separated list of field names as they will be referenced. .PP Fields can also always be specified by an integer column number, with 0 as the first column. .Ip "mv_all_chars" 4 .IX Item "mv_all_chars" Scan abbreviation: ac=[1|0]. Set this if searching is anticipated for lots of punctuation characters that might be special characters for Perl. The characters ()[]\e$^ are included. .Ip "mv_base_directory" 4 .IX Item "mv_base_directory" Scan abbreviation: bd=/directory/name. In the text search, set to the directory from which to base file searches. File names without leading / characters will be based from there. In the Glimpse search, passed to Glimpse with the \-H option, and Glimpse will look for its indices there. Default is ProductDir. .Sp If an absolute path directory is used, for security enable it in the users session with: .Sp .Vb 1 \& [set /directory/name]1[/set] .Ve This prevents users from setting an arbitrary value and viewing arbitrary files. .Ip "mv_begin_string" 4 .IX Item "mv_begin_string" If this is set, the string will only match if it is at the beginning of a field. The handling is a bit different for the default \s-1AND\s0 search compared to the \s-1OR\s0 search. With \s-1OR\s0 searches all words are searched for from the beginning of the field, with \s-1AND\s0 searches all are. .Sp This is a multiple parameter. If mv_coordinate is in force, it should be set as many times as necessary to match the field/searchstring combination. If set only once, it applies to all fields. If set more than once but not as many times as the fields, it will default to off. .Ip "mv_cache_key" 4 .IX Item "mv_cache_key" Not normally set by the user. It is a value that provides a pointer to the search reference by the more function. .Ip "mv_case" 4 .IX Item "mv_case" If this item is set to No, the search will return items without regard to upper or lower case. This is the default. Set to Yes if case should be matched. Implement with a checkbox <\s-1INPUT\s0 TYPE=CHECKBOX> field. .Sp If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field. .Sp Scan abbreviation: cs .Ip "mv_column_op" 4 .IX Item "mv_column_op" In the coordinated search, the operation that will be performed to check the field for a search match. These operations are supported: .Sp .Vb 1 \& != Not equal to .Ve .Ip "" 4 If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field. .PP Note that several of the operators are the same. They do either numeric or string comparisons based on the status of mv_numeric (alias nu) for that column. .Ip "mv_coordinate" 4 .IX Item "mv_coordinate" If this item is set to Yes, and the number of search fields equals the number of search specs, the search will return only items that match field to spec. (The search specifications are set by stacked mv_searchspec and mv_search_field variables.) .Sp Case sensitivity, substring matching, and negation all work on a field-by field basis according to the following: .RS 4 .Ip "" 8 If only one instance of the option is set, it will affect all fields. .Sp If the number of instances of the option is greater than or equal to the number of search specs, all will be used independently. Trailing instances will be ignored. .Sp If more than one instance of the options are set, but fewer than the number of search specifications, the default setting will be used for the trailing unset options. .Sp If a search specification is blank, it will be removed and all case-sensitivity/negation/substring options will be adjusted accordingly. If you need a blank string to match on, use quotes (""). .RE .RS 4 .RE .Ip "mv_dict_end" 4 .IX Item "mv_dict_end" If the string at the beginning of a line lexically exceeds this value, matching will stop. Ignored without mv_dict_look. .Ip "mv_dict_fold" 4 .IX Item "mv_dict_fold" Make dictionary matching case-insensitive. Ignored without mv_dict_look. .PP \&\fBNote: \fRThis is the reverse sense from mv_case. .Ip "mv_dict_limit" 4 .IX Item "mv_dict_limit" Automatically set the limiting string (mv_dict_end) to be one character greater than the mv_dict_look variable, at the character position specified. A value of 1, for instance, will set the limiting string to \*(L"fprsythe\*(R" if the value of mv_dict_look is \*(L"forsythe\*(R". A useful value is \-1, which will increment the last character (setting the mv_dict_end to \*(L"forsythf\*(R" in our example). This prevents having to scan the whole file once a unique match is found. .PP \&\fBNote: \fRThe order of this and the mv_dict_end variable is significant. Each will overwrite the other. .Ip "" 4 If this is set to a non-numeric value, an automatic mode is entered which looks for a dictionary-indexed file that corresponds to the file name plus .field, where field is whatever mv_dict_limit is set to. The actual value of mv_dict_limit is set to \-1. If the file does not exist, the original file is silently used. Also, the value of mv_return_fields is set to 1 to correspond to the location of the key in the auto-indexed file. .Sp To illustrate: .Sp .Vb 1 \& .Ve gory> .Sp is equal to: .Sp .Vb 2 \& \& .Ve \&\*(L"\-1\*(R"> .Sp The real utility would be in a form construct like .Sp .Vb 4 \& Sear beginning with .Ve h for .Sp which would allow automatic binary search file selection. .Sp Combined with the \s-1INDEX\s0 attribute to the Database directive, this allows fast binary search qualification combined with regular mv_searchspec text searches. .Ip "mv_dict_look" 4 .IX Item "mv_dict_look" The string at which to begin matching at in a dictionary-based search. If not set, the mv_dict_end, mv_dict_fold, and mv_dict_case variables will be ignored. May be set in a search profile based on other form variables. .Ip "mv_dict_order" 4 .IX Item "mv_dict_order" Make dictionary matching follow dictionary order, where only word characters and whitespace matter. Ignored without mv_dict_look. .Ip "mv_doit" 4 .IX Item "mv_doit" This can be set to search to make a form with a process action be a search page by default. The mv_todo variable takes precedence. .Ip "mv_exact_match" 4 .IX Item "mv_exact_match" Normally Interchange searches match words, as opposed to sentences. This behavior can be overridden with mv_exact_match, which when set will place quotes around any value in mv_searchspec or mv_dict_look. .Ip "mv_field_file" 4 .IX Item "mv_field_file" If you want to search a file which has no field header on the first line, you can specify a file to get the field names from. It expects a single line with the field names separated by \s-1TAB\s0 characters. .Ip "mv_field_names" 4 .IX Item "mv_field_names" Deprecated in favor of in-list sorting. Defines the field names for the file being searched. This guarantees that they will be available, and prevents a disk access if using named fields on a search file (that is not the product database \s-1ASCII\s0 source, where field names are already known). This must be exactly correct, or it will result in anomalous search operation. Usually passed in a hidden field or search profile as a comma-separated list. .PP \&\fBNote: \fRUse this on the product database only if planning on both pre-sorting with mv_sort_field and then post-sorting with [sort]field:opt[/sort]. .Ip "mv_first_match" 4 .IX Item "mv_first_match" Normally Interchange will return the first page of a search. If this variable is set, it will start the search return at the match specified, even if there is only one page. If set to a value greater than the number of matches, it will act as if no matches were found. .Ip "mv_head_skip" 4 .IX Item "mv_head_skip" Normally Interchange searches all lines of an index/product file but the first. Set this to the number of lines to skip at the beginning of the index. Default is 1 for the text search, which skips the header line in the product file. Default is 0 for a Glimpse search. .Ip "mv_index_delim" 4 .IX Item "mv_index_delim" Sets the delimiter for counting fields in a search index. The default is \s-1TAB\s0. It should rarely be changed unless you are searching a pipe-delimited or colon-delimited file. .Ip "mv_like_field" 4 .IX Item "mv_like_field" Specifies a field in a database search which should be used for a screening function based on the \s-1SQL\s0 like function. Needs mv_like_spec. .Ip "mv_like_spec" 4 .IX Item "mv_like_spec" The string that should be searched for in mv_like_field. The behavior of the % character and case-sensitivity depends on your \s-1SQL\s0 implementation. .Ip "mv_matchlimit" 4 .IX Item "mv_matchlimit" Function depends upon context. When the search results display is handled by one of the mechanisms which works with [more] lists (such as [search-region]), mv_matchlimit determines the number of results per page. If more matches than mv_matchlimit are found, the search paging mechanism will be employed if the proper [more-list] is present. When the search results are displayed as one continuous list (i.e.: with [loop search=\*(L"...\*(R"]), mv_matchlimit is equivalent in function to mv_max_matches. .Sp To have no matchlimit, use \fBnone\fR instead of a number. \fBall\fR does the same thing (since returning \*(L"all\*(R" is just anothing way of looking at no matchlimit). .Sp If no matchlimit is provided, or an invalid setting (some other string or 0) the default is taken from catalog variable \&\s-1MV_DEFAULT_MATCHLIMIT\s0, and if that's not set, is 50. .Ip "mv_max_matches" 4 .IX Item "mv_max_matches" The maximum number of records that will be returned in a search. Default is unlimited. If search results paging with [more-list] is to be employed, Use mv_matchlimit to set the number of results per page. .Ip "mv_min_string" 4 .IX Item "mv_min_string" Sets the minimum size of a search string for a search operation. Default is 4 for the Glimpse search, and 1 for the text search. .Ip "mv_negate" 4 .IX Item "mv_negate" Specifies that records \s-1NOT\s0 matching the search criteria will be returned. Default is no. It is not operative for the Glimpse search. .Sp If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field. .Ip "mv_orsearch" 4 .IX Item "mv_orsearch" If this item is set to Yes, the search will return items matching any of the words in searchspec. The default is No. .Ip "mv_profile" 4 .IX Item "mv_profile" Selects one of the pre-defined search specifications set by the SearchProfile directive. If the special variable within that file, mv_last, is defined, it will prevent the scanning of the form input for further search modifications. The values of mv_searchspec and mv_dict_look are always scanned, so specify this to do the equivalent of setting multiple checkboxes or radioboxes with one click, while still reading the search input text. .Ip "mv_record_delim" 4 .IX Item "mv_record_delim" Sets the delimiter for counting records in a search index. The default is newline, which works for the products and most line-based index files. .Ip "mv_return_fields" 4 .IX Item "mv_return_fields" The \fIfield\fR\|(s) that should be returned by the match, specified either by field name or by column number, separated by commas. Do not list the same field more than once per search. Specify 0 as the first field to be returned if searching the products database, since that is the key for accessing database fields. .PP As with \s-1SQL\s0 queries, you can use the '*' shortcut to return all fields. For example: .PP .Vb 1 \& [loop search="fi=nation/ra=yes/rf=*"] .Ve when used with a hypothetical 'nation' table would be equivalent to: .PP .Vb 5 \& [loop search=" \& fi=nation \& ra=yes \& rf=code,sorder,region,name,tax \& "] .Ve as well as: .PP .Vb 1 \& [loop search="fi=nation/ra=yes/rf=0,1,2,3,4"] .Ve and: .PP .Vb 1 \& [query sql="select * from nation"][/query] .Ve However, you probably rarely need to use every single field in a row. For maximum maintainability and execution speed the best practice is to list by name only the fields you want returned. .Ip "mv_return_spec" 4 .IX Item "mv_return_spec" Returns the string specified as the search (i.e., the value of mv_searchspec) as the one and only match. Typically used in a SKU/part number search. .Ip "mv_search_field" 4 .IX Item "mv_search_field" The \fIfield\fR\|(s) to be searched, specified either by column name or by column number. .Sp If the number of instances matches the number of fields specified in the mv_searchspec variable and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order). .Ip "mv_search_file" 4 .IX Item "mv_search_file" In the text search, set this variable to the \fIfile\fR\|(s) to be scanned for a match. The default, if not set, is to scan the default ProductFiles (i.e., products.txt). If set multiple times in a form (for a text search), will cause a search all the files. One file name per instance. .Sp In the Glimpse search, follows the Glimpse wildcard-based file name matching scheme. Use with caution and a liberal dose of the Glimpse man page. .Ip "mv_search_match_count" 4 .IX Item "mv_search_match_count" Set by the search to indicate the total number of matches found. .Ip "mv_search_page" 4 .IX Item "mv_search_page" The Interchange-style name of the page that should display the search results. This overrides the default value of search. .Ip "mv_searchspec" 4 .IX Item "mv_searchspec" The actual search string that is typed in by the customer. It is a text \s-1INPUT\s0 TYPE=TEXT field, or can be put in a select (drop-down) list to enable category searches. If multiple instances are found, they will be concatenated just as if multiple words had been placed in a text field. .Sp The user can place quotes around words to specify that they match as a string. To enable this by default, use the mv_exact_match variable. .Sp If mv_dict_look has a value, and mv_searchspec does not, then mv_searchspec will be set to the value of mv_dict_look. .Sp If the number of instances matches the number of fields specified in the mv_search_field variable and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order). .Ip "mv_searchtype" 4 .IX Item "mv_searchtype" If set to Glimpse, selects the Glimpse search (if Glimpse is defined). .Sp If set to db, iterates over every row of the database (not the associated text source file). .Sp If set to sql, same as db. .Sp If set to text, selects the text-based search. .Sp When using st=db, returned keys may be affected by TableRestrict. See \s-1CATALOG\s0.CFG. .Sp Defaults to text if Glimpse is not defined; defaults to Glimpse if it is defined. This can allow use of both search types if that is desirable. For instance, searching for very common strings is better done by the text-based search. An example might be searching for categories of items instead of individual items. .Ip "mv_small_data" 4 .IX Item "mv_small_data" .PP Tells the search engine that there is a small amount of data in the file and that it should perform the search function on every line. .PP Normally, when Interchange can find a fixed search expression it produces a \*(L"screening\*(R" function which will allow records to be quickly rejected when they don't match. If there are less than 50 records in the file or database, this may be counterproductive. .Ip "mv_sort_field" 4 .IX Item "mv_sort_field" The file \fIfield\fR\|(s) the search is to be sorted on, specified in one of two ways. If the \fIfile\fR\|(s) to be searched have a header line (the first line) that contains delimiter-separated field names, it can be specified by field name. It can also be specified by column number (the code or key is specified with a value of 0, for both types). These can be stacked if coming from a form or placed in a single specification separated by commas. .PP \&\fBNote: \fRIf specifying a sort for the product database, mv_field_names must be specified if doing a fieldname-addressed post-sort. .Ip "mv_sort_option" 4 .IX Item "mv_sort_option" The way that each field should be sorted. The flags are r, n, and f, reverse, numeric, and case-insensitive respectively. These can be stacked if coming from a form or placed in a single specification separated by commas. The stacked options will be applied to the sort fields as they are defined, presuming those are stacked. .Ip "mv_spelling_errors" 4 .IX Item "mv_spelling_errors" The number of spelling errors that will be tolerated. Ignored unless using Glimpse. For a large table, limit this to two. .Ip "mv_substring_match" 4 .IX Item "mv_substring_match" If mv_substring_match is set to Yes, matches on substrings as well as whole words. Typically set this for dictionary-based searches. .Sp If stacked to match the mv_search_field and mv_searchspec variables and mv_coordinate is set, it will operate only for the corresponding field. .Ip "mv_unique" 4 .IX Item "mv_unique" If set to a true value, causes the sort to return only unique results. This operates on whatever the search return is, as defined by mv_return_fields. .Ip "mv_value" 4 .IX Item "mv_value" This is normally only used in the one-click search (va=var=value). It allows setting of a session variable based on the clicked link, which makes for easy definition of headers and other display choices. (If had trouble using mv_searchspec for this before, this is what is needed.) .Sh "The Results Page" .IX Subsection "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. .PP On the search page, some special Interchange tags are used to format the otherwise standard \s-1HTML\s0. 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. .PP The basic structure looks like this: .PP .Vb 11 \& [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] .Ve 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. .Ip "[search-list]" 4 .IX Item "[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. .Sp The example tags shown have an item- prefix, which is the default. Set any prefix desired with the prefix parameter to [search-region]: .Sp .Vb 5 \& [search-region pref [search-list] \& SKU: [my-code] \& Title: [my-data products title] \& [/search-list] \& [/search-region] .Ve x=my] .Sp The standard set of Interchange iterative \s-1ITL\s0 tags are available. They are interpolated in this order: .Sp .Vb 21 \& [item-alternate N] true [else] false [/else] [/item-alte [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] .Ve nate] .PP \&\fBNote: \fRthose that reference the shopping cart do not apply, i.e., [item-quantity], [item-modifier ...] and friends. .Ip "[/search-list]" 4 .IX Item "[/search-list]" Ends the search list. .Ip "[no-match]" 4 .IX Item "[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. .Ip "[/no-match]" 4 .IX Item "[/no-match]" Ends the no match region. .Ip "[sort database:field:option* database:field:option*]" 4 .IX Item "[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 \s-1SORTING\s0. .Sp This is slow, and it is far better to pre-sort the return in the search specification. .Ip "[item-change marker]" 4 .IX Item "[item-change marker]" Active only within [search-list][/search-list]. .Sp 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]. .Sp Of course, this will only work as expected when the search results are properly sorted. .Sp 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. .Sp The following is a simple example for a search list that has a field category and subcategory associated with each item: .Sp .Vb 5 \& <
\& Page 2 
.Ve
er=3>
.Sp
[more-list next.gif prev.gif page_num.cgi] causes anchors of:
.Sp
.Vb 3
\& Previous
.Ve
gif">
.Sp
[more-list next.gif prev.gif 0 0] causes anchors of:
.Sp
.Vb 3
\& Previous
\& Page 2
.Ve
er=0>
.Sp
To set custom text for the \*(L"Previous\*(R" and \*(L"Next\*(R" 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 \f(CW$PAGE\fR$ will be replaced
with the page number in the latter. The same example:
.Sp
.Vb 7
\& [more [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]
.Ve
list]
.Sp
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:
.Sp
.Vb 2
\& $PAGE$ Page $MINPAGE$ Minimum match on page
\& $MAXPAGE$ Maximum match on page
.Ve
umber
.Sp
You can customize the \s-1HTML\s0 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.
.Sp
.Vb 1
\& [link-template]$ANCHOR$[/link-template]
.Ve
There are two tokens you can use as many times as needed in
[link-template], which will be replaced as follows:
.Sp
.Vb 2
\& $URL$ The URL for the 'more' page in qu $ANCHOR$ The page number or the word "Next" or "Previous"
\& for the link in question.
.Ve
stion
.Sp
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:
.Sp
.Vb 1
\& Previous 1 2 3 4 5 6 7 8 9 10 [more>>] Next
.Ve
and pages 11\-20 like:
.Sp
.Vb 1
\& Previous [<\& [/search-list] .Ve .Vb 4 \& [item-list] \& [sort products:price:rn] \& [item-price] [item-code]
\& [/item-list] .Ve .Vb 4 \& [loop search="ra=yes"] \& [sort products:category products:title] \& [loop-field category] [loop-field title]
\& [/loop] .Ve All sort situations, [search list], [loop list], [tag each table], and [item-list], take options of the form: .PP .Vb 1 \& [sort database:field:option* -n +n =n-n ... ] .Ve .Ip "database" 4 .IX Item "database" The Interchange database identifier. This must be supplied and should normally be 'products' if using the default name for the database. .Ip "field" 4 .IX Item "field" The field (column) of the database to be sorted on. .Ip "option" 4 .IX Item "option" None, any, or combinations of the options: .Sp .Vb 2 \& f case-insensitive sort (folded) (mutually exclusive n numeric order (mutually exclusive of f) \& r reverse sort .Ve of n) .Ip "\-n" 4 .IX Item "-n" The starting point of the list to be displayed, beginning at 1 for the first entry. .Ip "+n" 4 .IX Item "+n" The number of entries to display in this list segment. .Ip "=n-n" 4 .IX Item "=n-n" The starting and ending point of the list display. This is an alternative to \-n and +n. They should be specified in only one form. If both are specified, the last one will take effect. .Ip "..." 4 Don't really put ... in. This means that many sort levels are specified. Lots of sort levels with large databases will be quite slow. .PP Multiple levels of sort are supported, and database boundaries on different sort levels can be crossed. Cross-database sorts on the same level are not supported. If using multiple product databases, they must be sorted with embedded Perl. This is actually a feature in some cases, all items in a used database can be displayed before or after new ones in products. .PP Examples, all based on the simple demo: .Ip "Loop list" 4 .IX Item "Loop list" .Vb 3 \& [loop 00-0011 19-202 34-101 9 [sort products:title] \& [loop-code] [loop-field title]
\& [/loop] .Ve \&\-102] .Sp Will display: .Sp .Vb 3 \& 34-101 Family Po 00-0011 Mona Lisa \& 19-202 Radioactive Cats \& 99-102 The Art Store T-Shirt .Ve trait .Sp \&\eAlternatively: .Sp .Vb 3 \& [loop 00-0011 19-202 34-101 9 [sort products:title -3 +2] \& [loop-code] [loop-field title]
\& [/loop] .Ve \&\-102] .Sp \&\eDisplays: .Sp .Vb 1 \& 19-202 Radioactiv 99-102 The Art Store T-Shirt .Ve .Vb 1 \& Cats .Ve The tag [sort products:title =3\-4] is equivalent to the above. .Ip "Search list" 4 .IX Item "Search list" A search of all products (i.e., http://yoursystem.com/cgi-bin/simple/scan/ra=yes): .Sp .Vb 3 \& [search [sort products:artist products:title:rf] \& [item-field artist] [item-field title]
\& [/search-list] .Ve list] .Sp will display: .Sp .Vb 8 \& Gilded Grant Wood American Gothic \& Jean Langan Family Portrait \& Leonardo Da Vinci Mona Lisa \& Salvador Dali Persistence of Memory \& Sandy Skoglund Radioactive Cats \& The Art Store The Art Store T-Shirt \& Vincent Van Gogh The Starry Night \& Vincent Van Gogh Sunflowers .Ve Frame .Sp Note the reversed order of the title for Van Gogh and the presence of the accessory item Gilded Frame at the front of the list. It has no artist field and, as such, sorts first). .Sp Adding a slice option: .Sp .Vb 3 \& [search [sort products:artist products:title:rf =6-10] \& [item-field artist] [item-field title]
\& [/search-list] .Ve list] .Sp will display: .Sp .Vb 3 \& Sandy Skoglund Radioactiv The Art Store The Art Store T-Shirt \& Vincent Van Gogh The Starry Night \& Vincent Van Gogh Sunflowers .Ve .Vb 1 \& Cats .Ve If the end value/chunk size exceeds the size of the list, only the elements that exist will be displayed, starting from the start value. .Ip "Shopping cart" 4 .IX Item "Shopping cart" .Vb 3 \& [item [sort products:price:rn] \& [item-price] [item-code]
\& [/item-list] .Ve list] .Sp will display the items in the shopping cart sorted on their price, with the most expensive shown first. \s-1NOTE:\s0 This is based on the database field and doesn't take quantity price breaks or discounts into effect. Modifier values or quantities cannot be sorted. .Ip "Complete database contents" 4 .IX Item "Complete database contents" .Vb 3 \& [tag each pro [sort products:category products:title] \& [loop-field category] [loop-field title]
\& [/tag] .Ve ucts] .Sp A two level sort that will sort products based first on their category, then on their title within the category. .PP Note that large lists may take some time to sort. If a product database contains many thousands of items, using the [tag each products] sort is not recommended unless planning on caching or statically building pages. .SH "Shipping" .IX Header "Shipping" Interchange has a powerful custom shipping facility that performs \s-1UPS\s0 and other shipper lookups, as well as a flexible rule-based facility for figuring cost by other methods. .Sh "Shipping Cost Database" .IX Subsection "Shipping Cost Database" The shipping cost database (located in ProductDir/shipping.asc) is a tab-separated \s-1ASCII\s0 file with eight fields: code, text description, criteria (quantity or weight, for example), minimum number, maximum number, and cost, query, and options. None of the fields are case-sensitive. .PP To define the shipping database in a catalog configuration file, set the Variable \s-1MV_SHIPPING\s0 to what would be its contents. .PP To set the file to be something other than shipping.asc in the products directory, set the Special directive: .PP .Vb 1 \& Special shipping.asc /home/user/somewhere/shipping_defs .Ve There are two styles of setting which can be mixed in the same file. The first is line-based and expects six or more TAB-separated fields. They would look like: .PP .Vb 1 \& default No shipping weight 0 99999999 0 .Ve upsg \s-1UPS\s0 Ground weight 0 0 e Nothing to ship! upsg \s-1UPS\s0 Ground weight 0 150 u Ground [default zip 98366] 3.00 upsg \s-1UPS\s0 Ground weight 150 999999 e @@TOTAL@@ lbs too heavy for \s-1UPS\s0 .PP The second is a freeform method with a mode: Description text introducing the mode line. The special encoding is called out by indented parameters. The below is identical to the above: .PP .Vb 5 \& upsg: UPS Ground \& criteria weight \& min 0 \& max 0 \& cost e Nothing to ship! .Ve .Vb 7 \& min 0 \& max 150 \& cost u \& table 2ndDayAir \& geo zip \& default_geo 98366 \& adder 3 .Ve .Vb 3 \& min 150 \& max 999999 \& cost e @@TOTAL@@ lbs too heavy for UPS .Ve The second format has several advantages. Multiple lines can be spanned with the <<\s-1HERE\s0 document format, like so: .PP .Vb 9 \& upsg: UPS Ground \& criteria <