|Oracle® Fusion Middleware User Interface Customization Guide for Oracle WebCenter Interaction
10g Release 4 (10.3.3.0.0)
Part Number E14110-03
You can customize Oracle WebCenter Interaction Search in a number of ways. This chapter summarizes recommended approaches to common customizations, describes their capabilities and limitations, and points to more complete documentation and sample code.
The banner search box is the text search field that appears at the top of each portal page. By default, banner search will query for the text in the name, description, and full-text content of documents, document folders, communities, portlets, and users. When a user is viewing a community or document folder, banner search also offers an option to restrict the search to the area being viewed.
The advanced search page is used to add search constraints on portal properties. Administrators (not standard users) can search a much wider set of object types from advanced search, including administrative objects.
You can customize the behavior of portal banner search and advanced search in a number of ways. Before modifying portal search, see if one of the following solutions provides the functionality you need.
Snapshot Queries display search results in a portlet and cache results to avoid burdening portal search. For details on Snapshot Queries, see the portal online help.
Search Portlets can provide a customized search form, add constraints to search, and more. The Oracle WebCenter Interaction Development Kit (IDK) remote Search API allows you to run search queries against the Oracle WebCenter Interaction system. For details, see the Oracle WebCenter Interaction Web Service Development Guide.
Federated Search uses remote web services to search external repositories from the portal. For details, see the Oracle WebCenter Interaction Web Service Development Guide.
If none of these options fulfill your requirements, you can modify the behavior of portal banner search and advanced search. The sections that follow explain the most common customizations:
You can customize the functionality and appearance of the banner search box in many ways.
The Search Results Manager allows you to limit banner search to return only documents, and configure banner searches to search properties in addition to the Name, Description, and text content. For details, see the Administrator Guide for Oracle WebCenter Interaction.
SearchActions PEIs can be used to require that all results have a set value for a specific property and configure the portal to record every banner search.
To modify every banner search that users run or perform some action whenever users run a banner search, use the IBannerSearchActions PEI. For example, you can add constraints to certain searches, or log some information about each search. For details on implementing PEIs, see Chapter 12, "Using PEIs".
Adaptive page layouts allow you to change the look and feel of the portal user interface, including the search box and search results page using adaptive tags in standard XHTML For details, see Chapter 3, "Using Adaptive Page Layouts".
To change the look and feel of the banner search box or point banner search at another search results page or at the Federated Search results page, you can modify the associated View, PlumtreeTopBarView. PlumtreeTopBarView generates an HTML search form used for banner search, and other parts of the portal banner. For details on Views, see Chapter 13, "Using View Replacement".
To create a new search box in the portal UI, you can create a portlet or add a search box to the appropriate View. You can use the Oracle WebCenter Interaction Development Kit (IDK) remote Search API or the native PTSearch API to execute the query.
To use Federated Search in place of banner search, change the form's
in_hi_space input to point to the NetworkSearch space instead of the SearchResult space, and the
in_hi_control input to "NetworkSearch" instead of "bannerstart". You'll also need to add an
in_cb_source input to simulate checking one of the "Search Locations" on the Federated Search page.
To use an external search page, change the form's target to point to the external page. You will need to rename some other form inputs (such as the query string) to provide the correct names for your target page.
You can also customize the advanced search page. The Search for Text field on the advanced search page behaves similarly to banner search, with a few minor differences; advanced search queries are never spell-checked and the thesaurus is not used, because this page is meant to be a more precise interface for expert users.
To modify every advanced search that users run or perform some action whenever users run an advanced search, use the IAdvancedSearchActions PEI. For example, you can turn on spelling correction for advanced search queries, add constraints to certain searches, or log some information about each search. For details on implementing PEIs, see Chapter 12, "Using PEIs".
To customize the layout of the advanced search page, use one of the approaches below:
To modify the built-in advanced search page, subclass the Views in the com.plumtree.portalpages.browsing.search.advanced package. These Views inherit from the com.plumtree.portalpages.common.search package, so you might need to copy code from that package as a starting point. Be very careful if you modify the code in common.search; these classes are used elsewhere in the portal. For details on Views, see Chapter 13, "Using View Replacement".
To replace the built-in advanced search page entirely, create a custom Activity Space with the name "AdvancedSearch" and use the SearchFormFactory class to automate generation of the HTML form. For details on custom Activity Spaces, see Chapter 14, "Creating Custom Activity Spaces".
Removing an object type or folder from the advanced search page does not guarantee that it is unsearchable. A user can still concoct a URL that runs the search, even if the page never submits it. To prevent this, make sure your users do not have rights to see the objects, or use the IAdvancedSearchActions PEI to prevent unallowed queries.
You can also add search boxes to the portal UI.
Portlets can be used to provide search boxes that query the portal or external repositories. For details on portlets and the Oracle WebCenter Interaction Development Kit (IDK) remote search API, see the Oracle WebCenter Interaction Web Service Development Guide.
Custom Views can include additional search boxes. Use the SearchFormFactory class to automate generation of the HTML form. For more information on Views, see Chapter 13, "Using View Replacement".
Oracle Pathways is delivered with a set of Adaptive Tags to add Oracle Pathways UI elements to the portal UI, allowing users to access Oracle Pathways search from a portal page.
The following tags provide access to Oracle Pathways UI elements. For details on basic tag syntax and usage, see the Oracle WebCenter Interaction Web Service Development Guide.
Adds an OraclePathways search box.
Adds an Oracle Pathways search button.
Returns the URL to the Oracle Pathways home page. This tag is a data tag and must be used in conjunction with a display tag. For details on data tags, see the Oracle WebCenter Interaction Web Service Development Guide.
pt:text parameter defines the text to be displayed in the UI element. If you do not include the
pt:text parameter, no text will be displayed.
The example below adds an Oracle Pathways search box and button to the top bar in the portal banner, a tab to the main portal menu, and a link to the portal Directory tab. This example also includes tags from the UI Elements (pt:ui) and Navigation (pt:plugnav) Adaptive Tag libraries.
Note: This code is taken from the header example included with the Oracle Pathways installation (<PT_HOME>\ptimages\pathways\private\navtags\header.html). To install these samples in your portal environment, import the pathways_navigation_samples.pte file.
<span xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'> <!-- Topbar --> <table cellpadding="0" cellspacing="0" width="100%" border="0" class="banTopbarBg" id="pt-topbar"> <tr> <td align="left" valign="middle" nowrap="nowrap"> <pt:ptui.myhome pt:usespan="true"/> <span class="banGreetingText banText" id="pt-user-nav"> <pt:ptui.welcome pt:usespan="true" /> <span class="spacer" style="padding-left:8px;"></span> <pt:ptui.myaccount pt:usespan="true" /> <span class="spacer" style="padding-left:8px;"></span> <pt:ptui.login pt:usespan="true"/> </span> </td> <td align="right" valign="middle" nowrap="nowrap"> <pt:ptui.rulesdebug/> <pt:ptui.help/> <pt:ptui.searchform pt:usespan="true"> <pt:ptui.basicsearchbutton/> <pt:ptui.advancedsearchbutton/> <pt:ptui.federatedsearchbutton/> </pt:ptui.searchform> <!-- Add the Pathways Banner Search Elements --> <pt:pathways.pathwayssearchform pt:usespan="true" pt:text="Pathways:"> <pt:pathways.pathwayssearchbutton/> </pt:pathways.pathwayssearchform> </td> </tr> </table> <!-- Topbar section end --> <!-- Dropdown menus section begin --> <pt:ptdata.communityactionsdata pt:id="commmenu" /> <pt:ptdata.mycommunitiesdata pt:id="commmenu" /> <pt:ptdata.mandatorylinksdata pt:id="mandlinks" /> <pt:ptdata.mandtabcommsdata pt:id="menutabs" /> <pt:ptdata.administrationdata pt:id="menutabs" /> <!-- Add Pathways Home link as a menu tab. --> <pt:pathways.pathwayshome pt:id="menutabs" pt:text="Pathways Home"/> <pt:ptdata.mypageactionsdata pt:id="mypagemenu" /> <pt:ptdata.mypagesdata pt:id="mypagemenu" /> <pt:ptdata.currcommunitypagesdata pt:id="commpages" /> <pt:ptdata.currsubcommunitiesdata pt:id="subcomms" /> <pt:ptdata.currrelatedcommunitiesdata pt:id="relcomms" /> <pt:ptdata.directorybrowsedata pt:id="directorymenu" /> <pt:ptdata.directoryeditdata pt:id="directorymenu" /> <!-- Add Pathways Home link to the directory menu. --> <pt:pathways.pathwayshome pt:id="directorymenu" pt:text="Pathways Home"/> <pt:ptdata.mandatorylinknamedata pt:key="mandlinksname" /> <pt:plugnav.ddmenurowcontainer pt:menuvar="midrowmenu" pt:hideemptymenus="true" > <pt:plugnav.ddmenutab pt:containervar="midrowmenu" pt:datavar="mypagemenu" pt:text="$#1840.ptmsgs_portalbrowsingmsgs" /> <pt:plugnav.ddmenutab pt:containervar="midrowmenu" pt:datavar="commmenu" pt:text="$#1841.ptmsgs_portalbrowsingmsgs" /> <pt:plugnav.ddmenutab pt:containervar="midrowmenu" pt:datavar="directorymenu" pt:text="$#1842.ptmsgs_portalbrowsingmsgs" /> <pt:plugnav.ddmenutab pt:containervar="midrowmenu" pt:datavar="mandlinks" pt:text="$mandlinksname" /> <pt:plugnav.ddmenusimpletabs pt:containervar="midrowmenu" pt:datavar="menutabs" /> </pt:plugnav.ddmenurowcontainer> <!-- Dropdown menus section end --> ... </span>
The search results page is the portal page that users see after submitting any banner or advanced search. (This page is not used for Federated Search.)
You can customize the appearance of the search results page. There are some limitations because the portal uses this page in a number of ways; the Add Portlets and Join Communities pages are both customized versions of the search results page. The sections that follow summarize the most common customizations.
To display the results of a common query for a specific audience, you can use a Snapshot Query and Content Snapshot Portlet without writing any code. For details, see the portal online help. To create a custom results page that is hosted remotely, write a remote portlet that calls the Oracle WebCenter Interaction Development Kit (IDK) remote search API. Your "results page" is simply a community page with this portlet on it. For details, see the Oracle WebCenter Interaction Web Service Development Guide.
Adaptive page layouts allow you to change the look and feel of the search results page using adaptive tags in standard XHTML For details, see Chapter 3, "Using Adaptive Page Layouts".
If the Search Results Adaptive Layout does not provide the customization you need, you can customize the corresponding View classes. You can make minor modifications to the standard Views, or use them as a base to write your own Activity Space that replaces the main portal search results page.
The HTML for the portal's search results page is generated by View classes in the following packages:
com.plumtree.portaluiinfrastructure.search (in portaluiinfrastructure.jar)
com.plumtree.portalpages.browsing.results.search (in portalpages.jar)
The View classes use SearchResultModel, in com.plumtree.portaluiinfrastructure.search, as their corresponding model. SearchResultModel wraps PTSearch. Do not modify SearchResultModel, because the portal reuses it in many ways.
The search results View classes call read-only methods on SearchResultModel to get information about the search results. The most important View classes are GroupedResultsView and GroupedResultsViewHelper. For more information on Views, see Chapter 13, "Using View Replacement".
GroupedResultsView loops over the search results and calls methods in GroupedResultsViewHelper.
GroupedResultsViewHelper generates the HTML for each result. This View can be replaced at runtime by any other class that implements the same interface, to support results tables with a different look and feel.
Four other Views also appear on the search results page.
SearchSummaryView inspects the original request and summarizes it (for example , "Showing 10 results of 52, and dogg was corrected to dog").
FollowupSearchView lets the user run another search from the results page, either within the same results with the same settings, or a new search of the whole portal.
OrganizationView and its helper ReorganizationViewHelper let the user re-sort by last-modified date, folder, object type, or other properties, and show drill down links into these categories.
PaginationView provides links to more search results.
There are corresponding Control classes for each of the links in these Views (the UI framework invokes the Control's execute method when a user clicks a link). These Controls include PaginationControl, ReorganizationControl, SearchWithinResultsControl, and BreadcrumbControl. Most of these Controls have a static makeURL() method that you call from the View code to make a new link. In most cases, you only need to copy and customize Views and DisplayPages. The Models and Controls for this page are designed to be reusable (they are used several places in the portal).
To replace the built-in results page entirely, call your new ActivitySpace SearchResult. You can also use your customized page as the target for a custom search form; set the
in_hi_space input to the name of the new Activity Space.
Note: Test your changes thoroughly. Test both banner and advanced search. Make sure banner search works from every type of portal page (My Page, community, and Directory). Confirm that it works with every search result type
By default, the Sort By drop-down list on the search results page lets users organize results in four ways:
Relevance (Rank): Results are presented in decreasing order of relevance. To improve relevance ranking on the search results page, see Improving Relevance Ranking.
Last Modified Date: Results are re-ranked according to the date and time each object was last modified, with the most recently modified items ranked first.
Folder: Results are grouped according to the Knowledge Directory or Administration folders in which the results are stored. Clicking one of the folder links restricts the results to those that are stored in that folder.
Object Type: Results are grouped according to object type. Clicking one of the object type links restricts the results to those that are of a particular object type.
Adding new properties to the "Sort by" menu allows users to group results according to the property value. To display columns for additional properties on the search results page, you must modify the associated View as explained above.
Note: If the properties are not included in the portal search query, you must add the properties to the search request by writing a Portal Event Interface (PEI). See the next section for more information.
To add search properties to the "Sort by" menu, edit portalconfig.xml as explained below.
Determine the object ID of the property you want to add. Find the object in the directory and open it; the object ID is displayed in the associated editor. You can also determine the ID from the object link. The "in_hi_ObjectId" URL argument contains the integer that represents the object ID.
Open the portalconfig.xml file in a text editor (PT_HOME\settings\portal). Note: Always make a backup copy before editing; formatting errors in this file can disable the portal completely.
<component name="portal:Search"> section within portalconfig.xml. You will add two tags within this tag:
<setting name="CategoryName_1"> : This tag determines the name of the option as it will be displayed in the Sort by menu. It is not required to be the same as the name of the property. This string will be the same in all locales (the related code is not currently internationalized).
<setting name="CategoryField_1">: The integer object ID as determined in step 1 above, preceded by "PT" (all caps, no spaces). For the example above, object ID 200, the value would be PT200.
<component name="portal:Search" type="http://www.plumtree.com/config/component/types/portal/search"> <!-- The default number of search results to show per search results page. --> <setting name="NumSearchResultsPerPage"> <value xsi:type="xsd:string"/> </setting> <setting name="CategoryName_1"> <value xsi:type="DocumentTitle"/> </setting> <setting name="CategoryField_1"> <value xsi:type="PT105"/> </setting> ... </component>
You can add multiple categorization options by adding successive tags (CategoryName_2, CategoryField_2, CategoryName_3, CategoryField_3, etc.), as long as the sequence numbers are consecutive. If you ever delete an option, you must edit the tags to keep the numbers consecutive. Do not forget the trailing "/" before the closing ">".
Save and close portalconfig.xml, stop and restart the portal. Run a search to see your new "Sort by" option.
To query for additional properties using portal search, add new properties to the portal and associate them with the appropriate objects and documents. Once the properties are defined, you must make sure they are returned by the search query.
When choosing new properties to use for search categorization, there are two issues to consider:
Will the property be defined for a large percentage of search results? If 90% of results do not have the property defined, then most results will fall into the "uncategorized" group, and the new categorization will not be useful. Make sure that at least half of all documents and objects have values for the property before adding it as a categorization option.
Will the property values make good category titles? For categorization to work well, each value should be a single word or a short noun phrase, for example, "New England", "Midwest", "Product Management", "Food and Drug Administration". The values should not be full sentences or long lists of keywords, for example, "This content service crawls the New York Times finance section." It will look odd if a full sentence is returned as a category title.
Once you have chosen properties to use for categorization, the next steps are to ensure that the properties are defined in the portal and values for those properties are being assigned to documents and objects.
To create a new property, navigate to Administration and select Create Object | Property. Make sure the following options are checked:
This property is supported for use with documents
This property is visible in the UI
Consider making the property mandatory, since categorization will be of maximum value if every item has a value for the property. Name the property object appropriately and click Finish.
After you create a new property, you must make sure that values are defined for the property. This procedure differs for documents (cards) and administrative objects. The process is summarized below; for more information, see the portal online help.
For documents, the most efficient way to assign property values is through the content crawler that imports the documents. First, create a Content Type object, add the associated property, and set the "mapped attribute" appropriately. For example, for HTML documents the
<META> tag might contain the value. If the value should be the same for all documents the content crawler imports, set the "default" when adding the property to the Content Type. When you create content crawlers, associate your new Content Type with the documents to be crawled. You can also manually import documents and edit their properties.
Property values for administrative objects are generally set manually. First, go to Administration and select Utilities | Global Object Properties Map, and associate the property with each object type for which it should be defined. After the property is associated with an object, you can edit the property value in each object's editor. If the property is mandatory, a value will be required when creating or editing an object.
Customizing query behavior for banner search and advanced search is covered in the previous section.
You can improve the relevance ranking of search results in a variety of ways.
To hard-wire the top few results for specific search queries, use the Best Bets feature (banner search only). Results may be documents, document folders, communities, portlets, and users. For more information and instructions, see the portal online help.
To change the weight of different search fields, use the Search Results Manager utility (Banner Fields Alias page). You can also list additional properties to be searched (for example, a "keywords" or "author" field).
Perform these adjustments with care and test them carefully on all common searches. These settings affect all portal banner searches, and most adjustments will make some rankings better and others worse.
To replace search terms or define synonyms, load a thesaurus list into portal search and enable it. Thesaurus expansion replaces a term or phrase in a user's search with a set of custom, related terms before the search is performed. This feature allows you to improve search quality by handling unique, obscure, or industry-specific terminology. Fore more information, see the Administrator Guide for Oracle WebCenter Interaction.
Federated Search provides access to external repositories without adding documents to the portal Knowledge Directory. Federated Search is especially useful for content that is updated frequently or is only accessed by a small number of portal users. For details, see the Oracle WebCenter Interaction Web Service Development Guide.