1. Home
  2. Classes
  3. MLoadRecords

new MLoadRecords( formID [, enterLoadedData [, fulcrumHelpers ] ] )

Loads and manages records from a linked Fulcrum form

Description

Handles loading form schemas and records from companion Fulcrum apps. Creates a dictionary to convert form_value keys to data_name keys for easier access.

Common use cases:

  • Load records from a linked app based on a record link field
  • Refresh a record link field when records in the linked app reference this record
  • Prevent duplicate record selection across records in this app
Parameters
Name Type Attributes Default Description
formID string

Fulcrum form ID (required)
enterLoadedData function <optional>

Callback function to process loaded records
fulcrumHelpers FulcrumHelpers <optional>

Optional helper instance (creates new FulcrumHelpers if not provided)
Properties
Name Type Description
formID string

Fulcrum form ID of the linked app
enterLoadedData function | null

Callback to process records after loading
recIDs Array.<string> | null

Array of record IDs to load
appFvs Object

Dictionary mapping form_value keys to data_names
appRecords Array.<Object> | null

Loaded records with data_name keys
recordsOnLoad boolean

If true, loads records immediately after form schema
sortOrder Array.<Array> | null

Sort order for queries, e.g., [['report_id', 'dsc']]
dnRecLink string

Data name of record link field in this app
dnRecLinkIds string

Data name of text field storing record IDs
dnsRecLinkAuto Array.<string>

Data names to clear if duplicate found
dnRefreshRL string

Data name of record link field to refresh
addOnRefreshRL function

Additional callback after refreshing record link
duplicateAlert function

Function to call when duplicate detected
helpers FulcrumHelpers

FulcrumHelpers instance for utility methods
Examples

Basic usage - load records on change

const appID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

function processRecordsCallback() {
  const loadedRecords = loader.appRecords
  const titleList = loadedRecords.map(x => x.scientific_name + ' - ' + x.common_name)
  SETVALUE('result', titleList.join('\n'))
}

const loader = new MLoadRecords(appID, processRecordsCallback)
loader.dnRecLink = 'species_link'

ON('load-record', loader.buildAppFvDict)
ON('change', 'species_link', loader.updateLoadedRecords)

Duplicate checking

const loader = new MLoadRecords(appID, null)
loader.dnRecLink = 'project_link'
loader.dnRecLinkIds = 'project_id_text'
loader.dnsRecLinkAuto = ['project_name', 'project_date']

ON('load-record', loader.buildAppFvDict)
ON('change', 'project_link', loader.selfDupCheck)
Throws

If formID is not provided

If enterLoadedData is provided but is not a function

Details

Members

addOnRefreshRL :function

Additional callback after refreshing record link

Description

Override this to perform additional actions after refreshRecordLink completes.

Examples
loader.addOnRefreshRL = () => {
  SETVALUE('child_count', loader.appRecords.length)
}

duplicateAlert :function

Alert function for duplicate detection

Description

Override this to customize the duplicate record alert message.

Examples
loader.duplicateAlert = () => {
  ALERT('This project is already assigned to another record.')
}

loadForm

Loads form schema

Description

Loads a Fulcrum form schema and passes it to the callback. Delegates to FulcrumHelpers.loadForm.

Parameters
Name Type Description
formID string

Fulcrum form ID to load
callBack function

Function to receive the loaded form schema
Returns

loadRecords

Loads records with flexible parameter handling

Description

Wrapper for FulcrumHelpers.loadRecords with enhanced parameter handling. Supports flexible parameter formats for convenience in MLoadRecords context.

Parameters
Name Type Attributes Default Description
opts Object | Array.<string> | string | null <optional>

Can be: null (loads all), array of IDs, query object, or formID string
callback function | null <optional>

Callback function. Defaults to this.processRecords
Returns
Examples

Load by ID array

loader.loadRecords(['id1', 'id2'], myCallback)

Load with query object

const opts = loader.filterTemplate('status', 'equal_to', 'active')
loader.loadRecords(opts)

getAppFvs

Loads form schema and immediately loads records

Description

Use in ON('load-record') event. Sets recordsOnLoad=true, then loads form schema and continues to load records. Equivalent to setting recordsOnLoad=true and calling buildAppFvDict.

Parameters
Name Type Description
event Object

Fulcrum load-record event object
Returns
Examples
ON('load-record', loader.getAppFvs)
Details

deprecate getAppFvs in favor of buildAppFvDict with recordsOnLoad = true

buildAppFvDict

Loads form schema only (no records)

Description

Use in ON('load-record') event. Loads form schema to build the form_value to data_name dictionary, but does NOT load any records. Records can be loaded later via updateLoadedRecords or loadRecords.

Parameters
Name Type Description
event Object

Fulcrum load-record event object
Returns
Examples
ON('load-record', loader.buildAppFvDict)
ON('change', 'species_link', loader.updateLoadedRecords)

updateLoadedRecords

Updates loaded records from record link field

Description

Extracts record IDs from the configured record link field (dnRecLink) and loads those records. Clears auto fields if no IDs found.

Parameters
Name Type Description
event Object

Fulcrum change event object
Returns
Examples
loader.dnRecLink = 'species_link'
ON('change', 'species_link', loader.updateLoadedRecords)

processForm

Processes loaded form schema

Description

Callback for loadForm. Creates the form_value to data_name dictionary (appFvs). If recordsOnLoad is true, continues to load records via refreshRecordLink or updateLoadedRecords.

Parameters
Name Type Description
form Object

Fulcrum form schema object
Returns

processRecords

Processes loaded records

Description

Default callback for loadRecords. Converts form_value keys to data_name keys and stores in appRecords. Calls enterLoadedData callback if recordsOnLoad is true.

Parameters
Name Type Description
records Array.<Object>

Array of raw Fulcrum record objects
Returns

selfDupCheck

Checks for duplicate record selection

Description

Prevents selecting a record that is already linked in another record of this app. Queries for records containing the selected record ID and clears selection if found. Requires dnRecLink, dnRecLinkIds, and optionally dnsRecLinkAuto to be configured.

Parameters
Name Type Description
event Object

Fulcrum change event from record link field
Returns
Examples
loader.dnRecLink = 'project_link'
loader.dnRecLinkIds = 'project_id_text'
loader.dnsRecLinkAuto = ['project_name', 'project_date']
ON('change', 'project_link', loader.selfDupCheck)

processSelfDupCheck

Processes duplicate check results

Description

Callback for selfDupCheck. If records are found that aren't the current record, clears the selection, auto fields, and shows the duplicate alert.

Parameters
Name Type Description
records Array.<Object>

Array of raw Fulcrum record objects
Returns

processRefreshRL

Processes refresh record link results

Description

Callback for refreshRecordLink. Updates the record link field with the IDs of loaded records and calls addOnRefreshRL callback.

Parameters
Name Type Description
records Array.<Object>

Array of raw Fulcrum record objects
Returns

Refreshes a record link field with linked records

Description

Queries for records in the linked app that reference the current record (via dnRefreshRL field containing current RECORDID), then updates the record link field. Requires dnRefreshRL to be configured.

Returns
Examples
loader.dnRefreshRL = 'parent_record_link'
loader.dnRecLink = 'child_records'
loader.sortOrder = [['created_at', 'dsc']]

clearAutoFields

Clears auto-populated fields

Description

Clears all fields listed in dnsRecLinkAuto array. Called when record link is cleared or duplicate is detected.

Returns

Methods

filterEmpty() → {Object}

Creates a filter object for loading all records from a form

Description

Returns a query object with no predicates, which loads all records.

Returns

Empty filter object with form_id

Examples
const opts = loader.filterEmpty()
loader.loadRecords(opts, myCallback)

filterId( ids ) → {Object}

Creates a filter object for loading records by ID array

Description

Returns a query object that loads specific records by their IDs.

Parameters
Name Type Description
ids Array.<string>

Array of Fulcrum record IDs
Returns

Filter object with ids and form_id

Examples
const ids = ['abc-123', 'def-456']
const opts = loader.filterId(ids)
loader.loadRecords(opts, myCallback)

filterTemplate( dn, op, val [, order ] ) → {Object}

Creates a filter object with a single predicate

Description

Returns a query object with a single field filter. Common operators: "equal_to", "not_equal_to", "contains", "starts_with", "greater_than", "less_than"

Parameters
Name Type Attributes Default Description
dn string

Data name of field to filter on
op string

LOADRECORDS operator (e.g., "equal_to", "contains")
val string | number | boolean

Value to filter by
order Array.<Array> | null <optional>

Optional sort order, e.g., [['date', 'dsc']]
Returns

Filter object for LOADRECORDS

Examples
const opts = loader.filterTemplate('status', 'equal_to', 'active')
loader.loadRecords(opts, myCallback)

With sort order

const opts = loader.filterTemplate('project_id', 'equal_to', 'P123', [['created_at', 'dsc']])