Introduction

QueryBuilder uses jQuery events to notify the "outer world" about various things happening, like adding a rule or when a validation error happens. The events system is also used by plugins.

There are two types of events: triggers are used to identify a point in the code and changers are used to modify a value before it is used (eg: template, output rules). Both types are used the same way with the jQuery on method on the builder container.

Callbacks context

In all events callbacks, the first parameter is an Event object which contains the builder property, a reference to the QueryBuilder object currently used. Among other things it contains builder.settings which holds the current configuration.

Rule & Group

Read Inside the box to learn more about the Rule and Group objects.

Plugins events

Events added by plugins are detailed in their respective sections.

Triggers

Events marked with a can be cancelled by calling preventDefault(). The typical example is for the errors events :

$('#builder').on('validationError.queryBuilder', function(e, rule, error, value) {
  // never display error for my custom filter
  if (rule.filter.id == 'my_custom_filter') {
    e.preventDefault();
  }
});
Name Description & arguments
afterInit.queryBuilder When the initilization is done, just before creating the root group.
beforeAddGroup.queryBuilder Just before adding a group.
  • parent Group object
  • addRule true if an empty rule will be added in the group
  • level nesting level of the group, 1 is the root group
afterAddGroup.queryBuilder Just after adding a group.
  • model Group object
beforeDeleteGroup.queryBuilder Just before deleting a group.
  • group Group object
afterDeleteGroup.queryBuilder Just after deleting a group.
beforeAddRule.queryBuilder Just before adding a rule.
  • parent Group object
afterAddRule.queryBuilder Just after adding a rule.
  • rule Rule object
beforeDeleteRule.queryBuilder Just before deleting a rule.
  • rule Rule object
afterDeleteRule.queryBuilder Just after deleting a rule.
afterCreateRuleFilters.queryBuilder After creating the <select> for filters.
  • rule Rule object
afterCreateRuleOperators.queryBuilder After creating the <select> for operators.
  • rule Rule object
  • operators allowed for this rule
afterCreateRuleInput.queryBuilder After creating the input for a rule and initializing optional plugin.
  • rule Rule object
afterUpdateRuleValue.queryBuilder After the rule value has been modified.
  • rule Rule object
afterUpdateRuleFilter.queryBuilder After the filter has been updated and the operators and input re-created.
  • rule Rule object
afterUpdateRuleOperator.queryBuilder After the operator has been update and the input optionally re-created.
  • rule Rule object
afterApplyRuleFlags.queryBuilder After readonly flags has been applied.
  • rule Rule object
afterUpdateGroupCondition.queryBuilder After the group condition has been modified.
  • group Group object
validationError.queryBuilder Fired when a validation error occurred.
  • rule Rule or Group object
  • error
  • value
See error codes
beforeDestroy.queryBuilder Before destroy method.
afterReset.queryBuilder After reset method.
afterClear.queryBuilder After clear method.
afterMove.queryBuilder After a Rule or Group has been moved by the Sortable rules plugin.
  • node The Group or Rule
afterSetFilters.queryBuilder After setFilters method from Change filters plugin.
  • filters
afterInvert.queryBuilder After a Rule or Group has been inverted by the Invert plugin.
  • node The main Group or Rule that has been inverted
  • options

Changers

All changers events have an additional value property which holds the value to be altered (or not).

$('#builder').on('getGroupTemplate.queryBuilder.filter', function(e, level) {
  if (level == 1) {
    e.value = /* ... */
  }
});
Name Description & arguments
displayError.queryBuilder.filter Modified an error message before display.
  • e.value the error message (translated and formatted)
  • error The raw error array (error code and optional arguments)
  • node Group or Rule object
validate.queryBuilder.filter Modifies the result of validate method.
  • e.value boolean
getRules.queryBuilder.filter Modifies the result of getRules method.
  • e.value rules object
ruleToJson.queryBuilder.filter Modifies the JSON generated from the Rule object
  • e.value JSON object
  • rule Rule object
groupToJson.queryBuilder.filter Modifies the JSON generated from the Group object
  • e.value JSON object
  • group Group object
setRules.queryBuilder.filter Modifies data before setRules method.
  • e.value rules object
jsonToRule.queryBuilder.filter Modifies the Rule object generated from the JSON
  • e.value Rule object
  • data JSON object
jsonToGroup.queryBuilder.filter Modifies the Group object generated from the JSON
  • e.value Group object
  • data JSON object
validateValue.queryBuilder.filter Modifies the result of the rule validation method.
  • e.value true or an error array
  • value
  • rule Rule object
getOperators.queryBuilder.filter Modifies operators applicable to a rule.
  • e.value array of objects
  • rule Rule object
getRuleFilters.queryBuilder.filter Modifies filters applicable to a rule.
  • e.value array of objects
  • rule Rule object
getRuleValue.queryBuilder.filter Modifies the value grabbed from the DOM.
  • e.value rule value
  • rule Rule object
parseRuleFlags.queryBuilder.filter Modifies the consolidated rule flags.
  • e.value object of booleans
  • rule Rule object
getGroupTemplate.queryBuilder.filter Modifies the raw HTML of a group.
  • e.value HTML string
  • level starts from 1 (root)
getRuleTempate.queryBuilder.filter Modifies the raw HTML of a rule.
  • e.value HTML string
getRuleFilterSelect.queryBuilder.filter Modifies the raw HTML of the rule filter <select>.
  • e.value HTML string
  • rule Rule object
getRuleOperatorSelect.queryBuilder.filter Modifies the raw HTML of the rule operator <select>.
  • e.value HTML string
  • rule Rule object
getRuleInput.queryBuilder.filter Modifies the raw HTML of the rule input, radios group, checkboxes group, select, etc.
  • e.value HTML string
  • rule Rule object
  • name of the input
getDefaultFilter.queryBuilder.filter When default_filter is set or display_empty_filter = false, modifies the default filter of a rule.
  • e.value default filter id
  • rule Rule object