new QueryBuilder( $el, options )

Parameters
Name Type Description
$el jQuery
options object

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

Details

Members


<static, readonly> DEFAULTS :object

Description

Default configuration

Details
object

<static> Group :function

Details
function

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

Description

Default operators

Details
object.<string, object>

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

Description

Localized strings (see i18n/)

Details
object.<string, object>

<static> Rule :function

Details
function

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

Description

CSS selectors for common components

Details
object.<string, string>

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

Description

Template strings (see template.js)

Details
object.<string, string>

<static> utils :object

Details
object

<readonly> $el :jQuery

Description

Element container

Details
jQuery

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

Description

List of filters

Details

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

Description

List of icons

Details
object.<string, string>

<readonly> lang :object

Description

Translations object

Details
object

<readonly> model :Model

Description

Internal model

Details

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

Description

List of operators

Details

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

Description

Plugins configuration

Details
object.<string, object>

<readonly> settings :object

Description

Configuration object

Details
object

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

Description

List of templates

Details
object.<string, function()>

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
Details

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
Details

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

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

Description

Checks the configuration of each filter

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

ConfigError

Details

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

Description

Checks the configuration of each operator

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

ConfigError

Details

clear()

Description

Clears all rules and removes the root group

Details

clearErrors( [ node ] )

Description

Clears all errors markers

Parameters
Name Type Attributes Description
node Node <optional>

default is root Group

Details

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

Details

deleteRule( rule ) → {boolean}

Description

Tries to delete a rule

Parameters
Name Type Description
rule Rule
Returns

if the rule has been deleted

Details

destroy()

Description

Destroys the builder

Details

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

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
Details

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

on( type, cb ) → {QueryBuilder}

Description

Attaches an event listener on the builder container

Parameters
Name Type Description
type string
cb function
Returns
Details

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

reset()

Description

Clear all rules and resets the root group

Details

setOptions( options )

Description

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

Parameters
Name Type Description
options object
Details

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

Details

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

Throws

RulesError, UndefinedConditionError

Details

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
Details

trigger( type ) → {$.Event}

Description

Triggers an event on the builder container

Parameters
Name Type Description
type string
Returns
Details

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
Details

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

Description

Performs value validation

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

true or error array

Details

Type Definitions


Filter

Details
object

Operator

Details
object

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

changer:getDefaultFilter

Description

Modifies the default filter for a rule

Parameters
Name Type Description
filter QueryBuilder.Filter
rule Rule
Details

changer:getGroupTemplate

Description

Modifies the raw HTML of a group

Parameters
Name Type Description
html string
level int
Returns
Details

changer:getOperators

Description

Modifies the operators available for a filter

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

changer:getRuleFilters

Description

Modifies the list a filters available for a rule

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

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

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

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

changer:getRules

Description

Modifies the result of the QueryBuilder#getRules method

Parameters
Name Type Description
json object
Returns
Details

changer:getRuleTemplate

Description

Modifies the raw HTML of a rule

Parameters
Name Type Description
html string
Returns
Details

changer:getRuleValue

Description

Modifies the rule's value grabbed from the DOM

Parameters
Name Type Description
value *
rule Rule
Returns
Details

changer:groupToJson

Description

Modifies the JSON generated from a Group object

Parameters
Name Type Description
json object
group Group
Returns
Details

changer:jsonToGroup

Description

Modifies the Group object generated from the JSON

Parameters
Name Type Description
group Group
json object
Returns

the same group

Details

changer:jsonToRule

Description

Modifies the Rule object generated from the JSON

Parameters
Name Type Description
rule Rule
json object
Returns

the same rule

Details

changer:parseGroupFlags

Description

Modifies the consolidated group's flags

Parameters
Name Type Description
flags object
group object

not a Group object

Returns
Details

changer:parseRuleFlags

Description

Modifies the consolidated rule's flags

Parameters
Name Type Description
flags object
rule object

not a Rule object

Returns
Details

changer:ruleToJson

Description

Modifies the JSON generated from a Rule object

Parameters
Name Type Description
json object
rule Rule
Returns
Details

changer:setRules

Description

Modifies data before the QueryBuilder#setRules method

Parameters
Name Type Description
json object
options object
Returns
Details

changer:translate

Description

Modifies the translated label

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

changer:validate

Description

Modifies the result of the QueryBuilder#validate method

Parameters
Name Type Description
valid boolean
Returns
Details

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

afterAddGroup

Description

Just after adding a group

Parameters
Name Type Description
group Group
Details

afterAddRule

Description

Just after adding a rule

Parameters
Name Type Description
rule Rule
Details

afterApplyGroupFlags

Description

After group's flags has been applied

Parameters
Name Type Description
group Group
Details

afterApplyRuleFlags

Description

After rule's flags has been applied

Parameters
Name Type Description
rule Rule
Details

afterClear

Description

After the QueryBuilder#clear method

Details

afterCreateRuleFilters

Description

After creating the dropdown for filters

Parameters
Name Type Description
rule Rule
Details

afterCreateRuleInput

Description

After creating the input for a rule and initializing optional plugin

Parameters
Name Type Description
rule Rule
Details

afterCreateRuleOperators

Description

After creating the dropdown for operators

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

allowed operators for this rule

Details

afterDeleteGroup

Description

Just after deleting a group

Details

afterDeleteRule

Description

Just after deleting a rule

Details

afterInit

Description

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

Details

afterReset

Description

After the QueryBuilder#reset method

Details

afterSetRules

Description

After the QueryBuilder#setRules method

Details

afterUpdateGroupCondition

Description

After the group condition has been modified

Parameters
Name Type Description
group Group
previousCondition object
Details

afterUpdateRuleFilter

Description

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

Parameters
Name Type Description
rule Rule
previousFilter object
Details

afterUpdateRuleOperator

Description

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

Parameters
Name Type Description
rule Rule
previousOperator object
Details

afterUpdateRuleValue

Description

After the rule value has been modified

Parameters
Name Type Description
rule Rule
previousValue *
Details

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

beforeAddRule

Description

Just before adding a rule, can be prevented

Parameters
Name Type Description
parent Group
Details

beforeClear

Description

Before the QueryBuilder#clear method, can be prevented

Details

beforeDeleteGroup

Description

Just before deleting a group, can be prevented

Parameters
Name Type Description
parent Group
Details

beforeDeleteRule

Description

Just before deleting a rule, can be prevented

Parameters
Name Type Description
rule Rule
Details

beforeDestroy

Description

Before the QueryBuilder#destroy method

Details

beforeReset

Description

Before the QueryBuilder#reset method, can be prevented

Details

rulesChanged

Description

After any change in the rules

Details

validationError

Description

Fired when a validation error occurred, can be prevented

Parameters
Name Type Description
node Node
error string
value *
Details