Merjent Fulcrum Tools

A comprehensive JavaScript toolkit for Fulcrum field data collection applications, developed by Merjent environmental consultants.

Notes

/report-style contains html and css files related to pdf template design.
/tools contains PowerShell runner scripts that call Python tools in the separate merjent-fulcrum-pyTools repository.
build.bat starts shell script /build/buildPkg.ps1 which runs a series of commands to create the modules for distribution.
- Package is bundled with microbundle.
  - microbundle is a fork of Rollup and modules are written in ESM format. Almost all classes are written in ES6/ES2015 format.
  - The majority of the modules are intended for use in the data events of the Fulcrum App. This is a server-side Node.js environment, therefore the modules located in /dist are bundled as CommonJS modules using module.exports = ... instead of require.
- buildPkg.ps1 runs microbundle and also uses terser for minification. Text transformations use native PowerShell -replace operations.
- JSDOC constructed using foodoc.
Merjent Fulcrum Tools Development Resources
General Development Resources

Overview

Merjent Fulcrum Tools provides a suite of JavaScript utilities for building and maintaining Fulcrum mobile data collection apps. The package includes:

JavaScript Libraries - Reusable classes and helpers for Fulcrum data events and PDF reports
Build Pipeline - Automated bundling, minification, and documentation generation
Report Templates - HTML/CSS styling for professional PDF reports

Note: Python tools for batch operations and bulk updates have been moved to merjent-fulcrum-pyTools.

What is Fulcrum?

Fulcrum is a mobile data collection platform for field work. This toolkit extends Fulcrum's capabilities with:

Pre-built data validation and field calculations
Automated status workflows and permission management
Professional PDF report generation
Bulk operations across multiple apps

Features

JavaScript Modules

📊 Mtools (Data Events)

Commonly used methods for the data events scripting environment:

Field validation and calculation helpers
Form schema parsing and navigation
Weather data integration (NWS API, fire danger ratings)
API request helpers
General JavaScript utilities

📄 Mtools (PDF Reports)

Specialized methods for the PDF report scripting environment:

HTML table and grid generation
Photo galleries and image handling
Section-based report building
Professional formatting utilities

🎯 MerjentApp (Mapp)

Streamlined app creation for Fulcrum data events:

Permission Control - Restrict fields by user role (PM, coordinator, field staff)
Status Workflows - Automated status transitions (Pending → Submitted → Approved)
Field Locking - Lock fields based on status or role
Photo Management - Bulk operations on record photos
Template-Based - Pre-configured templates for common app patterns

🛠️ Utils

General JavaScript utilities included in all modules:

Data type validation and conversion
String manipulation and formatting
Date/time helpers
Object and array utilities

Installation

Prerequisites

Node.js 12.0.0 or higher
merjent-fulcrum-core - Required sibling repository for shared templates

Setup

Clone both repositories as siblings:

cd /path/to/Fulcrum
git clone https://github.com/slushmonk3y/merjent-fulcrum-tools.git
git clone https://github.com/slushmonk3y/merjent-fulcrum-core.git

Required folder structure:

Fulcrum/
├── merjent-fulcrum-core/    # Required - shared templates
└── merjent-fulcrum-tools/   # This repo

Install Node.js dependencies:
```
cd merjent-fulcrum-tools
npm install
```

Important: The build script expects merjent-fulcrum-core at ../merjent-fulcrum-core/. It will fail if the sibling repo is missing.

For Python tools (batch operations, bulk updates), see the merjent-fulcrum-pyTools repository.

Quick Start

Building the JavaScript Modules

Windows:

build.bat

PowerShell (direct):

powershell -NoProfile -ExecutionPolicy Unrestricted -Command .\build\buildPkg.ps1

Development mode (watch and rebuild):

npm run dev

This generates minified modules in dist/:

merjent-tools-de.mmin.js - Data events module
merjent-tools-mapp.mmin.js - Data events with MerjentApp
merjent-tools-report.mmin.js - PDF reports module
merjent-tools-utils.mmin.js - Standalone utilities

Using in Fulcrum

In a Data Event:

//#region !START MERJENT FULCRUM TOOLS!
// ... paste merjent-tools-de.mmin.js or merjent-tools-mapp.mmin.js ...
//#endregion !END MERJENT FULCRUM TOOLS!

// Instantiate Mtools and MerjentApp if using
const M = module.exports.Mtools
const mApp = module.exports.MApp

ON('change', mApp.dnSubmit, () => {
  if (VALUE(mApp.dnSubmit) === 'yes') {
    SETSTATUS('Submitted');
  }
});

In a PDF Report:

//#region !START MERJENT FULCRUM TOOLS!
// ... paste merjent-tools-report.mmin.js ...
//#endregion !END MERJENT FULCRUM TOOLS!

// M is already instantiated in the dist file
// Your custom code starts here
const photos = M.photosRequest([RECORDID()], $form.name, 'photos');
const html = M.buildPhotoSection(photos, { center: 'Site Photos' });

Deploying Updates

Use the PowerShell runner scripts in tools/ to deploy updates to all apps:

# Update all apps with latest MTools
.\tools\run_updateMtools.ps1

# Search/replace across all apps
.\tools\run_findMtoolFunctions.ps1

Note: These scripts call Python tools in the merjent-fulcrum-pyTools repository.

Module Structure

merjent-fulcrum-tools/
├── src/                          # Source code
│   ├── Mtools/                   # Core helper classes
│   │   ├── Utils.js              # General JavaScript utilities
│   │   ├── FulcrumHelpers.js     # Fulcrum-specific helpers
│   │   ├── RequestHelpers.js     # API request helpers
│   │   ├── DataEventHelpers.js   # Data event utilities
│   │   ├── FieldHelpers.js       # Field manipulation
│   │   ├── ReportHelpers.js      # PDF report generation
│   │   └── ReportTemplateBlocks.js # Auto-generated from merjent-fulcrum-core
│   │
│   ├── mApp/                     # MerjentApp module
│   │   ├── merjentApp.js         # Main MApp class
│   │   ├── mixins/               # Composable functionality
│   │   │   ├── PermissionMixins.js
│   │   │   ├── StatusMixins.js
│   │   │   ├── PhotoMixins.js
│   │   │   └── LockingMixins.js
│   │   └── templates/            # Pre-configured templates
│   │
│   ├── MtoolsDataEvents.js       # Entry point for data events
│   ├── MtoolsMerjentApp.js       # Entry point for MApp
│   ├── MtoolsReports.js          # Entry point for reports
│   └── MtoolsUtils.js            # Entry point for utilities
│
├── dist/                         # Built modules (generated)
│   ├── merjent-tools-de.mmin.js      + Data Events Mtools Only
│   ├── merjent-tools-mapp.mmin.js    + Data Events Mtools & Merjent App
│   ├── merjent-tools-report.mmin.js  + Report Mtools
│   └── merjent-tools-utils.mmin.js   + Utils Only
│
├── tools/                        # PowerShell runner scripts
│   ├── run_updateMtools.ps1      # Calls pyTools updateMtools
│   └── run_findMtoolFunctions.ps1 # Calls pyTools findMtoolFunctions
│
├── docs/                         # Generated JSDoc documentation
├── build/                        # Build scripts
│   └── buildPkg.ps1              # Main build orchestration
├── tutorials/                    # Detailed guides
│   ├── 01_overview.md
│   ├── 02_mtools.md
│   ├── 03_mapp.md
│   ├── 04_pdf-reports.md
│   ├── 06_merjent-dev.md
│   └── 07_general-dev.md
│
└── report-style/                 # Local CSS overrides (main styles in merjent-fulcrum-core)
    └── MJNT_Report.css           # See ../merjent-fulcrum-core/report-style/ for primary styles

Class Hierarchy

Two separate inheritance chains for different Fulcrum environments:

Data Events Chain:
Utils (base utilities)
  └── FulcrumHelpers (Fulcrum-specific)
      └── RequestHelpers (API requests)
          └── DataEventHelpers (data event boilerplate)

Reports Chain:
Utils (base utilities)
  └── FulcrumHelpers (Fulcrum-specific)
      └── FieldHelpers (field representation & rendering)
          └── ReportHelpers (PDF report generation)

MerjentApp (composable app builder)
  ├── PermissionMixins
  ├── StatusMixins
  ├── PhotoMixins
  └── LockingMixins

Build System

The build pipeline uses:

microbundle - Module bundling (Rollup fork)
terser - Minification with name preservation
Native PowerShell - Text transformations (-replace operator)
JSDoc + foodoc - Documentation generation

Build Process

Build merjent-fulcrum-core - Compiles shared templates (runs ../merjent-fulcrum-core/build/build.ps1)
Generate ReportTemplateBlocks.js - Creates template class from html-blocks.json
Bundling - Creates 4 CommonJS modules for Node.js
Post-processing - Injects version/timestamp, fixes exports
Minification - Creates .mmin.js versions (preserves class/function names for debugging)
Documentation - Generates HTML docs from JSDoc comments

Build Outputs

Each module is compiled as CommonJS for Fulcrum's Node.js server-side runtime:

File	Description	Exports
`merjent-tools-de.mmin.js`	Data events	`Mtools`, `MLoadRecords`
`merjent-tools-mapp.mmin.js`	Data events + MApp	`Mtools`, `MApp`, `MLoadRecords`
`merjent-tools-report.mmin.js`	PDF reports	`ReportHelpers`, `SecOpt`
`merjent-tools-utils.mmin.js`	Standalone utilities	`Utils`

Version Management

Version and build timestamp are:

Stored in package.json (version, since)
Injected into all dist files during build
Used by Python tools for deployment tracking

Documentation

Online Documentation

Overview - Package structure
Mtools - Data events helpers
MerjentApp - App building with Mapp
PDF Reports - Report generation
Merjent Development - Merjent-specific conventions
General Development - General resources

Python Tools Documentation: See merjent-fulcrum-pyTools tutorials

Generating Documentation

npm run generate-docs

Documentation is generated in docs/ using JSDoc with the foodoc template.

Fulcrum API References

When working with Fulcrum features, reference these official repositories:

Fulcrum API - REST API documentation
fulcrum-core - Data structures
fulcrum-expressions - Expression syntax
fulcrum-python - Python SDK

Contributing

Development Workflow

Make changes in src/
Build with build.bat or npm run dev (watch mode)
Test in Fulcrum environment
Generate docs with npm run generate-docs
Deploy with .\tools\run_updateMtools.ps1 (requires merjent-fulcrum-pyTools)

Code Style

Use ES6+ syntax for source files
Document all public methods with JSDoc
Preserve existing naming conventions
Test changes in actual Fulcrum apps before deploying

Changelog

[0.5.6] - 2026-01-22

✨ Added

PermissionMixins: New individual permission methods extracted from standardUpdate
- standardAdmin() - Admin restrictions: all fields editable unless complete lock, status always editable
- standardEditor() - Editor restrictions: fields editable unless complete lock, respects disableLocationEdit
- standardUser() - User restrictions: fields editable unless complete lock, respects disableLocationEdit
- standardViewer() - Viewer restrictions: all fields read-only, location and status locked
MerjentApp.dnAutoName: New property to auto-populate a field with user's full name on new record creation
ReportTemplateBlocks.sideBar: New HTML template for sidebar layout

🔧 Changed

DefaultTemplate.start(): Restructured event handlers
- disableNewRecordCreation now runs on load-record instead of new-record event
- Added auto-population of dnAutoName field on new-record event
Utils.fVal(): Improved handling of choice fields with "other" values
- Now filters out duplicate values when "other" option matches a choice_value
- Formats output as "choice1, choice2, other_value" without duplicates

🐛 Fix

PermissionMixins: Fixed arrow function this binding issue
- Converted standardAdmin, standardEditor, standardUser, standardViewer from arrow functions to regular functions
- Arrow functions cannot be rebound with .bind(), causing this to be undefined when called from standardUpdate

📚 Document

JSDoc cleanup: Removed redundant @method tags from MerjentApp stub methods
New permission methods: Added JSDoc for all 4 new permission methods in both PermissionMixins and MerjentApp stubs

[0.5.5] - 2026-01-13

♻️ Refactored

Build system: Completely refactored buildPkg.ps1 to use native PowerShell
- Removed rexreplace npm dependency
- Version/timestamp injection now uses PowerShell regex replacement
- Footer injection uses native string operations
- Simplified export pattern fixing with native PowerShell

🔧 Changed

Report assets centralized: Moved report styles and templates to merjent-fulcrum-core sibling repo
- CSS files (MJNT_Report.css, MJNT_Charts.css, MJNT_Themes.css) → merjent-fulcrum-core/report-style/
- HTML boilerplates → merjent-fulcrum-core/report-boilerplates/
- Build now generates ReportTemplateBlocks.js from core templates automatically

📚 Document

MerjentApp JSDoc: Major documentation improvements for template/mixin architecture
- MerjentApp.js: Added architecture overview, file structure diagram, mixin table, and binding table
- DefaultTemplate.js: Added mixin bindings table, composite methods list, extension hooks
- All mixin files: Added usage examples, @see cross-references, clearer @namespace docs
Tutorials updated: References updated for merjent-fulcrum-core structure
- 01_overview.md, 02_mtools.md, 04_pdf-reports.md, 06_merjent-dev.md

🗑️ Removed

Build artifacts: Deleted files now managed by merjent-fulcrum-core
- build/DataEventsContents.js, build/version.txt, build/footer*.txt
- build/copyButtonScript.html, build/copyButtonStyle.html
Report style directory: Entire report-style/ moved to merjent-fulcrum-core
Working files: src/Mtools/ReportTemplateBlocks_WORKING.js (no longer needed)
Root CLAUDE.md: Consolidated into .claude/CLAUDE.md
docs/ from git tracking: JSDoc output now in .gitignore (generated locally by build)

See CHANGELOG for complete history.

Merjent Fulcrum Tools

Merjent Fulcrum Tools

Notes

Github

Table of Contents

Overview

What is Fulcrum?

Features

JavaScript Modules

📊 Mtools (Data Events)

📄 Mtools (PDF Reports)

🎯 MerjentApp (Mapp)

🛠️ Utils

Installation

Prerequisites

Setup

Quick Start

Building the JavaScript Modules

Using in Fulcrum

Deploying Updates

Module Structure

Class Hierarchy

Build System

Build Process

Build Outputs

Version Management

Documentation

Online Documentation

Generating Documentation

Fulcrum API References

Contributing

Development Workflow

Code Style

Changelog

[0.5.6] - 2026-01-22

✨ Added

🔧 Changed

🐛 Fix

📚 Document

[0.5.5] - 2026-01-13

♻️ Refactored

🔧 Changed

📚 Document

🗑️ Removed

Search results