One of the more confounding challenges for those new to the Google Search Appliance (GSA) — at least for the XSLT-inexperienced such as ourselves — is figuring out how to build a search-results page such that one has 100% external stylesheet control. To be sure, the GSA includes a very handy “page layout helper” that provides interactive dialogs for creating a custom GSA “frontend” output page and/or search result page. One can use the page layout helper to incorporate your own custom header and footer markup, as well as add or exclude or modify a limited set of default GSA output page elements. Essentially, what the GSA native page layout helper does is provide a simple way to customize the underlying XSLT stylesheet without having to code directly in XSLT.

And as far as it goes, the GSA page layout helper is pretty handy. But what it is not so handy at is providing a way, without coding the XSLT directly, to give you complete, 100% external CSS control of how the search results display. True, you can add an external stylesheet link to the header markup you pop into the editor, but you are still stuck with all the native, embedded and inline styles that the GSA, by default, adds to the search results themselves. As those familiar with the order of importance in the cascade know well, inline styles trump embedded styles which in turn trump external styles. What’s a CSS coder who is not XSLT-savvy to do in this situation?

Here’s what we’ve done, in six (mostly) easy steps:

1. Build a design mockup of your search results page

The first thing we did is build a static XHTML page, with conventionally linked external CSS stylesheets, so that we had in-hand the markup we would fold in later to the GSA XSLT stylesheet. How you do this is entirely up to you. Here is a screenshot of our search-result page design. In this design, all the page elements at the top with a black background and to the right in the side-bar are what we will later add to the XSLT as part of the so-called “header,” described below. The markup that comprises the simple, light-gray footer at the very bottom will go into the “footer” section of the same XSLT. The “lorem ipsum” section of the markup in this mockup is just a placeholder, to show where the GSA search results will eventually appear.

2. “Process” your header and footer XHTML through the GSA page layout helper

This is akin to the “preparation” stage of cooking a recipe. What you need to do at this step is use the GSA page layout editor to convert the XHTML “header” and “footer” markup you created in the prior step, into a format that will play nice with the custom version of your GSA XSLT stylesheet described below.

To do that, login to your GSA admin panel, select “Serving” and then create a new GSA frontend. Click on the “Edit” link for the new frontend and then select the “Output Format” tab to display the Page Layout Helper. Click on “Global Attributes” and paste into the “Header” field all the XHTML code from the very top of your design mockup page (starting with the DOCTYPE) down to where the “header” markup ends. Do the same with your “footer” XHTML to the very end of the page markup (including the closing “body” and “html” tags) by pasting it into the “Footer” field. Click the “Save Page Layout Code” button, which prompts the GSA Page Layout Helper to process your markup and add it to the raw XSLT code.

You need to put your newly processed “header” and “footer” code to the side temporarily, for a later stage in this recipe. To do that, click on the “Edit underlying XSLT code” and then copy the raw XSLT code into your code editor of choice. Search for the line of code that begins and you’ll see that your header markup has been converted for use in the XSLT stylesheet. Copy everything between the opening and closing “my_page_header” template tags. Ditto, for the code between the “my_page_footer” template tags. Set these two code excerpts aside for a few minutes while you work on the next few steps. (Don’t worry about the default GSA XSLT stylesheet you just created, since it is going to be replaced, as described below.)

[Update: See the comments below, about the importance of assuring the header and footer XHTML "processed" via the GSA page layout helper are enclosed in each case by xsl:text tags.]

3. Download the Google Code open-source version of the GSA XSLT stylesheet

Download the open-source Google Code GSA XHTML Stylesheet. The advantage of this open-source XSLT stylesheet is that it offers a web-standards compliant version that generates well-formed, valid markup, something that natively generated Google pages are infamous for not doing. This open-source version of the GSA XSLT also makes it easier to modify the XSLT so that you can generate search results without any embedded or inline styles, and therefore subject completely to an external stylesheet. (A tip-of-the hat here to our GSA consultant, Michael Cizmar and his trusty sidekick Igor Taran for giving us the heads-up on this XSLT option.)

4. Edit the open source GSA XSLT stylesheet to turn off embedded and inline styles

Only two simple sets of edits are required to give you the external CSS style controls you want. The first is to edit the open source GSA XSLT stylesheet at line 67 to turn off embedded styles, by turning on external CSS styles; and at line 68 to provide a pointer to the specific directory (but not the CSS stylesheet itself) where your external CSS stylesheet resides.

Without modification, these two lines look like this:

<xsl:variable name="style_include">0</xsl:variable>
<xsl:variable name="style_include_prefix"></xsl:variable>

Modified for this example, the same two lines would look something like this, with the “style_include” set to true and the “style_include_prefix” set to the path of the external CSS stylesheet:

<xsl:variable name="style_include">1</xsl:variable>
<xsl:variable name="style_include_prefix">https://yourdomain.com/css/</xsl:variable>

The second edit is an optional edit. Sort of. At line 507 you’ll see this reference:

<link href="{$style_include_prefix}search.css" rel="stylesheet" type="text/css" media="screen,print"/>

Line 507 refers to the specific external CSS “screen” stylesheet that line 68 points toward. Actually, you can simply use that same “search.css” name for your external stylesheet, or change it to another name. It’s your call.

5. Edit the open source GSA XSLT stylesheet to add your custom “header” and “footer” template markup

Remember the processed XHTML “header” and “footer” template code you set aside, above? Here’s where you use it. In the same open-source GSA XSLT stylesheet, go to line 244 and add your processed “header” XHTML code and at line 248 add your processed “footer” XHTML code. The former goes between the “my_page_header” template tags:

<xsl:template name="my_page_header">
    <!-- add your processed xhtml here -->
</xsl:template>

And the latter goes between the “my_page_footer” template tags:

<xsl:template name="my_page_footer">
  <!-- add your processed xhtml here - -->
</xsl:template>

6. Substitute your edited version of the same XSLT stylesheet for the default GSA XSLT stylesheet

Now go back to the Page Layout Helper. If the XSLT code is not open for your custom frontend, click the “Edit underlying XSLT code” link, paste your edited version of the open source GSA XSLT stylesheet into the editor and then click the “Save XSLT Code” button to save your changes.

You should be good to go!

Now you can go to your external CSS stylesheet and change how any and all elements of your search results display, without any interference from GSA native embedded or inline styles.

It worked for us. After using {display:none} in the external CSS stylesheet to selectively hide some of the page elements in the search results page, and then tweaking the styles to get the results to display the way we wanted, we ended up with a very nice, customized look to our search results.