SiteSearch Viewtool documentation for the dotCMS Content Management System

The Site Search viewtool allows you to search for files, pages, and content on a SiteSearch index, and list all available SiteSearch indices.

• Methods
• Performing a Search
  • Parameters
  • Return Values
  • Common Query Terms
• Displaying Results
  • Displaying Highlights (Matches)
  • Displaying Content Type Fields
• Examples
  • Perform a Search
  • List Site Search Indices
• Toolbox.xml Configuration

Methods

Performing a Search

The search() method allows you to perform a search against a single site search index. Which index the search is performed against is determined by the indexAlias parameter you supply (if any); if no indexAlias parameter is supplied, the search is performed against the default SiteSearch index.

Parameters

Return Values

The search() methods return a SiteSearchResults (plural) object. The following methods are available on the returned object:

The getResults() method on the SiteSearchResults object returns a list that contains one individual SiteSearchResult (singular) object for each result. The following methods are available on each individual SiteSearchResult object:

Common Query Terms

The SiteSearch index contains certain common fields for all content items included in the index. You can include the following keywords in your query to search on these fields:

• content
• filename
• id
• host
• uri
• url
• mimeType
• title
• description
• keywords
• author
• contentLength
• modified
• score
• language

For more information on query syntax, please see the Content Search Syntax documentation.

Displaying Results

The results are returned in an object that contains properties of the search itself (such as the index alias), and a list of search results, one list item per content item that matched the query (up to the specified limit). Each item in the search results contains all of the properties that can be used to query the index, plus a highlights property.

For details on what specific properties are returned with the search results, please see the Velocity Example, below.

Displaying Highlights (Matches)

Each search result includes a highlights property. This is a list, which contains one entry for each time the content matched the query terms. Each highlight consists of a block of text surrounding the match for context, and the portion of that text which matched the query terms is highlighted (using HTML tags).

The text in each highlight is trimmed to 255 characters; if the field which contained the match is shorter than 255 characters, then the entire contents of the field will be included.

The following code snipped demonstrates how to display all the highlights for a single search result (stored in a Velocity variable named $result):

    #foreach($highlight in $result.highlights)
        <p>$highlight...</p>
    #end

If you only want to display the first highlight, you can add a Velocity #break command into the loop as follows:

    #foreach($highlight in $result.highlights)
        <p>$highlight...</p>
        #break
    #end

Displaying Content Type Fields

The Site Search results contain values that are shared by all content items, but do not contain custom Content Type fields you've added to your Content Types. However, you can display all the fields of your Content Type by calling the $dotcontent.find() method to retrieve the full content object, as in the following code snippet:

$dotcontent.find( "$result.id" )

Examples

The following examples demonstrate how to use the SiteSearch viewtool to query and display results on your site.

• Perform a Search
  • Example Queries
  • Example Velocity Code
• List Site Search Indices

Perform a Search

Example Queries

The following example queries demonstrate several different ways you can create queries for use with the Site Search view tool:

• Search for content that matches a keyword and a specific URI:

  +content:dotcms +uri:/events/index.dot

• Search for content that matches a list of mimeTypes:

  +(mimeType:text/html mimeType:image/jpeg)

• Search for content that matches a description OR author:

  +(description:dotcms* author:jason*)

• Search for content that matches a description OR author in a particular language:

  +(description:dotcms* author:jason*) +language:1

Example Velocity Code

The following code performs a query using the SiteSearch Tool, accessed the contents of the returned SiteSearchResults object, and displays each individual content item returned by the query.

##PERFORM THE SEARCH
#set($indexAlias="Default")
#set($query="dotcms")
#set($searchresults = $sitesearch.search($indexAlias,$query,0,100))

##DISPLAY THE SEARCH RESULTS OBJECT
<p>Start: $searchresults.start</p>
<p>Total Results: $searchresults.totalResults</p>
<p>Took: $searchresults.took</p>
<p>Limit: $searchresults.limit</p>
<p>Offset: $searchresults.offset</p>
<p>MaxScore: $searchresults.maxScore</p>
<p>Index: $searchresults.index</p>
<p></p>

##DISPLAY EACH INDIVIDUAL SEARCH RESULT
<p>Search Results: $searchresults.results.size()</p>
<ul>
#foreach($result in $searchresults.results)
    <li>Title:$result.title</li>
    ##DISPLAY COMMON PROPERTIES
    <ul>
        <li>Filename:$result.fileName</li>
        <li>ID:$result.id</li>
        <li>Host:$result.host</li>
        <li>Uri:$result.uri</li>
        <li>Url:$result.url</li>
        <li>MimeType:$result.mimeType</li>
        <li>Description: $result.description</li>
        <li>Keywords:$result.keywords</li>
        <li>Author:$result.author</li>
        <li>contentLength:$result.contentLength</li>
        <li>modified:$result.modified</li>
        <li>score:$result.score</li>
    </ul>
    ##DISPLAY CUSTOM CONTENT TYPE FIELDS
    #set( $contentObj = $dotcontent.find( "$result.id" ) )
    <ul>
        <li>tags: $contentObj.tags</li>
    </ul>
    ##DISPLAY HIGHLIGHTS
    <div>
        <li>Highlights:</li>
        #foreach($highlight in $result.highlights)
            <li>$highlight...</li>
        #end
    </div>
#end
</ul>

List Site Search Indices

<h3>Site Search Indexes:</h3>
<ul>
#foreach( $indexAlias in $sitesearch.listSearchIndicies() )
   <li>$indexAlias</li>
#end
</ul>

Toolbox.xml Configuration

The following example shows how the Site Search viewtool is mapped in the toolbox.xml file:

<tool>
    <key>sitesearch</key>
    <scope>request</scope>
    <class>com.dotmarketing.sitesearch.viewtool.SiteSearchWebAPI</class>
</tool>