Custom plugin form builder | TRMNL Help Center

If you're new to building plugins, see Private Plugins and Public Plugins API Docs.

Below is a guide to adding user-facing form fields inside a Private Plugin or Recipe.

How it works

Step 1 - Plugin author (you) creates custom fields

Step 2 - Plugin user (including you) can interact with rendered fields

Step 3 - Provided values are accessible via author-defined key/value pairs inside the Markup Editor

{{ trmnl.plugin_settings.custom_fields_values }}

# => { "password": "secret", "lookback_period": "7" }

Let's begin!

Supported field types

Where possible, TRMNL follows HTML5 input types to leverage native browser validations and UX features. Our current selection includes:

url
string
text (textarea)
code (like textarea, but monospace font)
number
password
date (M Y D)
time (HH:SS)
select (single or multi)
time_zone
copyable (produces 'click to copy' button)

Coming soon:

radio (binary toggle)
email
xhrFetch (select field that fetches <option> values from external URL)

Anatomy of a form field

The following key/value pairs are available to all field types:

keyname - parameterized identifier, not user-facing, ex user_email
field_type - one of the above "type" values
name - field label
description - secondary field label, HTML-friendly
help_text - tertiary field label, HTML-friendly (optional)
optional - boolean; unless set to true, required will be added to HTML input (omit if field should be required)
default - value if input is left blank; must be a lowercase, parameterized version of one of the provided options values or will not be pre-chosen on select field type. example: "Upcoming Movies" option => upcoming_movies as default

The following key/value pairs are available for some field types:

rows - number of visible rows on a text or code field
options - collection of option values for the select field
placeholder - example value if input is cleared; supported by url, string, text, number, date, code

When building a form field, only the following values are required:

keyname, name, field_type

Building form fields

Below are examples of every supported field type, which you may modify with optional parameters described above.

Note that every field must be indented 2 spaces and be preceded with a -, also called a block sequence.

url

- keyname: url
  field_type: url
  name: Web Address
  description: URL of RSS Feed
  placeholder: https://www.site.com/rss
  help_text: Please include http:// or https://

string

- keyname: api_key
  field_type: string
  name: API Key
  description: Account API Key
  placeholder: sa_api_key_qwerty

text (textarea)

- keyname: prompt
  field_type: text
  name: Prompt
  description: Enter your prompt for Chat GPT to respond.
  placeholder: Tell me a Dad Joke under 200 words.

number

- keyname: retirement_age
  field_type: number
  placeholder: '65'
  name: Retirement Age
  description: At what age do you plan to retire?

password

- keyname: password
  field_type: password
  name: Password
  description: Mobile app login password
  placeholder: s3cret!

code

- keyname: json_query
  field_type: code
  rows: 8
  name: JSON Query
  description: Provide a raw query
  placeholder: |
    { "cannot": "spare a square" }
  help_text: Learn how to do this <a href="https://jquery.com/" class="underline">here</a>.

date

- keyname: start_date
  field_type: date
  placeholder: '2024-11-26'
  name: Start Date
  description: Provide your start date

When using the date field, rendered form will have a M/D/Y picker. However the value inside {{ trmnl.plugin_settings.custom_fields_values }} will be YYYY-MM-DD.

time

- keyname: scroll_time
  field_type: time
  name: Fixed start time?
  description: By default, the week's earliest event time will be used.
  help_text: Optional. Applies to week view only.

select (single, unified label/value option tags)

- keyname: filter_by
  field_type: select
  options:
  - Upcoming # value will be 'upcoming'
  - Now Playing # value will be 'now_playing'
  default: now_playing
  name: Filter By
  description: Select a movie type

select (single, with separate label/value option tags)

- keyname: lookback_period
  field_type: select
  options:
  - One Week: 7
  - Two weeks: 14
  default: 14 # should be set to the value, not the label
  name: Lookback Period

select (multi)

- keyname: sales_pipeline
  field_type: select
  name: Pipeline Statuses
  description: Select up to 3 statuses
  options:
  - 'Discovery'
  - 'Pending'
  - 'Closed-lost'
  - 'Closed-won'
  multiple: true

Note: if you create a select field that has options "Yes" and "No", and you want the default option to be "No," then you must wrap the default in quotes as "no" or it will be considered truthy. Example:

- keyname: include_description
  field_type: select
  name: Include Description
  description: Select up to 3 statuses
  options:
  - "Yes"
  - "No"
  default: "no" # unless wrapped in quotes, value will be true

time_zone

- keyname: time_zone
  field_type: time_zone
  name: Time Zone
  description: Where are you located?

copyable

- keyname: webhook_url
  field_type: copyable
  name: Webhook URL
  value: "https://vandelayindustries.com/hooks/IMPORTS_EXPORTS"
  description: "(Webhook strategy only) Paste this into your integration"

Troubleshooting

Form fields don't appear

If your YAML cannot be parsed for any reason, it will be ignored and no errors will be returned.

Check your YAML syntax with a free online tool to ensure proper formatting before saving it in the Custom Fields code editor:

https://yaml-online-parser.appspot.com/