Back to Search Back to Search Results

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 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

This tag contains the following attributes.

Name Description Required Type Default
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. false String 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. false int 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. false Date 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. false Date none
createdSinceDays Only return results created in the preceding number of days specified by this attribute. false int 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. false String false
facets A space separated list of search facets. Facets do not affect search results. false Object null
filter A search query to be used as a search filter. The search filter is applied as a secondary search on primary search results. false String null
groupBy The property to group results by. This can either be a base property of 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. false String "itemKey"
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. false int 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. false int 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. false int 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). false String 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. false Date 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. false Date none
modifiedSinceDays Only return results modified in the preceding number of days specified by this attribute. false int none
portalContent Whether and how to include portal content in search. Valid values are "exclude", "include", and "only". false String exclude
query The search query. Must not be the empty string (""). false String *
resultsPerGroup The maximum number of "contexts" to return per group. false int 5
scope The scope of the @var attribute. Valid values are "page" and "request". false String "request"
sortBy The property or properties to sort by, separated by whitespace or comma. false String 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. false String ASC
startAfter Alternative pagination mode. The startNextAfter token from a previous page. false Object 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. false int 0
var The name of the variable used to access the result. true String none