The search script can search a database and present the results in any form you like. This is handy for presenting products, news or events, or when used in combination with the form and replace scripts, for displaying content you manage from a back office administration area.
TABLE OF CONTENTS:
DATA FILE STRUCTURE:
The database is a simple tab delimited text file located in the /web/data directory, with records separated by carriage returns and fields separated by tabs. Files larger than 1Mb can be processed easily using this script. The first line of the file must contain field names. The file name is in the format "searchname.data".
Example data file:
You can create your own tab delimited data file by typing it into a text editor like Textpad, BBedit, Notepad or similar or you can create it from a spreadsheet program such as Microsoft Excel as follows:
first last phone fax email
Tom Doe 111-2222 222-3333 firstname.lastname@example.org
Nancy Smith 333-4444 444-5555 email@example.com
Andy Johnson 555-6666 666-7777 firstname.lastname@example.org
- Create the spreadsheet with headers on the first line and don't skip any lines.
- Save the file as a spreadsheet for later editing.
- Select from the menu: File-SaveAs
- Change the "Save as type:" to Text (Tab Delimited) (*.txt), give the file a name and click "Save".
- Rename the file you just created to filename.data instead of filename.txt.
- Open the file in Textpad, BBedit, Notepad or similar text editor.
- Because Excel may put quotation marks around certain information, perform the following procedure to remove them:
- Replace "" (two quotes together) with zzzzz or other nonsense sequence.
- Replace " (one quote) with nothing
- Replace zzzzz with " (one quote)
A search can be performed either using form tags or using the URL string. If you are using a form, the following html will perform a search on the data file searchname.data and select only those items in the field "fieldname" that the user enters in the text box. If nothing is entered, all records will be returned.
<form action="/cgi-bin/search.pl/searchname" method="post">
<input type="text" name="fieldname">
<input type="submit" value="Search Now">
For example, this is what a search of the above database would look like if the database was called sample.data and we wanted to search the field "last".
- searchname is the data file name's prefix to search (i.e. searchname.data).
- fieldname is the name of the field you wish to search.
- Any or all of the fields in your database can be used.
<form action="/cgi-bin/search.pl/sample" method="post">
<input type="text" name="last">
<input type="submit" value="Search Now">
The results template is a file in your /web/data directory called somename.html. By default, the script looks for a file with the same name as your database (e.g.. in this example, a file called sample.html). You can change the name of the template file, but you must call it with
f_success as shown below.
- In the template,
<! search> starts search results and
<! /search> ends search results and anything between the tags is repeated for each record matching the search criteria.
- Between these two tags, you can retrieve information from any field by using
<! FIELD="fieldname"> or you can print the search criteria itself by using
- The value for
<! FIELD="fieldname"> between
<! search> and
<! /search> will be replaced with matches to the search criteria.
- The value for
<! form_fieldname> between
<! search> and
<! /search> will produce the value of the search criteria itself.
- The value for
<! FIELD="fieldname"> outside
<! search> and
<! /search> will be replaced with the match from the first record that matches the search criteria.
For example, our sample database has a column for first with values Tom, Nancy and Andy in the three records. Assume the search criteria for a search is "an". The search will result in two records where the value of
<! FIELD="first"> between the search tags will yield Nancy in one and Andy in the other. The value of
<! form_first> between the search tags will yield the search criteria itself: an for both records. The value of
<! FIELD="first"> outside the search tags will yield Nancy since she is the first matching record.
This is what the html for a basic results template might look like:
<p>Here are the results of your search</p>
<! field=first><! field=last> - <! field=phone><br>
To display searches in a template with a different name than the data file name or to display different searches on the same data file in different formats or with different fields shown, define the template as follows:
*Note* templatefilename is the prefix only. For example, If the actual template were named mysearchresults.html - it would have a templatefilename of mysearchresults
<form action="/cgi-bin/search.pl/searchname?templatefilename" method=post> or use
<input type="hidden" name="f_success" value="templatefilename">
<input type="text" name="f_find"> will search the whole database rather than just one field. This can be combined with any other type of search... i.e. fieldname, o_fieldname, or e_fieldname.
By default, the script will return only Boolean "and" results. For example, if you searched a field called "Vehicle" for "Chevy" and "Ford" you would find no results since both (Boolean "and") must be present for success. However, using the o_ function, you can perform "or" searches within a field. There are two ways to use the "or" search.
One is with a multi-line select list. If you name the select list o_fieldyouaresearching... a user can select multiple values using control clicking, and the results will contain any data file line that contains ANY ONE of the selected values within the field you are searching.
The second way is with two input fields, both with the same. For example...
If the visitor enters Richard as the firstname and Dick as the Nickname, the search will return any line that contains EITHER Richard OR Dick in the firstname column.
- First Name
Use the format !(string) or not(string) in a search field. For example, if you have a database with a field called "pet" and values, "dog", "cat" or "hamster" and you wanted all the people who don't own dogs, you would put !(dog) in the field to get your results.
Normally, a search will return any value that contains the string for which the user is searching. For example, if you search a field called firstname for "Tim", it will return lines with a firstname value such as Tim, Timothy, Stimey, Stimpy, etc.
If you rename the input field e_firstname, it will only return those that contain Tim and ONLY Tim.
EXACT "OR" SEARCHES
The two concepts above can be combined by using oe_fieldname
You can specify
f_distinct with a value of
fieldname to select a single distinct record from many with the same value. (
fieldname is the name of the field you want to test.) For example, if you have a data file with 100 products for your on line store and each record includes a field that lists one of the ten categories your products might fall into, you could use this feature to search the data file and populate a drop list of categories. The code for the search might look like this:
If your search is looking for a value which contain an ampersand (&), you will have to add
f_ampersand with a value of "Yes" or the search will not find your results in the data file.
<Input type=hidden name="f_fail" value="Full URL"> for the response page for a failed search.
ERROR PAGE TEMPLATE
Use f_error to set up an error page template. This page will return errors not caught by f_fail, or will replace the fail page if f_fail is not present. The error page template must be in the data directory.
ALTERNATE DATA FILE LOCATION
<INPUT TYPE="hidden" NAME="f_error" VALUE="name.html"> sets the error page.
<Input type=hidden name="f_data" value="datafilename"> for the name of the data file if you don't want it to show up in the URL string
/cgi-bin/search.pl/searchname for use in the URL string.
- If your data file is /data/work/filename.data, use "work/filename" for value.
Any f_ can go in a configuration file in your /data folder rather than hidden fields in the html.
Configuration file name must be: filename.conf where filename is the data file name.
Example of file contents:
DIRECT URL SEARCH
checkref on or off (to disable referer checking)
You can search using a call from a URL without using a form as follows.
NUMBER OF RESULTS
<Input type=hidden name="f_sort" value="fieldname"> fieldname is the field to sort by.
<Input type=hidden name="f_sortorder" value="123"> is the default or
321 for reverse order or
random for random order.
<Input type=hidden name="f_sort2" value="fieldname"> fieldname is the field on which the script will perform a secondary sort. You can also use
f_sort3, f_sort4 and f_sort5.
<Input type=hidden name="f_sortorder2" value="123"> is the default or
321 for reverse order or
random for random order for the secondary sort order. As above, you can specify sortorder for up to five sorts.
NEXT - PREVIOUS
<Input type=hidden name="f_match" value="limit"> where limit is the maximum number of matches to return. The default is 50.
If you have a very long list of items that you would like to break up, you can display a fixed number of results at a time. Use f_match in the search to set the number you want displayed at a time on the results page.
Use the following fields to describe the results on the search results template:
Use these template tags like you would any other
- v_pagestart : number of first record displayed
- v_pageend : number of last record displayed
- v_found : total number found
- v_total : total items in database
<! FIELD=""> tag in the template. For example, the results page might have this above the
<! search> tag:
Page <! field="v_pagestart"> - <! field="v_pageend"> of <! field="v_found"> found.
or maybe this:
Displaying records <! field=v_pagestart> through <! field=v_pagend> of <! field=v_found> found in this search of <! field=v_total> database entries.
Use the following template tags to define the next and previous buttons and optionally, a list of pages if you want them. The "button content" can be images or text. Be sure these items are on separate lines as shown below. They do not need a break or paragraph between them, so they will display next to each other, but if they are written in the html on the same line, they may not produce the desired results. Only necessary links will show up. If there are no next or previous results, the "button content" will not display.
SAVE RESULTS AS HTML
<! SEARCHPREV>button content<! /SEARCHPREV>
<! SEARCHNEXT>button content<! /SEARCHNEXT>
You can save any search results as an html page. This might be useful if you had a back office administrative area for updating data files to generate dynamic content, but you want the search results page to be easily spidered by search engines. To save results as html, use the following fields:
IMPORTANT - You must list all allowable values for f_outputfile on separate lines in a file called
f_outputfile is the URL of html page to create
username is your username for admin functions
password is your password for admin functions
search.allow. This file must be located in your
www/data directory in order for the save function to work.
The search script can insert banner ads into the template page. There are three steps:
1) Make a hidden field called f_ads with a value that is the prefix of your ad data file.
2) Setup the data file as follows:
<input type="hidden" name="f_ads" value="adlist">
- You can also call this directly in a URL
- These would pull the ads randomly from a text file at /data/adlist.data
5 columns separated by tabs. The columns are in this order:
A http://www.cnn.comhttp://www.yoursite.com/pics/cnn.gif 20 30
A http://www.cubs.com http://www.yoursite.com/pics/gocubs.gif 50 50
B http://language.nashville.net http://www.yoursite.com/pics/languages.gif 40 40
If you gave your f_ads field in step 1 a name of "adverts" you would save your data file as adverts.data inside the data directory.
groupname link image width height
3) On the template page, insert
<! AD=nameofgroup> wherever you want the ad to show up. In the example above, I would call it either
<! AD=A> or
SPECIAL SWEB INSTRUCTIONS
If you are searching for data on our secure server AND are calling the search from any script-generated page (i.e. search inside of a search), you MUST add the following field to your search or it WILL NOT WORK:
<input type="hidden" name="f_username" value="usernameofsite"> OR add it to the url:
To calculate the sum total or the average of any field in your search results, there are two steps. First, you must tell the script you want to do a calculation on a certain field. Then you must display the results on your template page.
For step 1, add a hidden field to the form that calls the script or add a name/value pair to the search string. For example:
For step 2, on your results template, you may refer to the summed or averaged results as follows:
<input type="hidden" name="sum_fieldname" value="1"> or
where fieldname is the name of the field on which you wish to perform the calculations and the value represents the number of decimal places for the results display.
These tags may be be used inside or outside of the search tags, but they will always reflect the total sum or average of the search results for that field. If your search result displays 10 items and only 9 have a value, the average is calculated using the 9. If you want a zero calculated into the average, you must have a value of zero rather than a blank in your data set.
<! field="sum_fieldname"> displays the total
<! field="avg_fieldname"> displays the average
<! field="num_fieldname"> displays the number of items with values
SPECIAL -----111 INSTRUCTIONS
If you wish to use the search script with Build111, Church111 or Agent111 you can do so by adding
<input type="hidden" name="f_cms" value="XX" /> where XX is your site ID found in the top right hand corner of your administration area.
Search our on-line clothing store and add a product to your NetMerchant shopping cart. Here is a more complex example. Take a look at the code to see how it works. The database contains three categories of products with two products in each category and three sizes for each product. We won't dwell on NetMerchant here since it's not relevant to the search script, but we will show you the appropriate NetMerchant code when we get there if you're interested.