Search Interface Customization: Skin Bundles

You can alter the look and feel of the Search application by creating a custom "skin" -- or user interface -- with different graphics, fonts, and colors. The files composing a custom skin are called, collectively, a skin bundle.

Support Bundles

All of the files associated with the Search application user interface for a particular release are supplied in a support bundle. These files include FreeMarker templates, images, style sheets, and JavaScript libraries.

The templates that you modify or replace are included in your skin bundle. When Oracle SES does not find a template file in the skin bundle that is needed to display a page in the Search application, then it uses the template file in the support bundle.

Both support bundles and skin bundles are associated with a particular release. This association enables you to migrate skin bundles to future releases of Oracle SES, even though the default user interface might change. When rendering the Search application pages, Oracle SES can still combine files from the skin bundle with files in the support bundle for the same release.

The current support bundle is located in this directory:

ORACLE_HOME/search/data/queryapp/support/11_1_2_0_0

FreeMarker Templates

FreeMarker is an open-source tool that generates text from templates. The templates replace HTML files for generating a page in a browser. Oracle SES uses FreeMarker to isolate the look-and-feel of the Search Application from the search software.

The FreeMarker templates are located in the templates directory of the support bundle and have an ftl extension to the file name, such as templates/results.ftl. Before editing the template files, you should become familiar with FreeMarker.

Asset Files

Cascading style sheets, graphics, and JavaScript files are assets. You can revise an asset file from the support bundle the same as a template file, or you can create your own custom asset files.

When using custom asset files, you must include references to them using macros within standard HTML. For example, you might create a style sheet named mystyles.css with redefined tags from the support bundle, then include it in your skin bundle templates with a tag like the following. Note the use of the <@ses.skin_asset> macro, which identifies the location of mystyles.css in the skin bundle.

<link rel="stylesheet" type="text/css" href="<@ses.skin_asset filename='css/mystyles.css'/>">

Similarly, the next tag references a graphics file named mylogo.gif:

<img src="<@ses.skin_asset filename='images/mylogo.gif'/>" ALT="Example, Inc."/>

Alternatively, you might copy search.css and oraclelogo_medium.gif into your skin bundle and modify their contents. Then you would modify references to these files to use the <@ses.skin_asset> macro, which points to the version of the asset in your skin bundle instead of the file in the support bundle.

Tip:

To trace the styles formatting a particular element on the page, use the development tools of your browser, such as the Firebug extension to Mozilla Firefox, the Inspect Element tool in Google Chrome, or the Developer Toolbar extension to Microsoft Internet Explorer.

JavaScript Libraries

The Oracle SES 11.1.2.0.0 support bundle contains two JavaScript libraries:

Yahoo! User Interface (YUI) Library: A set of utilities and controls for building interactive Web applications.
Bubbling Library extension to YUI: A set of plug-ins and widgets.

Template Library

The support library contains a file named seslib.ftl that references all of the resources available to the templates: JavaScript files, style sheets, macros, and so forth. The Freemaker templates import seslib.ftl using this tag at the top of each file:

<#import "/lib/oracle.com/seslib.ftl" as ses>

The tag makes these resources available for use in the template. You can delete the tag if you do not need these resources to generate a particular page, but do not modify the file.

Configuration Settings

Configuration settings for the Search application are stored in <variable> elements in this file:

ORACLE_HOME/search/tools/weblogic/deploy/plans/QueryPlan.xml

The Oracle Secure Enterprise Search Administrator's Guide describes these settings. After making any changes, issue the following shell command from Linux and UNIX-based operating systems:

sh $ORACLE_HOME/search/tools/weblogic/deploy/deployer.sh -serverURL t3://host:port/ -user weblogic -password password -name search_query -plan $ORACLE_HOME/search/tools/weblogic/deploy/plans/QueryPlan.xml -process redeploy

Or run this batch file from Windows:

%ORACLE_HOME%\search\tools\weblogic\deploy\deployer.bat -serverURL t3://host:port/ -user weblogic -password password -name search_query -plan %ORACLE_HOME%\search\tools\weblogic\deploy\plans\QueryPlan.xml -process redeploy

Where:

host:port is the host name and WebLogic service port, such as example:7777. This is the same port that you use to open the Administration GUI.

password is the password for eqsys.

Assembling the Skin Bundle Files

To assemble the skin bundle files:

Decide on the changes to make to the Search application, such as replacing the logo or the icons, changing the default font or background color, or adding an RSS feed.

Create the following directory structure for storing the files composing the skin bundle:

/skinBundle_name
     /templates
     /assets
          /images
          /css
          /js

Identify the template files that render the changed pages.

For descriptions of the template files, see the Oracle Secure Enterprise Search Administrator's Guide.
Copy the ftl files from the support bundle for the current release of Oracle SES into the templates directory. Do not change the names of these files.
Modify the templates as desired, using a text editor. Templates can include HTML tags, FreeMarker tags, and Oracle SES tags. You can change text and various settings, and reference custom graphics, style sheets, and JavaScript. See "FreeMarker Templates".
Create the graphic files, cascading style sheets, and JavaScript files as desired. Copy the graphics files into the images directory, the cascading style sheets into the css directory, and the JavaScript files into the js directory.
Create an XML document that describes the skin bundle. See skinBundle.

Creating a skinBundle Object

To create a skinBundle object using the command-line API:

Assemble the files composing the skin bundle, as previously described.
Create a text file that lists all of the files in the skin bundle. See the Notes for create skinBundle.
Issue a create command to create the skinBundle object.

To create a skinBundle object using the Web service API:

Assemble the files composing the skin bundle, as previously described.
Compose the SOAP message for a create operation, as described in Chapter 4, "Web Service Operations." Include an <attachments> element for each file in the skin bundle.
Submit the request to the Web service to create the skinBundle object.

To create a skinBundle object using the Java client, see the Oracle Secure Enterprise Search Java API Reference.

Using a Skin Bundle to Render the Search Application User Interface

To use a skin bundle when rendering the Search interface:

Issue an activate operation for the skinBundle. When you activate a default skin bundle, it can be used immediately to render the Search Application interface.
To use a skin bundle that is not the default, add a skin=skin_name attribute to the URL for the Search Application interface:
```
http://host:port/search/query/search?skin=skin_name
```

If the modified pages fail to open in a browser or appear with errors, read the middle-tier log file at

ORACLE_HOME/search/base_domain/servers/AdminServer/logs/AdminServer.out.

After updating the skin bundle, restart the middle tier:

ORACLE_HOME/bin/searchctl restart

Skin Bundle Example

This example makes a few changes to the default results page, which is shown in Figure 2-1.

Changes to the Example Results Page

Table 2-6 identifies the changes that this example makes to the default results page. You can see these differences by comparing Figure 2-1 and Figure 2-2. The title in the browser title bar is not shown.

Changes to results.ftl do not affect any other pages of the Search application, which continue to use the default skin. However, the example makes changes to inc_logo_querybox.ftl and inc_footer.ftl, which affect all of the pages that include those templates.

Table 2-6 Differences Between the Default Skin and the Example Skin

Default Skin	Example Skin	Template Rendering the Element
Oracle logo	Example Inc. logo	inc_logo_querybox.ftl
Search button	Search icon	inc_logo_querybox.ftl
Sidebar on left	Sidebar on right	results.ftl
Title of Oracle Secure Enterprise Search	Title of Example Inc.	results.ftl
No RSS feed	RSS feed icon on the Results bar	results.ftl
No corporate identifier	Example, Inc. above the copyright	inc_footer.ftl

Figure 2-1 Default Results Page

Description of "Figure 2-1 Default Results Page"

Figure 2-2 Example Results Page

Description of "Figure 2-2 Example Results Page"

Changes to the Example Footer

The only change to the footer is the addition of Example Inc., as shown in Figure 2-3. The following pages use the same footer template, so all of them are affected by this change:

Initial splash screen: query.ftl
Results page: results.ftl
No results page: noresults.ftl
Error page: error.ftl

Figure 2-3 Example Footer

Description of "Figure 2-3 Example Footer"

Creating the Example Directory Structure

To make the changes to the skin shown in the previous section, the skin bundle must contain these files:

results.ftl: The template that renders the search results.
inc_logo_querybox.ftl: A template included by results.ftl to generate the logo and the query box.
inc_footer.ftl: A template included by results.ftl (and other templates) to generate the footer.
example.gif: A graphic file with the logo for a fictitious company named Example Inc.
search.jpg: a graphic file with the search icon.
rss.jpg: A graphic file with the standard RSS icon.

To create the example skin bundle directory structure:

On the Oracle SES host, create these directories:
```
/example/templates
/example/assets/images
```
Copy the ftl files to the templates directory from

ORACLE_HOME/data/queryapp/support/11_1_2_0_0/templates
Copy the graphics file (created or acquired elsewhere) into the images directory.

The resulting directories have this structure:

/example
   /templates
      /inc_footer.ftl
      /inc_logo_querybox.ftl
      /results.ftl
   /assets
      /images
         /example.gif
         /rss.jpg
         /search.jpg

Customizing results.ftl

The results page contains numerous elements. Some elements appear by default, while you must define others, such as source groups and suggested links, for a specific installation. The results.ftl template uses the FreeMarker <#include> tag to include the following template files, which define distinct areas of the results page:

inc_header.ftl
inc_logo_querybox.ftl
inc_footer.ftl

This example uses the default inc_header.ftl, but alters the other templates. Figure 2-0 identifies the altered elements that are generated directly by results.ftl.

To customize results.ftl:

Open example/templates/results.ftl in a text editor.

To move the sidebar to the right, change:

<#assign sidebarPageAlign = "left">

<#assign sidebarPageAlign = "right">

To replace the page title, change:

<title>${msg("ORACLE_ENTERPRISE_SEARCH")}
   <#if req.displayQuery??>
      - ${req.displayQuery}
   </#if>
</title>

<title>Example Inc.</title>

For the RSS feed, add the following immediately after <@ses.hit_stats/>:

<#assign feed_img_src><@ses.skin_asset 'images/rss.jpg'/></#assign>
<@ses.feed_icon title="Results Feed" img_src="${feed_img_src}">
   <@ses.feed_href/>
</@ses.feed_icon>

Save and close the file.

Customizing inc_logo_querybox.ftl

The inc_logo_querybox.ftl template renders a section of the results page immediately following the header. This section includes these elements in the default user interface:

Oracle logo
Query box
Search button
Attribute filters, both the link and the form
Browse link
Optional source group tab links above the query box, such as E-mail, Calendar, and Sales.

To customize inc_logo_querybox.ftl:

Open example/templates/inc_logo_querybox.ftl in a text editor.

To replace the Oracle logo with the Example logo, change:

<@ses.oracle_logo size="small" href="${logoHref}"/>

<img src="<@ses.skin_asset filename='images/example.gif'/>">

To replace the Search button with an icon, change:

<input type="submit" name="btnSearch" value="${msg("SEARCH")}">

<input type="image" src="<@ses.skin_asset filename="images/search.jpg" />"
name="${msg("SEARCH")}" alt="${msg("SEARCH")}" 
style="vertical-align: bottom;">

Save and close the file.

Customizing inc_footer.ftl

The inc_footer.ftl template renders the links, such as Help, and the copyright information at the bottom of the page.

To customize inc_footer.ftl:

Open example/templates/inc_footer.ftl in a text editor.

For the company name, add the following immediately before :

<div style="padding-top:10px;font-size:16px;font-weight:bold;
font-style:italic;color:red;font-family:'Book Antigua',Palatino,serif;
text-align:center">
   Example Inc.
</div>

Save and close the file.

Creating the Example Skin Bundle File List

Create a text file that identifies all of the files in the skin bundle. In this example, the file list is named /scratch/skins/example.lst. Substitute the actual path you are using for /scratch/skins.

assets/images/example.gif::/scratch/skins/example/assets/images/example.gif
assets/images/search.jpg::/scratch/skins/example/assets/images/search.jpg
assets/images/rss.jpg::/scratch/skins/example/assets/images/rss.jpg
templates/inc_footer.ftl::/scratch/skins/example/templates/inc_footer.ftl
templates/inc_logo_querybox.ftl::/scratch/skins/example/templates/inc_logo_querybox.ftl
templates/results.ftl::/scratch/skins/example/templates/results.ftl

Creating an XML Description of the Example Skin Bundle

Create an XML file that describes the Example skin bundle. In this example, the XML file is named /scratch/skins/example.xml.

<?xml version="1.0" encoding="UTF-8" ?>
 
<search:config productVersion="11.1.2.0.0" xmlns:search="http://xmlns.oracle.com/search">
   <search:skinBundles>
      <search:skinBundle>
         <search:name>example</search:name>
         <search:isDefault>false</search:isDefault>
         <search:linkedVersion>11.1.2.0.0</search:linkedVersion>
         <search:files>
            <search:file path="templates/inc_footer.ftl"/>
            <search:file path="templates/inc_logo_querybox.ftl"/>
            <search:file path="templates/results.ftl"/>
            <search:file path="assets/images/example.gif"/>
            <search:file path="assets/images/search.jpg"/>
            <search:file path="assets/images/rss.jpg"/>
         </search:files>
      </search:skinBundle>
   </search:skinBundles>
</search:config>

Creating the Example skinBundle Object

To create the Example skin bundle:

At the host command prompt, navigate to the /scratch/skins directory.
Open searchadmin in session mode, as described in "Opening an Interactive Session".

To create the skin bundle, issue this command:

create skinBundle --NAME=example --INPUT_FILE=example.xml --ATTACHMENT_LIST=example.lst

To activate the skin bundle, issue this command:
```
activate skinBundle --NAME=example
```

Using the Example Skin Bundle to Render the Search Application

Because the example skin bundle is not defined as the default, you must include the skin attribute in the URL to view the Search application.

To use the Example skin bundle:

In a browser, enter a URL like the following, substituting the appropriate host and port:
```
http://host:port/search/query/search?skin=example
```
The footer displays Example Inc., while the rest of the page uses the default skin.
Enter a search string. The results page has the changes shown in Figure 2-2, "Example Results Page".