Overview of the Search GUI

You can customize the Oracle SES query UI by modifying certain template files that define the display content in the UI. These template files can then be used by the application logic to render the Oracle SES query UI. You can also create style sheets (CSS files) that define how the pages are visually styled and then provide a link to the CSS files from the template files.

To customize the UI using the template files and style sheets, you must know how to use the FreeMarker Template language and CSS style sheets. See the FreeMarker Web site for information about FreeMarker template files.

The changes that can be made to the UI include:

  • Changing the logo

  • Changing the look and feel including the colors and fonts

  • Modifying the page header and footer including static text and links to other pages

  • Supporting multiple skins for the UI. These skins can be selected using a URL parameter.

  • Supporting RSS, Atom, and CSV formats on the result list.

  • Using common header and footer templates that can be included by all pages.

  • Modifying certain behavior of Oracle SES JavaScript components, such as result clustering.

The following aspects of the Query UI cannot be customized using template files and style sheets:

  • The search results list, which is handled by the Search Results List Advanced Configuration Style Sheets.

  • The Oracle SES query engine full-text search pipeline. The search query on the text index is performed first. Then, the results data is used to render the search results using customized template files.

  • The internal rendering logic for the various visual components on the search results pages. These components are provided as FreeMarker macros in the template library.

User Interface Components

Oracle SES provides a set of user interface components in a template library called seslib.ftl. You can import this library into the template files. To use the library in a template file, insert the following line at the beginning of the template file:

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

The user interface components are implemented using macros in FreeMarker.

These components help in separating the code that defines the internal operations of the Oracle SES query engine from the code that defines the display layout of the UI. You can thus alter the text and modify the display layout without editing any of the code files that control the query engine (.jsp files).

The UI components are listed in Figure 10-1.

Figure 10-1 The UI Components of the Search Results Page

Description of Figure 10-1 follows
Description of "Figure 10-1 The UI Components of the Search Results Page"

The user interface components include:

  1. Header and footer (inc_header.ftl, inc_footer.ftl)

  2. Search query box

  3. Suggested links and suggested content display panel

  4. Context bar subcomponents including bread crumbs and hit statistics

  5. Expandable sidebar

  6. Result cluster trees

  7. Sorting and grouping controls

  8. Result list

  9. Pagination links

  10. Alternate keywords display

Editable Template Files

Oracle SES contains template files that are written in the FreeMarker template language (.ftl). To customize the UI, you can modify these template files. Table 10-1 lists the template files and the corresponding query application pages where they are included. For more information on editing the template files, see Oracle Secure Enterprise Search Administration API Guide.

Table 10-1 List of Template Files

UI Pages Description Template Files to Customize the UI Pages

Main search pages

These pages display the query box, search results, and any search errors and offer the most customization possibilities.

The following template files are used to customize the main search pages:

  • query.ftl: The initial page displayed before a user enters a search query. Can be customized to display a splash screen.

  • results.ftl: Displays the search results page.

  • noresults.ftl: This page is displayed when a search query returns no results. You can customize it to provide useful query suggestions to the user.

  • error.ftl: Displays an error message for invalid search queries, such as invalid syntax.

  • inc_header.ftl, inc_footer.ftl: These template files are used to customize the header and footer information of the main search pages

Cache page

This page acts as the header for pages displayed from the cache.

The cache page logo can be customized using the file web.xml.

Supplemental pages

These pages include the

  • Links page: display_links.jsp

  • E-mail result browser: mail.jsp and pmail.jsp

  • Customize pages: customize.jsp

  • Submit URL page: submit_url.jsp

  • Login page: login.jsp

The header, footer, and CSS files for the supplemental pages can be customized by modifying the following template files:inc_supplemental_header.ftl, inc_supplemental_footer.ftl, and inc_supplemental_includes.ftl

Feeds and CSV

These output pages display the search results as RSS feeds or in a comma-delimited format.

These pages can be customized using the following template files:

  • atom.ftl: Provides an ATOM feed of the search results, which are returned as text or XML from the feed page. This is done by specifying the option feed?output=atom. The default template renders the data in the ATOM Feed 0.3 format.

  • rss.ftl: Provides an RSS feed of the search results. The results are returned in the text or XML format from the feed page. The default template renders the data in the RSS 2.0 format.

  • csv.ftl: This provides the search results in a comma-delimited format. The results are returned in the text format from the csv page.

Template File for Additional Error Handling

In addition to the template files listed in Table 10-1, there is a template file called unchecked_error.ftl, which is used for error handling. This template file is used when there is a severe error and the application throws an unexpected exception. In such cases, the normal UI consisting of the source group tabs, query box, browse popup, and cluster sidebar is not displayed. Instead, the display page consists of the error message, and the header and footer. This template file also includes the supplemental template files inc_supplemental_includes.ftl, inc_supplemental_header.ftl, and inc_supplemental_footer.ftl, to render the header and footer.

Data Model for the Template Files

The data model of a template file defines the dynamic data that is used to render the view.

Data Model for the Main Search Pages

The data model for the files query.ftl, results.ftl, noresults.ftl, and error.ftl contains the variables listed in Table 10-2:

Table 10-2 Data Models for the Main Search Pages

Variable Description

authn

This hash contains information related to secure login and authentication.

authn.isLoggedIn

Boolean value that indicates whether the current user is logged in.

authn.loggedInUser.displayName

If isloggedIn is set to true, then this parameter holds the user name. If isLoggedIn is set to false, then this parameter does not hold any value.

authn.isAuthenticationActive

Boolean value that indicates whether secure search is enabled.

params

This hash contains the URL query parameters for the request. It is an HttpRequestParameterHashModel, as provided by the FreeMarker API.

htmlLang

The language for the <html> tag.

skin

The current skin name.

sourceGroups[]

This sequence is a list of hashes, each representing one source group active on the instance.

sourceGroups[n].id

The source group ID.

sourceGroups[n].name

The source group untranslated name.

sourceGroups[n].displayName

The translated source group name.

pageUrls

This hash contains variables that contain the URL of pages in the query application.

pageUrls.search

the URL for /search.

pageUrls.help

The URL for online help.

pageUrls.login

The login URL, if the user is not logged in.

pageUrls.logout

The logout URL, if the user is logged in.

pageUrls.customize

The Personalize URL.

pageUrls.submitUrl

The URL for the Submit URL page.

showSidebar

Boolean value that indicates whether the result clustering sidebar should be shown.

errorMessage

If an error occurred, this variable holds the error message.

req

This hash represents the search query request.

req.displayQuery

The search query to be displayed, usually for the page title and the hit statistics.

req.queryboxQuery

The portion of the search query entered in the input box, excluding attribute filters.

res

This hash represents the search query response.

res.queryId

The query ID, used for click statistics.

res.startNum

The index of the first result document returned.

res.endNum

The index of the last result document returned.

res.docsReturned

The number of documents returned with this request.

res.estimatedHitCount

The estimated total of all documents that match the query.

res.suggestedLinks[]

This sequence is a list of hashes, each representing a suggested links.

res.suggestedLinks[n].title

The title to display for the suggested link.

res.suggestedLinks[n].url

The URL of the suggested link.

res.resultElements[]

This sequence is a list of hashes, each representing a result document. The format of each result document is not exposed.

perf

This includes basic performance metrics.

perf.reqTime

The total request time from the start of the JSP processing to immediately before template rendering.

perf.searchTime

The time spent in the Java midtier query and backend layers for the text query.

perf.templateLoadTime

The time spent loading the FreeMarker template from the ftl file.

Data Model for the Supplemental Pages

The data model for the supplemental pages is as listed in Table 10-3:

Table 10-3 Data Models for Supplemental Pages

Variables Description

authn

This hash contains information related to secure login and authentication.

authn.isLoggedIn

Boolean value that indicates whether the current user is logged in.

authn.loggedInUser.displayName

If isloggedIn is set to true, then this parameter holds the user name. If isLoggedIn is set to false, then this parameter does not hold any value.

authn.isAuthenticationActive

Boolean value that indicates whether secure search is enabled.

htmlLang

The language for the <html> tag

skin

The current skin name.

pageUrls

This hash contains variables that contain the URL of pages in the query app.

pageUrls.search

The URL for /search.

pageUrls.help

The URL for online help.

pageUrls.login

The login URL, if the user is not logged in.

pageUrls.logout

The logout URL, if the user is logged in.

pageUrls.customize

The Personalize URL.

pageUrls.submitUrl

The URL for the Submit URL page.

Data Model for Output Format Pages

The data model for the files atom.ftl, rss.ftl, and csv.ftl contains the following variables, as listed in Table 10-4:

Table 10-4 Data Model for Output Format Pages

Variables Description

authn

This hash contains information related to secure login and authentication.

authn.isLoggedIn

Boolean value that indicates whether the current user is logged in.

authn.loggedInUser.displayName

If isloggedIn is set to true, then this parameter holds the user name. If isLoggedIn is set to false, then this parameter does not hold any value.

authn.isAuthenticationActive

Boolean value that indicates whether secure search is enabled.

isError

Boolean value that indicates whether an error occurred. This would be equivalent to a situation in which the error.ftl template was invoked.

params

This hash contains the URL query parameters for the request. It is an HttpRequestParameterHashModel, as provided by the FreeMarker API.

currentDate

The current date.

requestURL

The request URL, as returned by HttpServletRequest.getRequestURL().

requestURLParams

The request query string, as returned by HttpServletRequest.getQueryString().

req

This hash represents the search query request.

req.displayQuery

The search query to be displayed, usually for the page title and the hit statistics.

req.queryboxQuery

The portion of the search query entered in the input box, excluding attribute filters.

res

This hash represents the search query response.

res.startNum

The index of the first result document returned.

res.endNum

The index of the last result document returned.

res.docsReturned

The number of documents returned with this request.

res.estimatedHitCount

The estimated total of all documents that match the query.

res.resultElements[]

This sequence is a list of hashes, each representing a result document. The format of each result document is not exposed.

Handling Errors and Exceptions

Errors can creep in while creating the template files. Errors can also occur due to incorrect query syntax from the user end.

Errors in Template Files

Simple syntax errors in the template files are logged in a file called AdminServer_yyyy_MM_dd_hh_mm.log located at ORACLE_HOME/search/base_domain/servers/AdminServer/logs.

Severe exceptions are handled by the file searcherr.jsp which contains the template file unchecked_error.ftl. This page displays only the error message. It does not display the source group tabs, the query box, the clustering sidebar, or the login information.

End User Query Syntax Errors

Query syntax exceptions and other handled exceptions are rendered by the error.ftl file in search.jsp. For example, if a user enters a query that contains invalid syntax or is too broad, then the rendered page contains an error message and other information such as the source groups and the login information.

Configuration Files

Starting in Oracle SES 11g, the Web application configuration parameters are stored in the file QueryPlan.xml. This file is located at ORACLE_HOME/search/tools/weblogic/deploy/plans/.

For changes made to this file to take effect, run the deployer.sh file on Linux as shown:

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

If SES is deployed on a Windows system, then run the batch file deployer.bat, as shown:

%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 is the host name, and port is the WebLogic service port. This is the same port that you use to open the Administration GUI. password is the password for eqsys.

Note:

In previous releases, the configuration parameters were stored in the files web.xml and orion-web.xml.

Using the QueryPlan.xml File

The QueryPlan.xml file contains the following parameters related to the query UI:

  • default_src_group: If no source group is specified, default to querying under the specified group, identified by name. If this parameter value is empty, default to the 'All' group.

  • template_update_delay: The time in seconds since last checking for a newer version of a template file before checking again. The default is 3600 seconds, or one hour.

  • suppress_src_groups: Comma-delimited list of source groups to be hidden from the query UI. This is useful for testing and staging.

  • error_on_invalid_src_group: Flag indicating whether to display an error page if an invalid source group is specified in the query parameters. It takes the values true or false. If set to false, then Oracle SES performs query on the default source group.

  • num_visible_group_tabs: Number of source group tabs displayed above the search box.

  • cluster_more_limit: The number of cluster nodes in the first level of the tree before the remaining nodes are hidden behind the "more…" link. Default value is 5.

  • show_empty_clusters: Flag indicating whether clusters with zero nodes are hidden or displayed in gray. It takes the value true or false.

  • fresh_user_show_sidebar: Flag indicating whether a user visiting Oracle SES through a fresh browser (no cookies) can view the sidebar on the results page. Default value is false.

  • auto_load_topn_results: Flag indicating whether to automatically load the top-N results for the results page. If false, a button icon allows users to manually load the top-N results. Default value is true.

The following example shows how you can configure parameters in the QueryPlan.xml file:

<variable>
 <name>template_update_delay</name>
 <value>0</value>
 <description>Time in seconds since last checking for a newer version of a template before checking again. Default is 3600 seconds.</description>
</variable>

It can be very useful to set the template_update_delay parameter to a value of 0, so that there is no delay in picking up changes made to the template files.

Configuring the JavaScript Components

The following JavaScript components can be configured to render different UI pages.

SearchView

This component manages the query form, page variables, source group selection, and the search within display options.

Constructor

ORACLE.ses.SearchView(obj config)

Key configuration properties

  • searchFormName: Name of the query form.

Key events

  • clearBrowse: When the link clear for the Search within option is clicked.

  • groupTabClick: When a source group tab is clicked.

Result Cluster Tree

Configure the display options for the result cluster tree that is displayed in the search results page using the JavaScript component called ClusterView.

The constructor is

ORACLE.ses.ClusterView(str|HTMLElement el, obj config);

The key configuration properties are:

  • displayEmptyTrees: Boolean that determines the display option of trees. Set as true to display grayed-out empty trees, or false to hide them.

  • autoExpandFirstLevel: Boolean indicating whether the first level of each cluster tree should be expanded or not.

  • moreLimit: Number of nodes in the first-level of each cluster tree before the more option is used.

  • highlightMode: Whether to highlight the currently selected cluster node. It can take the values OFF, NODE, or SUBTREE. For example, the value can be ORACLE.ses.ClusterView.HIGHLIGHT_MODE.SUBTREE. Default value is OFF.

  • allowSelectionToggle: A boolean that indicates whether clicking on a selected node toggles it off, or whether it remains selected. Default is off/false.

  • removeFilterId: The ID of the link to remove filter.

The key events are:

  • beforeRenderClusterTree: Fired before cluster tree is rendered.

  • renderClusterTree: Fired after cluster tree is rendered.

  • beforeRenderClusterNode: Fired before cluster node is rendered.

  • renderClusterNode: Fired after cluster node is rendered.

  • beforeSelectNode: Fired before cluster node is selected. Allows canceling selection.

  • selectNode: Fired after cluster node is selected.

  • beforeDeselectNode: Fired before cluster node is selected. Allows canceling selection.

  • deselectNode: Fired after cluster node is deselected.

These events can be used for various functions such as changing the order of cluster nodes within a tree or relabeling cluster nodes. For example, changing the month label from 1 to January.

Note:

The beforeDeselectNode and deselectNode events are fired before any selectNode events. If deselection is canceled, the selection of the new node does not occur, because multiple selection is not allowed.

ResultsView and ResultsModel

This component asynchronously retrieves the top-N results, renders the results list, handles client-side caching of search results, pagination, and similar documents. Also handles grouping and sorting of the results list, besides asynchronous fetching of email threads.

Constructor

ORACLE.ses.ResultsView (obj SESConnectionFactory, obj config)

Key configuration properties

  • searchView: The search view instance.

  • resultsListContainer: The ID of the container element for the results list.

  • disableTopNResults: Enables disabling the top-N results functionality while still loading the ResultsView component, for example, to support email threading.

  • paginatorContainers: An array of elements or IDs of the containers for pagination links. If multiple containers are passed in, then they are updated together. This registers the paginators to be updated when the results change.

  • hitReportEl: This registers the element to be updated when the results change.

  • loadingImg: The ID of the loading icon image.

  • groupSortContextMsgEl: An element representing the grouping or sorting context message. This registers the element to be updated when the results change. For example, if the @topn_context_msg macro is called directly to render the content message, then use the ID provided to the macro as the value for groupSortContextMsgEl.

  • groupingEl: An element representing the grouping list. This registers the element to be updated when the results change. For example, if the @grouping_control macro is called directly to render the grouping list, then use the ID provided to the macro as the value for groupingEl.

  • sortingEl: An element representing the sorting list and sort order toggle icon. This registers the element to be updated when the results change. For example, if the @sorting_control macro is called directly to render the sorting list, then use the ID provided to the macro as the value for sortingEl.

Key events

  • beforeRenderGroupedResults: Fired before grouped search results are rendered. Allows reordering of the groups.

  • modelChange: Fired when any change occurs to the results model.

  • newResults: Fired when new top-N results are retrieved.

InlineAdvancedView

This component displays the inline attribute filters table.

Constructor

ORACLE.ses.InlineAdvancedView(str|HTMLElement el, str attrNamesArrayID)

BrowseView and BrowseModel

Displays the infosource browse tree. You can control the display of the browse tree such that the entire infosource hierarchy is not loaded initially.

Constructor

ORACLE.ses.BrowseView(str|HTMLElement el, obj SESConnectionFactory, obj config)

Key configuration properties

  • prefetchBrowseGroups: Boolean indicating whether to prefetch the top-level list of source groups, or load the list when the browse overlay is initially opened.

  • statusEl: An element representing the browse tree status message, for example, Loading.

Key events

  • browseUpdate: Fired when an update occurs to the browse model.

  • browseOff: Fired when browse search within is switched off, for example, when all infosource nodes in the browse tree are deselected. As a result, the source group tabs are displayed.

  • allDocsClick: Fired when a document count is clicked to view all the documents in that node.

SuggestedContentView and SuggestedContentModel

Displays suggested links and contents in a tabbed view.

Constructor

ORACLE.ses.SuggestedContentView(str|HTMLElement el, obj SESConnectionFactory, obj config)

Key configuration properties

  • encQuery: The URL encoded query string.

SESConnectionFactory and SESConnection

Stores the base URL and any routing parameters to allow components to make an asynchronous requests to the Oracle SES server.

Constructor

ORACLE.ses.util.SESConnectionFactory(obj config)

Key configuration properties

  • baseurl:The base URL of the Oracle SES application.

  • routingParams: An array of routing parameters.

Key events

  • asyncRequest: Supports the same options as YAHOO.util.Connect.asyncRequest(). Not however that the URI is relative to the base URL, and an additional options parameter allows passing in {serverAffinity: true} if routing parameters are needed for a particular asynchronous request.

AnchoredOverlay

The default usage of this component is to display the Browse Tree overlay next to the Browse link.

Constructor

ORACLE.ses.AnchoredOverlay(str|HTMLElement el)

Key methods

  • setAnchor(str contextElId, str overlayCorner, str contextElCorner)

  • render()

Template File for Initializing JavaScript Components

In addition to the template files listed in Table 10-1, there is a template file called inc_bootstrap_js.ftl initializes the JavaScript components for the query application. This includes initialization of the Search, Results, Browse, and Cluster components.

FreeMarker Macros

The template library file seslib.ftl contains the definitions of the following macros. The output of these macros can be customized by changing the values of the input arguments when the macros are called from the customized templates in a skin bundle.

@navigation_links: Create a list of navigation links. Takes the following parameters:

  • separator: The character or string to be displayed between each link.

  • preLinks, postLinks: The list of links that must be displayed before and after the set of default links.

@logged_in_user: Displays the name of the logged in user.

@when_logged_in, @when_not_logged_in: You can specify content depending on if a user is logged in or not. For example, for an anonymous user, you can set the following display message:

<@when_not_logged_in>
 No secure results are shown.  Please log in to view secure results.
 </@when_not_logged_in>

@source_group_tabs, @source_groups_dropdown: To set the display of source groups as tabs or as a drop-down list.

Note that either macro can be used in a page. However, you must not use both the macros together in a page.

The parameters are:

  • showDefaultAll: Set this to true to display the default All group, or false to hide it.

  • suppressGroups: The set of source groups that must not be displayed.

To suppress a multibyte source group, you must specify the source group name using its hexadecimal Unicode code (UCS code). Typically, UCS codes are of the format \uxxxx. For example \u793e. In the FreeMarker template file, you must replace u with x. For example, the UCS code \u793e\u4f1a must be specified as \x793e\x4f1a.

For example,

<@ses.source_group_tabs formName="${searchFormName}" suppressGroups
=["\x793e\x4f1a"]/>

Note:

There are many Web sites that provide multibyte character to UCS code conversion.

@source_groups_dropdown contains the following additional parameter:

  • submitOnChange: Set this as true to submit the query form when a user selects a source group from the list.

@overlay: Renders the HTML for an overlay window. An overlay window can contain arbitrary content, for example, a browse tree or help content. This macro is intended to be used with the AnchoredOverlay JavaScript component. The parameters are:

  • id: ID of the overlay window. This ID is passed in to the constructor of the AnchoredOverlay JavaScript component.

  • isVisible: Set as true to display the overlay by default.

@feed_href, @feed_icon, @feed_link_tag: These are used to render ATOM or RSS feeds. feed_icon renders an icon for the feed. feed_link_tag renders an autodiscovery tag to the head section of the html.

The parameters for @feed_href are:

  • format: Specifies whether it is an ATOM or RSS feed.

  • num: The number of results to be displayed in the feed.

  • customAttrs: List of names of attributes to include in the feed.

The @feed_icon parameters are:

  • img_src/width/height: Provide the relative or absolute URL of the image, and its dimensions.

  • extra args: Additional arguments may be used to add attributes to the anchor tag, for example to add a link target.

The @feed_link_tag parameters are:

  • format: atom for ATOM feeds and rss for RSS feeds.

  • title: The title attribute to use for the link tag.

For example, the following code displays a feed icon:

<@feed_icon img_src="images/icon/rss.gif"
target="_blank"><@feed_href customAttrs=["contributor", "category"]/>
</@feed_icon>

Similarly, to add a ATOM autodiscovery to a results page, add the following code to the template file results.ftl:

<html>
<head>
   <@feed_link_tag format="atom"><@feed_href/></@feed_link_tag>
...
</head>
...
</html>

@paginator: Renders pagination links for search results in the results.ftl template file. The parameters are:

  • formName: The name of the query form.

  • id: ID of the paginator container. It is used in the paginatorContainers argument when initializing the ResultsView JavaScript component.

@topn_status_icon: Displays a loading icon, error icon, or load icon depending on the state of the ResultsView JavaScript component.

@grouping_control: Displays the results grouping list.

@sorting_control: Displays the results sorting list along with the sort-order icon.

@topn_context_msg: Displays the on top NNN message.

The following parameters are common to the four macros:

  • id: The ID of the control used in the ResultsView component.

  • addClass: A CSS class to add to the control's div element. By default, the @results_list_controls macro adds the controlBarItem class to each individual control to manage styling and alignment.

@results_list_controls: This macro controls the four macros listed above. Use this to set the default values for all four macros.

Note:

  • If a customized arrangement of controls is used, then the corresponding parameter values that are used to register the controls with the ResultsView component should be changed or omitted. For example, if the grouping control is removed from a template, then the groupingEl parameter should not be passed in to the ResultsView component.

  • Multibyte source group names must always be specified using the equivalent Unicode code (UCS code).