TextExpander
 

Help: Creating and Using Fill-In Fields

Introduction to Fill-in fields

You can add fill-in fields to a snippet to make it easy to create customized boilerplate text at the time you expand an abbreviation. A great way to learn more is to watch these snippets in action in our video Fill-in Snippets.

Here is an example of a snippet with fill-in fields in action:

Fill-in field examples


TextExpander supports four kinds of fill-in fields, as seen above:

  1. single-line fields:
  2. Type or copy / paste in a customer's name or numerical quantity.

  3. Popup menus:
  4. Assign a few standard options, like “today”, “in one day”, “in two days.”

  5. Optional sections:
  6. This content will always be the same, but does not have to appear every time.

  7. Multi-line fields:
  8. Allows for multiple lines of text to appear. You can type, copy/paste, or expand other snippets in this and the single-line field.

Creating a Fill-in Snippet

  1. Create a new snippet by selecting New Snippet new snippet button in the TextExpander menubar.
  2. Choose the Fill-ins button located at the top of the snippet editor and select one of the options. A dialog will appear to let you customize some of the field's options.
    • You will notice a fifth option, “Show at top.” This will allow all the fill-in fields to appear at the top of the fill-in window, useful if you create a long snippet with lots of fields.

    Fill-in Menu

  3. Set your field’s options, including the field name.
    • Field name:
      This helps you remember what to fill the field with as you use the snippet, and let’s TextExpander recognize different fields. If two different fill-in fields of the same type have the same Field Name they are treated as one. Meaning, as you fill out one field, the other will fill with the same text.
  4. Editing fill-in fields

  5. Select OK to close the popup dialog. Double-click on the field’s entry to open the dialog and edit the field’s properties again.

Popup Dialog

All of the fields are optional. The fill-in will work even if you don't change any of the defaults. Note: All fill-ins with the same Field Name will have the same value, so will be filled the same.

  • Field Name:
  • A descriptive name helps you organize if you have several fields. For example: “name”, “date”, “quantity”, etc.

  • Default Value:
  • You may leave this field blank. If you have nothing specific to put in this field at the time you expand the snippet, you may want some default text which will always appear there instead. In the case of this example, if you do not know the customer's first name, some default text for the customer name field might be “Sir/Ma’am.” You can also include dates and times in this field.

  • Width:
  • The visual width of the field as you expand it. The default width is 20, shown in the example snippet above for the “customer name” field. The quantity field in the example has a specified width of 4. This is purely for your visual preference when viewing the snippet in the expansion window.

Features

  • Access Fill-ins via the Fill-in button in the editing bar at the top of the snippet editor.
  • Double-click within a field entry to edit it in a popup dialog.
  • Expand other snippets into the fill-in fields in the expansion window.
  • Switch applications without dismissing the fill-in window.
  • Text and popup fill-in fields support default values.
  • “Show at top”: For longer snippets, display the fields at the top of the fill-in window to make filling out the fields easier. This also works for longer script snippets.
  • Type, copy/paste, or expand other snippets in the single-line and multi-line fields.

Advanced: Fill-in Syntax

Fill-ins appear as visual blocks. However, if you wish to see and edit the macro syntax used to make them, you may switch your snippet’s Content: menu from "Plain Text" or "Formatted Text, Picture" to one of the script formats to see it and edit it.

  • Single-line fields
    • Syntax:

      %filltext[:name=<field name>][:default=<default value>][:width=<width>]%

      Field name, default value, and width are all optional. Default width is 20.

      Example:

      %filltext:name=quantity:default=1:width=4%

  • Multi-line fields
    • Syntax:

      %fillarea[:name=<area name>][:default=<default value>][:width=<width>][:height=<height>]%

      Area name, default value, width, and height are all optional. Default width is 30. Default height is 5.

      Example:

      %fillarea:name=custom:default=Thanks for ordering from Acme Widgets. We are a family owned business, established in 1891. We really appreciate your business.:width=40:height=4%

  • Popup menus
    • Syntax:

      %fillpopup[:name=<popup name>]:[default=]<value>:[default=]<value>…%

      Name is optional. At least one <value> should be specified. Multiple <value>s are encouraged. If no default is specified, the first <value> will be the default.

      Example:

      %fillpopup:name=ship timeframe:today:default=tomorrow:next week%

  • Optional sections
    • Syntax:

      %fillpart[:name=<section name>]:[default=yes'no]%<content of optional section>%fillpartend%

      Example:

      %fillpart:name=Payment Due:default=yes%You did not include payment information with your order. Please call our office at 555-1212 to provide payment details.%fillpartend%

      Name is optional. Default is optional: yes or no; if not specified, no is used. Content can contain other fill-ins.

  • Show at top
    • Syntax:

      %filltop%

      Place this macro anywhere in the snippet content, including nested snippets, for it to have the effect of displaying fields at the top of the fill-in window upon snippet expansion.

Notes

When edited in this way, fill-in field names and default values cannot contain % (percent sign) or : (colon). (They can contain these characters when the snippet type is Plain or Formatted text.)

If two fill-in fields in a snippet have the same name, their value will be synchronized when you expand the snippet.

(For more macros, see Date, Time, and Math Macros and Advanced Snippet Functions: Macros).

 

Smile logo

© 2006-2019 SmileOnMyMac, LLC, dba Smile. All rights reserved.
TextExpander is a registered trademark, Smile and the Smile logo are trademarks of SmileOnMyMac, LLC, dba Smile.