Global

Members

ColumnLeaf

Prototype additions object for extending FilterLeaf.

Resulting object is similar to FilterLeaf except:

  1. The operand property names another column rather than contains a literal.
  2. Operators are limited to equality, inequalities, and sets (IN/NOT IN). Omitted are the string and pattern scans (BEGINS/NOT BEGINS, ENDS/NOT ENDS, CONTAINS/NOT CONTAINS, and LIKE/NOT LIKE).
Properties:
Name Type Description
identifier string

Name of column (member of data row object) to compare against this column (member of data row object named by column).

converters

Properties:
Name Type Description
number converter
int converter

synonym of number
float converter

synonym of number
date converter
string converter

dateConverter :converter

Type:

editors

Hash of constructors for objects that extend from FilterLeaf, which is the Default member here.

Add additional editors to this object (in the prototype) prior to instantiating a leaf node that refers to it. This object exists in the prototype and additions to it will affect all nodes that don't have their an "own" hash.

If you create an "own" hash in your instance be sure to include the default editor, for example: { Default: FilterTree.prototype.editors.Default, ... }. (One way of overriding would be to include such an object in an editors member of the options object passed to the constructor on instantiation. This works because all miscellaneous members are simply copied to the new instance. Not to be confused with the standard option editor which is a string containing a key from this hash and tells the leaf node what type to use.)

numberConverter :converter

Type:

treeOperators :object

A hash of treeOperator objects.

Type:
  • object

Methods

addEditor(keyopt, extopt, BaseEditoropt) → {FillterLeaf}

An extension is a hash of prototype overrides (methods, properties) used to extend the default editor.

Parameters:
Name Type Attributes Default Description
key string <optional>
 'Default'

Nme of the new extension given in ext or name of an existing extension in FilterTree.extensions. As a constructor, should have an initial capital. If omitted, replaces the default editor (FilterLeaf).
ext object <optional>

An extension hash
BaseEditor FilerLeaf <optional>
 this.editors.Default

Constructor to extend from.
Returns:

A new class extended from BaseEditor -- which is initially FilterLeaf but may itself have been extended by a call to .addEditor('Default', extension).

Type
FillterLeaf

cleanUpAndMoveOn()

change event handler for all form controls. Rebuilds the operator drop-down as needed. Removes error CSS class from control. Adds warning CSS class from control if blank; removes if not blank. Adds warning CSS class from control if blank; removes if not blank. Moves focus to next non-blank sibling control.

This:

copy(el, textopt) → {undefined|string}

  1. Trim the text in the given input element
  2. select it
  3. copy it to the clipboard
  4. deselect it
  5. return it
Parameters:
Name Type Attributes Default Description
el HTMLElement | HTMLTextAreaElement
text string <optional>
 el.value

Text to copy.
Returns:

Trimmed text in element or undefined if unable to copy.

Type
undefined | string

copyAll(containingElopt, prefixopt, separatoropt, suffixopt, transformeropt)

Parameters:
Name Type Attributes Default Description
containingEl HTMLElement <optional>
 document
prefix string <optional>
 ''
separator string <optional>
 ''
suffix string <optional>
 ''
transformer function <optional>
 multiLineTrim

Function to transform each input control's text value.

filterCount() → {number}

Returns:

Number of filters (terminal nodes) defined in this subtree.

Type
number

firstChildOfType(selector)

Work-around for this.el.querySelector(':scope>' + selector) because :scope not supported in IE11.

Parameters:
Name Type Description
selector string

getOpMenu(columnName) → {undefined|Array.<menuItem>}

This:
Parameters:
Name Type Description
columnName string
Returns:
Type
undefined | Array.<menuItem>

getProperty(columnName, propertyName, mixinopt) → {object}

Get the node property.

Priority ladder:

  1. Schema property.
  2. Mixin (if given).
  3. Node property is final priority.
This:
Parameters:
Name Type Attributes Description
columnName string
propertyName string
mixin function | boolean <optional>

Optional function or value if schema property undefined. If function, called in context with propertyName and columnName.
Returns:
Type
object

initialize(optionsopt)

Create a new node or subtree.

Typically used by the application layer to create the entire filter tree; and internally, recursively, to create each node including both subtrees and leaves.

Node properties and options: Nodes are instantiated with:

  1. Certain required properties which differ for subtrees and leaves.
  2. Arbitrary non-standard option properties are defined on the options object (so long as their names do not conflict with any standard options) and never persist.
  3. Certain standard options properties as defined in the optionsSchema hash, come from various sources, as prioritized as follows:
    1. options object; does not persist
    2. state; object; persists
    3. parent object; persists
    4. default object; does not persist

Notes:

  1. "Persists" means output by getState().
  2. The parent object is generated internally for subtrees. It allows standard options to inherit from the parent node.
  3. The default object comes from the default property, if any, of the schema object for the standard option in question. Note that once defined, subtrees will then inherit this value.
  4. If not defined by any of the above, the standard option remains undefined on the node.

Query Builder UI support: If your app wants to make use of the generated UI, you are responsible for inserting the top-level .el into the DOM. (Otherwise just ignore it.)

Parameters:
Name Type Attributes Description
options FilterTreeOptionsObject <optional>

The node state; or an options object possibly containing state among other options. Although you can instantiate a filter without any options, this is generally not useful. See Instantiating a filter in the readme for a practical discussion of minimum options.

  • @memberOf FilterNode#

makeOpMenu(columnName)

This:
Parameters:
Name Type Description
columnName string

mixInNonstandardOptions(options)

Parameters:
Name Type Description
options

mixInStandardOptions(state, options)

Create each standard option from when found on the options or state objects, respectively; or if not an "own" option, on the parent object or from the options schema default (if any)

Parameters:
Name Type Description
state
options

Type Definitions

converter

Type:
  • object
Properties:
Name Type Description
toType function

Returns input value converted to type. Fails silently.
failed function

Tests input value against type, returning false if type ortrue` if not type.

filterLeafViewObject

Type:
  • object
Properties:
Name Type Description
column HTMLElement

A drop-down with options from the FilterLeaf instance's schema. Value is the name of the column being tested (i.e., the column to which this conditional expression applies).
operator

A drop-down with options from columnOpMenu, typeOpMap, or treeOpMenu. Value is the string representation of the operator.
operand

An input element, such as a drop-down or a text box.

FilterTreeGetStateOptionsObject

Object containing options for producing a state object.

State is commonly used for two purposes:

  1. To persist the filter state so that it can be reloaded later.
  2. To send a query to a database engine.
Type:
  • object
Properties:
Name Type Attributes Default Description
syntax boolean <optional>
 'object'

A case-sensitive string indicating the expected type and format of a state object to be generated from a filter tree. One of:

  • 'object' (default) A raw state object produced by walking the tree using unstrungify(), respecting JSON.stringify()'s "toJSON() behavior," and returning a plain object suitable for resubmitting to setState. This is an "essential" version of the actual node objects in the tree.
  • 'JSON' - A stringified state object produced by walking the tree using JSON.stringify(), returning a JSON string by calling toJSON at every node. This is a string representation of the same "essential" object as that produced by the 'object' option, but "stringified" and therefore suitable for text-based storage media.
  • 'SQL' - The subexpression in SQL conditional syntax produced by walking the tree and returning a SQL search condition expression. Suitable for use in the WHERE clause of a SQL SELECT statement used to query a database for a filtered result set.

FilterTreeOptionsObject

Type:
  • object
Properties:
Name Type Attributes Default Description
schema Array.<menuItem> <optional>

A default list of column names for field drop-downs of all descendant terminal nodes. Overrides options.state.schema (see). May be defined for any node and pertains to all descendants of that node (including terminal nodes). If omitted (and no ownSchema), will use the nearest ancestor schema definition. However, descendants with their own definition of types will override any ancestor definition.

Typically only used by the caller for the top-level (root) tree.
ownSchema Array.<menuItem> <optional>

A default list of column names for field drop-downs of immediate descendant terminal nodes only. Overrides options.state.ownSchema (see).

Although both options.schema and options.ownSchema are notated as optional herein, by the time a terminal node tries to render a schema drop-down, a schema list should be defined through (in order of priority):

  • Terminal node's own options.schema (or options.state.schema) definition.
  • Terminal node's parent node's option.ownSchema (or option.state.nodesFields) definition.
  • Terminal node's parent (or any ancestor) node's options.schema (or options.state.schema) definition.
state FilterTreeStateObject <optional>

A data structure that describes a tree, subtree, or leaf (terminal node). If undefined, loads an empty filter, which is a FilterTree node consisting the default operator value ('op-and').
editor function <optional>
 'Default'

The name of the conditional expression's UI "editor." This name must be registered in the parent node's editors hash, where it maps to a leaf constructor (FilterLeaf or a descendant thereof). (Use FilterTree#addEditor to register new editors.)
parent FilterTree <optional>

Used internally to insert element when creating nested subtrees. The only time it may be (and must be) omitted is when creating the root node.
cssStylesheetReferenceElement string | HTMLElement <optional>

passed to cssInsert

FilterTreeSetStateOptionsObject

Type:
  • object
Properties:
Name Type Attributes Default Description
syntax boolean <optional>
 'auto'

Specify parser to use on state. One of:

FilterTreeStateObject

State with which to create a new node or replace an existing node.

A string or plain object that describes a filter-tree node. If a string, it is parsed into an object by FilterNode~parseStateString. (See, for available overloads.)

The resulting object may be a flat object that describes a terminal node or a childless root or branch node; or may be a hierarchical object to define an entire tree or subtree.

In any case, the resulting object may have any of the following properties:

Type:
  • object | string
Properties:
Name Type Attributes Default Description
schema Array.<menuItem> <optional>

See schema property of FilterTreeOptionsObject.
editor string <optional>
 'Default'

See editor property of FilterTreeOptionsObject.
misc

Other miscellaneous properties will be copied directly to the new FitlerNode object. (The name "misc" here is just a stand-in; there is no specific property called "misc".)

  • May describe a non-terminal node with properties:
    • schema - Overridden on instantiation by options.schema. If both unspecified, uses parent's definition.
    • operator - One of treeOperators.
    • children - Array containing additional terminal and non-terminal nodes.

The constructor auto-detects state's type:

  • JSON string to be parsed by JSON.parse() into a plain object
  • SQL WHERE clause string to be parsed into a plain object
  • CSS selector of an Element whose value contains one of the above
  • plain object

FilterTreeValidationOptionsObject

Type:
  • object
Properties:
Name Type Attributes Default Description
throw boolean <optional>
 false

Throw (do not catch) FilterTreeErrors.
alert boolean <optional>
 false

Announce error via window.alert() before returning.
focus boolean <optional>
 false

Place the focus on the offending control and give it error color.

operationReducer(p, q) → {boolean}

Parameters:
Name Type Description
p boolean
q boolean
Returns:

The result of applying the operator to the two parameters.

Type
boolean

optionsSchemaObject

Standard option schema

Standard options are automatically added to nodes. Data sources for standard options include options, state, parent and default (in that order). Describes standard options through various properties:

Properties:
Name Type Attributes Description
ignore boolean <optional>

Do not automatically add to nodes (processed elsewhere).
own boolean <optional>

Do not automatically add from parent or default.
rootBound boolean <optional>

Automatically add to root node only.
default * <optional>

This is the default data source when all other strategies fail.

relationalOperator

Type:
  • object
Properties:
Name Type Attributes Description
test relationalTest
make relationalSyntax
type string <optional>

relationalSyntax(a, b) → {string}

Generates human-readable string syntax from conditionals.

The type of the parameters will always be homogeneous and is determined by FilterLeaf's typing algorithm, which attempts to convert the data in it's natural string form to the type sepcified by the field's type, if defined. If both sides cannot be converted, it falls back to strings.

Parameters:
Name Type Description
a string | number | Date

Left side of dyadic conditional expression.
b string | number | Date

Right side of dyadic conditional expression.
Returns:

Syntax for that expressions a specific relationship between a and b.

Type
string

relationalTest(a, b) → {boolean}

Parameters:
Name Type Description
a string | number | Date

Left side of dyadic conditional expression.
b string | number | Date

Right side of dyadic conditional expression.
Returns:

The result of comparing a and b.

Type
boolean

sqlIdQtsObject

On a practical level, the useful characters are:

  • SQL-92 standard: "double quotes"
  • SQL Server: "double quotes" or [square brackets]
  • mySQL: `tick marks`
Type:
  • object
Properties:
Name Type Description
beg string

The open quote character.
end string

The close quote character.

treeOperator

Each treeOperator object describes two things:

  1. How to take the test results of n child nodes by applying the operator to all the results to "reduce" it down to a single result.
  2. How to generate SQL WHERE clause syntax that applies the operator to n child nodes.
Type:
  • obejct
Properties:
Name Type Description
reduce operationReducer
seed boolean

-
abort boolean

-
negate boolean

-
SQL.op string

-
SQL.beg string

-
SQL.end string

-