Widget Patterns

This section documents recurring code patterns found across Protrak custom widget implementations. Each pattern explains the intent, the applicable layout types, and shows a working code example drawn from real customer projects.

Use these patterns as building blocks when generating or reviewing widget code. Most widgets are a single pattern, but some (e.g., paymentlayout.js) combine two or three.

Read These First

Before writing any widget code:

Widget Introduction — How widgets are loaded at runtime, key constraints (no imports, global scope, naming rules), and widget registration via .json files.
pageContext Reference — Complete API for the pageContext argument: common props, per-target shapes, AttributeObject structure, onAttributeEdit signature, and attribute type helpers.
Save Integration — The three mechanisms for syncing widget state with the parent form's save lifecycle (onAttributeEdit, saveInstance, saveOperationState).

Pattern Catalog

Display-only patterns

Pattern	Description	Layout Target
Branding / Home Widget	Display logo or welcome banner using platform settings	HomePage
User Context Display	Display current user's profile information from `userData`	ViewLayout, HomePage
Dashboard: totalData + Pipe Parsing	Parse platform pre-aggregated pipe-delimited report rows; includes picklist variant and ExportCSVButton	DashboardLayout, ReportLayout
Dashboard: Async Report (useReportQuery)	Poll for async report completion using `useReportQuery` global hook	DashboardLayout
Dashboard: Data Fetch + Filter Table	Fetch own data via `useProtrakApi`, render filterable/exportable table	DashboardLayout, ViewLayout
Report Layout Custom Visualization	Custom table/chart for a Report Layout; uses `data`, `totalData`, `onClick`, `ShowDrillDownData` for drill-down	ReportLayout
Embedded Instance Grid	Embed a full sortable/paginated instance grid via `InstanceGridForCustomWidget`	ViewLayout, DashboardLayout
Attribute Renderer	Customize a single field cell — read-only masking, or click-to-dialog with own API save	CustomAttributeRenderer, ViewLayoutWidget

Action patterns

Pattern	Description	Layout Target	Save
Utility / Action Widget	Read an attribute value and trigger an external action (file download, API call)	ViewLayout, EditLayout, CreateLayout	None / Own API
Bulk Action Widget	Operate on multiple selected instances via dialog with per-instance progress	CustomAction	Own API

Edit / Create patterns

Pattern	Description	Layout Target	Save mechanism
JSON Attribute Editor	Manage a complex data structure (table, schedule, list) stored as JSON in a Text attribute; save synced with parent form	EditLayout, CreateLayout	`onAttributeEdit`
Reference Attribute Editor	Dropdown that manages a single Reference attribute; filters options from related data	EditLayout, CreateLayout	`onAttributeEdit`
Multi-Attribute Calculator	Widget manages multiple attributes with calculated derived fields; full save integration	EditLayout	`onAttributeEdit` + `saveInstance` + `saveOperationState`

Quick Decision Guide

Home layout with logo/banner?              → Branding / Home Widget
Showing the logged-in user's profile?      → User Context Display
Dashboard layout?
  Platform pre-aggregates data as rows?    → Dashboard: totalData + Pipe Parsing
    Need picklist labels from type def?    →   (see same doc — Picklist variant)
  Long-running async report?               → Dashboard: Async Report
  Widget fetches its own data?             → Dashboard: Data Fetch + Filter
Report Layout (custom visualization)?
  Clickable cells + drill-down rows?       → Report Layout Custom Visualization
View layout — need a related records grid? → Embedded Instance Grid
Replacing a single field cell?             → Attribute Renderer
Read attribute + trigger an action?        → Utility / Action Widget
Bulk-action button on a list?              → Bulk Action Widget
Edit/Create layout group?
  Stores data as JSON in Text attribute?   → JSON Attribute Editor
  Manages a Reference dropdown?            → Reference Attribute Editor
  Multiple fields with calculated values?  → Multi-Attribute Calculator

Anti-Patterns

See Anti-Patterns and Known Issues for a list of common mistakes found in real widget implementations and how to fix them.

Read These First​

Pattern Catalog​

Display-only patterns​

Action patterns​

Edit / Create patterns​

Quick Decision Guide​

Anti-Patterns​