Filter builder

Embed the filter builder of a layer, send it the fields and an existing filter, and receive the filter the user builds.

The filter-builder widget lets the user build a named filter from rules over the fields of a table, and sends that filter back to your page.

URL and parameters

The parameters that start with _ are the same for every widget. See Widgets.

Parameter	Meaning	Required
`schema_source_item_id`	The id of the table that the fields come from. The widget reads the fields from this table itself.	No, if you send `schema`
`schema`	The fields to choose from. Sent with `post-widget-parameters`, not in the URL.	No, if you give `schema_source_item_id`
`value`	An existing filter to edit. Also sent with `post-widget-parameters`.	No

Without both schema_source_item_id and schema the widget shows no name and no rules.

schema is an object keyed by field id. Each field has type and name, and hidden: true hides it. The widget uses fields of type String, Number, Boolean, DateTime, Date, Time and OneToOne.

value is { name, filters }, and filters is an array with one root group.

Messages

For the common messages see Widgets.

action	Direction	payload
`ready`	widget to your page	None. Sent when the widget has loaded.
`post-widget-parameters`	your page to the widget	`{ schema, value }`. Send it after `ready`.
`done`	widget to your page	`{ name, filters }`. The user confirmed the filter.
`cancel`	widget to your page	None. The user closed it without a filter.

Each post-widget-parameters replaces the earlier values as a whole, so send schema and value together.

The widget sends done only when the filter has a name.

A group is { decision: 'all' | 'any', children: [...] }. A rule is { type, field, decision, value }, where decision is ==, !=, <, <=, > or >=. Dates and times in done are ISO strings.

Example

Embed the iframe as Widgets shows, then add this.

// frame is the iframe whose src is `${site}/widgets/filter-builder?${params}`
// and params has the schema_source_item_id of the table
addEventListener('message', (e) => {
  if (e.origin !== site || e.data.messageToken !== messageToken) return
  const { action, payload } = e.data
  if (action === 'ready') {
    frame.contentWindow.postMessage(
      {
        messageToken,
        action: 'post-widget-parameters',
        payload: { value: { name: 'My filter', filters: [] } },
      },
      site
    )
  }
  if (action === 'done') save(payload) // { name, filters }
  if (action === 'cancel') frame.remove()
})

URL and parametersCopy Anchor Link

MessagesCopy Anchor Link

ExampleCopy Anchor Link

On this page

URL and parameters

Messages

Example