With Oracle SES 11g, the query UI can be customized using skin bundles, which are files grouped into a unit that create a customized skin for the search interface. A skin bundle may include JavaScript files, CSS and image files, and FreeMarker templates. See Oracle Secure Enterprise Search Administration API Guide for more information about skin bundles and using the Administration API to manage skin bundles.
In addition to using the Administration API, you can manage skin bundles using a WebDAV interface to the SES instance. The WebDAV interface enables you to track, edit, and manage the skin bundles. You can add and update the skins including the template files and asset files through the WebDAV interface. See "About the WebDAV Interface" for more information.
In addition to versioned support bundles, Oracle SES also includes versioned skin bundles. Each skin is packaged as a skin bundle and contains the template files, and the asset files including CSS files and image files that define the skin. A skin bundle can be linked to a support bundle.
You can define the following properties for a skin bundle:
skinname: Name of the skin.
linkedVersion: The version of the Oracle SES UI support bundle that this skin is linked to, such as 11.1.2.0.0. If no version is specified when a skin bundle is created, the default value is the current major Oracle SES version. Note that the version number must consist of five numerals separated by dots (for example 11.1.2.0.0).
isDefault: A flag to indicate whether a skin is the default skin. It can be set to true or false. If a user accesses the query application without specifying a skin name, then the skin bundle marked as default is used to render the UI. Only one skin bundle must be marked as the default skin. If no skin bundle is marked as default, then the default query UI is displayed, using the template files located in the current UI support bundle.
enabled: A flag to indicate whether a skin is currently active in Oracle SES. It can be set to true or false. If set to false, then it is unavailable to end users. By default, the status for a skin is set to false.
For more information about these parameters, see "Configuring the Skin Bundle Properties".
For any query request made by the user, Oracle SES selects an active skin bundle in the following order, terminating at the first match:
If a skin name is specified in the URL, then Oracle SES searches for the skin bundle. If the skin bundle is found and its state is set to enabled, then Oracle SES makes it the active skin bundle for this request.
If only one skin bundle is marked as default and it is set to enabled, then Oracle SES makes it the active skin bundle for this request.
If a skin bundle is not found based on the above criteria, then there are no active skin bundles. In such a scenario, Oracle SES displays the default UI support bundle.
Note:
Only one skin bundle must be marked as default using theisDefault parameter. However, using the WebDAV interface, it is possible to set multiple skin bundles as default. In such a scenario, Oracle SES is unable to determine the default skin bundle. In such cases, Oracle SES uses the default support bundle to render the query result.After Oracle SES determines the active skin bundle to be used for rendering the query request, the selection of the template files is done in the following order, terminating at the first match:
Oracle SES uses the template files available within the active skin bundle.
Else, it uses the template files available within the linked support bundle.
If template files are not available in either of the locations, then an error exception is thrown.
The support bundles and the skin bundles are stored in the DB XML repository, and can be easily accessed over the WebDAV file access interface. To support WebDAV access, a listener port is enabled for the XML DB repository. This listener port enables the WebDAV HTTP port to communicate with the DB repository. The communication channel between the WebDAV interface and the repository is secured using an authentication mechanism. See "Securing the Oracle SES-WebDAV Communication Channel" for more details.
The support bundles and the skin bundles are stored in the DB repository. The top level folder is skins and is available at /search/queryapp/skins/.
The skins folder holds separate folders for each skin, that is /search/queryapp/skins/skinnames/.
Each skin folder contains subfolders called templates and assets, that is /search/queryapp/skins/skinname/templates
and
/search/queryapp/skins/skinname/assets
The templates folder contains the FreeMarker template files. The assets folder may hold JavaScript files, CSS style sheet files, and image files. Within the templates and assets folders, users can create their own subfolders. This is especially useful within the assets folder, where users can create separate subfolders to store images, style sheets, and JavaScript files.
For example, if you create a skin called blue, then the folder structure for the template file results.ftl is:
/search/queryapp/skins/blue/templates/results.ftl
and the path of a CSS file blue.css is:
/search/queryapp/skins/blue/assets/blue.css
or you can create a subfolder called css to store style sheets, in which case the path is:
/search/queryapp/skins/blue/assets/css/blue.css
FreeMarker macros enable you to retrieve the file paths of the various files that are available within skin bundles and support (product) bundles. This is useful when you need to reference any asset file from a template file. For example, you might need to reference an image file from a template file. In such cases, you are required to provide the relative path of the files, be it within a skin bundle or a support bundle.
The following macros enable you to output the relative URL paths of skin bundle asset files, support bundle JavaScript files, support bundle CSS files, and support bundle image files, respectively.
@skin_asset filename=file_name: Retrieves the file location of any asset file located within the current skin bundle. It returns the URL of the file. This URL makes it accessible from a Web browser. For the filename parameter, you must specify the relative path of the asset file within the /assets/folder of the skin bundle.
@support_js filename=file_name lib=lib_name: Retrieves the location of any JavaScript file located within the current support bundle. It returns the URL of the file. This URL makes it accessible from a Web browser. For the filename parameter, you must specify the relative path of the JavaScript file, depending on the JavaScript library specified with the lib parameter. Valid values for the lib parameter are: ses, yui, and bubbling. The @includes_page_head macro located in the seslib.ftl template file contains relevant examples.
@support_css filename=file_name lib=lib_name: Retrieves the location of any CSS file located within the current support bundle. It returns the URL of the file. This URL makes it accessible from a Web browser. For the filename parameter, you must specify the relative path of the CSS file, depending on the library specified with the lib parameter. Valid values for the lib parameter are ses and yui. The @includes_page_head macro located in the seslib.ftl template file contains relevant examples.
@support_img filename=file_name lib=lib_name: Retrieves the location of any image file located within the current support bundle. It returns the URL of the file. This URL makes it accessible from a Web browser. For the filename parameter, you must specify the relative path of the image file, depending on the library specified with the lib parameter. Valid values for the lib parameter are ses and yui. The @includes_page_head macro located in the seslib.ftl template file contains relevant examples.
For example, consider a template file within the skin blue, deployed to the Oracle SES server http://myhost.example.com:7777/search/query/.
Suppose the template file contains the following template code to reference an asset file arrow.gif:
<img src="<@ses.skin_asset filename="images/arrow.gif"/>">
Then the html output includes the complete URL path for the image file arrow.gif. It is of the format:
<img src="http://myhost.example.com:7777/search/query/assets/skins/blue/images/arrow.gif">
The parameters to configure a skin bundle are listed in an XML file called skinconfig.xml, which can be accessed and modified over the WebDAV interface. Any changes that you make to this file is immediately reflected in the Oracle SES query application.
This XML file must be placed directly within the folder for each skin. For example, for the skin blue, the skinconfig.xml file must be placed within /search/queryapp/skins/blue/.
The properties that can be set include the linked version, the isDefault flag, and the enabled/disabled state as described in "Customizing the Skin Bundles".
The following example lists the contents of a skinconfig.xml file.
<skinconfig xmlns="http://xmlns.oracle.com/search/skinconfig.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/search/skinconfig.xsd http://xmlns.oracle.com/search/skinconfig.xsd"> <isDefault>false</isDefault> <linkedVersion>11.1.2.0.0</linkedVersion> <enabled>true</enabled> </skinConfig>
Access to the Oracle SES application over the WebDAV interface is secured using an authentication mechanism, whereby only the eqsys user is allowed to access the skin bundle and support bundle folders.
By default, Oracle SES does not allow users to connect to listener ports from remote computers. This is controlled using the parameters tcp.invited_nodes and tcp.validnode in ORACLE_HOME/network/admin/sqlnet.ora.
To allow the eqsys user access to the WebDAV HTTP port from a remote computer, you must edit the following parameters in sqlnet.ora file as shown in the example:
tcp.invited_nodes=(testhost1,testhost2,127.0.0.1) tcp.validnode_checking=yes
where testhost1, testhost2, and 127.0.0.1 are the IDs of remote computers that can access the listener.
Restart the Oracle SES midtier and backend after modifying sqlnet.ora.
searchctl restartall
Note that you can also provide the network address of the remote computer as the ID. If it is not desirable to open up the WebDAV port for remote access, then the Administration API can be used to manage skin bundles as an alternative to the WebDAV interface.
Note:
In previous releases, the base path of Oracle SES was referred to asORACLE_HOME. In Oracle SES release 11g, the base path is referred to as ORACLE_BASE. This represents the Software Location that you specify at the time of installing Oracle SES.
ORACLE_HOME now refers to the path ORACLE_BASE/seshome.
For more information about ORACLE_BASE, see "Conventions".