web design and hosting
features and pricing my account customer support about ICG Link, Inc. contact ICG Link, Inc.

Search.pl
   
 
 
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:
      first     last        phone       fax         email
      Tom       Doe         111-2222    222-3333    tomdoe@aol.com
      Nancy     Smith       333-4444    444-5555    nancy@smith.net
      Andy      Johnson     555-6666    666-7777    andy@johnson.biz
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:
  • 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)

MINIMUM NECESSARY:

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">
</form>

Notes:
  • 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.
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".
<form action="/cgi-bin/search.pl/sample" method="post">
Last: <input type="text" name="last">
<input type="submit" value="Search Now">
</form>
Last:
RESULTS TEMPLATES:
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 <! form_fieldname>.
  • 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:

<html>
<head>
<title>Search Results</title>
</head>
<body>
<p>Here are the results of your search</p>
<! search>
<! field=first><! field=last> - <! field=phone><br>
<! /search>
</body>
</html>

MULTIPLE TEMPLATES

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:
  • <form action="/cgi-bin/search.pl/searchname?templatefilename" method=post> or use
  • <input type="hidden" name="f_success" value="templatefilename">
*Note* templatefilename is the prefix only. For example, If the actual template were named mysearchresults.html - it would have a templatefilename of mysearchresults

OVERALL SEARCH

<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.

"OR" SEARCHES

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...
  • First Name <input name="o_firstname">
  • Nickname <input name="o_firstname">
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.

"NOT" SEARCHES

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.

EXACT SEARCHES

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

DISTINCT SEARCH

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:

http://www.icglink.com/cgi-bin/search.pl/products?f_distinct=category

SPECIAL CONSIDERATIONS

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.

FAILED SEARCH
  • <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.
    <INPUT TYPE="hidden" NAME="f_error" VALUE="name.html"> sets the error page.
ALTERNATE DATA FILE LOCATION
  • <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
  • Use /cgi-bin/search.pl?f_data=searchname or /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.
CONFIGURATION FILES

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:

sort value
sortorder value
checkref on or off (to disable referer checking)
DIRECT URL SEARCH

You can search using a call from a URL without using a form as follows.

http://www.icglink.com/cgi-bin/search.pl/datafilename?f_success=datafile&fieldname=value&...etc

SORTING
  • <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.
NUMBER OF RESULTS
  • <Input type=hidden name="f_match" value="limit"> where limit is the maximum number of matches to return. The default is 50.
NEXT - PREVIOUS

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:
  • 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
Use these template tags like you would any other <! 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.

<! SEARCHPREV>button content<! /SEARCHPREV>
<! SEARCHPAGES>
<! SEARCHNEXT>button content<! /SEARCHNEXT>
SAVE RESULTS AS HTML

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:
  • f_outputfile=/folder/pagename.html where f_outputfile is the URL of html page to create
  • username=icglink where username is your username for admin functions
  • password=secret where password is your password for admin functions
IMPORTANT - You must list all allowable values for f_outputfile on separate lines in a file called search.allow. This file must be located in your www/data directory in order for the save function to work.

BANNER ADS

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.
  • <input type="hidden" name="f_ads" value="adlist">
  • You can also call this directly in a URL
  • /cgi-bin/search.pl/searchname?f_ads=adfilename&f_success=sucesspagename
  • These would pull the ads randomly from a text file at /data/adlist.data
2) Setup the data file as follows:

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
5 columns separated by tabs. The columns are in this order:
groupname   link   image   width   height
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.

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 <! AD=B>.

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: /cgi-bin/search.pl/searchname?f_username=usernameofsite

CALCULATIONS

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:
<input type="hidden" name="sum_fieldname" value="1"> or
/cgi-bin/search.pl/searchname?sum_fieldname=1

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.
For step 2, on your results template, you may refer to the summed or averaged results as follows:
<! field="sum_fieldname"> displays the total
<! field="avg_fieldname"> displays the average
<! field="num_fieldname"> displays the number of items with values
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.

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.

EXAMPLE:

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.
Select a category:
ICG Link, Inc. 7003 Chadwick Drive, Suite 111, Brentwood, TN 37027