Home > Fluid Dynamics Search Engine > Help > 1193

Customizing the FDSE layout using PHP

Overview and notes:

This article describes how the FDSE layout -- including the search tips page and the search results page -- can be rendered using PHP. This is intended for advanced developers who want to integrate FDSE into a web site that uses consistent, PHP-based layout on all pages.

Please note:

Definition of areas:

The output of FDSE consists of the following four "areas":

  1. Invisible HTTP headers (Perl-generated)

  2. HTML header and optional left sidebar (template /search/searchdata/templates/header.htm)

  3. Active area (Perl-generated)

  4. HTML footer and optional right sidebar (template /search/searchdata/templates/footer.htm)

Set-Cookie: fdse_cp=0
Content-Type: text/html
Invisible HTTP headers
HTML header and optional left sidebar

# the script "active area", including:

Search Results
Your search for foo found the following documents (of 455 documents searched):
Displaying documents 1-10 of 58, with best matches first:

1. Installer Help
foo bar xyz
URL: http://www.xav.com/scripts/installer/3004.html - 2KB - 30 Jul 2002

2. How to manage files whose names begin with a dot
Filenames beginning with a dot are considered "hidden files" in the Unix world...
URL: http://www.xav.com/scripts/installer/3061.html - 6KB - 13 Aug 2003

HTML footer and optional right sidebar

With PHP integration, all areas except the center active area are suppressed. The HTML for the active area is made available as the return value of a PHP 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 a PHP script is layered above the Perl script.

Changes during integration:

When using PHP 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 PHP as the return value of function FDSE_output().

In addition, all self-referencing navigation is changed to the use the URL of the parent PHP 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 PHP layout:

  1. Install FDSE version or newer.

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

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

  4. 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 PHP. It will be very difficult to debug problems in the PHP integration if the core Perl interfaces are failing.

  5. In the same folder as "search.pl", create a file named "search.php" containing the following:

    Request the file with your browser. If it doesn't print out "hello world", then there is no way that FDSE-PHP integration will work on your server. Quit now.

  6. Next, modify your "search.php" file to contain:

    (This tests whether PHP can locate the FDSE-PHP integration code and understand its syntax, without executing it.)

    Request "search.php" with your browser. It must still print out "hello world". If there are any warnings or errors printed, then FDSE-PHP integration will not work.

  7. Next, modify "search.php" to contain:

    Customize the variables as needed:

    1. $search_script - this is the relative filename of your Perl search script. 95% of the time it will be "search.pl". You may need to change it to "search.cgi". If you've renamed the Perl script, just make sure that this variable points to the new filename.

      This variable will be used for a system call, so use the file system path, not the URL path.

      $search_script = "search.pl";                              # GOOD
      $search_script = "/usr/home/xav/search.pl";                # GOOD
      $search_script = "e:\\webroot\\www.xav.com\\search.pl";    # GOOD
      $search_script = "http://www.xav.com/search.pl";  # NO! BAD! WILL NOT WORK
    2. $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.

    3. $self_url - this is the URL of the PHP page. The default value, $_SERVER['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.php".

    4. path_to_perl - enter the full file system path to Perl. (On Windows, use double backslashes to separate folders.) This value was found in step 3 above. Examples of valid values are "c:\\perl\\bin\\perl.exe" and "/usr/bin/perl".

  8. Visit the PHP page with your browser.

    You should see some default 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, you should see the default search form and search tips below that.

    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-php-2", then you are out of luck. System calls are not working on your web server.

    • If you receive error "fdse-php-3", then the PHP script is not able to find your Perl script. Double-check the value of the $search_script variable.

    • If you receive error "fdse-php-4", then the URL to your PHP script is too complex. FDSE has to pass that URL on a command line, and to maximize security, it only allows characters from a certain set to appear. The set is A-Z, 0-9, underscore, hyphen, period, and slash.

    If you receive any other error, then you should post to the Discussion Forum with full details.

  9. 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. Click through the "Prev / 1 / 2 / 3 / Next" navigation links and confirm that each request connects back with your custom PHP file.

    If subsequent form submissions and links do not connect back to your custom PHP file, you should post to the Discussion Forum with full details.

  10. Finally, once testing has been completed, edit the PHP file again and set "$verbose" to 0. Then add in all of your standard PHP 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 PHP file in your root folder like http://www.mysite.tld/search.php, then your PHP file will need to contain:

	# ...
	$search_script = "search/search.pl";


    "Customizing the FDSE layout using PHP"