1. Home
  2. Classes
  3. FieldHelpers

new FieldHelpers()

Helper methods for rendering field values in pdf reports

Description

This class contains helper methods for working with fields in a form. It is intended to be used in conjunction with the ReportHelpers class.

Inheritance: Utils → FulcrumHelpers → FieldHelpers

Extended by: ReportHelpers

Inherited Methods:

  • All Utils utility methods (see Utils documentation)
  • All FulcrumHelpers Fulcrum-specific methods (see FulcrumHelpers documentation)

Methods Defined in This Class: Only field rendering and value formatting methods are documented below.

Classes

new MfldTypes( [ fieldData ] )

Constructor for Merjent Fulcrum field types

new MfldColl()

Constructor for array of Mflds

Methods

optionIs( opt, option ) → {boolean|null}

Checks Mfld for options.

Description

Checks if a field option string contains a specific option. Current options supported: -rdo = radio buttons instead of checkboxes -cb = choice boxes (checkboxes) -hcb = horizontal choice boxes -syn = short yes no (first letter only) -yon = yes no only (no neutral option) -na = replace null values with 'N/A' instead of '---' -hn = hide null values (do not display field if value is null)

Parameters
Name Type Default Description
opt string

The option string (e.g., '-cb-hcb-rdo').
option string

The option to check for (e.g., 'cb', 'hcb', 'rdo').
Returns

mkMfld( dn [, span [, opt ] ] ) → {Mfld}

Make Merjent Field

Description

This function creates a Mfld object which possesess most of the properties as a fulcrum field with the addition of: span, opt

Parameters
Name Type Attributes Default Description
dn string

Data name of the field.
span number <optional>
 4

Span value for the field.
opt string <optional>

Option string for the field.
Returns
  • Mfld object.

mkMflds( [ arr [, opt [, span ] ] ] ) → {MfldColl}

Make Merjent Fields

Description

make Mflds (array of Mfld)

Parameters
Name Type Attributes Default Description
arr Object <optional>
 []
opt string <optional>
span number <optional>
 4
Returns

spliceMflds( mflds [, dn [, key ], val ] )

Deprecated

Description

Description placeholder

Parameters
Name Type Attributes Default Description
mflds MfldColl
dn string <optional>
 ''
key string <optional>
 ''
val *
Details

MUTATES existing array

is this used anywhere? otherwise delete it.

fldVal( input [, i ] ) → {string}

Field Value

Description

This function returns the report HTML formatted value of a field. For null values default return is '---'.

Parameters
Name Type Attributes Default Description
input string | Mfld

field to be formatted. It can be a string of a data_name or a Mfld object.
i number <optional>

only used for repeatable values. index of the value in a repeatable field.
Returns
  • An html string of the formatted value of the field.
Examples
fldVal('inspector_name') // returns the value of the inspector_name field
fldVal('inspector_name', 0) // returns the value of the inspector_name field in the first repeatable section

getReportVal( [ dn [, mfld [, val ] ] ] ) → {*}

sub-function of fldVal

Description

Produces the html string of a field value based on its type and options after checking for repeatable values.

Parameters
Name Type Attributes Default Description
dn string <optional>
 ''
mfld * <optional>
val * <optional>

val only needed for repeatable values
Returns
  • html string

customynBox( input [, val ] ) → {string}

Custiom Yes No Box

Description

get custom yn field as appropriate

opt = -syn | -yno | -rdo -syn only first letter of label (or 3 if neutral)

Parameters
Name Type Attributes Default Description
input string | Mfld

Mfld. Checks neutral_enabled. opt = optionIsShortYN | optionIsYonly | optionIsRadio
val * <optional>

val is only used for yn boxes in a repeatable
Returns
  • html string
Details

Add option to color boxes green/red if yes/no

choiceBoxes( input [, val ] ) → {string}

Create list of checkboxes for choicevalues

Description

Creates an HTML string from a choice field with a list of checkboxes for choicevalues

opts = -hcb -hcb is horizontal choiceboxes, default is vertical choiceboxes.

Parameters
Name Type Attributes Default Description
input *
val * <optional>
Returns
  • html string

devUnhide( event ) → {void}

Developer Unhide

Description

Sets all fields visible if USERROLE() == 'Owner'

Parameters
Name Type Description
event *
Returns
Details

FulcrumHelpers#devUnhide

devEdit( event ) → {void}

Developer Edit

Description

Sets all fields editable if USERROLE() == 'Owner'

Parameters
Name Type Description
event *
Returns
Details

FulcrumHelpers#devEdit

setAllRO( [ bol [, exc [, sec ] ] ] ) → {void}

Set All Read-only

Description

Sets all fields to readonly or editable or default, except those in the exclude list or not in the section if specified.

Parameters
Name Type Attributes Default Description
bol boolean <optional>
 false

Set field to readonly, null sets to default.
exc Array.<string> <optional>

Array of datanames to exclude
sec string <optional>
 ''

Restrict function to only data names in this section
Returns
Details

FulcrumHelpers#setAllRO

isMerjentEmail() → {boolean}

Description

Checks if current user email ends in'merjent.com'

Returns
Details

FulcrumHelpers#isMerjentEmail

disableLocationEdit( event ) → {void}

Description

Disable editing location

Parameters
Name Type Description
event *
Returns
Details

FulcrumHelpers#disableLocationEdit

userInit() → {string}

User Initials

Description

Gets current users initials

Returns
Details

FulcrumHelpers#userInit

getReportIDvars( [ reportDate ] ) → {Object}

Get Report ID Variables

Description

Get information pieces used to build report id

Parameters
Name Type Attributes Default Description
reportDate string <optional>
Returns
Details

FulcrumHelpers#getReportIDvars

photoLandscape( event ) → {boolean}

Require photo to be taken landscape

Description

Validation for photo orientation, must be called from an ONCHANGE event of a photo field.

Parameters
Name Type Description
event *
Returns
Details

FulcrumHelpers#photoLandscape

photoSetLoc( event ) → {void}

Photo Set Location

Description

Sets record location to the location of the first photo taken

Parameters
Name Type Description
event *
Returns
Details

FulcrumHelpers#photoSetLoc

clearRLAutoPops( event ) → {void}

Clear Record-Link Auto-populates

Description

If the value of the record-link field is null, on change, this data event will clear all of the auto-populate fields.

Parameters
Name Type Description
event *
Returns
Examples
ON('change', 'project_name', clearRLAutoPops)
Details

FulcrumHelpers#clearRLAutoPops

popLatLon( [ dn ] ) → {string}

Populate Latitude Longitude

Description

For use in data event. Sets value of {data_name} to current lat/lon as a string "lat,lon". Alerts if no GPS info.

Parameters
Name Type Attributes Default Description
dn string <optional>

output field data name to write to
Returns
Details

FulcrumHelpers#popLatLon

photoCheck4Caps( dn ) → {boolean}

Photo Check for Captions

Description

Checks photofield for photos without a caption. Returns an Alert.

Parameters
Name Type Description
dn string
Returns
Details

FulcrumHelpers#photoCheck4Caps

photoCheckCapLen( dn, max ) → {void}

Photo Check Caption Length

Description

Description placeholder

Parameters
Name Type Description
dn string
max number
Returns
Details

FulcrumHelpers#photoCheckCapLen

makeDnsRow( dns [, exc ] ) → {Object}

Make data_names Row

Description

Creates an object from a list of data names. Excludes Labels, Sections and HyperlinkFields.

Parameters
Name Type Attributes Default Description
dns *
exc Array.<string> <optional>
 []
Returns
Details

FulcrumHelpers#makeDnsRow

dns2Row

makeRepRows( repeatableDn [, exc ] ) → {Array.<Object>}

Make Repeatable Rows

Description

Converts a repeatable to an Array of Objects. Input repeatable data name.

Parameters
Name Type Attributes Default Description
repeatableDn string
exc Array.<string> <optional>
 []
Returns
Details

FulcrumHelpers#makeRepRows

rep2Rows

rows2Summary( rows [, exc ] ) → {Array.<string>}

Rows to Summary

Description

Converts an array of objects to an array of summary strings, excluding specified keys. Each summary string lists key-value pairs separated by commas.

Parameters
Name Type Attributes Default Description
rows Array.<Object>

Array of objects to summarize.
exc Array.<string> <optional>
 []

Array of keys to exclude from summary.
Returns
Details

FulcrumHelpers#rows2Summary

fv2DnRows( rows, dict ) → {Array.<Object>}

Form Values to Data Names Rows

Description

Converts an array of Fulcrum rows to an array of objects with data names as keys. Uses a dictionary to map form_value keys to data names.

Parameters
Name Type Description
rows Array.<Object>

Array of Fulcrum record objects.
dict Object

Dictionary mapping form_value keys to data names.
Returns
  • Array of objects with mapped keys and values.
Details

FulcrumHelpers#fv2DnRows

loadRecords( arr, formID, callback ) → {void}

Load Records

Description

Wrapper function for LOADRECORDS() expression.

Parameters
Name Type Description
arr Array.<string>
formID string
callback function

function to process records and store them to a variable or field. Callback must have one parameter for records. See example.
Returns
Examples
processRecordsCallback(records){
  loadedRecords = convertFV2DN(records,loadedFvs)
  var out = []
  for(const record of loadedRecords){
    var add = record.scientific_name + ' - ' + record.common_name
    out.push(add)
  }
  SETVALUE('result',out.join('\n'))
}

M.loadRecords(recIDs,appID,processRecordsCallback)
Details

FulcrumHelpers#loadRecords

getRepDn( dn ) → {string}

Get Repeatable Parent

Description

get parent data_name for a field. Returns only the next parent that is a repeatable.

Parameters
Name Type Description
dn string
Returns
  • data_name of the parent (repeatable or section) of a field. If there is no parent, it returns null.
Examples
getRepDn('inspector_name') // returns 'background'
Details

FulcrumHelpers#getRepDn

repParent? digParent? - make generic recursion function that produces row of all parents and parent types. For repeatables, secctions or elements of form schema.

digElement( el, collector ) → {void}

Dig Element

Description

Recursively collects all data_name:form_value pairs from element. Adds element to collector array. Primarily used as a sub-function within makeFvDict.

Parameters
Name Type Description
el Object

The parent element to start from.
collector object

The object to collect elements into.
Returns
  • Adds element to collector array
Details

FulcrumHelpers#digElement

makeFvDict( form ) → {Object}

Make Form Values Dictionary

Description

Input a fulcrum form schema Object and returns a dictionary object of {data_name:form_value}.

Parameters
Name Type Description
form Object

Fulcrum form schema object.
Returns
  • Dictionary of {data_name:form_value}.
Details

FulcrumHelpers#makeFvDict

mkLocalFvDict( el ) → {Object}

Make Local Form Values Dictionary

Description

Creates a local dictionary of {form_value:data_name} for fields within the specified element or the entire form if no element is provided.

Parameters
Name Type Default Description
el Object | null

Fulcrum form element object. If null, uses the entire form.
Returns
  • Dictionary of {form_value:data_name}.
Details

FulcrumHelpers#mkLocalFvDict

repeatable2jrows( repDn [, exc ] ) → {Array.<Object>}

Repeatable to JSON Rows

Description

Converts a repeatable field's value into an array of objects with data names as keys.

Parameters
Name Type Attributes Default Description
repDn string

Data name of the repeatable field.
exc Array.<string> <optional>
 []

Array of data names to exclude.
Returns
  • Array of objects representing each row in the repeatable.
Details

FulcrumHelpers#repeatable2jrows

loadForm( formID, callback ) → {void}

Description

Description placeholder

Parameters
Name Type Description
formID string

fulcrum form id
callback function

function to process form schema
Returns
Examples
processFormCallback(form){
    loadedFvs = M.flipKVpair(this.makeFvDict(form))
 }

M.loadForm(formID,processFormCallback)
Details

FulcrumHelpers#loadForm

eachSecDn( secDn, callback ) → {void}

Each Section Data Name

Description

Performs callback function on each data name in a section.

Parameters
Name Type Description
secDn string

Section data name.
callback function

Function to perform for each data name.
Returns
Details

FulcrumHelpers#eachSecDn

clear( dn ) → {void}

Description

Clears value in fulcrum field.

Parameters
Name Type Description
dn string

Data name to clear.
Returns
Details

FulcrumHelpers#clear

getRepeatableValues( repVals, dnFv ) → {Object}

Description

Description placeholder

Parameters
Name Type Description
repVals *

this is from VALUE(repeatable data name)
dnFv string
Returns
Details

FulcrumHelpers#getRepeatableValues

getNestedRepeatable( parentDn, childDn, dnFv ) → {Object}

Description

Description placeholder

Parameters
Name Type Description
parentDn string
childDn string
dnFv string
Returns
Details

FulcrumHelpers#getNestedRepeatable

deprecate or add recursion

timedProcessingMsg( time ) → {void}

Timed Processing Message

Description

block input into form with an alert message for a set time in milliseconds.

Parameters
Name Type Description
time number

milliseconds for settimeout
Returns
Details

FulcrumHelpers#timedProcessingMsg

add example

valProcessingMsg( dn, time ) → {void}

Value Processing Message

Description

block input into form with an alert message until a value is present in the specified data name or until a settimeout.

Parameters
Name Type Description
dn string
time number

milliseconds for settimeout
Returns
Details

FulcrumHelpers#valProcessingMsg

mkPhotoDirHandler( photoFldDn [, photoDirDn [, photoCardDn [, secondary ] ] ] ) → {PhotoDirHandler}

Description

Factory method for PhotoDirHandler (backward compatibility)

Parameters
Name Type Attributes Default Description
photoFldDn string

Photo field data name
photoDirDn string <optional>
 ""

Direction field data name (degrees)
photoCardDn string <optional>
 ""

Cardinal direction field data name
secondary boolean <optional>
 false

Use 16-point compass if true, 8-point if false
Returns

PhotoDirHandler instance

Examples
const photoDirObj = M.mkPhotoDirHandler('photo_field', 'direction_deg', 'direction_cardinal')
function changeDir(event){
  photoDirObj.popOther(event)
}
ON('change', photoDirObj.dnDir, changeDir)
ON('change', photoDirObj.dnCard, changeDir)
ON('add-photo', photoDirObj.photoDn, photoDirObj.extractPhotoDir)
Details

FulcrumHelpers#mkPhotoDirHandler

mkMLoadRecords( formID, enterLoadedData [, fulcrumHelpers ] ) → {MLoadRecords}

Description

Factory method for MLoadRecords (backward compatibility)

Parameters
Name Type Attributes Default Description
formID string

Fulcrum form ID
enterLoadedData function

Callback function to process loaded records
fulcrumHelpers FulcrumHelpers <optional>
 this

Optional helper instance (defaults to current FulcrumHelpers instance)
Returns

MLoadRecords instance

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

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

const loader = M.mkMLoadRecords(appID, processRecords)

ON('load-record', loader.getAppFvs)
ON('change', 'species_link', loader.loadRecords)
Details

FulcrumHelpers#mkMLoadRecords

Type Definitions

MfldOpt

Options for Mfld instances

Description

Options for Mfld to specify drawing of values in Merjent pdf reports. Properties are strings starting with -. ie: '-hcb'.

Entire opt property of Mfld is a concatenated string. ie: '-cb-hcb-rdo'

Properties
Name Type Description
na string

replaces null values with 'N/A' instead of '---'
syn string

short yes no: Positive and negative labels replaced with first character. Neutral replaced with first 3 characters. (ie: Y | N | N/A)
cb string

Display choice values as a list of checkboxes. Checkboxes will be displayed vertically.
hcb string

Modifier for -cb. Checkboxes will be displayed horizontally.
yon string

yes no only: Neutral label will not be displayed.
rdo string

Modifier for -cb. Checkboxes will be replaced with radio buttons.
hn string

hide null values: Do not display field if value is null.