FormBuilder Helper

The FormBuilder is a utility that helps you create forms programmatically using a fluent API. It's accessible through the Modal Form plugin API.

Getting Started

Access the form builder through the plugin API:

const modalForm = app.plugins.plugins.modalforms.api;
const builder = modalForm.builder;

// Create a new form
const form = builder("example-contact-form", "Example Contact Form")
  .text({ name: "username", label: "Username" })
  .email({ name: "email", label: "Email" })
  .build();

// Open the form modal
modalForm.openForm(form);

Core Methods

builder(name: string, title?: string)

Creates a new form builder instance. The name parameter is required and must be unique. The title parameter is optional and defaults to the name.

const form = builder("example-form", "Example Form")
  // ... add fields
  .build();

build()

Finalizes the form creation and returns a form definition that can be used with openModalForm.

const form = builder("example-form")
  .text({ name: "username" })
  .build();

Field Methods

Each field method accepts these common parameters:

• name: (required) Unique identifier for the field
• label: (optional) Display label for the field
• description: (optional) Help text or description
• hidden: (optional) Whether the field should be hidden

text

Adds a text input field.

builder("example-form")
  .text({ name: "username", label: "Username" })

number

Adds a number input field.

builder("example-age-form")
  .number({ name: "age", label: "Age" })

date

Adds a date input field.

builder("example-birthday-form")
  .date({ name: "birthdate", label: "Birth Date" })

time

Adds a time input field.

builder("example-meeting-form")
  .time({ name: "meeting", label: "Meeting Time" })

datetime

Adds a datetime input field.

builder("example-appointment-form")
  .datetime({ name: "appointment", label: "Appointment" })

textarea

Adds a multi-line text input field.

builder("example-notes-form")
  .textarea({ name: "notes", label: "Notes" })

toggle

Adds a toggle/switch input field.

builder("example-settings-form")
  .toggle({ name: "active", label: "Active" })

email

Adds an email input field.

builder("example-contact-form")
  .email({ name: "contact", label: "Contact Email" })

tel

Adds a telephone number input field.

builder("example-phone-form")
  .tel({ name: "phone", label: "Phone Number" })

note

Adds a note field that references an Obsidian note.

builder("example-reference-form")
  .note({ name: "reference", label: "Reference", folder: "Notes" })

folder

Adds a folder selection field.

builder("example-save-location-form")
  .folder({ name: "destination", label: "Save Location" })

slider

Adds a numeric slider input field.

builder("example-rating-form")
  .slider({ name: "rating", label: "Rating", min: 0, max: 5 })

tag

Adds a tag selection field.

builder("example-categories-form")
  .tag({ name: "categories", label: "Categories" })

select

Adds a dropdown selection field.

builder("example-priority-form")
  .select({ 
    name: "priority", 
    label: "Priority", 
    options: ["Low", "Medium", "High"] 
  })

dataview

Adds a field populated by a Dataview query.

builder("example-tasks-form")
  .dataview({ 
    name: "tasks", 
    label: "Tasks",
    query: "task from #project" 
  })

multiselect

Adds a multiple selection field.

builder("example-tags-form")
  .multiselect({ 
    name: "tags", 
    label: "Tags",
    options: ["work", "personal", "urgent"]
  })

document_block

Adds a document block field.

builder("example-document-form")
  .document_block({ 
    name: "content", 
    label: "Content",
    body: "Initial content" 
  })

markdown_block

Adds a markdown block field.

builder("example-markdown-form")
  .markdown_block({ 
    name: "notes", 
    label: "Notes",
    body: "# Notes" 
  })

image

Adds an image upload field.

builder("example-avatar-form")
  .image({ 
    name: "avatar", 
    label: "Avatar",
    filenameTemplate: "avatar-${date}",
    saveLocation: "assets/images" 
  })

file

Adds a file upload field.

builder("example-attachment-form")
  .file({ 
    name: "attachment", 
    label: "Attachment",
    folder: "attachments",
    allowedExtensions: [".pdf", ".doc", ".docx"] 
  })

Complete Example

Here's a complete example of creating and opening a contact form:

const modalForm = app.plugins.plugins.modalforms.api;
const form = modalForm.builder("example-contact-form", "Example Contact Form")
  .text({ name: "name", label: "Full Name" })
  .email({ name: "email", label: "Email Address" })
  .tel({ name: "phone", label: "Phone Number" })
  .textarea({ name: "message", label: "Message" })
  .build();

modalForm.openForm(form);