The Site Search viewtool allows you to search for files, pages, and content on a SiteSearch index, and list all available SiteSearch indices.
Methods
| Method | Return Value | Description |
|---|---|---|
$sitesearch.search(query, offset, limit) | SiteSearchResults object | Run the query on the default SiteSearch index and return the specified content items. |
$sitesearch.search(indexAlias, query, offset, limit) | SiteSearchResults object | Run the query on the SiteSearch index specified by the indexAlias, and return the specified content items. |
$sitesearch.listSearchIndicies() | List of String | Returns a list of all available Site Search index names. You can pass the name of any index as the first argument to the search() method, above. |
Perform 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
| Argument | Description |
|---|---|
| indexAlias | Alias of the index where the search is to be performed. If an alias is not specified, the default SiteSearch index will be used. |
| query | Query used to perform the search. You may use the Show Query feature to create queries that you can copy and paste directly into this view tool. You can use the Site Search Tool to test your queries in the dotCMS backend. |
| offset | Start record number (for pagination). |
| limit | Number of results to return (for pagination). |
Return Values
The search() methods return a SiteSearchResults (plural) object. The following methods are available on the returned object:
| Method | Value Returned |
|---|---|
| getStart() | The start record. |
| getTotalResults() | Total number of results returned by the query. |
| getTook() | Time it took to run the query. |
| getLimit() | Value of the limit argument. |
| getOffset() | Value of the offset argument. |
| getResults() | List of search results (see below). |
| getMaxScore() | Maxiumum search score of all the search results. |
| getIndex() | The index where the search was performed. |
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:
| Method | Value Returned |
|---|---|
| getContent() | Content object for the search result. |
| getFilename() | File name of the search result (if appropriate to the Content Type). |
| getLanguage() | Language (as an integer) of the Content. |
| getId() | Identifier (id) of the Content. |
| getHost() | Host where the Content is stored. |
| getUri() | URI of the Content (the path to the Content within the dotCMS asset tree). |
| getUrl() | URL of the Content (the browser URL to access the Content). |
| getMimeType() | mimeType of the Content. |
| getTitle() | Content Title field. |
| getDescription() | Content Description field. |
| getKeywords() | Content keywords field. |
| getAuthor() | Content author. |
| getContentLength() | Content length (in bytes). |
| getModified() | Date the Content was last modified. |
| getScore() | Search score for the Content. |
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.
Examples
The following examples demonstrate how to use the SiteSearch viewtool to query and display results on your site.
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>
<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>
#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>