Creating Elements
There are a lot of system Elements that ship with Search Blueprints. If none of the system Elements meets your needs, there are many ways to create your own Search Blueprints Elements:
- Use the Custom JSON Element to create Elements from the Search Blueprints Query Builder.
- Use the Add Element source editor to write Elements using a more robust Element editor, including handy preview functionality and a listing of the predefined template variables in the system.
- Duplicate a system Element to get a head start on developing your own custom Element.
- Use the Paste Any Elasticsearch Query system Element if you’re familiar with using the Elasticsearch query DSL and need to cook up an Element quickly based on an Elasticsearch query.
Using the Custom JSON Element
Elements that are not meant to be reused in other Blueprints can be added in the Query Builder while working on a Blueprint. These are only available in the Blueprint of origin and are not visible in the Elements section of Search Blueprints.
Add the Custom JSON Element to the builder and begin editing the boilerplate JSON:
{
"description_i18n": {
"en_US": "Editable JSON Text Area"
},
"elementDefinition": {
"category": "custom",
"configuration": {},
"icon": "custom-field"
},
"title_i18n": {
"en_US": "Custom JSON Element"
}
}
As you type in the JSON editor, auto-completion reveals the available properties. To further understand them, see Understanding the Schema.
While any Element can be written in the Custom JSON Element, usually this approach is best reserved for simple Elements that add a query clause and perhaps a condition. Often these don’t need a uiConfiguration section and don’t make extensive use of the predefined template variables that can be used in an Element. For more complex cases, use the Element source editor.
For example, the below Exclude Journal Articles Element is based on the Custom JSON Element. It adds a condition so that the Element’s query is only applied if a parameter called exclude.journal_articles is true. The query adds a must_not term query clause to make sure results do not match a Web Content article’s entryClassName field.
{
"description_i18n": {
"en_US": "Exclude journal articles from the search."
},
"elementDefinition": {
"category": "hide",
"configuration": {
"queryConfiguration": {
"queryEntries": [
{
"clauses": [
{
"context": "query",
"occur": "filter",
"query": {
"bool": {
"should": [
{
"bool": {
"must_not": [
{
"term": {
"entryClassName": {
"value": "com.liferay.journal.model.JournalArticle"}
}
}
]
}
},
{
"bool": {
"must": [
{
"term": {
"discussion": false
}
}
]
}
}
]
}
}
}
],
"condition": {
"contains": {
"parameterName": "exclude.journal_articles",
"value": "true"
}
}
}
]
}
},
"icon": "hidden"
},
"title_i18n": {
"en_US": "Exclude Journal Articles"
}
}
This Element depends on a custom variable you can add using the Parameter Configuration of a Blueprint. See the Search Blueprints Configuration Reference to learn about adding custom variables to the Blueprint.
Using the Add Element Source Editor
You can have a more robust editing experience for building your Elements. From the Elements section of Search Blueprints, click Add (
).
Name the Element and click Create. The Element Source editor appears, with the Predefined Variables in the pane to the left of the editor. As you type in the JSON editor, auto-completion reveals the available properties. To further understand the available JSON properties, see Understanding the Schema.
The UI configuration options are defined in a uiConfiguration property in the Element JSON. To preview the Element’s configuration window in the Query Builder, click the Preview link (next to the Cancel button).
Using Predefined Variables
To insert a predefined variable to the Element in the Element Source editor, place the cursor at the desired location, then click the variable in the left hand sidebar. In the Custom JSON Element you must type the variable directly into the editor.
See the Predefined Element Variables Reference for details.
Understanding the Element Schema
The Element schema can change. If the schema changes between Liferay versions, importing the older Element’s JSON may fail.
The schema for Search Blueprint Elements is defined in the sxp-query-element.schema.json file. Users with access to the REST API Explorer can browse the schema more conveniently. While logged in to Liferay visit
Expand the POST /v1.0/sxp-blueprints endpoint entry. Scroll down and click the Schema link (next to the Example Value link).
Inspect the syntax in the system Elements to better understand how the Elements are constructed using the schema elements.
Each Element has two mandatory top-level properties: elementDefinition and title_i18n. The elementDefinition must include the category and the configuration → queryConfiguration properties:
{
"elementDefinition": {
"category": "custom",
"configuration": {
"queryConfiguration": {}
}
},
"title_i18n": {
"en_US": "Custom JSON Element"
}
}
In the title field, set the title text for the Element in as many languages as needed.
Creating the Element elementDefinition
The elementDefinition is where you’ll do the bulk of the work. Its properties include category, configuration, icon, and uiConfiguration.
category provides a string that classifies the behavior of the Element. Specify match, boost, conditional, filter, hide, or custom.
configuration provides the queryConfiguration, which holds the query clauses you’re contributing, via the queryEntries property.
icon sets a string that sets which available icon to use for the Element. Any image available in the Lexicon Icon Library can be used (e.g., thumbs-up).
uiConfiguration sets the configuration elements that you’ll show in the UI and then pass into your custom Element with the configured values.
For example, an Element that boosts a term query match on the entryClassName field can configure the query and the UI like this:
"configuration": {
"queryConfiguration": {
"queryEntries": [
{
"clauses": [
{
"query": {
"term": {
"entryClassName": {
"boost": "${configuration.boost}",
"value": "${configuration.entry_class_name}"
}
}
}
}
]
}
]
}
},
"uiConfiguration": {
"fieldSets": [
{
"fields": [
{
"defaultValue": 1,
"label": "Boost",
"name": "boost",
"type": "number",
"typeOptions": {
"min": 0
}
}
]
}
}
Defining the Element configuration
The configuration property holds the nested properties queryConfiguration → queryEntries.
Diving into the queryEntries JSON, it can contain the properties clauses, conditions, enabled, postFilterClauses, and rescores.
- The snippet above shows the Element using
clauses(an array of elements) to add a query clause to the Blueprint-driven search. In addition toquery, you can addadditive,boost,content,disabled,field,name,occur,parent,type, orvalueproperties. - A
conditionprovides a boolean check. If true, the provided clauses are included in the search query; if false, they are left out. - Set
enabledto false (it’s true by default) to disable the Element. - Add
postFilterClauses(as an array ofclauseelements). You can addadditive,boost,content,disabled,field,name,occur,parent,query,type, orvalueproperties. - Add
rescoresto recalculate the relevance score for results of a query. Specify thequery,queryWeight,rescoreQueryWeight,scoreMode, andwindowSize. See the Elasticsearch documentation for details.
The uiConfiguration property holds the nested properties fieldSet and field.
There are several configuration properties you can add for each field in the UI Configuration:
- Use
defaultValueto enter an initial value for the field. - Enter
helpTextto display help text for the field in the Blueprints UI. - Enter a human readable
label. - Enter a
namethat can be used to reference the field elsewhere in the Element, like when passing the field value into the query clause:${configuration.name}. - Set the
typeof the field. Choose fromdate,fieldMapping,fieldMappingList(a list of the available fields, with their locale and a field boost),itemSelector,json,keywords,multiselect,number,select,slider, andtext - Use the
typeOptionsproperty to configure the options available for each type of field. For example, set theoptionsdisplayed for a select field.boostsets a per-field numeric boost value.formatdetermines the acceptable date format (e.g.,yyyyMMddHHmmss).nullablesets whether a null value can be passed.optionssets the options of a select field.requiredsets whether the configuration must have a value.stepsets the numeric increment or decrement value for a number or slider field.unitsets the unit of measurement for a number field.unitSuffixsets the unit notation to display for a number field with a unit (for example, ifunitiskm, you could set theunitSuffixaskmorkilometers).