Guides

Working with Forms

Forms provide you with a variety of fillable form fields in your Text Blaze snippets.

The form commands in Text Blaze are:

  1. {formtext} - A single line text input field.
  2. {formparagraph} - A multiline paragraph input field.command.
  3. {formtoggle} - A toggle switch that can enable or disable a block of text.
  4. {formmenu} - A menu input to select one or more items.
  5. {formdate} - A date input field.

When you insert a snippet that contains one or more form commands, the snippet isn't inserted immediately. Instead, a popup appears, prompting you to fill in the form fields, allowing you to customize the content that is inserted with the snippet.

The following example shows these commands in action:

The Form Commands
Text: {formtext} Paragraph: {formparagraph} Toggle: {formtoggle}This is optional text{endformtoggle} Menu: {formmenu: option 1; option 2; option 3} Date: {formdate: YYYY-MM-DD}
_

General Form Settings

All form commands in Text Blaze come with 3 optional named settings that are consistent across all of the form commands. These are called General Form Settings.

These settings are:

  • default - The default value for the form field.
  • formatter - A function that formats the value of the field before snippet insertion.
  • name - A value used to label the form field and for data bindings.

Besides the general form settings that each form command has, each form command might or might not contain additional settings that are specific to it.

For example, the {formtoggle} command has no additional settings besides the above 3, but the {formmenu} command contains an additional 4 settings. See the documentation page for each form command to see which settings are available to you.

The default Setting

One of the general settings that you get access to in form commands is default. It allows you to set the initial value that you see in the form field when the form popup appears for you to fill out.

This can be powerful to set the initial value of the form field. It can also be used as a fallback value if you don't modify the value of the field.

Default Values With Forms
First Name: {formtext: default=John} Last Name: {formtext: default=Smith}
Hey {formtext: default=there}, thank you for your email.
{formtoggle: default=yes}
{formmenu: option 1; option 2; option 3; default=option 4}
{formdate: YYYY-MM-DD; default=2001-02-01}
_

If you went through the above exercises you'll notice that these form commands already set a default value for you. The default setting lets you override what that value is.

If the default setting isn't explicitly overridden for the {formtoggle} command, then it will be no. In {formmenu}'s case, it will be the first item in the menu. In {formparagraph} and {formtext}'s text, it will be an empty string (""). Lastly, in {formdate}'s case, it will be today's date.

The name Setting

Another general form setting that you get access to is name. At its most basic level, the name setting is used to label the field.

A powerful feature of the name setting, is that form commands with the same name are linked. When one of them updates, the others will also update. You can watch this in action below:

Linked Form Fields
First: {formtext: name=first; default=John} Last: {formtext: name=last; default=Smith}

Your name is: {formtext: name=first} {formtext: name=last}
_

It is generally recommended to stick to single-word form names, as this simplifies things when referencing these names in formulas.

However, if you have multi-word form names, you can still reference them in formulas by enclosing them with back-ticks. For example:

Multi-word form names
Base Price: ${formtext: name=Base Price; default=100}

Price with Service Charge (15%): ${=`Base Price` * 1.15}
_

Besides using the name setting to label the field, it's also used for data binding when using a variety of other Text Blaze commands. See the next section to learn more.

Forms and Formulas

Form commands are often used in combination with the {=} (Formula Command) command, the {if} command, and the {repeat} command. The {=} (Formula Command) command lets you specify dynamic formulas in your snippets. Form fields with the name setting explicitly set can be used within formulas.

The following shows the combination of forms and formulas used together:

Forms and Formulas
Price ($): {formtext: name=price; default=5000} Tax Rate (%): {formtext: name=tax; default=12.5} Total Cost: {= price * (1 + tax/100); format=$,.2f}
_

The {if} command lets you hide or show a block of text based on whether the formula evaluates to yes or no. It has a main block that is shown if the formula evaluates to yes and an optional else block that is shown if the formula evaluates to no.

If Command
Price ($): {formtext: name=price; default=5000} {if: price > 1000}That's too expensive for me!{else}Great Price! I am buying it.{endif}
_

Form Validation

The {error} command can be used to validate the contents of a form. It can also be used to prevent the insertion of the snippet until the issue is resolved.

Form Validation
First Name: {formtext: name=first} Last Name: {formtext: name=last}

{if: first="" or last=""}{error: Both the first and last name must be entered; block=yes}{endif}
_

Nested Commands

Commands in Text Blaze can be nested. Combined with forms and formulas, this enables a range of interesting capabilities.

The following adjusts the above example to show how we can change the formatting of a number on the fly.

Nested Commands
Decimals: {formtext: name=decimals; default=2} (max is 20)

Price ($): {formtext: name=price; default=5000} Tax Rate (%): {formtext: name=tax; default=12.5} Total Cost: {= price * (1 + tax/100); format=$,.{=decimals}f}
_

Now when you combine forms and command packs it gets even more powerful. Imagine setting the default value of a {formtext} to the recipient's name when you're using Gmail. Convenient!