Throughout these documentation I've referred to SimpleSearch. This is our first WidgetType, and it's designed to do simple lookup and display of information from backends implementing the same query style as ERM.
I'm now going to walk you through some of the setup we have for SimpleSearch, in order to help illustrate some of this.
WidgetType
This is going to dig a bit deeper into the type JSON for SimpleSearch. The WidgetType is quite large, so I'm going to break it into component sections and talk about what they do and how you can use them to define a WidgetDefinition which conforms to this Type.
Top level
At the top level, this schema looks like the following:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "SimpleSearch widget",
"type": "object",
"description": "SimpleSearch widget type",
"additionalProperties": false,
"required": ["baseUrl", "results"],
"properties": { ... }
}
This specifies some simple information about the type, as well as any required information a WidgetDefinition must contain in order to be a valid Definition for this Type. This is where anything the frontend absolutely requires for basic functionality has to be contained.
Let's look at some of the properties:
"properties": {
"baseUrl": {
"type": "string",
"description": "The base url queries built with this widget will go to"
},
"results": {
"$ref": "#/$defs/results"
},
"filters": {
"$ref": "#/$defs/filters"
},
"sort": {
"$ref": "#/$defs/sort"
},
"configurableProperties": {
"$ref": "#/$defs/configurableProperties"
}
}
As you can see, some of the properties may be very simple fields, such as baseUrl, and some of the properties may require more complicated objects. In this case, most of the top-level properties require more detailed information, so to keep the JSON schema as efficient and flat as possible, this information is split out into a "$defs" section.
Let's look next at the "results" property:
"results": {
"type": "object",
"title": "Results",
"description": "Contains all the information the dashboard needs to fetch and parse results",
"additionalProperties": false,
"required": ["columns"],
"properties": {
"columns": {
"type": "array",
"items": { "$ref": "#/$defs/resultColumn" }
}
}
},
"resultColumn": {
"type": "object",
"title": "Result column",
"description": "Describes the columns to be made available in the output",
"additionalProperties": false,
"required": ["accessPath", "name", "valueType"],
"properties": {
"accessPath": {
"type": "string",
"description": "a string defining the path to the specified object property"
},
"label": {
"type": "string",
"description": "an optional string prescribing the display label of the field"
},
"name": {
"type": "string",
"description": "a string defining the name of the property for this column"
},
"valueType": {
"type": "string",
"enum": ["String", "Integer", "Float", "Boolean", "Date"],
"description": "a string defining the type of property we are displaying"
}
}
}
All of this information is to specify that the shape for this property must look like the following:
results: {
columns: [
{
accessPath: "path.to.property.on.object",
name: "name of property",
label: "display label of field, can be overwritten",
valueType: String
},
...
]
}