Overview

QueryBuilder is an UI component to create queries and filters.

• It can be used on advanced search engine pages, administration backends, etc.
• It is highly customizable and is pluggable to many jQuery widgets like autocompleters, sliders and datepickers.
• It outputs a structured JSON of rules which can be easily parsed to create SQL/NoSQL/whatever queries.
• And it also comes with a set of great plugins and has a full events system for even more features.

Getting started

Dependencies

• jQuery >= 1.10
• Bootstrap >= 3.1 (CSS Buttons and Utilities only)
• $.extendext
• MomentJS (optional, for Date/Time validation)
• Other libraries used by plugins

Let's go!

Include query-builder.css in your page head and query-builder.js after the dependencies. Then add QueryBuilder to any <div> you want.

<div id="builder"></div>

<script>
  $('#builder').queryBuilder({
    filters: [ ... ]
  });
</script>

QueryBuilder can also be used with CommonJS :

require(['jquery', 'query-builder'], function($) {
  $('#builder').queryBuilder({
    filters: [ ... ]
  });
});

A standalone version is available with $.extendext included (you still need to add jQuery and Bootstrap).

Backends

Awesome people implemented parsers in various language, check them out :

• JAVA (JDBC) itfsw / QueryBuilder
• JAVA (JOOQ) Kowalski.io / jqb2jooq
• .NET castle-it / dynamic-linq-query-builder
• PHP (Doctrine ORM) fourlabsldn / QBJSParser
• PHP (Symfony with Doctrine ORM) fourlabsldn / QBJSParserBundle
• PHP (Illuminate, Laravel with Illuminate) timgws / QueryBuilderParser
• PHP (Yii 2) leandrogehlen / yii2-querybuilder
• PHP (Symfony with Doctrine ORM) josedacosta / jQueryQueryBuilderBundle
• Python NorthIsUp / querybuilder
• Python shunyeka / jQuery-QueryBuilder-Python-Evaluator
• Python (SQLAlchemy ORM) ocurero / sqlalchemy-querybuilder
• Rails SixiS / jquery_query_builder-rails
• Go enjoei/pkg/ / querybuilder

Want your project listed here ? Open an issue or create a pull request on the gh-pages branch.

Usage

Options

optgroups: {
  core: '-- Core',
  plugins: '-- Plugins'
}

optgroups: {
  core: {
    'en': '-- Core',
    'fr': '-- Coeur',
    'de': '-- Kern'
  }
}

Filters

The filters option is an array of plain objects defining the rules possible contents. Here are the available attributes:

label: {
  'en': 'Name',
  'fr': 'Nom',
  'es': 'Nombre'
}

Validation

QueryBuilder integrates a configurable validation system triggered when validate() or getRules() methods are called. The default validator checks for emptyness and can be extended with format check and bounds.
Optionally you can define a custom validation callback.

Here are the available attributes of the validation field of each filter:

validation: {
  format: /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/,
  messages: {
    format: 'The provided IP is not valid'
  }
}

Methods

The plugin's function acts as a proxy to access all underlying methods.

$('#builder').queryBuilder('methodName', param_1, param_2);

You can also execute methods by getting a reference to the builder instance.

$('#builder')[0].queryBuilder.methodName(param_1, param_2);

Only main methods are described, consult the API documentation to learn more about all available methods.

// get all rules
$('#builder').queryBuilder('getRules');

// get all rules and their flags when applicable
$('#builder').queryBuilder('getRules', { get_flags: true });

$('#builder').queryBuilder('setRules', { ... });

{
  "condition": "AND",
  "rules": [
    {
      "id": "price",
      "field": "price",
      "type": "double",
      "input": "text",
      "operator": "less",
      "value": "10.25"
    },
    {
      "condition": "OR",
      "rules": [
        {
          "id": "category",
          "field": "category",
          "type": "integer",
          "input": "select",
          "operator": "equal",
          "value": "2"
        },
        {
          "id": "category",
          "field": "category",
          "type": "integer",
          "input": "select",
          "operator": "equal",
          "value": "1"
        }
      ]
    }
  ]
}

$('#builder').queryBuilder('setRules', {
  condition: 'AND',
  data: { // group data
    foo: 'bar'
  },
  rules: [
    {
      /* rule definition */
      data: { // rule data
        foo: 'bar'
      }
    }
  ]
});

$('#builder').queryBuilder('setRules', {
  condition: 'AND',
  rules: [
    {
      /* standard rule */
    },
    {
      /* empty rule */
      empty: true
    }
  ]
});

{
    filter_readonly: true,
    operator_readonly: true,
    value_readonly: true,
    no_delete: true
}

{
  condition_readonly: true,
  no_add_rule: true,
  no_add_group: true,
  no_delete: true
}

var root_model = $('#builder').queryBuilder('getModel');

var last_node_model = $('#builder').queryBuilder('getModel', $('#builder .rule-container').last());

$('#builder').queryBuilder('reset');

$('#builder').queryBuilder('destroy');

Events

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.

The full list of events can be found in the API documentation.

$('#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();
  }
});

$('#builder').on('getGroupTemplate.queryBuilder.filter', function(e, level) {
  if (level == 1) {
    e.value = /* ... */
  }
});

Themes

QueryBuilder comes with two colors-schemes: default (clear) and dark. Change the active theme by switching stylesheets. You cannot use both color-schemes on the same page.

Advanced

Operators

QueryBuilder is bundled with an extensive list of operators. You can change which operators are available for each filter (see filters configuration) but you can also modify/reorder the operators globally and even add new custom operators.

The operators config property is an array of strings (existing operators) or object (existing and new operators). The operators properties are :

For example to only use "equal" and "not equal" operators you use this config :

operators: ['equal', 'not_equal']

To use "equal" and "not equal" and a custom operator, in custom optgroups :

operators: [
  { type: 'equal', optgroup: 'basic' },
  { type: 'not_equal', optgroup: 'basic' },
  { type: 'geo', optgroup: 'custom', nb_inputs: 3, multiple: false, apply_to: ['number'] }
]

Translation

Translation files are available in the i18n folder. Just include one of the files after the main JavaScript to use it.

You can load multiple translation files and use the lang_code option to choose which language to use.

Available languages are (some are partially translated) :

Alternatively you can overwrite some translations with the lang option. It is very useful for custom operators and conditions.
Default English strings are in the source code .

Icons

The icons option provides a way of using alternate icons sets. Available attributes:

Templates

For very specific customizations, QueryBuilder provides a way to completely overwrite the HTML templates used to display rules and groups. It uses the JS template litterals by default, but can be used with most JS template engines, like underscore.js one.

Templates must be provided as a function taking an object of variables and returning an HTML string (_.template for instance). Check the default templates in the source code.

For all templates, these variables are available :

• builder reference to the QueryBuilder object
• settings short-hand for builder.settings
• lang short-hand for builder.settings.lang
• icons short-hand for builder.settings.icons

Inside the box

You might have noticed that callbacks and events refer to two objects Rule and Group. These objects are part of the data model with partial data-binding used internally by QueryBuilder. Here are the structures of these two objects. Most attributes will live-update the builder when modified.