Text Snippets

Introduction to Text Snippets

The text snippets feature of ComposeIt allows you to conveniently replace short character sequences (called "shorthand") with arbitrary text fragments. This helps you save time and avoid typing errors. ComposeIT maintains a database of the shorthands and text snippets you define, and lets you configure the hot-key to trigger the replacement. If you only wish to use the other features of ComposeIT, you may also deactivate the text snippet functionality altogether. This will stop ComposeIT from listening to any hot-keys, which might be useful if you have other extensions installed which have assigned hot-keys, too.

Other solutions for replacing shorthands with text fragments exist for the Mac. Typically these solutions work system-wide, i.e. in all situations where you type any text. And they work in a, what we would characterize as a "hungry" mode; i.e. whenever a shorthand is recognized in any input text, the replacement text is immediately inserted, without any e.g. prevent inadvertent text replacements in situations where you might be using artificial languages (like e.g. computer programming languages), which bears a high risk of "false positive", i.e. a legitimate part of the artificial language could match one of your further ado. With some of those solutions, you can specify lists of excluded applications to shorthands. But if you exclude for instance your favourite text editor from text snippet expansion so it does not disturb you from - say - programming scripts for your website, you will not be able to use text snippets when writing a letter using that same favourite text editor. Or if you insert a few lines of programming code into your email, text replacement may strike. At the end of the day this approach comes down to you constantly thinking about whether what you are currently typing might be one of your shorthands, and you constantly checking the screen to notice any unwanted text replacements.

We hence decided that such a text snippet feature would need to meet two fundamental requirements:

  1. The shorthands and replacements want to be context (i.e. application) specific. The text fragments you use for email will very likely be distinct from those you would want to use when authoring a Web page.
  2. The replacement only wants to occur upon specific user intent, not automatically. You can type ahead and focus on what you wanted to say, instead of whether any of your text was suddenly replaced with something you didn't want to say. Only when you trigger it explicitly, shorthand expansion will be attempted.

ComposeIT meets both of these requirements: it is specific to Mail.app, and text snippets are only expanded when you hit a hot-key.

Basics of Working With Text Snippets

As explained above, using a text snippet entails three things:

Basic scheme of using text snippets

As in any good computer book, we will start with a "Hello World" example. So let's assume you would like to replace the shorthand string "hw" with the text "Hello World!". As shown in the ComposeIT will then start examining the text immediately before the insertion point figure above, you would type the shorthand ("hw" in our case), and then hit the hot-key. (aka. text cursor) and scan backwards for a word boundary (i.e. white space, line break, or punctuation). It will then take the sequence of characters it found, and compare that against its database of shorthands. If it finds a match, it fetches the text snippet associated with the shorthand ("Hello World!" in our case). It then replaces the shorthand character sequence with the text snippet. The cursor remains where it was; after the text. That way, you can insert some text quickly, and continue typing at full speed without having to navigate back.

First, enter the shorthand sequence.

To prevent unexpected text modifications, you will choose a hot-key that is not normally used in text input or editing. The factory default hot-key in ComposeIT is Shift-Return. Hence, in our "Hello World" example, you would type h, w, and then Shift-Return to get the result "Hello World!" as shown in the figures above and below. Yes, it's that simple.

Then, hit the hot-key and the text snippet replaces the shorthand.

Of course you can also use the text snippet feature anywhere in a text, not just at the beginning as shown in the example so far. Just bear in mind that ComposeIT will scan backwards for a word boundary, starting from the insertion point.

A word boundary before the insertion point is needed to recognize the shorthand.

In the figure above, the example shorthand "hw" is embedded in the word "archway", and the insertion point is positioned immediately after the letters "hw". If you hit the hot-key now, nothing will happen. ComposeIT scans backwards for a word boundary, starting from the insertion point. In the figure above, it will find the sequence "archw". This does not match the (so far only) entry in the replacement database, for which the shorthand is "hw", and not "archw".

The scanning direction is always backwards with respect to the writing direction that you are using. This means that ComposeIT will work with right-to-left scripts just as well as with left-to-right scripts.

Advanced Use of Text Snippets

In addition to increasing your typing speed by inserting pre-recorded text snippets, ComposeIT provides you with an additional means of easing your editing job. Sometimes a canned phrase just won't cut it, and you will want to make it personal, e.g. by enriching a salutation with a name. So instead of addressing someone with a polite, yet anonymous "Dear Sir", you will probably want to use "Dear Mr. Appleseed". ComposeIT allows you to do that with three quick and easy steps, by allowing you to define a marker (the default is "<|>") that tells ComposeIT where to position the insertion point in the text snippet. If no marker is present, the insertion point will be positiioned after the text snippet.

Text snippets can define where the insertion point will be.

Let's assume you have defined a text snippet as shown in the figure above to respond quickly to questions people send you. First, you want to address your correspondent by name, then you want to thank him for his kind inquiry, and finally you will answer his question. Using text snippet replacement in conjunction with insertion point control, this can be done in three quick steps and with a minimum of keystrokes.

Three easy and quick steps to a personalized response opening.

With the shorthand and text snippet defined as shown above, follow these three steps to achieve the example results:

  1. Type "d" followed by the hot-key Shift-Return to insert the multi-line text snippet. Note that the insertion point is positioned just before the comma on the "Dear" line.
  2. Type "Mr. Appleseed" to make the address personal. Note that you did not have to use any arrow keys to position the insertion point to do this.
  3. Type Command-ArrowDown to move the insertion point to the end of the message, and begin answering John's question.

Apart from the name "Mr. Appleseed", that is only five keystrokes. Had you typed the same text manually, it would have cost you 53 keystrokes (again excluding "Mr. Appleseed", but including Shift keys for capitalization, spaces and line breaks).

Configuring Text Snippets

To configure the behaviour of text snippets, the ComposeIT preferences pane offers you two sections: the snippet behaviour section, and the text snippets section.

The snippet behaviour section of the ComposeIT preferences

The controls in this section work as follows:

  1. Credits: Click this button to open a small pop-up window detailing the copyright information, Open Source information, and links for further reading.
  2. Support: Click this button to open the support Website for ComposeIT. Check here if any new versions are available for download.
  3. Use Text Snippets: Untick this to deactivate the text snippet feature altogether. The hot-key (see number 4 below) will no longer be recognized, and no text replacements will occur.
  4. Hot-Key: Click inside the hot-key field to configure the keystroke combination you want to use to trigger text replacement. If the keystroke combination you chose is already in use, an error message will pop up, informing you to which command the kombination has already been assigned.
  5. Insertion Point Marker: Edit the content of this text field to set the marker which you would like to use in text snippets to tell ComposeIT where the insertion point shall be set after inserting the text snippet.

To configure the shorthands, and their associated replacements, select the text snippets section in the ComposeIT preferences.

The text snippets section of the ComposeIT preferences

The controls in this section work as follows:

  1. Snippet list: This table lists all text snippets and their associated shorthands. Change the sorting order by clicking on the column headers.
  2. Add button: Click the plus sign to add a new entry to the table.
  3. Remove button: Click the minus sign to remove the currently selected table entries. Note that you can select more than one entries by Command-Clicking them. You may also select all entries at once by typing Command-A.

When you add a new text snippet by clicling the plus sign, a new entry is added to the snippet table, and it is pre-populated with "key" and "value". If you click the plus sign several times, you will end up with "key1", "value1", "key2", "value2", and so on.

Adding a new text snippet

After you have added a new text snippet, double-click the table entry to open the editing popover window. Use click-to-edit to change the shorthand and replacement texts.

Editing a text snippet

The replacement text field offers the full spell checking and auto correction features as you configured in the System Preferences.

The replacement text may contain line breaks. Therefore, the Return or Enter key does not dismiss the popover window as in many situations. Instead, it inserts line breaks in the replacement text. The shorthand may of course not contain any white-space, punctuation, or line breaks. To dismiss the popover window, and apply any changes you made, click outside the popover window, or hit the Escape key.

To remove one or more text snippets, select the table entries you would like to remove (select more than one by Command-Clicking them, or select all by typing Command-A), and click the minus sign.

Removing a text snippet