Create and Use Complex Snippets

TextExpander’s capability to substitute a simple text string on the fly for something that you type is well worth the price of admission. But TextExpander snippets can contain more than just simple text, and they can do some cool things.

You can create snippets that include formatted text and images. Moreover, using TextExpander macros, you can make snippets that include clipboard content, move your cursor, and type special keys like Escape and Tab. Snippets can even perform date and time math, combine several snippets into one, and generate fill-in forms.

“Complex,” however, does not mean “hard”—complex snippets are easy to create and easy to use.

And the uses, as you might imagine, are plentiful.

Add Formatting and Pictures

As you saw in Learn the Types of Snippet Content a few pages back, one of the four types of snippet content is Formatted Text, Pictures. When you choose this item from the pop-up menu above the snippet Content field, the Formatting pop-up menu beneath the Content field is enabled (Figure 7) and the snippet Content field becomes ready to accept images.

Applying Formatting

The two available submenus on the Formatting pop-up menu provide the standard text formatting commands that you probably have seen in many other OS X programs (Figure 8).

You can use the commands on these menus to format the text of a snippet in all sorts of sophisticated ways, adjusting text sizes, line layout, styles, kerning, and colors. The formatting menus effectively turn the snippet Content field from a plain text editor into a small but powerful word processor.

For even more formatting control, choose Format > Text > Show Ruler. You can access style, justification, line spacing, list formatting, and tab stops from the ruler that appears (Figure 9).

You don’t, however, have to rely upon TextExpander’s menu commands to format text in the Content field. It’s just as easy—in fact, easier—to use a word processor, like, say, Pages, to create and format your snippet’s text and then just copy it and paste it into the Content field.

Inserting a Picture

Nor are you limited to formatted text: as you have surely figured out from its name, you can drag or copy and paste graphical objects into a Formatted Text, Pictures snippet as well. Figure 10, for example, shows some text I sometimes use as part of an email signature. The snippet includes a cover image of one of my books and an active Web link.

How might you use a Formatted Text, Pictures snippet? Here are just a few examples (I’m sure you can think of others):

• A standard letterhead for correspondence
• A corporate logo
• Complex “boilerplate” passages that contain a mix of fonts and styles, such as might be used in a contract, form letter, or invoice
• A section separator graphic for a manuscript
• Your scanned signature
• An inline graphic, such as a menu icon that you may need to use repeatedly when writing a book about TextExpander

Formatted Text, Pictures snippets can be as long or as short as you like. You can create them for any situation where you need to reuse formatted text, pictures, or a combination of the two.

Meet the Macros

Much of the magic of TextExpander comes by way of macros. These are instructions you place in a snippet’s text, no matter whether it’s a plain or formatted snippet. When TextExpander expands the snippet, it follows the macros’ instructions before it inserts the expanded snippet into the current text-editing environment. A macro can perform a special action or it can insert text into the expanded snippet. For example, a macro can position the cursor, it can expand into the current or a calculated date and time, and it can generate a special keypress, such as Return or Tab, as though you had typed it yourself.

TextExpander recognizes dozens of macros. All TextExpander macros begin, and some of them end, with a % character. When TextExpander sees a % in a snippet, it interprets the next character as the beginning of a macro.

Putting a macro into a snippet is not hard: most of them are quite short. If you have a good memory and are a quick typist, you can type each macro that you want directly into a snippet.

However, there’s an easier way for the hunt-and-pecker to put a macro into a snippet: use the Insert pop-up menu (Figure 11) that appears just below the snippet Content field. The vast majority of items on this menu and its submenus insert macros into your snippet.

Place the Cursor

TextExpander ordinarily positions the insertion point (which TextExpander calls the cursor) at the end of an expanded snippet. While that makes sense in the vast majority of cases, sometimes you may need to expand a snippet and then position the insertion point elsewhere.

For example, suppose you have lent some of your books to various friends and now you’d like them to be returned before you move to a new city. You write a generic email message and make it into a snippet so you can nag these book-nappers:

As I recall, you borrowed the book, X, from me some time ago. Since I’ll be moving soon, I’d really like the book back so I can finish packing. Thanks!

That message, of course, would work just fine for all of your book-borrowing buddies, but it does mean that you have to move your insertion point back to the middle of the snippet and replace X with the title of the book for each borrower that you plan to email.

TextExpander can help you streamline this task even more: you can insert a macro in the snippet to position the insertion point right where you want it when the snippet is expanded (see Meet the Macros, a page or so earlier).

The macro for specifying the insertion point position within a snippet is %| (that’s a percent sign followed by a vertical line character—Shift-backslash on your keyboard). Just stick %| where “X” appears in your original version of the snippet, and when the snippet expands, your insertion point ends up where %| appeared in the snippet’s contents.

Alternatively, here’s how to use the Insert pop-up menu to insert the cursor position macro within the snippet:

1. In the TextExpander window’s Content field, place your insertion point where you want it to appear in the expanded snippet.
2. Click the Insert button to see the pop-up menu, and then choose Cursor > Position Cursor Here.

You can also position the insertion point elsewhere than inside the snippet or at the end of it. Along with the Position Cursor Here command, the Cursor submenu provides macros for moving the insertion point left, up, right, or down (the commands to insert these macros appear as arrows [←, ↑, →, ↓] on the Cursor submenu). You can insert as many of these insertion point movement macros as you like at the end of a snippet.

If, for example, you regularly need to insert a snippet and then position the insertion point two lines below it, you can simply choose Cursor > ↓ twice at the end of the snippet (or type %v%v). Programmers and Web developers, in particular, often have the need to insert some canned text and then move the insertion point elsewhere nearby.

Insert the Clipboard or Another Snippet

You can type a macro, or insert one using an Insert menu command, to place the current contents of the clipboard one or more times into a snippet. The macro is easy to remember: %clipboard.

This capability comes in handy when you have to merge information with a snippet. Here’s a simple example: you want to send a party announcement to a few dozen people via email and insert each invitee’s name into the email at several points. To do this, make a snippet containing the email, and use %clipboard at each place in that snippet where the name is to be inserted. Then, you can just copy names off a list one at a time onto the clipboard and type the snippet’s abbreviation into a new email. Voilà!

You can also use a macro to insert the contents of one snippet into another snippet: %snippet:<snippetabbrev>% (where <snippetabbrev> is the abbreviation of the snippet you want to insert). For example, to use a quotation in several different snippets, put the quotation into one snippet and a macro referring to it in each of the other snippets.

You are not limited to one level of reference when you use a snippet macro: you can have a snippet that contains a macro referring to another snippet that, in turn, has a macro referring to yet another snippet, and so on.

Include Special Keys

Some keys are difficult to put into a snippet: if you type the Tab key in the snippet Content field, for example, you won’t insert a tab character into the snippet. Instead, you’ll watch your cursor move to the next field in the window.

TextExpander provides one macro that can insert four of these problem keys: %key:<key-name>%. For example, if you need a tab character in a snippet, from the Insert pop-up menu choose Key > Tab, or type %key:tab% in the snippet Content field. When the snippet expands, the tab character is sent to whatever application is running, just as if you had typed it from the keyboard.

The four key names you can use are as follows:

• enter
• esc
• return
• tab

You can use this capability in Web forms, for example: a snippet containing 432-555-1212%key:tab% when used in a Web form field enters the phone number in the field and then tabs to the next field.

Include Dates and Times

There are many times when inserting a time or a date in a snippet is useful. For example, you might want to have a letterhead snippet that includes the current date, or you might want to have a snippet that expands to the current date and time so that you can quickly and easily create a time-sheet for work being performed. You can even perform date and time math in a snippet.

Use Date and Time Macros

TextExpander provides macros for all the common components used for presenting dates and times. The following list shows the available date and time macros, illustrated with how they represent the example date and time of Friday, July 3, 2015, 1:09:03 PM:

Years:

• %Y: four-digit year number (“2015”)
• %y: two-digit year number (“15”)

Months:

• %B: fully spelled month (“July”)
• %b: abbreviated month name (“Jul”)
• %m: two-digit month number, with leading zero if required (“07”)
• %1m: month number (“7”)

Days:

• %A: fully spelled day name (“Friday”)
• %a: abbreviated day name (“Fri”)
• %d: two-digit day number, with leading zero if required (“03”)
• %e: day number (“3”)

Hours:

• %H: two-digit 24-hour clock number (“01” for 1 AM, “13” for 1 PM)
• %I: two-digit 12-hour clock number (“01” for 1 AM or 1 PM)
• %1H: trimmed 24-hour clock number (“1” for 1 AM, “13” for 1 PM)
• %1I: trimmed 12-hour clock number (“1” for 1 AM or 1 PM)

Minutes and seconds:

• %M: two-digit minute number (“09”)
• %1M: trimmed minute number (“9”)
• %S: two-digit second number (“03”)
• %1S: trimmed second number (“3”)

AM/PM:

• %p: expands to AM or PM, depending on the time

Naturally, all the macros listed above are available from the Insert pop-up menu below the TextExpander window’s Content field.

Remember, too, you can insert text around and between these macros, such as a colon between an hour macro and a minute macro, as follows: %H:%M (which expands to “13:09” using our example time).

Finally, you can use standard Unicode date format patterns by inserting the %date:<pattern>% macro in a snippet. (In addition to its work specifying character sets, the Unicode Consortium maintains other technical standards, including one for specifying dates.) With this macro, you can insert both dates and times, and even include arbitrary text in a single macro. For example, %date:yyyy.MM.dd 'at' HH:mm:ss zzz% expands to 2015.05.24 at 15:28:22 PDT (which is the exact date and time that I expanded the snippet I made containing that macro).

Unfortunately, the Insert menu does not provide a command for the Unicode date format patterns macro, but you can easily type it if you know the pattern you want. You can find out more about the macro in the Smile blog article More TextExpander Date and Time Formatting Options.

Perform Date and Time Math

Not all of us live in the present: sometimes it’s useful to insert a date or a time other than the current one. For example, if you need to email your colleagues that a certain report is due 3 weeks from today, you can use the following snippet:

Hey, team, make sure you get your report back to me by %@+21D%B %e, %Y.

From Use Date and Time Macros just above, you can probably figure out that the %B %e, %Y part is three macros that expand to the current date. What precedes that set of date macros is a date/time math macro. In this case, the %@+21D macro means “add 21 days to any date/time-related macros that come later in this snippet.” When the snippet expands, the date it contains is 3 weeks (21 days) in the future.

All date/time math macros begin with %@, followed by a + to add time or a - to subtract time, followed by the amount of time to add or subtract in number form, and conclude with a letter indicating the time unit to add or subtract. So, for example, %@-24M means “subtract 24 months from the current date,” and %@+16h means “add 16 hours to the current time.”

Of course, the Insert pop-up menu can insert date/time math macros into a snippet’s content for you, but you still must adjust the numeric portion of the macro for the amount of time to add or subtract.

Here’s a quick reference to the time units used for addition and subtraction in date/time math macros:

• Years: Y
• Months: M
• Days: D
• Hours: h
• Minutes: m
• Seconds: s

Make a Fill-in Snippet

Several times in this chapter I’ve mentioned form letters as one of the ways you can use snippets. For the ultimate in form-letter writing flexibility, TextExpander provides four kinds of fill-in macros you can include in snippets and, even better, four specialized popover editors for those macros so you don’t have to fiddle with percent signs and other macro syntax to use them.

When a snippet includes fill-in macros, TextExpander presents a fill-in window when it expands the snippet so you can enter the fill-ins, as in Figure 13. When you finish, click OK to insert the expanded snippet in your text, along with its filled-in information; click Cancel to discard the abbreviation and its associated snippet.

TextExpander offers you four types of fill-in macros and one display command from the Fill-ins submenu on the Insert pop-up menu:

• Single-Line Field: This fill-in macro shows up as a text entry field in a TextExpander fill-in window. In the fill-in window shown in Figure 13 (above), you can see four such text entry fields.

  When you choose Single-Line Field from the Insert pop-up menu, you see a popover editor (Figure 14) in which you can specify the field’s name, its default value (if any), and how wide you want the field to appear in the fill-in window. In the snippet Content field, a Single-Line Field begins with %filltext and ends with %.

• Multi-Line Field: This item shows up as a text entry field that is as many lines tall as you specify in its popover editor (you can even make the field one line tall, if you are perverse). A Multi-Line Field fill-in macro is useful for short lists. Note that you can add as many lines of text as you need to a Multi-Line Field when you actually fill it in; the height you specify when you create it affects only the field’s appearance in the fill-in window. In the snippet Content field, a Multi-Line Field begins with %fillarea and ends with %.
• Popup Menu: If you want to restrict a fill-in item’s contents to a few specific values, use a Popup Menu fill-in macro. It will appear as a pop-up menu in the fill-in window (Figure 13, earlier, includes a Popup Menu macro for the month). You can add, remove, and edit the menu items in a Popup Menu macro’s popover editor, and you can specify which item is the default. In the snippet Content field, a Popup menu macro begins with %fillpopup and ends with %.
• Optional Section: Use this when you have a chunk of boilerplate text that you don’t always want to include in the expanded snippet. You specify the optional text in the Optional Section macro’s popover editor. When the fill-in window containing an Optional Section appears, you’ll see a checkbox for whether to include the optional text. The optional text you choose to include appears in the fill-in window with a green background (Figure 13, previously), while excluded optional text has a red background. The text of an Optional Section can contain fill-in macros and other snippets.

  In the snippet Content field, an Optional Section macro has two parts: the first part of the macro identifies the start of the optional content, and it begins with %fillpart and ends with %; the second part identifies the end of the optional content and contains %fillpartend%.

• Show at Top: The %filltop% macro is inserted when you choose this fill-in from the Fill-ins submenu. It instructs TextExpander to display all of the single-line fields and popups that the snippet contains at the top of the window (Figure 15)—except for those fill-ins that appear in optional sections (see the previous bullet).

  

  You can insert %filltop% anywhere in the snippet, and in multiple places, but it only needs to be there once (I suggest at the beginning or end so it’s easy to find). Show at Top saves you from having to hunt through the fill-in window to find all the fill-ins. You can show or hide the part of the window that shows the fill-ins in place by clicking the toggle button below the gathered fill-ins, which is especially useful if you have optional sections containing fill-ins in your snippet.

Although I have just described the syntax that represents each fill-in macro type, I almost didn’t need to bother, since you never have to edit a fill-in macro by hand. Instead, double-click anywhere in a fill-in macro’s text in the snippet Content field and TextExpander presents that fill-in macro’s popover editor.

The text of the snippet that produces the fill-in window shown a few pages back in Figure 13 can be seen in Figure 16:

In the sample snippet text shown in Figure 16, notice that all the fill-in macros include a name= string. This part of a fill-in macro serves to identify it. Although a fill-in macro doesn’t have to have a name, it is a good idea to name all of your fill-in macros. Here are two reasons why:

• Identification: The names you assign to fill-in macros for fields and optional sections can appear in the fill-in window. For a yet-to-be-filled-in field, the macro’s name appears in gray; for an Optional Section macro, the name labels the checkbox for the section.
• Content sharing: If you use the same name for two or more fill-in macros, whatever you enter in one of them in the fill-in window is used in all other macros that have the same name. For example, the Single-Line Field macro named First Name in my fill-in snippet example appears twice: type a name in either occurrence of the field in the fill-in window and the name appears in the other field as well.