Search Patterns

Learn how to use where() and findWhere() methods to query documents, templates, clients, elements, and other objects in the SDK.

Overview

Core Concept

The SDK provides two primary methods for querying data: where() and findWhere(). These methods are available on factory objects and elements.

where(criteria)

Returns all matching objects as an array. Use when you expect multiple results.

var results = Document.where({ typeId: 'estimate' });
// Returns: [doc1, doc2, doc3, ...]

findWhere(criteria)

Returns the first matching object, or null if not found. Use when you expect one result.

var result = Document.findWhere({ id: 12345 });
// Returns: doc or null

Available On

Objectwhere()findWhere()
Document✓✓
Template✓✓
Client✓✓
WorkLog✓✓
Schedule✓✓
Elements✓✓
Children Collection✓✓

Criteria Object

Parameters

The criteria object specifies which fields to match. Only provide fields you want to filter by.

Document / Template Criteria

FieldTypeDescription
idnumberMatch by unique ID
namestringMatch by name (partial)
typeIdstringMatch by type (estimate, invoice, etc.)

Client Criteria

FieldTypeDescription
idnumberMatch by unique ID
namestringMatch by client name
citystringMatch by city
statestringMatch by state

Element Criteria

FieldTypeDescription
idnumberMatch by element ID
namestringMatch by display name
propNamestringMatch by property name
typestringMatch by element type

WorkLog / Schedule Criteria

FieldTypeDescription
idnumberMatch by unique ID
clientIdnumberMatch by associated client
projectIdnumberMatch by associated project

Matching Logic

How It Works

The search uses a 3-state matching system for each criteria field:

3-State Matching

StateCriteria ValueBehavior
Not Provided Field omitted Field is ignored (matches anything)
Null/Undefined null or undefined Matches only null/empty values
Value Specific value Matches that exact value

Multiple Criteria (AND Logic)

When multiple fields are provided, ALL must match (AND logic).

// Must match BOTH type AND name
var results = template.where({
  type: 'numeric',
  name: 'Length'
});
// Only returns numeric elements named "Length"
Case Sensitivity: String matching is generally case-insensitive for better usability.

Practical Examples

Code Examples

Finding Documents

// Find all estimates
var estimates = Document.where({ typeId: 'estimate' });

// Find specific document by ID
var doc = Document.findWhere({ id: 12345 });

// Find documents by name
var kitchenDocs = Document.where({ name: 'Kitchen' });

// Combine criteria
var recentEstimate = Document.findWhere({
  typeId: 'estimate',
  name: 'Kitchen Renovation'
});

Finding Elements in Templates

// Find all numeric elements
var numerics = template.where({ type: 'numeric' });

// Find element by propName
var length = template.findWhere({ propName: 'roomLength' });

// Find all items
var items = template.where({ type: 'item' });

// Find visible checkboxes
var checkboxes = template.where({ type: 'checkbox' });
var visibleChecks = [];
for (var i = 0; i < checkboxes.length; i++) {
  if (checkboxes[i].visible) {
    visibleChecks.push(checkboxes[i]);
  }
}

Finding Clients

// Find client by ID
var client = Client.findWhere({ id: 789 });

// Find clients by city
var localClients = Client.where({ city: 'Springfield' });

// Find clients by state
var stateClients = Client.where({ state: 'IL' });

Nested Element Search

// Search within a section
var section = template.findWhere({ propName: 'materials' });
if (section) {
  var items = section.where({ type: 'item' });
  console.log('Found ' + items.length + ' items in materials section');
}

// Deep search through all children
function findAllByType(element, type) {
  var results = [];
  var matches = element.where({ type: type });
  results = results.concat(matches);

  for (var i = 0; i < element.children.length; i++) {
    var child = element.children[i];
    if (child.children && child.children.length > 0) {
      results = results.concat(findAllByType(child, type));
    }
  }
  return results;
}

var allItems = findAllByType(template, 'item');

Handling Results

// Safe handling of findWhere (might return null)
var doc = Document.findWhere({ name: 'Project X' });
if (doc) {
  console.log('Found: ' + doc.name);
} else {
  console.log('Not found');
}

// Processing where results (always an array)
var items = template.where({ type: 'item' });
if (items.length === 0) {
  console.log('No items found');
} else {
  var total = 0;
  for (var i = 0; i < items.length; i++) {
    total += (items[i].quantity || 0) * (items[i].price || 0);
  }
  console.log('Total: $' + total);
}