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
| Object | where() | findWhere() |
|---|---|---|
| Document | ✓ | ✓ |
| Template | ✓ | ✓ |
| Client | ✓ | ✓ |
| WorkLog | ✓ | ✓ |
| Schedule | ✓ | ✓ |
| Elements | ✓ | ✓ |
| Children Collection | ✓ | ✓ |
Criteria Object
ParametersThe criteria object specifies which fields to match. Only provide fields you want to filter by.
Document / Template Criteria
| Field | Type | Description |
|---|---|---|
id | number | Match by unique ID |
name | string | Match by name (partial) |
typeId | string | Match by type (estimate, invoice, etc.) |
Client Criteria
| Field | Type | Description |
|---|---|---|
id | number | Match by unique ID |
name | string | Match by client name |
city | string | Match by city |
state | string | Match by state |
Element Criteria
| Field | Type | Description |
|---|---|---|
id | number | Match by element ID |
name | string | Match by display name |
propName | string | Match by property name |
type | string | Match by element type |
WorkLog / Schedule Criteria
| Field | Type | Description |
|---|---|---|
id | number | Match by unique ID |
clientId | number | Match by associated client |
projectId | number | Match by associated project |
Matching Logic
How It WorksThe search uses a 3-state matching system for each criteria field:
3-State Matching
| State | Criteria Value | Behavior |
|---|---|---|
| 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 ExamplesFinding 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);
}