1. Home
  2. Classes
  3. QueryBuilder

new QueryBuilder( $el, options )

Parameters
Name Type Description
$el jQuery
options object

see http://querybuilder.js.org/#options
Details

main.js, line 18

Members

<static, readonly> DEFAULTS :object

Description

Default configuration

Details
object

defaults.js, line 125

<static> Group :function

Details
function

model.js, line 542

Group

<static, readonly> OPERATORS :object.<string, object>

Description

Default operators

Details
object.<string, object>

defaults.js, line 97

<static, readonly> regional :object.<string, object>

Description

Localized strings (see i18n/)

Details
object.<string, object>

defaults.js, line 90

<static> Rule :function

Details
function

model.js, line 549

Rule

<static, readonly> selectors :object.<string, string>

Description

CSS selectors for common components

Details
object.<string, string>

defaults.js, line 51

<static, readonly> templates :object.<string, string>

Description

Template strings (see template.js)

Details
object.<string, string>

defaults.js, line 83

<static> utils :object

Details
object

utils.js, line 11

Utils

<readonly> $el :jQuery

Description

Element container

Details
jQuery

main.js, line 26

<readonly> filters :Array.<QueryBuilder.Filter>

Description

List of filters

Details
Array.<QueryBuilder.Filter>

main.js, line 68

<readonly> icons :object.<string, string>

Description

List of icons

Details
object.<string, string>

main.js, line 75

<readonly> lang :object

Description

Translations object

Details
object

main.js, line 103

<readonly> model :Model

Description

Internal model

Details
Model

main.js, line 40

<readonly> operators :Array.<QueryBuilder.Operator>

Description

List of operators

Details
Array.<QueryBuilder.Operator>

main.js, line 82

<readonly> plugins :object.<string, object>

Description

Plugins configuration

Details
object.<string, object>

main.js, line 96

<readonly> settings :object

Description

Configuration object

Details
object

main.js, line 33

<readonly> templates :object.<string, function()>

Description

List of templates

Details
object.<string, function()>

main.js, line 89

Methods

addGroup( parent [, addRule [, data [, flags ] ] ] ) → {Group}

Description

Adds a new group

Parameters
Name Type Attributes Default Description
parent Group
addRule boolean <optional>
 true

adds a default empty rule
data object <optional>

group custom data
flags object <optional>

flags to apply to the group
Returns
Fires
Details

core.js, line 377

addRule( parent [, data [, flags ] ] ) → {Rule}

Description

Adds a new rule

Parameters
Name Type Attributes Description
parent Group
data object <optional>

rule custom data
flags object <optional>

flags to apply to the rule
Returns
Fires
Details

core.js, line 525

change( type, value ) → {*}

Description

Triggers an event on the builder container and returns the modified value

Parameters
Name Type Description
type string
value *
Returns
Details

main.js, line 167

checkFilters( filters ) → {Array.<QueryBuilder.Filter>}

Description

Checks the configuration of each filter

Parameters
Name Type Description
filters Array.<QueryBuilder.Filter>
Returns
Throws

ConfigError

Details

core.js, line 30

checkOperators( operators ) → {Array.<QueryBuilder.Operator>}

Description

Checks the configuration of each operator

Parameters
Name Type Description
operators Array.<QueryBuilder.Operator>
Returns
Throws

ConfigError

Details

core.js, line 163

clear()

Description

Clears all rules and removes the root group

Fires
Details

public.js, line 70

clearErrors( [ node ] )

Description

Clears all errors markers

Parameters
Name Type Attributes Description
node Node <optional>

default is root Group
Details

core.js, line 905

deleteGroup( group ) → {boolean}

Description

Tries to delete a group. The group is not deleted if at least one rule is flagged no_delete.

Parameters
Name Type Description
group Group
Returns

if the group has been deleted

Fires
Details

core.js, line 432

deleteRule( rule ) → {boolean}

Description

Tries to delete a rule

Parameters
Name Type Description
rule Rule
Returns

if the rule has been deleted

Fires
Details

core.js, line 581

destroy()

Description

Destroys the builder

Fires
Details

public.js, line 5

getModel( [ target ] ) → {Node}

Description

Returns the model associated to a DOM object, or the root model

Parameters
Name Type Attributes Description
target jQuery <optional>
Returns
Details

public.js, line 117

getRules( [ options ] ) → {object}

Description

Gets an object representing current rules

Parameters
Name Type Attributes Description
options object <optional>
Name Type Attributes Default Description
get_flags boolean | string <optional>
 false

export flags, true: only changes from default flags or 'all'
allow_invalid boolean <optional>
 false

returns rules even if they are invalid
skip_empty boolean <optional>
 false

remove rules that have no filter selected
Returns
Fires
Details

public.js, line 224

off( type [, cb ] ) → {QueryBuilder}

Description

Removes an event listener from the builder container

Parameters
Name Type Attributes Description
type string
cb function <optional>
Returns
Details

main.js, line 195

on( type, cb ) → {QueryBuilder}

Description

Attaches an event listener on the builder container

Parameters
Name Type Description
type string
cb function
Returns
Details

main.js, line 184

once( type, cb ) → {QueryBuilder}

Description

Attaches an event listener called once on the builder container

Parameters
Name Type Description
type string
cb function
Returns
Details

main.js, line 206

reset()

Description

Clear all rules and resets the root group

Fires
Details

public.js, line 33

setOptions( options )

Description

Modifies the builder configuration.
Only options defined in QueryBuilder.modifiable_options are modifiable

Parameters
Name Type Description
options object
Details

public.js, line 104

setRoot( [ addRule [, data [, flags ] ] ] ) → {Group}

Description

Creates the root group

Parameters
Name Type Attributes Default Description
addRule boolean <optional>
 true

adds a default empty rule
data object <optional>

group custom data
flags object <optional>

flags to apply to the group
Returns

root group

Fires
Details

core.js, line 344

setRules( data [, options ] )

Description

Sets rules from object

Parameters
Name Type Attributes Description
data object
options object <optional>
Name Type Attributes Default Description
allow_invalid boolean <optional>
 false

silent-fail if the data are invalid
Fires
Throws

RulesError, UndefinedConditionError

Details

public.js, line 337

translate( [ category ], key ) → {string}

Description

Translate a label either by looking in the lang object or in itself if it's an object where keys are language codes

Parameters
Name Type Attributes Description
category string <optional>
key string | object
Returns
Fires
Details

data.js, line 633

trigger( type ) → {$.Event}

Description

Triggers an event on the builder container

Parameters
Name Type Description
type string
Returns
Details

main.js, line 151

validate( [ options ] ) → {boolean}

Description

Validates the whole builder

Parameters
Name Type Attributes Description
options object <optional>
Name Type Attributes Default Description
skip_empty boolean <optional>
 false

skips validating rules that have no filter selected
Returns
Fires
Details

public.js, line 136

validateValue( rule, value ) → {array|boolean}

Description

Performs value validation

Parameters
Name Type Description
rule Rule
value string | Array.<string>
Returns

true or error array

Fires
Details

data.js, line 8

Type Definitions

Filter

Description

See http://querybuilder.js.org/index.html#filters

Details
object

main.js, line 1

Operator

Description

See http://querybuilder.js.org/index.html#operators

Details
object

main.js, line 7

Events

changer:displayError

Description

Modifies an error message before display

Parameters
Name Type Description
errorMessage string

the error message (translated and formatted)
error array

the raw error array (error code and optional arguments)
node Node
Returns
Details

core.js, line 938

changer:getDefaultFilter

Description

Modifies the default filter for a rule

Parameters
Name Type Description
filter QueryBuilder.Filter
rule Rule
Returns
Details

core.js, line 557

changer:getGroupTemplate

Description

Modifies the raw HTML of a group

Parameters
Name Type Description
html string
level int
Returns
Details

template.js, line 127

changer:getOperators

Description

Modifies the operators available for a filter

Parameters
Name Type Description
operators Array.<QueryBuilder.Operator>
filter QueryBuilder.Filter
Returns
Details

data.js, line 304

changer:getRuleFilters

Description

Modifies the list a filters available for a rule

Parameters
Name Type Description
filters Array.<QueryBuilder.Filter>
rule Rule
Returns
Details

core.js, line 619

changer:getRuleFilterSelect

Description

Modifies the raw HTML of the rule's filter dropdown

Parameters
Name Type Description
html string
rule Rule
filters Array.<QueryBuilder.Filter>
Returns
Details

template.js, line 182

changer:getRuleInput

Description

Modifies the raw HTML of the rule's input

Parameters
Name Type Description
html string
rule Rule
name string

the name that the input must have
Returns
Details

template.js, line 315

changer:getRuleOperatorSelect

Description

Modifies the raw HTML of the rule's operator dropdown

Parameters
Name Type Description
html string
rule Rule
operators Array.<QueryBuilder.Operator>
Returns
Details

template.js, line 212

changer:getRules

Description

Modifies the result of the QueryBuilder#getRules method

Parameters
Name Type Description
json object
Returns
Details

public.js, line 316

changer:getRuleTemplate

Description

Modifies the raw HTML of a rule

Parameters
Name Type Description
html string
Returns
Details

template.js, line 154

changer:getRuleValue

Description

Modifies the rule's value grabbed from the DOM

Parameters
Name Type Description
value *
rule Rule
Returns
Details

data.js, line 445

changer:getRuleValueSelect

Description

Modifies the raw HTML of the rule's value dropdown (in case of a "select filter)

Parameters
Name Type Description
html string
string}

name
rule Rule
Returns
Details

template.js, line 242

changer:groupToJson

Description

Modifies the JSON generated from a Group object

Parameters
Name Type Description
json object
group Group
Returns
Details

public.js, line 302

changer:jsonToGroup

Description

Modifies the Group object generated from the JSON

Parameters
Name Type Description
group Group
json object
Returns

the same group

Details

public.js, line 451

changer:jsonToRule

Description

Modifies the Rule object generated from the JSON

Parameters
Name Type Description
rule Rule
json object
Returns

the same rule

Details

public.js, line 437

changer:parseGroupFlags

Description

Modifies the consolidated group's flags

Parameters
Name Type Description
flags object
group object

not a Group object
Returns
Details

data.js, line 593

changer:parseRuleFlags

Description

Modifies the consolidated rule's flags

Parameters
Name Type Description
flags object
rule object

not a Rule object
Returns
Details

data.js, line 537

changer:ruleToJson

Description

Modifies the JSON generated from a Rule object

Parameters
Name Type Description
json object
rule Rule
Returns
Details

public.js, line 285

changer:setRules

Description

Modifies data before the QueryBuilder#setRules method

Parameters
Name Type Description
json object
options object
Returns
Details

public.js, line 356

changer:translate

Description

Modifies the translated label

Parameters
Name Type Attributes Description
translation string
key string | object
category string <optional>
Returns
Details

data.js, line 647

changer:validate

Description

Modifies the result of the QueryBuilder#validate method

Parameters
Name Type Description
valid boolean
Returns
Details

public.js, line 203

changer:validateValue

Description

Modifies the result of the rule validation method

Parameters
Name Type Description
result array | boolean

true or an error array
value *
rule Rule
Returns
Details

data.js, line 19

afterAddGroup

Description

Just after adding a group

Parameters
Name Type Description
group Group
Details

core.js, line 403

afterAddRule

Description

Just after adding a rule

Parameters
Name Type Description
rule Rule
Details

core.js, line 544

afterApplyGroupFlags

Description

After group's flags has been applied

Parameters
Name Type Description
group Group
Details

core.js, line 892

afterApplyRuleFlags

Description

After rule's flags has been applied

Parameters
Name Type Description
rule Rule
Details

core.js, line 860

afterClear

Description

After the QueryBuilder#clear method

Details

public.js, line 89

afterCreateRuleFilters

Description

After creating the dropdown for filters

Parameters
Name Type Description
rule Rule
Details

core.js, line 632

afterCreateRuleInput

Description

After creating the input for a rule and initializing optional plugin

Parameters
Name Type Description
rule Rule
Details

core.js, line 723

afterCreateRuleOperators

Description

After creating the dropdown for operators

Parameters
Name Type Description
rule Rule
operators Array.<QueryBuilder.Operator>

allowed operators for this rule
Details

core.js, line 671

afterDeleteGroup

Description

Just after deleting a group

Details

core.js, line 459

afterDeleteRule

Description

Just after deleting a rule

Details

core.js, line 599

afterInit

Description

When the initilization is done, just before creating the root group

Details

core.js, line 8

afterReset

Description

After the QueryBuilder#reset method

Details

public.js, line 55

afterSetRules

Description

After the QueryBuilder#setRules method

Details

public.js, line 465

afterUpdateGroupCondition

Description

After the group condition has been modified

Parameters
Name Type Description
group Group
previousCondition object
Details

core.js, line 486

afterUpdateRuleFilter

Description

After the filter has been updated and the operators and input re-created

Parameters
Name Type Description
rule Rule
previousFilter object
Details

core.js, line 761

afterUpdateRuleOperator

Description

After the operator has been updated and the input optionally re-created

Parameters
Name Type Description
rule Rule
previousOperator object
Details

core.js, line 806

afterUpdateRuleValue

Description

After the rule value has been modified

Parameters
Name Type Description
rule Rule
previousValue *
Details

core.js, line 830

beforeAddGroup

Description

Just before adding a group, can be prevented.

Parameters
Name Type Description
parent Group
addRule boolean

if an empty rule will be added in the group
level int

nesting level of the group, 1 is the root group
Details

core.js, line 382

beforeAddRule

Description

Just before adding a rule, can be prevented

Parameters
Name Type Description
parent Group
Details

core.js, line 526

beforeClear

Description

Before the QueryBuilder#clear method, can be prevented

Details

public.js, line 71

beforeDeleteGroup

Description

Just before deleting a group, can be prevented

Parameters
Name Type Description
parent Group
Details

core.js, line 437

beforeDeleteRule

Description

Just before deleting a rule, can be prevented

Parameters
Name Type Description
rule Rule
Details

core.js, line 586

beforeDestroy

Description

Before the QueryBuilder#destroy method

Details

public.js, line 6

beforeReset

Description

Before the QueryBuilder#reset method, can be prevented

Details

public.js, line 34

rulesChanged

Description

After any change in the rules

Details

core.js, line 411

validationError

Description

Fired when a validation error occurred, can be prevented

Parameters
Name Type Description
node Node
error string
value *
Details

core.js, line 969