Back to Search Back to Search Results

<@td.groupSearch>

The groupSearch tag executes a search over the contextualized content in the portal (i.e. DITA topics used by maps) as well as top-level publications, grouping the results by their context and storing the results in a variable. The result placed into @var is a SearchResultsPage. Note that the prevailing metadata search values (from the search request URL parameters) will be appended to the search query specified in the query attribute. This may lead to unexpected results if the tag is invoked in various search results contexts.

This tag contains the following attributes:

cacheKey
Unique identifier for this tag. If specified and cacheSecs is positive, this will serve as the cache key. Otherwise the relevant attributes will be used and all tags with the same attribute values will share the cache.
  • Required: false
  • Type: String
  • Default: none
cacheSecs
The number of seconds to cache the results. All calls to this tag with the same attributes will receive the cached value for the specified length of time unless the cacheKey attribute is specified, in which case only tags with the same ID will be affected by the caching. Specify 0 or a negative number to disable caching.
  • Required: false
  • Type: int
  • Default: 0
createdBefore
A Date value specifying the last creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.
  • Required: false
  • Type: Date
  • Default: none
createdSince
A Date value specifying the earliest creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.
  • Required: false
  • Type: Date
  • Default: none
createdSinceDays
Only return results created in the preceding number of days specified by this attribute.
  • Required: false
  • Type: int
  • Default: none
escape
Whether to escape characters in the query so that it operates as a true full-text search rather than a more formal search engine query. When set to 'true', colons, parentheses, and other special characters used to structure queries will be escaped and treated as plain text. If false, the query will be treated as a formal search engine query, and syntax errors will cause failures. The default is false.
  • Required: false
  • Type: String
  • Default: false
  • Since: 4.2
facets
A space separated list of search facets. Facets do not affect search results.
  • Required: false
  • Type: Object
  • Default: null
  • Since: 4.2
filter
A search query to be used as a search filter. The search filter is applied as a secondary search on primary search results.
  • Required: false
  • Type: String
  • Default: null
  • Since: 4.2
groupBy
The property to group results by. This can either be a base property of SearchResultDocument or a metadata field. If a metadata field, the name should end in "_md". For instance, to group by "product" metadata, specify "product_md". The default value is "itemKey", meaning that different uses of the same DITA topic in different DITA maps will be grouped together.
  • Required: false
  • Type: String
  • Default: "itemKey"
  • Since: 4.2.1
highlightSize
The total number of characters before and after the given search term in a result. Note that if the search term is "*" then the highlight size will be 0. Must be an integer n 0 <= n <= 2147483647.
  • Required: false
  • Type: int
  • Default: 300
limit
The maximum number of results per page. Must be a positive integer n where 0 < n <= 2147483647. This does not limit the total number of search results, which may be limited by other settings.
  • Required: false
  • Type: int
  • Default: 10
maxFacetValues
The maximum number of facet values to return when executing the search. The resulting facets will be listed from most-hits to least-hits. Note that this can have a significant impact on search performance.
  • Required: false
  • Type: int
  • Default: 10
metadataFields
Space-separated list of metadata fields to return with each search result. If the list is empty, all default metadata fields will be returned. Otherwise, only the listed fields will be returned. An asterisk ("*") may be used in any term as a wildcard. Use just "*" to return all metadata fields (both default and custom).
  • Required: false
  • Type: String
  • Default: null
modifiedBefore
A Date value specifying the last modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.
  • Required: false
  • Type: Date
  • Default: none
modifiedSince
A Date value specifying the earliest modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.
  • Required: false
  • Type: Date
  • Default: none
modifiedSinceDays
Only return results modified in the preceding number of days specified by this attribute.
  • Required: false
  • Type: int
  • Default: none
portalContent
Whether and how to include portal content in search. Valid values are "exclude", "include", and "only".
  • Required: false
  • Type: String
  • Default: exclude
  • Since: 4.2
query
The search query. Must not be the empty string ("").
  • Required: false
  • Type: String
  • Default: *
resultsPerGroup
The maximum number of "contexts" to return per group.
  • Required: false
  • Type: int
  • Default: 5
scope
The scope of the @var attribute. Valid values are "page" and "request".
  • Required: false
  • Type: String
  • Default: "request"
sortBy
The property or properties to sort by, separated by whitespace or comma.
  • Required: false
  • Type: String
  • Default: none
sortDirection
A list of sort directions ('ASC' or 'DESC'), corresponding in order to the list of 'sortBy' fields. If the list is empty or shorter than the 'sortBy' list, the default of 'ASC' will be used for the missing directions.
  • Required: false
  • Type: String
  • Default: ASC
startAfter
Alternative pagination mode. The startNextAfter token from a previous page.
  • Required: false
  • Type: Object
  • Default: null
startPage
The page number to return. Must be an integer 0 <= n <= 10000. Note that ithe preferred pagination method is to use the startAfter attribute.
  • Required: false
  • Type: int
  • Default: 0
var
The name of the variable used to access the result.
  • Required: true
  • Type: String
  • Default: none

Example usage:

When content is written in DITA, search results are "grouped" by topic, with each individual search result within that group representing the topic as it appears in a given context. To facilitate this, the Group Search tag differs from the Search tag in the following ways.

  • It takes one additional optional attribute, resultsPerGroup that specifies the maximum number of "contexts" to return per group.
  • The data placed into @var is an instance of SearchResultsPage instead of a list of SearchResultDocuments.

The body of this tag can contain any number of <@td.metadataFilter> tags.

<@td.groupSearch var="results" query="Titania" />

<ul>
  <#list results.content as group>
    <li>${group.firstResult.title?html}</li>
    <ul>
      <#list group.results as result>
        <li><a href=<@td.viewerUrl searchResult=result />>${result.contextName}</a></li>
      </#list>
    </ul>
  </#list>
</ul>
Note: Non-DITA content and DITA topics not referenced by any DITA map will only have a single entry in result.content.results which will be identical to result.content.firstResult. Additionally, Portal Theme developers may want to create custom viewer pages for non-DITA content types.

Related information:

<@td.search>
Custom Viewer Pages
Search Syntax
Parent topic: The Titania Tag Library