How to Customize Plan Detail Forms with JavaScript in OnePlan

Direct Answer: How to Customize Plan Detail Forms with JavaScript in OnePlan

To customize a Plan Details form with JavaScript in OnePlan, open the Form Editor for the Plan Type, select the ⋮ (kebab) menu in the top right (next to Copy), and select Validation. Each Plan Type has its own validation code, organized into four tabs — Initialize, Load Plan, Step Ids, and Fields — where you can register field-level validators, value changers, and toolbar Customizations using the form’s built-in JavaScript API. This is an advanced capability intended for administrators comfortable writing JavaScript; OnePlan can assist with customizations on request.

What This Article Covers: JavaScript Form Customization

This article explains the JavaScript customization capability available on Plan Details forms, including the four editor tabs, the functions available on fields and the form, and how to add custom validation, dynamic field behavior, and toolbar buttons.

What you will accomplish By the end of this article, you will understand where to write JavaScript customizations for a Plan Details form, and how to use validators, changers, and custom toolbar buttons to extend the form beyond what Business Rules can configure.

Before You Begin: Customizing a Form with JavaScript

Before you begin, make sure you have:

• A OnePlan account with administrator permissions and access to the Plan Details App
• Working knowledge of JavaScript
• The internal field names for any fields you plan to reference (available in the Fields tab of the Validation editor)

Most conditional field behavior — hiding, requiring, or locking fields or sections based on plan data or the logged-in user — can be configured without code using Business Rules. See How to Create Business Rules for Plan Details Forms in OnePlan. Reach for JavaScript customization when you need logic that Business Rules can’t express, such as custom validation messages, cross-field calculations, or custom toolbar buttons.

Why This Matters: JavaScript Customization on Plan Details Forms

Context: When to Use JavaScript Instead of Business Rules

Business Rules cover most conditional show/hide/require/read-only scenarios through configuration. JavaScript customization exists for cases beyond that scope — custom validation logic and messaging, computed field values, and custom UI elements like toolbar buttons.

Context: Where Customizations Live

Each Plan Type has its own JavaScript, accessed from the Validation option in the Form Editor’s ⋮ (kebab) menu. Code is organized into four tabs so initialization logic, per-plan-load logic, process step references, and field references stay separated.

Step-by-Step: Customizing a Plan Details Form with JavaScript

Task: Open the JavaScript Editor

1. Open the Form Editor for the Plan Type you want to customize — see How to Configure Plan Detail Forms in OnePlan for the two ways to access it.
2. Select the ⋮ (kebab) menu in the top right of the Form Editor, next to Copy.
3. Select Validation.

Task: Use the Four Editor Tabs

The Validation editor opens in its own window, organized into four tabs:

• Initialize — Used to build validators and changers. This code runs once during form building and does not run again. A form variable is passed in, which you use to add validators and changers.
• Load Plan — Used to process plan-related items every time a plan is loaded. This code runs every time the Details form is shown. A form variable is passed in.
• Step Ids — A reference table of the process flow step Id and Name values available on the current Plan Details form, used when a validator or changer needs to apply only to specific steps.

• Fields — A reference table of every field’s Internal Name and display Name on the current Plan Details form. Use the internal name to reference a field elsewhere in your code.

Task: Reference Form and Field Functions

The following functions are available for use in your customizations:

Form functions:

• getField(fieldname) — Returns the field object for the given internal field name.
• validateField(fieldname) — Runs validation for a single field.
• validateAllFields() — Runs validation for every field on the form.

Field functions:

• getValue() — Returns the field’s current value.
• setValue(v) — Sets the field’s value.
• hide() — Hides the field.
• show() — Shows the field.

Task: Add a Field Validator

Use validators.push({...}) on a field to add validation logic:

• Error — The message to show when validation fails.
• OnChange — Set to true to validate whenever the field changes.
• Steps — An array of step IDs (from the Step Ids tab) to validate against, both on change and when moving between steps.
• Fn — The validation function. Receives the field and the current step ID, and returns false when validation fails.

form.getField("Name").validators.push({
  Error: "Cannot be blank",
  OnChange: true,
  Steps: ["aeaf7420-9040-44a4-3a67-b3c45ef10997"],
  Fn: function (field, step) {
    if (field.getValue() == "") {
      return false;
    }
  }
});

Task: Add a Field Changer

Use changers.push({...}) on a field to run logic whenever its value changes. The Fn function receives the form, the field, and the current step ID.

form.getField("Name").changers.push({
  Fn: function (form, field, step) {
    if (field.getValue() == "Some Name") {
      form.getField("someField").hide();
    }
  }
});

Example: hide a field based on another field’s value

form.getField("FlagField").changers.push({
  Fn: function (form, field, step) {
    var fieldValue = field.getValue("FlagField");
    if (fieldValue) {
      form.getField("MultiBusinessField").hide();
    } else {
      form.getField("MultiBusinessField").show();
    }
  }
});

Task: Add a Custom Toolbar Button

Add a button to the form toolbar from the Initialize tab:

form.down("toolbar").add({
  text: "Test Button",
  handler: function () {
    var p = DetailsApp.GetActivePlan(this);
    OnePlanCore.Plans.GetPlan(p).then(function (plan) {
      // Do something with plan here
    });
  }
});

JavaScript customization is an advanced capability. Contact OnePlan for assistance building or troubleshooting custom validators, changers, or toolbar buttons.

Frequently Asked Questions: JavaScript Form Customization

Q: When should I use JavaScript instead of Business Rules on a Plan Details form in OnePlan? A: In OnePlan, use Business Rules for standard show/hide/require/read-only logic driven by plan data or the logged-in user. Use JavaScript customization for logic Business Rules can’t express, such as custom validation messages, computed values, or custom toolbar buttons. See How to Create Business Rules for Plan Details Forms in OnePlan.

Q: How often does the Initialize tab’s code run in OnePlan? A: In OnePlan, code in the Initialize tab runs once during form building and is not run again for that session. Code in the Load Plan tab runs every time the Details form is displayed.

Q: Where do I find a field’s internal name for use in JavaScript in OnePlan? A: In OnePlan, internal field names are listed in the Fields tab of the Validation editor, opened from the ⋮ (kebab) menu of the Plan Details Form Editor for that Plan Type.

Q: Where do I find a process flow step’s ID for use in JavaScript in OnePlan? A: In OnePlan, process flow step IDs are listed in the Step Ids tab of the Validation editor, opened from the ⋮ (kebab) menu of the Plan Details Form Editor for that Plan Type.

What to Do Next: JavaScript Form Customization

Learn about related topics: - How to Create Business Rules for Plan Details Forms in OnePlan - How to Configure Plan Detail Forms in OnePlan - How to Set Up Split Fields for Plan Detail Forms in OnePlan