Customizing the FDSE layout using ASP
Overview and notes:
This article describes how the FDSE layout -- including the search tips page and the search results page -- can be rendered using Active Server Pages. This is intended for advanced developers who want to integrate FDSE into a web site that uses consistent, ASP-based layout on all pages.
FDSE can already crawl, index, and search ASP pages. No special techniques are necessary for that.
The advanced techniques outlined in this help file are for advanced ASP developers who want to embed FDSE within an ASP page. Not every ASP-based site will need to use these advanced techniques.
FDSE-ASP integration uses a system call from within ASP. Thus, ASP integration can only be done on servers where the user has permission to make system calls, and where the WScript.Shell object is pre-installed.
When integrating with ASP, Perl must still be installed on the server and the *.pl web server mapping must still be enabled. Admin tasks still require direct access to the original "search.pl" file.
FDSE-ASP integration is supported in FDSE version 2.0.0.0068 and newer. This integration is "under development" -- interfaces may be changed with later releases, and support for integration may be removed in the future if there are too many platform dependency problems.
FDSE-ASP integration was developed and tested on Windows 2000 SP4 with IIS 5 and Activestate Perl 5.8 build 806.
Definition of areas:
The output of FDSE consists of the following four "areas":
Invisible HTTP headers (Perl-generated)
HTML header and optional left sidebar (template /search/searchdata/templates/header.htm)
Active area (Perl-generated)
HTML footer and optional right sidebar (template /search/searchdata/templates/footer.htm)
With ASP integration, all areas except the center active area are suppressed. The HTML for the active area is made available as the return value of an ASP function call.
Definition of self-reference:
FDSE contains many types of navigation, including the search form, the "search tips" link, and the "Prev / 1 / 2 / 3 / Next" links which appear when there are multiple pages of results.
Such navigation uses the automatically-detected URL of the search script to ensure that all requests continue to come back to the same script. This is called self-referencing navigation and it requires special treatment when an ASP script is layered above the Perl script.
Changes during integration:
When using ASP integration, FDSE chooses not to print the hidden HTTP headers, the HTML header, and the HTML footer. Instead, it creates only the active area. The HTML for the active area is made available within ASP as the return value of function
In addition, all self-referencing navigation is changed to the use the URL of the parent ASP page, rather than the URL of the Perl script which is being called "under the hood".
Steps to enable:
Follow these steps to embed FDSE within your ASP layout:
Install FDSE version 2.0.0.0068 or newer.
Once installed, visit the FDSE admin page via the normal Perl script ("search.pl?Mode=Admin"). Ensure that you can login. Create a search realm that contains test content.
Go to Admin Page => General Settings. At the very top of the page will be the version and path of Perl; it will read something like "Perl version is 5.008 (E:\perl\bin\perl.exe)". Take note of the path to Perl.
Visit the default search page "search.pl". Perform a test search to ensure that results are returned.
It is essential that you configure FDSE to work properly via the standard Perl interfaces first, before moving to ASP. It will be very difficult to debug problems in the ASP integration if the core Perl interfaces are failing.
In the same folder as "search.pl", create a file named "search.asp" containing the following:
Request the file with your browser. If it doesn't print out "hello world", then there is no way that FDSE-ASP integration will work on your server. Quit now.
Next, modify your "search.asp" file to contain:
(This tests whether ASP can locate the FDSE-ASP integration code and understand its syntax, without executing it.)
Request "search.asp" with your browser. It must still print out "hello world". If there are any warnings or errors printed, then FDSE-ASP integration will not work.
Next, modify "search.asp" to contain:
Customize the four variables as needed:
search_script - this is the relative filename of your Perl search script. 99% of the time it will be "search.pl" or "search.cgi". If you've renamed the script, just make sure that this variable points to the new name.
This path will be used for a system call, so use the full file system path if needed:
search_script = "e:\webroot\www.xav.com\search\search.pl"
Do not use the URL path here.
verbose - this is a Boolean flag for including extra tests and debug output. Leave at 1 at first. Set it to 0 once things work properly.
self_url - this is the URL of the ASP page. The default value, Request.ServerVariables("SCRIPT_NAME"), should be sufficient in 99.99% of cases. If that dynamic auto-detect value doesn't work, you should enter the explicit URL, like "/search/search.asp".
path_to_perl - enter the full Windows file system path to Perl, using single backslashes to separate folders. This value was found in step 3 above. Examples of valid values are "c:\perl\bin\perl.exe" and "e:\perl\bin\perl.exe".
Visit "search.asp" again with your browser.
Now you should see some colored table cells for the various page areas. In the center table cell, you should see some red-highlighted debug output. If all goes well, below that you should see the default search form and search tips.
If you don't see the default search form and tips, then the red-highlighted debug output will probably contain an error message.
If you receive error "fdse-asp-1", then you are out of luck. System calls are not working on your web server because the WScript.WShell object is not present or cannot be launched.
If you receive error "fdse-asp-2", then there is a problem shelling to the Perl interpreter. Double-check your "path_to_perl" variable. If you continue to have problems, it may be that your web server does not allow system calls, in which case you are out of luck.
If you receive error "fdse-asp-4", then system calls are failing. More accurately, the "perl -v" command does not contain the expected substring "Larry Wall". This test is done because "perl -v" is a very well-behaved, standard system call that always returns similar substrings. We use it as a test before moving on to the more subtle return values of "perl search.pl params".
If you receive error "fdse-asp-5", then full Windows file path to your Perl script is too complex. FDSE has to pass that path on a command line, and to maximize security, it only allows characters from a certain set to appear in the path. The set is A-Z, 0-9, underscore, hyphen, period, slash, backslash, and colon.
If you receive any other error, then you should post to the Discussion Forum with full details.
If the search form and search tips appear as expected, you should perform some test searches. Include at least one search that returns multiple pages of results, and click through the "Prev / 1 / 2 / 3 / Next" navigation links. Confirm that each request connects back with your custom ASP file.
If subsequent form submissions and links do not connect back to your custom ASP file, you should post to the Discussion Forum with full details.
Finally, once testing has been completed, edit the ASP file again and set "echo_verbose" to 0. Then add in all of your standard ASP header and footer code, so that the FDSE layout matches that of the rest of your site.
Note that if you host FDSE at http://www.mysite.tld/search/search.pl, and want the ASP file in your root folder like http://www.mysite.tld/search.asp, then your ASP file will need to contain:
<!--#include file="search/searchmods/integrate.asp" --> <% search_script = "search/search.pl" ...
After setting up ASP integration, the "HTML Forms for Searching" found under FDSE Admin Page => User Interface will no longer be accurate. They will still point to the "search.pl" script. If you use the "HTML Forms" interface to get cut-n-pastable HTML for your other pages, you will need to manually replace the "search.pl" URL with your new "search.asp" URL.
After setting up ASP integration, the feature described at Admin Page => User Interface => Handling Url Search Terms will no longer work. Automatic redirects to a URL require that FDSE modify the outgoing HTTP headers, but it is not able to do that when integrated with ASP.
The FDSE-ASP integration is very crude, based on a single system call that returns a single string. The only point of the integration is to allow ASP code within standard layout areas.
As such, ASP code is limited to the header, footer, and sidebar areas of the search output. ASP code cannot be used with FDSE directly, or within internal FDSE templates like "searchform.htm" and "line_listing.txt".
Also, the ASP script receives only a single HTML string back from FDSE, rather than a more granular array of individual line listing records. The ASP code is not able to make decisions based on the number of results found.
Finally, the prompting for search inputs and the reading of search parameters is handled entirely by FDSE. The ASP code is not able to access or influence search parameters.
There are no plans to change any of this to allow for a greater level of integration. Those who need ASP code tightly integrated with search functions should use a different search product which is written entirely in ASP.
"Customizing the FDSE layout using ASP" http://www.xav.com/scripts/search/help/1192.html