Class: FilterTree

FilterTree

new FilterTree()

An object that represents the root node or a branch node in a filter tree.

A node representing a subexpression in the filter expression. May be thought of as a parenthesized subexpression in algebraic expression syntax. As discussed under FilterNode, a FilterTree instance's child nodes may be either:

  • Other (nested) FilterTree (or subclass thereof) nodes representing subexpressions.
  • FilterLeaf (or subclass thereof) terminal nodes representing conditional expressions.

The FilterTree object also has methods, some of which operate on a specific subtree instance, and some of which recurse through all the subtree's child nodes and all their descendants, etc.

The recursive methods are interesting. They all work similarly, looping through the list of child nodes, recursing when the child node is a nested subtree (which will recurse further when it has its own nested subtrees); and calling the polymorphic method when the child node is a FilterLeaf object, which is a terminal node. Such polymorphic methods include setState(), getState(), invalid(), and test().

For example, calling test(dataRow) on the root tree recurses through any subtrees eventually calling test(dataRow) on each of its leaf nodes and concatenating the results together using the subtree's operator. The subtree's test(dataRow) call then returns the result to it's parent's test() call, etc., eventually bubbling up to the root node's test(dataRow) call, which returns the final result to the original caller. This result determines if the given data row passed through the entire filter expression successfully (true) and should be displayed, or was blocked somewhere (false) and should not be displayed.

Note that in practice:

  1. children may be empty. This represents a an empty subexpression. Normally pointless, empty subexpressions could be pruned. Filter-tree allows them however as harmless placeholders.
  2. operator may be omitted in which case it defaults to AND.
  3. A false result from a child node will short-stop an AND operation; a true result will short-stop an OR or NOR operation.

Additional notes:

  1. A FilterTree may consist of a single leaf, in which case the concatenation operator is not needed and may be left undefined. However, if a second child is added and the operator is still undefined, it will be set to the default ('op-and').
  2. The order of the children is undefined as all operators are commutative. For the 'op-or' operator, evaluation ceases on the first positive result and for efficiency, all simple conditional expressions will be evaluated before any complex subexpressions.
  3. A nested FilterTree is distinguished (duck-typed) from a leaf node by the presence of a children member.
  4. Nesting a FilterTree containing a single child is valid (albeit pointless).

See also the properties of the superclass: FilterNode

Properties:
Name Type Attributes Default Description
operator string <optional>
 'op-and'

The operator that concatentates the test results from all the node's children (child nodes). Must be one of:

  • 'op-and'
  • 'op-or'
  • 'op-nor'

Note that there is only one operator per subexpression. If you need to mix operators, create a subordinate subexpression as one of the child nodes.
children Array.<FilterNode>

A list of descendants of this node. As noted, these may be other FilterTree (or subclass thereof) nodes; or may be terminal FilterLeaf (or subclass thereof) nodes. May be any length including 0 (none; empty).
keep boolean <optional>
 false

Do not automatically prune when last child removed.
ownSchema Array.<fieldItem> <optional>

Column menu to be used only by leaf nodes that are children (direct descendants) of this node.
type string <optional>
 'subtree'

Type of node, for rendering purposes; names the rendering template to use to generate the node's UI representation.

Methods

add(optionsopt) → {FilterNode}

Create a new node as per state.

Parameters:
Name Type Attributes Default Description
options object <optional>
 {state:{}}

May be one of:

  • an options object containing a state property
  • a state object (in which case there is no options object)

In any case, resulting state object may be either...

  • A new subtree (has a children property): Add a new FilterTree node.
  • A new leaf (no children property): add a new FilterLeaf node:
    • If there is an editor property: Add leaf using this.editors[state.editor].
    • Otherwise (including the case where state is undefined): Add leaf using this.editors.Default.
Properties
Name Type Attributes Default Description
focus boolean <optional>
 false

Call invalid() after inserting to focus on first blank control (if any).
Returns:

The new node.

Type
FilterNode

createView()

getState(optionsopt) → {object|string}

Get a representation of filter state.

Calling this on the root will get the entire tree's state; calling this on any subtree will get just that subtree's state.

Only essential properties will be output:

  1. FilterTree nodes will output at least 2 properties:
    • operator
    • children
  2. FilterLeaf nodes will output (via getState) at least 3 properties, one property for each item in it's view:
    • column
    • operator
    • operand
  3. Additional node properties will be output when:
    1. When the property was NOT externally sourced:
      1. Did not come from the options object on node instantiation.
      2. Did not come from the options schema default object, if any.
    2. AND at least one of the following is true:
      1. When it's an "own" property.
      2. When its value differs from it's parent's.
      3. When this is the root node.
Parameters:
Name Type Attributes Description
options FilterTreeGetStateOptionsObject <optional>
Properties
Name Type Attributes Description
sqlIdQts object <optional>

When options.syntax === 'SQL', forwarded to conditionals.pushSqlIdQts().
Returns:

Returns object when options.syntax === 'object'; otherwise returns string.

Type
object | string

invalid(optionsopt) → {undefined|FilterTreeError}

Parameters:
Name Type Attributes Description
options FilterTreeValidationOptionsObject <optional>
Returns:

undefined if valid; or the caught FilterTreeError if error.

Type
undefined | FilterTreeError

loadState()

removeEditor(key)

Parameters:
Name Type Description
key string

The name of the existing editor to remove.

render()

test(dataRow) → {boolean}

Parameters:
Name Type Description
dataRow
Returns:
Type
boolean