Advanced Velocity Workshop #LiveFromRTC2019
Allows a query function that searches, filters, and sorts assets using a number of properties, with the returned collection containing Cascade API objects.
Can include non-indexable and non-publishable assets.
Like the Locator Tool, it requires no XML data, so no index block is needed.
Create and initialize the query object.
$_.query()
After applying filtering options, execute the query to collect results.
execute()
All search, filter, and sort methods and properties are set using the Java dot notation. Searching can only be done on a collection of shared metadata set or content type.
Example:
$_.query().byMetadataSet(PATH)$_.query().byContentType(PATH)
The path argument will be in the form of a string that points to the path of the metadata set or content type.
For the remaing examples, we will capture the initialization of the query object in a variable called $query. Note that the execute() method is not done until all criteria are set.
Example:
#set($query = $_.query().byMetadataSet("News Article"))
Queried results can come from a particular site or across all sites. There are two methods to handle this filter.
Example: Specify a Particular Site
#set($query = $query.siteName(SITENAME))
Example: Search Across All Sites
#set($query = $query.searchAcrossAllSites())
To filter by dynamic metadata, use the hasMetadata() or hasAnyMetadataValues() method.
Example: Metadata Filter for Single Value
#set($query = $query.hasMetadata(NAME, VALUE))
Example Metadata Filter for Multiple Values
#set($query = $query.hasAnyMetadataValues(NAME, ["VALUE1", "VALUE2"]))
The number of assets returned in a query collection is limited to 100 by default. This number can increased or decreased using the maxResults(INT) method. There is currently a hard maximum limit of 2000 since v8.9.
Example:
#set($query = $query.maxResults(200))
The Query Tool provides two sort methods. The sortBy() method takes in the field name as a string. Fields that can be used are:
The sortDirection() takes in either the string "asc" or "desc" as an argument.
Example: Sort By
#set($query = $query.sortBy("startDate"))
Example: Sort Direction
#set($query = $query.sortDirection("asc")) Seven additional methods are provided to explicitly include or exclude assets that are of a particular entity type, set to be indexable, or set to be publishable. These methods all take in a boolean as an argument and their defaults are listed to the right.
Example: Include by Entity Type
includePages() => trueincludeBlocks() => trueincludeFiles() => falseincludeFolders() => trueincludeSymlinks() => trueindexableOnly() => truepublishableOnly() => false
API Changelog often presents new Query Tool features or updates.
Locator Tool and Query API lists out more methods and contains more examples.