Perl Search Script for your Website, Perl Search engine, MySQL Search Script

Please read the Perl Services Licensing Agreement

By downloading, purchasing, acquiring and/or implementing any PerlServices software, you agree to be bound by the terms and conditions of the distribution policy.

To Top

Introduction

Thank you for choosing PSLightningSearch.

The is a very powerful, easy to use, setup and configure search engine. This search engine does full document searches and does not require an index. Each search can be in real time so results are always up to date. Or you can index your site for even faster search processing.

To Top

Requirements

PSLightningSearch can be installed on Unix, Linux, Mac, or Windows servers that have Perl enabled (a cgi-bin).

To Top

Configuration

There is only one few configuration item you need address, and that is your path to Perl. Although the default path we've included is correct on around 95% of servers.

All CGI programs written in Perl must start with a line that tells the web server where to look for the Perl interpreter. This means the very first line of each of the .cgi files MUST be the Path to Perl. Here are some examples of the most common paths to Perl:

#!/usr/lib/perl
#!/usr/bin/perl
#!/usr/local/bin/perl

This program was shipped with a default path of: #!/usr/bin/perl

The first configuration item to address is to make sure that this is the correct Path to Perl for your web server. Your Host's support/FAQ pages will tell you what the correct Path to Perl is for your web server. If this information can not be found on the support/FAQ pages then you should contact your System Administrator or Support Dept. to find out the correct value. In lieu of them being available, the samples above are fairly standard. Try them all out in the order above and see if any work for you.

On most servers, this should be the end of any configuration changes you have to set in the script. Please note that you do not have to set any variables in any of the scripts unless you encounter errors during the Installation Process.

This program uses our advanced set-up routine, which will create all it's own directories and set it's own permissions on data directories. If the program encounters a problem during the set-up process, you will be given specific directions on what to do. If the instructions given don't allow you to successfully install the program or you are not comfortable following the instructions, contact us through the Perl Services support page.

To Top

Installation

To install this program, you must have an FTP client and be familiar with how to use its basic functions. If your not sure how to achieve any of the stated functions or commands with your FTP client, please refer to our tutorial on installation perl scripts and on using FTP clients.

Here are the installation steps:

1. Open your FTP client and connect to your web space.

2. In your cgi-bin (some call it just "cgi") create a sub-directory with any legal name that you want (i.e. "search").

3. CHMOD this sub-directory to 755 (rwx-rx-rx).

4. Change into this sub-directory with your FTP client.

5. Making sure your FTP client is set to transfer in ASCII mode and not binary mode, transfer all cgi files into the newly created sub-directory.

6. CHMOD each of the .cgi files to 755 (rwx-rx-rx).

7. Launch your web browser and in the address line of the browser, type the full URL to the search_setup.cgi script:

i.e. http://www.foo.com/cgi-bin/search/search_setup.cgi

8. You should now see a set-up screen asking you to enter a User Name and Password (you have to enter the password twice). If you see this screen, it means the program has been configured correctly. Enter your new User Name and Password. Enter the Password a second time in the space provided. Submit the form.

If you made any mistakes along the way, you will get a warning message with instructions on what to do to correct the error. If you get an error that says the program could not set-up the password file, this means that the program is unable to access the data directory. If this was the first pass through the set-up screen, then there is a server specific configuration issue. Contact us at our support centre for assistance.

If you're on a server that requires .pl extensions (Some Windows servers), rename all files so they have a .pl extension, then edit the following files :

search.cgi
search_admin.cgi
search_setup.cgi

Look for :

my $ext = "cgi"; and change it to my $ext = "pl";

near the very top of all three scripts, then re-upload them and call the search_setup.pl script in your browser.

To Top

Quick Start Guide

Log in to the administration program and click on the "Search WebSite" link at the top right of the Page. You should be able to perform a Live search on your site.

To Top

Administration Function Bar

After logging into the administration program, the top portion of the screen will contain the administration functions. Use this to navigate the various options and functions that this administration program contains.

To Top

Login

Whenever you wish to use the PSLightningSearch administration program, you must first sign into the program. Enter the full URL to the search_admin.cgi script in the address line of your browser. You will be presented with the login screen. Enter your user name and password and click the "Log in" button. At any time, you can change your password by clicking on "Change Pass". To do this, enter your current user name and password then enter your new user name and password. You will have to enter the new password twice.

To Top

Summary

When you sign into the administration program, you will be presented with the summary screen. This screen can also be reached at any time you are signed into the program by clicking on "Summary" on the top row of the function bar.

The summary screen is a screen you can use as an escape action to back out of a function/screen you don't wish to complete or wish to abandon. It also displays a full list of keywords searched for by your website visitors in order of popularity.

To Top

Change Password

You can change your administrative password at any time by clicking on "Change Pass" on the top row of the function bar. To change your password, you need to enter five pieces of information on the Change Password screen. First, you must enter your current user name and password. This information is validated against current values just to make sure someone doesn't change the information if you walk away from your terminal.

Next, enter your new user name and then enter your new password. You will have to enter your new password twice. When you click the button, the program will change your user name and password to the new settings.

To Top

Settings

The Settings screen is where you configure all of the options for the program operations. Most of these are sensibly pre-configured by the Installation process. You can however modify them to suit your desires.

To Top

Program Aesthetics

The Program Aesthetics, found at the top of the "Settings" pages, allow you to control Search Result output font and colors. For the Background colour, Text colour, Warning Messages (this is the color of highlighted words in each search result) and Mouseover link colour (this is also used as the color of the website address printed beneath each result), select a colour from the drop down list. If the colour you want isn't there, then you can enter your own Hex colour. Simply enter your Hex number (in the format "#ABC123") in that entry field. This will supercede any options selected from the drop down list of colours.

For a background image, enter the full URL (ie: http://www.foo.com/path/to/my_background.gif) in that Settings's entry field. You then have the option of specifying the repeat sequence for that background image. This sequencing is accomplished with style sheets. The option selected most often and the default setting on all browsers is "repeat".

Page Margins will be set on all pages that do not have a customized header (see below) associated with it. This value is in pixels and will apply to top, bottom, left side and right sides of the page.

You can select one of the pre-defined font faces/combinations from the drop down list. You can also enter your own combination of faces in the box below the list. Separate each value with a comma.

Font size can be selected from the drop down list. We hope we have included enough of a span for you.

Enter the name of your site in this field. It will be used to display on the title bar of the users browser and will be used in certain display messages within the program.

Enter an integer for the "Returns per page". This will determine how many results are displayed on a single page of search results.

Remember, if you're using a Custom Header and Footer, all of the above Aesthetic options are ignored. You control them entirely using your own HTML code and Style Sheets.

To Top

Indexed vs. Live Search

Running the search engine in Live Search mode will examine every single searchable page for the most up to the minute search results. Running the search engine in Indexed mode will still perform the same search but only the database since the last time the site indexer was run. This still returns a comprehensive search but also saves system resources especially if you have a large site with over a thousand pages to be searched.

To turn on the Index mode, follow these steps:

1) Click on Settings in the function bar.
2) Make sure your Directory list is up to date. Click on "Rebuild Tree" to fetch the full list of directories your website currently contains.
3) Remove any directories you do not want to be searchable, then save your changes.
4) Set "Use indexed search" to "Yes" then save your changes.
5) Click the "Index now" link and you're done.

Your site has just been indexed and is now up to date. If you have more than 250 files that are to be indexed, you will see a progress bar appear as PS Lightning search processes your website and stores all full text strings in your database.

To turn of the Index mode off and go back to Live Search, set "Use indexed search" to "No". Note that switching to Live mode will NOT destroy the previous index database.

To Top

Searchable Directories

We hummed and hawed over how to have the program perform it's searches. There were several options open to us, however, we settled on the most practical option. Rather than automatically searching your entire website, we have added provision for you specify exactly which directories can be searched. This means that if you don't want a directory included in the search, you don't list it. All directories that make up your website are automatically listed. If you ever need to rebuild the list, simply click on "Rebuild Tree" beside "Folders to search" on the "Settings" page.

Your directory tree is listed in alphabetical order.

To Top

Excluding Documents

Since you may have a series of testing documents, template documents or information you may not want returned on a search, the program easily allows you to exclude these from searching. Click on "Settings" on the function bar. Scroll down to "Docs to ignore" and enter the absolute path to all documents to be excluded. For example, if we had a document www.foo.com/products/test_index.html that we did not want returned then we would enter something similar to:

/usr/foo/public_html/products/test_index.html

Copy the path from the text box just above it that lists your Searchable Directories

To Top

Excluding Keywords

It is a good idea to establish a list of keywords that are to be ignored. For example, we recommend that you ignore keywords such as: am, are, is, was, were, been, be, the, if, how, where, it, etc. By eliminating them, you speed up the searches and return more accurate results. Note, however, that if the persons submits a search to match "This Phrase" then no keywords are ignored and the entire phrase is matched as is.

To Top

Custom Header

You can incorporate your website's look and feel in to the search result pages. Simply paste your HTML code in the box provided at the bottom of the Settings page. Be sure to include absolute paths in your element tags such as images and links. Set "Use Custom Header" to "Yes" and save the settings form. Remember, using your own custom code overrides the Aesthetical Settings.

To Top

Custom Footer

You can incorporate your website's look and feel in to the search result pages. Simply paste your HTML code in the box provided at the bottom of the Settings page. Be sure to include absolute paths in your element tags such as images and links. Set "Use Custom Footer" to "Yes" and save the settings form. Remember, using your own custom code overrides the Aesthetical Settings.

To Top

Log out

Whenever you are done working with the program or are going to be stepping away from your desk, we strongly urge you to log out by clicking the "Log out" link at the top of the page. Even if your working from home and stepping away from the desk, EXIT THE PROGRAM. It has been my experience that a curious six year old or a cat walking across the keyboard can wreck untold havoc on even the most careful users.

To Top

Search Log

Each time a Search is performed, parameters such as the Term used, Date and number of results are recorded. This data is then used to display the most popular keywords on the Summary Page. If you'd like to remove select Search phrases from the Search Log tick off the desired phrases and then Submit the form. Or to clear them all, scroll to the bottom of the Search log and click on "Check All" then Submit the form. Note that clearing your Search Log also affects the KeyWord rankings on the Summary Page.

To Top

Search Forms

Two types of search forms are generated by the program. The first is a small search form with predefined criteria and the second is an advanced search form that allows your visitor to select the type of search to be performed. Beneath the search form is a textbox that allows you to enter a custom message if no matches were found. The special marker,

%%%TERM%%%

is replaced with the term entered by the user. You can place this marker anywhere in the message, any number of times.

If at any time, you have removed or entered code that is causing the page to render erroneously, you can restore the default form by placing a tick in the "Restore default" checkbox. Submit the form and the selected files will be restored to their original state.

To Top

Simple search

By default, the simple search form will allow the user to search your entire site (the files and folders you have listed or indexed) using an "Any word" search. Simply copy and paste the code to any web document and you're set. However, you may change the search criteria by adding hidden form fields. Use the hidden form tags below to change the functionality of the simple search from :

And search
<input type="Hidden" name="type" value="and">

Exact search
<input type="Hidden" name="type" value="exact">

You can also specify which folders should be searched. By default the files and folders you have listed or indexed will be searched. If you have just set up the program and have not yet changed your settings, your entire site will be searched. To search specified folders, enter the path (starting with your root folder) to the folder that should be searched. Your root folder is the folder your home page resides in. Separate each folder with a comma. To search all folders within specified folders, add an * to the end of each path. See examples below.

One folder search
<input type="Hidden" name="dirs" value="tutorials">

Three folder search
<input type="Hidden" name="dirs" value="tutorials, faqs, docs/large/movies">

All folders listed search
<input type="Hidden" name="dirs" value="all">

All folders listed search
<input type="Hidden" name="dirs" value="*">

Root folder search
<input type="Hidden" name="dirs" value="/">

Recursive folder search
<input type="Hidden" name="dirs" value="tutorials*, faqs, docs*">

In the last example, all folders and sub folders within the tutorials folder and all folders and sub folders within the docs folder will also be searched.

To Top

Advanced search

As with the Simple search form, the Advanced searched form can also be edited and restored. The Advanced search form is displayed on the results page, beneath any results returned. You can use the Advanced search form in place of the simple search and it accepts the same parameters but which can be displayed in a visual format. The folders to search must be displayed in a drop down select menu using the same values and conventions as used in the Simple Search Form.

Select Menu
<select name="dirs">
<option value="tutorials*, faqs, /docs/large*">Tutorials, FAQs, Docs
<option value="tutorials">Tutorials
<option value="/">Root Folder
<option value="*">Entire Site
</select>

In the example above, the following folders will be searched depending on which option the user selected.

tutorials and all folders and sub folders with it, faqs, /docs/large and all folders and sub folders with it.

tutorials (just the tutorials folder)

root folder (this is the folder your home page resides in)

Entire site (all folders specified in your settings)

One of three search types are available (and, or, exact). Type selection is made possible through the use of Radio Buttons. If no type is passed to the script, a type of "or" will be used which searches for any word entered by the user. Each Radio button must have a name value of "type". Use the "checked" keyword to specify which type should be checked by default.

Search Type
<input type="Radio" name="type" value="or" checked>

<input type="Radio" name="type" value="and">

<input type="Radio" name="type" value="exact">

To Top

No Results Message

Sometimes, a visitor is looking for something you have not addressed in your documentation or web site information, subsequently no results are found or printed. Rather than leave the searcher bewildered and optionless, you can guide them with instructions or alternative options with your own Custom message. To enter/modify the default message, click on "Search Forms" in the function bar and scroll to the bottom text box.

To Top

Support

If you are unable to set-up this program or are uncomfortable setting up the program then please contact our support department. We offer an installation service for a small fee, details of which are available at the support centre.

To Top

PS Lightning Search 3.1