DayPilot.Modal.form

The form() method displays a modal dialog with the specified fields.

Availability:

Standalone DayPilot.Modal library, since version 3.0 (open-source)
DayPilot Lite for JavaScript, since version 2021.2.261 (open-source)
DayPilot Pro for JavaScript, since version 2019.4.4153 (commercial)

Instead of building the form manually using the API, you can design it using the DayPilot Modal Builder.

For a detailed description of the available form field types, see the DayPilot Modal documentation.

Declaration

DayPilot.Modal.form(form[, data[, options]])

Parameters

form (array) - modal dialog field definitions
data (object) - source data object used to fill the initial values
options (object) - an object that specifies custom DayPilot.Modal properties

The form array items can define the following properties:

name (string) - field label displayed as a description
id (string) - field identifier used to load the value from data and store it in args.result
type ("text" | "date" | "datetime" | "searchable" | "select" | "radio" | "checkbox" | "table" | "title" | "image" | "html" | "textarea" | "scrollable") - field type (see the documentation)
dateFormat (string) - date/time format used for "date" fields; it uses the patterns from DayPilot.Date.toString()
columns (array) - table columns for "table" fields; each item is an object with name, id, and type properties (supported types: "text", "number", "select"); "select" columns specify options using the options property
height (number) - height in pixels for "textarea" and "scrollable" fields
html (string) - static HTML content for "html" and "scrollable" fields
text (string) - static text content for "html" and "scrollable" fields
image (string) - static image URL for "image" fields
children (string) - optional children for "radio" fields
cssClass (string) - custom CSS class applied to the field
disabled (boolean) - makes the field disabled when set to true
locale (string) - custom locale ID that overrides the form DayPilot.Modal.locale (applies to type="date" and type="datetime" fields)
onValidate (function) - validation callback
onNewRow (function) - new row content callback for "table" fields
options (array) - items used for "select" fields; each item is an object with name (item text) and id (item value) properties

Return Value

Returns a Promise. The promise resolves when the modal dialog is closed, including when the Cancel button is used or the background is clicked. The promise never rejects.

The resolved args object includes a copy of data, updated with the selected values, in args.result.

Notes

If the field type is not specified explicitly, it is detected automatically using the following rules:

If the form item defines image, the "image" type is used.
If the form item defines html or text, the "html" type is used.
If the form item defines options, the "searchable" type is used.
If the form item defines columns, the "table" type is used.
If the form item defines dateFormat, the "date" type is used.
Otherwise, the "text" type is used.

Example

Basic form definition:

const form = [
  {name: "First Name", id: "first"},
  {name: "Last Name", id: "last"},
  {name: "Birthday", id: "birthday", dateFormat: "MMMM d, yyyy"}
];

const args = await DayPilot.Modal.form(form);
console.log(args.result);

Using initial values with async/await (ES2017; not supported in Internet Explorer):

const form = [
  {name: "First Name", id: "first"},
  {name: "Last Name", id: "last"}
];

const data = {
  first: "Jane",
  last: "Doe",
  id: 1204
};

const args = await DayPilot.Modal.form(form, data);
if (!args.canceled) {
  console.log("data", args.result);
}

Promise syntax:

const form = [
  {name: "First Name", id: "first"},
  {name: "Last Name", id: "last"}
];

const data = {
  first: "Jane",
  last: "Doe",
  id: 1204
};

DayPilot.Modal.form(form, data).then((args) => {
  if (!args.canceled) {
    console.log("data", args.result);
  }
});

Validation example:

const resources = [
  {name: "Resource A", id: "A"},
  {name: "Resource B", id: "B"},
  {name: "Resource C", id: "C"}
];

function validateTextRequired(args) {
  const value = args.value || "";
  if (value.trim().length === 0) {
    args.valid = false;
    args.message = "Text required";
  }
  else if (value.toLowerCase().includes("a")) {
    args.valid = false;
    args.message = "Text must not contain 'a'.";
  }
  else if (value.includes("2020")) {
    args.valid = false;
    args.message = "2020 not allowed.";
  }
}

const form = [
  {name: "Text", id: "text", onValidate: validateTextRequired},
  {name: "Note", id: "note", onValidate: validateTextRequired},
  {name: "Start", id: "start", type: "date", onValidate: validateTextRequired},
  {name: "End", id: "end", type: "date"},
  {name: "Resource", id: "resource", options: resources, onValidate: validateTextRequired}
];

const data = {
  start: "2020-11-01",
  end: "2020-11-02",
  resource: "B"
};

DayPilot.Modal.form(form, data).then((args) => {
  console.log(args);
});

Availability

Availability of this API item in DayPilot editions:

Product	Lite	Pro
DayPilot for JavaScript