Formatter

OmniOutliner provides controls for determining how data is displayed as text in your document. For example, an outline may contain columns that display numeric values as percentages or as currency values. Or a column may contain dates, whose representation could be altered to display them in many ways, from long format (Sunday, October 1, 2017) to short format (10/1/17), or any customized variation.

Scripts use the Formatter class to determine and control the formatting for columns in an outline. Specifically, there are three types of Formatters scripts can use:

• Date Formatter for controlling how date values are displayed
• Decimal Formatter for controlling how numeric values are displayed
• Duration Formatter for controlling how time values are displayed

This webpage describes how to create and apply formatters, especially when adding columns to an OmniOutliner outline.

This first section will examine how create and use Date Formatters, especially when applying their format to columns.

Before we cover the Date Formatter, it is important to mention the JavaScript’s built-in Date object. The Date object can be used to generate date strings and date objects, and is fully documented at the w3cschools.com website.

When used as a class method Date() the result will be a string. When used as a constructor new Date() the result will be a date object. (see below)

The JavaScript Date Object is often used in scripts to generate a string or object for the current date.

Date Formatter Class Properties

Here are the properties of the Formater.Date class:

• iso8601 (Formatter.Date r/o) • Return a date formatter that produces ISO–8601 formatted dates, using the Gregorian calendar and the UTC time zone.

Date Formatter Instance Properties

Here are the properties of an instance of the Formater.Date class:

• calendar (Calendar) • The instance of the Calendar class currently used by the formatter.

• dateFormat (String r/o) • A string indicating the text formatting of the date result. For example: M/d/yy

• locale (Locale) • An instance of the Locale class that represents one of the standard localities.

• timeZone (TimeZone) • An instance of the Timezone class representing one of the standard time zones.

Properties of the Calendar class include: buddhist, chinese, coptic, ethiopicAmeteAlem, ethiopicAmeteMihret, gregorian, hebrew, indian, islamic, islamicCivil, islamicTabular, islamicUmmAlQura, iso8601, japanese, persian, republicOfChina, and identifier. [see the documentation of the Calendar class for more information]

Date Formatter Class Methods (functions)

Here are the methods (functions) of the Formater.Date class:

• withStyle(dateStyle:Formatter.Date.Style, timeStyle:Formatter.Date.Style or nil) (--> Formatter.Date) • A formatter that will display dates according to the user’s “short” format selected in system settings.

• withFormat(format:String) (--> Formatter.Date) • Returns a formatter with a specific ICU date format and the user’s current locale, calendar, and timeZone. See userguide.icu-project.org/formatparse/datetime/ for details on date format strings.

Here are some of the possible combinations of date/time formatting. NOTE: including time is optional, and time and date formats are not required to be the same.

Date Formatter Instance Methods (functions)

Here are the methods (functions) of an instance of the Formater.Date class:

• stringFromDate(date:Date) → (String) • Returns a formatted date string for the passed-in date object, using the formatting of the formatter instance.

• dateFromString(string:String) → (Date or nil) • Converts the passed-in date string into a date object. NOTE: the date string can be in any standard date format.

Calendar

The calendar used by the formatter is indicated with one of the following properties:

• buddhist (Calendar r/o) • The Buddhist calendar is a set of lunisolar calendars primarily used in mainland Southeast Asian countries of Cambodia, Laos, Myanmar and Thailand as well as in Sri Lanka and Chinese populations of Malaysia and Singapore for religious or official occasions. (Wikipedia)

• chinese (Calendar r/o) • The traditional Chinese calendar is a lunisolar calendar which reckons years, months and days according to astronomical phenomena. It was developed by the Qin Dynasty. As of 2017, the Chinese calendar is defined by GB/T 33661-2017 Calculation and promulgation of the Chinese calendar, which the Standardization Administration of China issued on May 12, 2017. (Wikipedia)

• coptic (Calendar r/o) • The Coptic calendar, also called the Alexandrian calendar, is a liturgical calendar used by the Coptic Orthodox Church and still used in Egypt. This calendar is based on the ancient Egyptian calendar. (Wikipedia)

• ethiopicAmeteAlem (Calendar r/o) • The Ethiopic (Amete Alem) calendar is a solar calendar which in turn derives from the Egyptian Calendar, but like the Julian Calendar, it adds a leap day every four years without exception, and begins the year on August 29 or August 30 in the Julian Calendar. (Wikipedia)

• ethiopicAmeteMihret (Calendar r/o) • The Ethiopic (Amete Mihret) calendar is a solar calendar which in turn derives from the Egyptian Calendar, but like the Julian Calendar, it adds a leap day every four years without exception, and begins the year on August 29 or August 30 in the Julian Calendar. (Wikipedia)

• gregorian (Calendar r/o) • The Gregorian calendar is internationally the most widely used civil calendar.[1][2][Note 1] It is named after Pope Gregory XIII, who introduced it in October 1582. (Wikipedia)

• hebrew (Calendar r/o) • The Hebrew or Jewish calendar is a lunisolar calendar used today predominantly for Jewish religious observances. (Wikipedia)

• islamic (Calendar r/o) • The Islamic, Muslim, or Hijri calendar is a lunar calendar consisting of 12 months in a year of 354 or 355 days. It is used (often alongside the Gregorian calendar) to date events in many Muslim countries. It is also used by Muslims to determine the proper days of Islamic holidays and rituals, such as the annual period of fasting and the proper time for the pilgrimage to Mecca. (Wikipedia)

• islamicCivil (Calendar r/o) • (see Islamic calendar).

• islamicTabular (Calendar r/o) • The Tabular Islamic calendar (an example is the Fatimid or Misri calendar) is a rule-based variation of the Islamic calendar. It has the same numbering of years and months, but the months are determined by arithmetical rules rather than by observation or astronomical calculations. (Wikipedia)

• islamicUmmAlQura (Calendar r/o) • Saudi Arabia uses the sighting method to determine the beginning of each month of the Hijri calendar. Since AH 1419 (1998/99) several official hilal sighting committees have been set up by the government to determine the first visual sighting of the lunar crescent at the beginning of each lunar month. (Wikipedia)

• iso8601 (Calendar r/o) • Representation of dates and times is an international standard covering the exchange of date- and time-related data. It was issued by the International Organization for Standardization (ISO) and was first published in 1988. (Wikipedia)

• japanese (Calendar r/o) • Japanese calendar types have included a range of official and unofficial systems. At present, Japan uses the Gregorian calendar together with year designations stating the year of the reign of the current Emperor. (Wikipedia)

• persian (Calendar r/o) • The Iranian calendars are a succession of calendars invented or used for over two millennia in Iran (Persia). One of the longest chronological records in human history, the Iranian calendar has been modified time and again during its history to suit administrative, climatic, and religious purposes. (Wikipedia)

• republicOfChina (Calendar r/o) • The Minguo calendar (Republic of China calendar) is the method of numbering years currently used in Taiwan by officials and other territories under the control of the Republic of China. It was used in mainland China from 1912 until the founding of the People’s Republic of China in 1949. (Wikipedia)

The Decimal Formatter is used when a column is to display numeric data.

Decimal Formatter Class Properties

Here are the properties of the Formater.Decimal class:

• currencyCodes (--> String r/o) • Returns the list of known ISO currency codes

• custom (--> Formater.Decimal r/o) • Returns a new formatter that can be configured with custom settings.

• decimal (--> Formater.Decimal r/o) • Returns a new number formatter that will use both a decimal separator.

• percent (--> Formater.Decimal r/o) • Returns a new number formatter that will display the value as a percentage.

• percentWithDecimal (--> Formater.Decimal r/o) • Returns a new number formatter that will display the value as a percentage with a decimal separator.

• plain (--> Formater.Decimal r/o) • Returns a new number formatter that will not use any separators.

• thousandsAndDecimal (--> Formater.Decimal r/o) • Returns a new number formatter that will use both a thousands and decimal separator.

Decimal Formatter Instance Properties

Here are the properties of an instance of the Formater.Decimal class:

• decimalSeparator (String) • No documentation available.

• negativeFormat (String) • A format string to use for negative values.

• positiveFormat (String) • A format string to use for positive values.

• thousandsSeparator (String) • No documentation available.

• zeroSymbol (String) • The string to use when displaying a zero value. If this is null, the positiveFormat is used.

Decimal Formatter Class Methods (functions)

Here are the methods (functions) of the Formater.Decimal class:

• currency(code:String or nil) (--> Formatter.Decimal) • Returns a new formatter that will display the value as a currency value. An ISO currency code may be specified to pick a specific currency, or null may be passed to use the default currency for the user’s locale. If the argument is not a valid currency code, an error will be thrown.

Decimal Formatter Instance Methods (functions)

Here are the methods (functions) of an instance of the Formater.Decimal class:

• stringFromDecimal(number:Decimal) (--> String or nil) • Generates a corresponding string for the provided decimal value.

• decimalFromString(string:String) (--> Decimal or nil) • Generates a corresponding decimal value for the provided string.

The Duration Formatter is used when a column is to display time-based data.

Duration Formatter Constructor (function)

Here is the constructor (function) of the Formater.Duration class:

• new Formatter.Duration() (--> Formatter.Duration) • Creates a new instance of the Formatter.Duration class.

Duration Formatter Instance Properties

Here are the properties of an instance of the Formatter.Duration class:

• hoursPerDay (--> Number) • The number of hours considered to comprise a “work day” (In the U.S. the default is 8).

• hoursPerWeek (--> Number) • The number of hours considered to comprise a “work week” (In the U.S. the default is 40).

• useVerboseFormat (--> Boolean) • f true, the formatter spells out the time durations; for example, 1d 4h gets expanded to 1 day 4 hours.

Duration Formatter Instance Methods (functions)

Here are the methods (functions) of an instance of the Formater.Duration class:

• stringFromDecimal(number:Decimal) (--> String or nil) • Generates a corresponding string for the provided decimal value.

• decimalFromString(string:String) (--> Decimal or nil) • Generates a corresponding decimal value for the provided string.

Example Plug-In

Here’s an example plug-in that appends a numeric column after the last column on the right side of the document. The action displays a text input form to prompt the user to title the column.