2 Administration Object Types

This chapter describes the object types in the Oracle SES Administration API. It contains these topics:

• Alphabetic List of Administration Object Types

• Document Support

• Globalization Support

• Encryption

• XML Description of State Properties

• Partitioning for Parallel Query

• Disk Space Management: Quotas and Alerts

• Search Interface Customization: Skin Bundles

Alphabetic List of Administration Object Types

A C I P Q R S T

A

alert
altWord

C

clustering
clusterTree
crawlerSettings

I

identityPlugin
index
indexOptimizer

P

partitionConfig
proxyLogin

Q

queryConfig

R

resultList

S

schedule
searchAttr
skinBundle
source
sourceGroup
sourceType
spaceCalculator
storageArea
suggLink

T

task
thesaurus

Document Support

Table 2-1 identifies the document formats supported by Oracle SES.

Table 2-1 Document Formats

Document Format	MIME Type
Adobe Framemaker Document	application/x-framemaker
Adobe Framemaker Interchange Format (MIF) Document	application/vnd.mif
Corel Presentations Document	application/vnd.corel-presentations
DICOM Image	application/dicom
DocuShare Ichitaro Document	application/x-js-taro
GIF Image	image/gif
GNU ZIP Archive	application/x-gzip
Haansoft HWP Document	application/x-hwp
HTML	text/html
JPEG 2000 Image	image/jp2
JPEG Image	image/jpeg
Lotus 1-2-3 Document	application/x-lotus123 (also represents application/vnd.lotus-1-2-3)
Lotus AMI Pro Document	application/x-ami
Lotus Freelance Document	application/x-freelance (also represents application/vnd.lotus-freelance)
Lotus Word Pro Document	application/vnd.lotus-wordpro
LZH Archive	application/x-lzh-compressed
Microsoft Excel Document	application/x-msexcel (also represents application/vnd.ms-excel and application/ms-excel)
Microsoft Office Project	application/vnd.ms-project
Microsoft PowerPoint Document	application/x-mspowerpoint (also represents application/vnd.ms-powerpoint)
Microsoft Visio	application/vnd.visio
Microsoft Word Document	application/msword
Microsoft Works Word Processor Document	application/x-msworks-wp
MS Write	application/x-mswrite
PDF Document	application/pdf
Plain Text	text/plain
Quattro Pro for Windows Document	application/x-quattro-win
Rich Text Format (RTF) Document	application/rtf
StarOffice Calc Document	application/vnd.stardivision.calc
StarOffice Impress Document	application/vnd.stardivision.impress
Sun XML Writer Document	application/vnd.sun.xml.writer
TIF Image	image/tiff
WordPerfect 5.1 Document	application/wordperfect5.1
WordPerfect 6 Document	application/x-wordperfect6
XML	text/xml
XyWrite Document	application/x-xywrite
ZIP Archive	application/zip

Globalization Support

Oracle SES provides localization support for source documents, metadata translation, and user queries. You can specify this information in the configuration of administration objects.

Product Languages

Oracle SES user interface components are translated into the languages listed in Table 2-2. The locale of the Oracle SES host system sets the default language for error messages, as well as the Administration GUI and the Search Application. In the Web services interface, you can set the language for error messages in individual operations.

Table 2-2 Product Languages

Language	Code
Chinese, Simplified	zh_CN
Chinese, Traditional	zh_TW
English	en
French	fr
German	de
Italian	it
Japanese	ja
Korean	ko
Portuguese, Brazilian	pt_BR
Spanish	es

Crawlable Documents

For Oracle SES to crawl and index source documents, they must be stored in a supported language and character set.

Table 2-3 lists the codes for languages supported by the crawler.

Table 2-3 Crawlable Languages

Language	Code
Arabic	ar
Chinese	zh
Czech	cs
Danish	da
Dutch	nl
English	en
Finnish	fi
French	fr
German	de
Greek	el
Hebrew	he
Hungarian	hu
Italian	it
Japanese	ja
Korean	ko
Norwegian	no
Polish	pl
Portuguese	pt
Romanian	ro
Russian	ru
Slovak	sk
Spanish	es
Swedish	sv
Turkish	tr

Table 2-4 lists the codes for character sets supported by the crawler.

Table 2-4 Crawlable Character Sets

Character Set	Code
Standard UTF-8	UTF8
16-Bit UCS Transformation Format	UTF-16
Big 5 Traditional Chinese	Big5
CNS 11643 Traditional Chinese	CNS11643
GB 18030 Simplified Chinese	GB18030
GB2312-80 Simplified Chinese	GB2312
GBK Simplified Chinese	GBK
ISO Latin/Arabic	8859-6
ISO Latin/Cyrillic	8859-5
ISO Latin/Greek	8859-7
ISO Latin/Hebrew	8859-8
ISO Latin-1	8859-1
ISO Latin-2	8859-2
ISO Latin-3	8859-3
ISO Latin-4	8859-4
ISO Latin-5	8859-9
Japanese (Auto-Detect)	JISAutoDetect
Japanese (EUC)	EUC_JP
Japanese (JIS)	JIS
Japanese (Shift-JIS)	SJIS
KSC5601 Korean	KSC5601
Macintosh Arabic	MacArabic
Macintosh Croatian	MacCroatian
Macintosh Cyrillic	MacCyrillic
Macintosh Dingbat	MacDingbat
Macintosh Greek	MacGreek
Macintosh Hebrew	MacHebrew
Macintosh Iceland	MacIceland
Macintosh Latin-2	MacCentralEurope
Macintosh Roman	MacRoman
Macintosh Romania	MacRomania
Macintosh Symbol	MacSymbol
Macintosh Thai	MacThai
Macintosh Turkish	MacTurkish
Macintosh Ukraine	MacUkraine
PC Arabic	Cp864
PC Baltic	Cp775
PC Canadian French	Cp863
PC Cyrillic	Cp855
PC Greek	Cp737
PC Hebrew	Cp862
PC Icelandic	Cp861
PC Latin-1	Cp850
PC Latin-2	Cp852
PC Modern Greek	Cp869
PC Nordic	Cp865
PC Original	Cp437
PC Portuguese	Cp860
PC Russian	Cp866
PC Turkish	Cp857
Windows Arabic	Cp1256
Windows Baltic	Cp1257
Windows Cyrillic	Cp1251
Windows Eastern Europe/Latin-2	Cp1250
Windows Greek	Cp1253
Windows Hebrew	Cp1255
Windows Japanese	MS932
Windows Thai	Cp874
Windows Turkish	Cp1254
Windows Vietnamese	Cp1258
Windows Western Europe/Latin-1	Cp1252

Providing Translations of Object Names

The names of some administration objects are displayed to users in the Search interface, such as source, sourceGroup, and clusterTree. You can provide a display name in one or more languages by using the <search:translations> element, as shown here:

<search:name>
   <search:translations>
      <search:translation>
         <search:translatedValue>

Element Descriptions 

<search:name>

Name of the administration object.

<search:translations>

Contains one or more <search:translation> elements.

<search:translation>

Contains a <search:translatedValue> element.

Attribute	Value
language	A code identifying the language of the translated value. The codes are not case sensitive. See Table 2-5, "Query Language Codes".

<search:translatedValue>

Contains a description of the object in the translation language. This value is displayed in the Search Application.

Table 2-5 Query Language Codes

Language	Code
Arabic	ar
Catalan	ca
Chinese, Simplified	zh_CN
Chinese, Traditional	zh_TW
Czech	cs
Danish	da
Dutch	nl
English	en
Finnish	fi
French	fr
German	de
Greek	el
Hebrew	iw
Hungarian	hu
Italian	it
Japanese	ja
Korean	ko
Norwegian	no
Polish	pl
Portuguese	pt
Portuguese, Brazilian	pt_BR
Romanian	ro
Russian	ru
Slovak	sk
Spanish	es
Swedish	sv
Thai	th
Turkish	tr

Encryption

The Administration API provides an encryption system to safeguard sensitive information, such as passwords, contained in the XML description of an object.

When you import an XML document using an operation such as create or update, you can indicate in the XML whether a value is encrypted. In this example, the password is in plain text, which either sets it for the first time or changes it to a new value:

<search:password encrypted="false">password</search:password>

Oracle SES stores the password in an encrypted form. The next example shows an encrypted password, which was exported in an XML document from Oracle SES:

<search:password encrypted="true">
128b6b43091659ffa1ff068666b8eb6445dabd361871b6a5b97941f00ee8c842e76bcc1eb3c0806fd0f6ee2e3ab371febcf053255ffd4e46888909cdd553914bfabe99eda51861d7
</search:password>

When exporting an XML document containing a password, Oracle SES requires you to provide an encryption key. If you use this document as input to an operation (encrypted="true"), then you must use the same encryption key as the export operation so that Oracle SES can decrypt the password.

XML Description of State Properties

Both universal and creatable objects can have state properties. The getState, getStateList, and getAllStates commands return an XML document describing the current state of one or more objects.

The <search:state> element describes the current state of an object.

<search:state>
   <search:objectStates>
      <search:objectState>
         <search:objectState>
         <search:objectType>

<!-- For creatable objects -->
            <search:objectKey>
               <search:keyPairs>
                  <search:keyPair>
                     <search:name>
                     <search:value>

<!-- For all objects -->
         <search:stateProperties>
            <search:stateProperty>
               <search:propertyName>
               <search:propertyValues>
                  <search:propertyValue>
                     <search:propertyValue>

Element Descriptions 

<search:state>

Contains a <search:objectStates> element.

Attribute	Value
productVersion	Oracle SES product version
xmlns:search	Namespace for the Oracle SES Administration API

<search:objectStates>

Contains one or more <search:objectState> elements.

<search:objectState>

Describes the state properties of a particular object, using these child elements:

<search:objectType>
<search:objectKey>
<search:stateProperties>

<search:objectType>

Contains an object type with one or more state properties:

clustering
clusterTree
identityPlugin
index
indexOptimizer
resultList
schedule
skinBundle
spaceCalculator
task

<search:objectKey>

Contains the object key that identifies a specific instance of a creatable object type. It contains a <search:keyPairs> element.

<search:keyPairs>

Contains one or more <search:keyPair> elements.

<search:keyPair>

Contains these child elements:

<search:name>
<search:value>

<search:name>

Contains a key name for this object type.

<search:value>

Contains the key value for this object.

<search:stateProperties>

Contains one or more <search:stateProperty> elements.

<search:stateProperty>

Contains a <search:propertyName> element.

<search:propertyName>

Contains the name of a property.

<search:propertyValues>

Contains one or more <search:propertyValue> elements.

<search:propertyValue>

Contains a <search:value> element.

Attribute	Value
key	Provides additional context, such as the name of the data source associated with the property for a schedule that crawls multiple sources.

<search:value>

Contains the current value of the property.

Partitioning for Parallel Query

You can optimize query performance of large document sources by storing the crawler index in partitions distributed across several independent disks. Oracle SES then executes parallel subqueries automatically against the partitions. Both I/O and CPU resources are used in parallel.

These administrative objects support parallel query:

• partitionConfig

• storageArea

Note:

To support parallel query, you must create the partitions immediately after installing Oracle SES. You cannot create them after crawling a document source.

To support parallel query: 

1. Open a SQL session as the administrative user:

   sqlplus eqsys
   

2. Execute two PL/SQL procedures to enable the partitioning feature of the Oracle SES instance:

   exec eq_adm.use_instance(1)
   exec eq_par.enable_partition
   

3. Define one or more storageArea objects with a usage of PARTITION on each physical storage device available to this instance.

4. Update the partitionConfig object to have a rule type of HASH and to use the new storageArea objects.

5. Create document sources and schedule them for crawling.

See Also:

"Parallel Query Indexing" in the Oracle Secure Enterprise Search Administrator's Guide.

Parallel Query Example

This example creates two partitions, using the default OES storage area and a newly created OES1 storage area:

1. Using searchadmin, export the XML description of the default OES storage area to a file named oes.xml:

   export storageArea --NAME=oes --OUTPUT_FILE=oes.xml
   

2. Export the XML description of the partition configuration to a file named part.xml:

   export partitionConfig --OUTPUT_FILE=part.xml
   

3. Open oes.xml in a text editor and edit it as follows:

   <search:config productVersion="11.1.2.2.0" xmlns:search="http://xmlns.oracle.com/search">
      <search:storageAreas>
         <search:storageArea>
            <search:name>OES1</search:name>
            <search:description>
               Default storage area extension
            </search:description>
            <search:usage>PARTITION</search:usage>
            <search:locations>
               <search:location>
                  <search:path>/ses_storage/</search:path>
                  <search:device>default</search:device>
                  <search:preAllocatedSpace>20</search:preAllocatedSpace>
                  <search:quota>400</search:quota>
               </search:location>
            </search:locations>
         </search:storageArea>
      </search:storageAreas>
   </search:config>
   

4. Open part.xml in a text editor and edit it as follows:

   <search:config productVersion="11.1.2.2.0" xmlns:search="http://xmlns.oracle.com/search">
      <search:partitionConfig>
         <search:partitionRules>
            <search:partitionRule>
               <search:partitionValue>EQ_DEFAULT</search:partitionValue>
               <search:valueType>META</search:valueType>
               <search:ruleType>HASH</search:ruleType>
               <search:storageArea>oes, oes1</search:storageArea>
            </search:partitionRule>
         </search:partitionRules>
      </search:partitionConfig>
   </search:config>
   

5. Create the new storage area:

   create storageArea --NAME=oes1 --INPUT_FILE=oes.xml
   

6. Update the partition configuration:

   update partitionConfig --INPUT_FILE=part.xml --UPDATE_METHOD=overwrite
   

Disk Space Management: Quotas and Alerts

Oracle SES uses quotas to restrict the amount of disk space that it consumes. These administrative objects set and enforce these quotas:

• alert

• spaceCalculator

• storageArea

A quota is set on the default data storage location as a post- installation step, computed as half the remaining disk space plus its initial size. You can alter this quota and set quotas on other storage areas.

See Also:

See "Managing Disk Space Usage" in the Oracle Secure Enterprise Search Administrator's Guide

To set a disk space quota: 

1. Identify the storage area that you want to create or modify.

2. In the XML description of the object, set the <search:quota> element to the maximum desired size in megabytes.

3. Use the create, createAll, update, or updateAll operation to create or modify the object.

4. Configure the space calculator to run at the desired intervals.

   The space calculator is set initially to run daily and is activated automatically. It issues a warning if a quota is 80% filled, or an alert if a quota is exceeded.

You can see alerts on the Home - General page of the Administration GUI, or by issuing an exportAll alert operation. You must clear an alert before normal operations can resume.

To clear an alert: 

1. Remove the cause of the alert, such as by increasing the quota or removing files from the storage area.

2. Start the space calculator to check the storage area size against the quota again.

   The space calculator changes the alerts to RESOLVED if the storage area is within the quota. Otherwise, the alert remains OPEN.

3. Start the resumeAllSpaceConsumingTasks task to resume normal operation.

Tip:

You can delete crawler logs and cache files. If this does not free enough space, you can create a storage area on another disk for the crawler to use. The crawler stores data in Oracle data files (*.dbf), which you should not delete at the operating system level.

To remove a storage area quota: 

1. In the XML description of the object, set the <search:quota> element to -1.

2. Use the update or updateAll operation to modify the object.

Space Management Examples

This example changes the default quota on the data storage location:

1. Export the data storage object to a file named datastore.xml:

   export storageArea --NAME="Data storage location" --OUTPUT_FILE=datastore.xml
   

2. Open datastore.xml in an XML or text editor and change the value of the <search:quota> element as desired. This example sets it to 64 GB (64*1024 MB).

   <search:quota>65536</search:quota>
   

3. Save and close datastore.xml.

4. Update the changes for this storage area:

   update storageArea --NAME="Data storage location" --INPUT_FILE=datastore.xml --UPDATE_METHOD=overwrite
   

5. Check the current disk usage:

   start spaceCalculator
   

The next example clears an alert signalled by the space calculator.

1. Fix the cause of the alert. In this example, a new Web source was defined with an unlimited crawling depth. The solution was to limit the crawling depth of the Web source and increase the quota on the data storage location to accommodate the additional crawled documents.

2. Start the space calculator:

   start spaceCalculator
   

3. Check the status of the alert on the Oracle Administration GUI or by exporting the alert:

   export alert --NAME=alert_1
    
   

   This XML description shows that the problem is resolved:

   <?xml version="1.0" encoding="UTF-8"?>
   <search:config productVersion="11.1.2.2.0" xmlns:search="http://xmlns.oracle.com/search">
      <search:alerts>
         <search:alert>
            <search:name>alert_1</search:name>
            <search:time>Thu, 14 Jan 2010 15:38:21 GMT</search:time>
            <search:type>SPACE</search:type>
            <search:status>RESOLVED</search:status>
            <search:causes>
               <search:cause location="/home/oracle/dbs/sesmain/" quota="4" size="293" storageArea="Data storage location" time="14 Jan 2010 09:38:21"/>
            </search:causes>
         </search:alert>
      </search:alerts>
   </search:config>
   

4. Resume normal operations:

   start task --NAME=resumeAllSpaceConsumingTasks
   

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.

See Also:

FreeMarker Web site at http://www.freemarker.org/.

The templates contain HTML and two other types of tags:

• FreeMarker tags: These tags are predefined in FreeMarker and begin with <#. For example, this tag appears at the beginning of most templates:

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

  The FreeMarker Manual describes these tags, which invoke predefined directives, at http://freemarker.org/docs/ref_directives.html.

• Oracle SES tags: These tags are specific to Oracle SES and begin with <@. For example, this tag references a graphic file named logo.gif in the skin bundle:

  <@ses.skin_asset 'images/logo.gif'/>
  

  Oracle SES tags invoke macros (also called user-defined directives) defined in seslib.ftl, so any template that uses them must import that file. The Oracle Secure Enterprise Search Administrator's Guide describes these macros.

Asset Files

Cascading style sheets, graphics, and JavaScript files are assets. You can revise an asset file from the support bundle like 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.2.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.

See Also:

• YUI Library section of the Yahoo! Developer Network site at http://developer.yahoo.com/yui/.

• Bubbling Library Web site at http://bubbling-library.com/.

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:

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

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

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

3. Identify the template files that render the changed pages.

   For descriptions of the template files, see the Oracle Secure Enterprise Search Administrator's Guide.

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

5. 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".

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

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

1. Assemble the files composing the skin bundle, as previously described.

2. Create a text file that lists all of the files in the skin bundle. See the Notes for create skinBundle.

3. Issue a create command to create the skinBundle object.

To create a skinBundle object using the Web service API:

1. Assemble the files composing the skin bundle, as previously described.

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

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

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

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

1. On the Oracle SES host, create these directories:

   /example/templates
   /example/assets/images
   

2. Copy the ftl files to the templates directory from

   ORACLE_HOME/data/queryapp/support/11_1_2_0_0/templates

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

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

2. To move the sidebar to the right, change:

   <#assign sidebarPageAlign = "left">
   

   to

   <#assign sidebarPageAlign = "right">
   

3. To replace the page title, change:

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

   to

   <title>Example Inc.</title>
   

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

5. 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: 

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

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

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

   to

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

3. To replace the Search button with an icon, change:

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

   to

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

4. 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: 

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

2. For the company name, add the following immediately before <!-- Bottom Line -->:

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

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

1. At the host command prompt, navigate to the /scratch/skins directory.

2. Open searchadmin in session mode, as described in "Opening an Interactive Session".

3. To create the skin bundle, issue this command:

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

4. 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: 

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

2. Enter a search string. The results page has the changes shown in Figure 2-2, "Example Results Page".