Presentation

Plugins are used to extend the possibilities of QueryBuilder either by adding new public method or by modifying default behaviour.

Some plugins like Mongo support and SQL support don't require any configuration and are usable as long as they are loaded. Other plugins must be manually activated with the plugins option. This option is an object where keys are plugin names and values are plugin configuration (or null).

$('#builder').queryBuilder({
  plugins: {
    'bt-tooltip-errors': { delay: 100 },
    'sortable': null
  }
});

Below you can find the plugins shipped by default with QueryBuilder, with their identifiers.

Want to create a new plugin ? Check our developer doc.

Import/Export plugins

These plugins do not need to be initialized with the plugins option. You can directly use the new methods.

SQL export sql-support

Allows to export rules as a SQL WHERE statement.

New methods

.getSQL([mode [, linebreaks]])

Performs validation and returns the rules as a valid SQL WHERE statement. See the demo for output example. The first parameter can be:

false outputs plain SQL
'question_mark' outputs prepared statement with ? placeholders
'numbered' outputs prepared statement with numbered ($1, $2, ...) placeholders
'named' outputs prepared statement with named (:id, :category, ...) placeholders
'numbered([char])' outputs prepared statement with numbered placeholders with a custom prefix (one char only, example: numbered(@), numbered(:))
'named([char])' outputs prepared statement with named placeholders with a custom prefix (one char only, example: named(@), named($))

Set the second parameter to true to enable new lines in output.

// prepared statements with question mark params
var sql_stmt = $('#builder').queryBuilder('getSQL', 'question_mark');

// prepared statement with custom named params
var sql_stmt_cust = $('#builder').queryBuilder('getSQL', 'named(@)');

// plan SQL with linebreaks
var sql_raw = $('#builder').queryBuilder('getSQL', false, true);

.setRulesFromSQL(sql [, mode])

Clears the builder and set new rules from an SQL query. This method requires SQLParser to be loaded. The second parameter is used to inform the parser which kind of prepared statements are used (if any).

// no statements
$('#builder').queryBuilder('setRulesFromSQL', 'author LIKE "%Tolkien%" AND publish_date BETWEEN "1954/01/01" AND "1956/01/01"');

// statements with question marks
$('#builder').queryBuilder('setRulesFromSQL', {
  sql: 'author LIKE ? AND publish_date BETWEEN ? AND ?',
  params: ['%Tolkien%', '1954/01/01', '1956/01/01']
}, 'question_mark');

// named statements
$('#builder').queryBuilder('setRulesFromSQL', {
  sql: 'author LIKE :author AND publish_date BETWEEN :begin AND :end',
  params: {
    author: '%Tolkien%',
    begin: '1954/01/01',
    end: '1956/01/01'
  }
}, 'named');

New events

Check the API documentation for the list of events added by this plugin.

Requirements

<!-- SQLParser -->
<script src="sql-parser/browser/sql-parser.js"></script>

Operators

The SQL plugin requires special configuration for operators to convert rules to a valid SQL query. This configuration is stored in the sqlOperators option, see the source code for more details.

About filters' id

setRulesFromSQL assumes that you have only one filter by database field. If this is not the case, you can use the getSQLFieldID changer to determine the filter's id.

MongoDB import/export mongodb-support

Allows to export rules as a MongoDB find object as well as populating the builder from a MongoDB object.

New methods

.getMongo()

Performs validation and returns the rules as a valid MongoDB find object. See the demo for output example.

var mongo = $('#builder').queryBuilder('getMongo');

.setRulesFromMongo(query)

Clears the builder and set new rules from a MongoDB find object. The general rules syntax must be the same as what getMongo outputs.

$('#builder').queryBuilder('setRulesFromMongo', { /* ... */ });

New events

Check the API documentation for the list of events added by this plugin.

Operators

The MongoDB module requires special configuration of operators to convert rules to a valid Mongo JSON and vice-versa. This configuration is stored in the mongoOperators and mongoRuleOperators options, the keys are the operators types and the values are formatting functions, see the source code for more details.

About filters' id

setRulesFromMongo assumes that you have only one filter by database field. If this is not the case, you can use the getMongoDBFieldID changer to determine the filter's id.

Other

The following export plugins are maintained by the community :

New features

Sortable rules sortable

Enables drag & drop sort of rules and groups. It is based on interact.js to offer touch screen support.

The plugin also adds two new rule/group flags useable with setRules method: no_sortable and no_drop.

Requirements

<!-- interact.js -->
<script src="interact/dist/interact.min.js"></script>

Options

Name type default description
icon string 'glyphicon glyphicon-sort' The font-icon used as drag handle
inherit_no_sortable boolean true When a group is no_sortable, should its rules and sub-groups be no_sortable too.
inherit_no_drop boolean true When a group is no_drop, should its rules and sub-groups be no_drop too.

New events

Check the API documentation for the list of events added by this plugin.

Filter description filter-description

Provides three ways to display a description about a filter: inline, Bootstrap Popover or Bootbox.

The description is defined in the description attribute of each filter. It can be a string or a function returning a string. The description can contain HTML.

filters: [{
    /* .... */
    description: 'This filter is <b>awesome</b> !'
}, {
    /* .... */
    description: function(rule) {
        return 'The description for ' + (rule.operator ? rule.operator.type : 'anything');
    }
}]

Requirements

<!-- Bootstrap CSS & JS -->
<link rel="stylesheet" href="bootstrap/css/bootstrap.min.css">
<script src="bootstrap/js/bootstrap.min.js"></script>

<!-- Bootbox JS (requires Bootstrap CSS & JS) -->
<script src="bootbox/bootbox.js"></script>

Options

Name type default description
icon string 'glyphicon glyphicon-info-sign' The font-icon used for the button
mode string 'popover' inline, popover or bootbox

Unique filter unique-filter

Allows to define some filters as "unique": which can be used for only one rule, globally or in the same group.

The plugin adds a new filter attribute named unique, set it to true to define the filter globally unique, or to group to define the filter unique inside its group.

filters: [
  {
    /* .... */
    unique: true // this filter can be used only once in the whole builder
  },
  {
    /* .... */
    unique: 'group' // this filter can be used only once in each group
  }
]

Invert rules invert

Adds a button in each group & rule to easily "invert" a part of the builder, that means transform "AND" into "OR", "equal" into "not equal", and so on.

If a filter must never be inverted, set it's no_invert option to true.

filters: [{
    /* .... */
    no_invert: true
}]

New methods

.invert([options])

Performs invertion programatically on the whole builder or on a particular Node. It also takes an optionnal object of behavioral options similar to the plugin's options.

This method is available even if the plugin is not initialized in the builder (plugins builder option).

// invert the whole builder with default options
$('#builder').queryBuilder('invert');

// invert the whole builder with custom behavior
$('#builder').queryBuilder('invert', {
  invert_rules: false,
  silent_fail: true
});

// invert a particular Group with options
$('#builder').queryBuilder('invert', group, {/* ... */});

Options

The plugin uses the operatorOpposites and conditionOpposites builder options to map each condition/operator to its invert. You must update it if you add new operators and conditions. Set silent_fail plugin option to false if one of your new condition/operator has no invert value.

Name type default description
icon string 'glyphicon glyphicon-random' The font-icon used for the button
recursive boolean true Recursively invert conditions an operators
invert_rules boolean true Invert rules operators as well as groups conditions
display_rules_button boolean false Display the invert button for each rule (by default the button is only on groups)
silent_fail boolean false Do not throw an error when a condition or an operator has no invert defined

New events

Check the API documentation for the list of events added by this plugin.

Not group not-group

Adds a checkbox in front of the group conditions to apply a NOT operator to the whole group. It differs from the Invert rules plugin has it does not modify the conditions and operators but only add a not flag to the groups, it also only works on groups.

It comes with support for the SQL and MongoDB plugins.

New events

Name Description & arguments
afterUpdateGroupNot.queryBuilder After the not flag of a group has been changed.
  • group Group object

Options

Name type default description
icon_unchecked string 'glyphicon glyphicon-unchecked' The font-icon used for the button when not checked
icon_checked string 'glyphicon glyphicon-check' The font-icon used for the button when checked

New events

Check the API documentation for the list of events added by this plugin.

Change filters change-filters

This plugin does not require initialization through the plugins config. It adds new methods to change the list of filters after builder initialization.

New methods

.setFilters([force,] filters)

Replace all filters by new ones. If a rule is using an old filter an error will be throw, unless you set the first parameter to true, in which case such rules will be deleted.

// change filters, might throw an error
$('#builder').queryBuilder('setFilters', [ /* ... */ ]);

// change filters and delete orphan rules
$('#builder').queryBuilder('setFilters', true, [ /* ... */ ]);

.addFilter(filter|filters [, position])

Adds one or more new filters at a specific position.

// add a filter at the end of the list
$('#builder').queryBuilder('addFilter', { /* ... */ });

// add a two filters at the begining of the list
$('#builder').queryBuilder('addFilter', [
    { /* ... */ },
    { /* ... */ },
], 0);

// add a filter after filter "name"
$('#builder').queryBuilder('addFilter', { /* ... */ }, 'name');

// add a filter at position 4
$('#builder').queryBuilder('addFilter', { /* ... */ }, 4);

.removeFilter(filterName|filtersNames [, force])

Removes one or more filters by their identifier.

// remove filter "name", might throw an error
$('#builder').queryBuilder('removeFilter', 'name');

// remove filters "name" and "age" and delete orphan rules
$('#builder').queryBuilder('setFilters', ['name', 'age'], true);

New events

Check the API documentation for the list of events added by this plugin.

Display

BT Tooltips for errors bt-tooltips-errors

Applies Bootstrap Tooltips on validation error messages.

Requirements

<!-- Bootstrap CSS & JS -->
<link rel="stylesheet" href="bootstrap/css/bootstrap.min.css">
<script src="bootstrap/js/bootstrap.min.js"></script>

Options

All options supported by the tooltips plugin.

BT Selectpicker for filters/operators bt-selectpicker

Applies Bootstrap Select on filters and operators combo-boxes.

Requirements

<!-- Bootstrap Select CSS & JS -->
<link rel="stylesheet" href="bootstrap-select/dist/css/bootstrap-select.min.css">
<script src="bootstrap-select/dist/js/bootstrap.min.js"></script>

Options

All options supported by the selectpicker plugin.

Awesome BT Checkbox bt-checkbox

Applies Awesome Bootstrap Checkbox to checkbox and radio inputs.

The input color (all 6 Bootstrap colors) can be configured globally but also per-filter or even per-value with the colors filter attribute.

filters: [
  {
    /* .... */
    input: 'checkbox',
    color: 'primary' // same color for each checkbox
  },
  {
    /* .... */
    input: 'radio',
    colors: { // different color for each radio
      0: 'danger',
      1: 'success'
    }
  }
]

Requirements

<!-- Awesome Bootstrap Checkbox CSS -->
<link rel="stylesheet" href="awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css">

Options

Name type default description
color string 'default' Default color, one of the six Bootstrap "colors"
font string 'glyphicons' glyphicons or fontawesome