Text in OmniOutliner

Aside from its remarkable ability to organize data, a core strength of OmniOutliner is found in its robust support for displaying textual data. The characters, words, sentences, and paragraphs of outline documents can be formatted with a broad range of styling attributes, including: typeface, color, kerning, weight, line spacing, baseline positioning, writing direction, and horizontal alignement, to name some of the basic options.

This section examines how to manipulate text in an OmniOutliner document using Omni Automation.

Text Strings and Text Objects

By default, all text in an outline document is styled. Every row’s text has a full range of style attributes applied to it, such as: typeface, weight, color, alignment, etc. Even the text in a blank outline has style attributes applied to it using the default style attribute values of the application.

When using Omni Automation to manipulate and edit the textual content of a document, scripts can work with the text as either:

• a collection of individual characters (text strings), or
• as range of characters with their corresponding style data (text objects).

In terms of Omni Automation, text without style data is a text string or “string” for short. Text with style data is a text object.

Text Strings

Text strings exist in scripts as a collection of characters, stored and manipulated within the script itself. For example, the value of the topic property of the Item class is the collection of characters represented by the styled text in a row.

For example, if we use the topic property of an item to get the text of the first row of the outline shown above, the result is returned as a “string” of characters:

Note that the result of the script (line 2 above) contains no information about the typeface used to style to row, or that the words “textual contents” are displayed as bold red characters. The resulting “string” is simply the sequence of characters displayed from left to right in the row.

In those cases where all the text in a row is styled using the default style, manipulating the text contents of a row can be done easily using the many standard built-in JavaScript functions for manipulating text, like the replace() function that replaces a found substring with another in the main string.

However, if any of the characters within the row’s text have additional style attributes applied to them, that styling will be lost when the value of the topic property is set to a new value.

Executing the above script will result in edited text for row, but the styling of the row will revert to the default style if no level style is set:

Here is the result if the row had a non-default level style previously applied. Note that the custom styling of the words “textual content” have been replaced with the styling of the first character in the row:

SUMMARY: Editing the text content of outline rows by manipulating and reassigning text strings is perfect for those documents that have defined level styles and no additionally formatted characters within the topic string. For those documents, using the editing techniques described below will be useful. For detailed information describing all of JavaScript’s built-in string editing methods, visit the excellent w3cschools website.

The following are examples of using some common string methods to edit rows in an outline document.

Prepending/Appending Strings

One of the basic text edits is to add text to the beginning (prepend) or the ending (append) of a string. This is easily accomplished using the standard JavaScript string concatenation method: prependingString + ReceivingString + appendingString

The first example prepends the tag “DRAFT: ” to every row:

To selected rows:

And the second example appends a date string to every row:

And to selected rows:

Trim Leading|Ending Tags from Topic Strings

The following example demonstrates how to trim characters from the start of a topic string. In this script, the leading tag is identified by its beginning and ending characters, which are opening and closing brackets: [ ]

The script uses the indexOf() method to confirm the existence of the leading tag, and then uses the substr() method to return the rest of the topic after past the tag.

Also note the use of the trim() method (end of line 5) to remove the space between the tag and the topic string.

And here is a variation of the previous script that uses the lastIndexOf() method to remove tags from the end of every row:

Replacing Text within Strings

A common task when working with text is to locate and change occurrences of specific substring (a segment within a string) into something else. JavaScript’s built-in replace() method is an excellent tool for performing this task.

The replace() method searches a string for a specified value, or a regular expression, and returns a new string where the specified values are replaced. Here is the syntax for the method:

Let’s use the replace() method to replace the word Seattle with Portland in the text of the first row of this outline:

In the illustration above, note that the replace() method only changed the first occurence of “Seattle,” not all occurrences. To change every instance of a specific word or substring, include the global parameter (g) with the method call:

Note that by default, the global parameter is case sensitive, in that the current case of replaced characters will be honored. To perform a global, case-insensitive replacement, use this syntax for the method:

A complete overview of the replace() method and its parameters, can be found at the excellent w3cschools website.

And here’s an example of how to use the replace() method for the entire outline:

And only in the selected rows:

Changing Case

Another common text-editing task is to change the case of the text in topic strings. This can accomplished using standard JavaScript methods combined with some custom routines from the past.

• Upper Case

Here’s how to change the text in a topic string to upper case using the toUpperCase() method.

• Lower Case

Here’s how to change the text in a topic string to lower case using the toLowerCase() method.

• Sentence Case

Applying a sentence case means capitalizing the first character of a sentence. This is accomplish using the charAt() and substr() methods to get the first character and the remaining characters of a sentence.

According to grammar-monster.com titles should be written in “title case.” This means only using capital letters for the principal words. Articles, conjunctions, and prepositions do not get capital letters unless they start the title. For example: The Last of the Mohicans

Applying title case to strings using a script can be very challenging. But fortunately for users of Omni Automation, John Resig translated to JavaScript a Perl script written by John Gruber, that provides a comprehensive application of title case.

With gratitude and thanks to these gentlemen for their creativity and generosity, we’re providing an enhanced version of Mr. Resig’s JavaScript function for use with Omni Automation. In addition to providing the functionality of the orignial code, this version enables the processing of those possessive terms using a curly single-quote character: ( ’ )

Here is a link to the Set to Title Case script saved as an OmniOutliner solitary action:

• Set to Title Case

To install on macOS, download and unpack the ZIP archive, then choose “Plug-Ins…” from the OmniOutliner automation menu, and place the file in the PlugIns folder opened on the desktop. The script will be available from the OmniOutliner Automation menu.

To install on iOS, tap the link, choosing the “Open” option in forthcoming dialog. Then tap “More…” and choose the “Copy to OmniOutliner” option. The installed action will appear in the Plug-Ins view on your device, and will be available from the OmniOutliner automation menu.