Method Overview

Method Details

convertDateFormatToIntlOptions(format){Intl.DateTimeFormatOptions}

Converts a web map date format string to an Intl.DateTimeFormat options object.

Parameter:

format String optional A web map date format string to convert. Possible Values:"short-date"|"short-date-short-time"|"short-date-short-time-24"|"short-date-long-time"|"short-date-long-time-24"|"long-month-day-year"|"long-month-day-year-short-time"|"long-month-day-year-short-time-24"|"long-month-day-year-long-time"|"long-month-day-year-long-time-24"|"day-short-month-year"|"day-short-month-year-short-time"|"day-short-month-year-short-time-24"|"day-short-month-year-long-time"|"day-short-month-year-long-time-24"|"long-date"|"long-date-short-time"|"long-date-short-time-24"|"long-date-long-time"|"long-date-long-time-24"|"long-month-year"|"short-month-year"|"year"|"short-time"|"long-time"

Returns:

Type	Description
Intl.DateTimeFormatOptions	The date format options derived from the format string as defined in the web map specification.

See also:

• FieldInfoFormat.dateFormat

Example:

const dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time");

// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters
// Setting the string value 'short-date-short-time' is similar to what is set in the object below
// dateFormatIntlOptions = {
//   day: "numeric",
//   month: "numeric",
//   year: "numeric",
//   hour: "numeric",
//   minute: "numeric"
// }

const now = Date.now(); // 1560375191812
const formattedDate = intl.formatDate(now, dateFormatIntlOptions);

console.log(formattedDate); // expected output for US English locale: "6/12/2019, 2:33 PM"

convertNumberFormatToIntlOptions(format){Intl.NumberFormatOptions}

Converts a NumberFormat to an Intl.NumberFormatOptions object.

Parameter:

format NumberFormat optional The NumberFormat to convert.

Returns:

Type	Description
Intl.NumberFormatOptions	The Intl number format options.

See also:

• FieldInfoFormat

Example:

const numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({
  places: 2,
  digitSeparator: true
});

// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters
// Setting the places and digitSeparator above is similar to what is set below
// numberFormatIntlOptions = {
//   useGrouping: true,
//   minimumFractionDigits: 2,
//   maximumFractionDigits: 2
// }

const number = 123456.789;
const formattedNumber = intl.formatNumber(number, numberFormatIntlOptions);
console.log(formattedNumber); // expected output for English locale: 123,456.79

formatDate(value, formatOptions){String}

Formats a Date or Number value to a string in the current locale.

Internally formatDate creates Intl formatter instances for the current locale. The formatters are cached using their options as a cache key. Reuse the same options objects for best performance.

Parameters:

value Date|Number The Date object, or the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC, to be formatted.

formatOptions Intl.DateTimeFormatOptions optional Date format options.

Returns:

Type	Description
String	Formatted string for the input Date value.

See also:

• FieldInfoFormat.dateFormat

Example:

const now = Date.now(); // 1560375191812
const dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time");

const formattedDate = intl.formatDate(now, dateFormatIntlOptions);

console.log(formattedDate); // expected output for English locale: "6/12/2019, 2:33 PM"

formatNumber(value, formatOptions){String}

Formats a Number value to a string in the current locale.

Internally formatNumber creates Intl formatter instances for the current locale. The formatters are cached using their options as a cache key. Reuse the same options objects for best performance.

Parameters:

value Number Number to be formatted.

formatOptions Intl.NumberFormatOptions optional Number format options.

Returns:

Type	Description
String	Formatted string for the input Number.

Examples:

// Formats a number with a fixed number of places using a digit separator
const numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({
  places: 2,
  digitSeparator: true
});

const number = 123456.789;
const formattedNumber = intl.formatNumber(123456.789, numberFormatIntlOptions);
console.log(formattedNumber); // In US English locale: 123,456.79

// Formats a number as currency, in Euros
const amount = 14;
const formattedNumber = intl.formatNumber(amount, {
  style: "currency",
  currency: "EUR",
  currencyDisplay: "symbol"
});
console.log(formattedNumber); // In for US English locale: €14.00

// Formats a number as percentage
const growth = 0.5;
const formattedNumber = intl.formatNumber(growth, {
  style: "percent"
});
console.log(formattedNumber); // In for US English locale: 50%

substitute(template, data, options){String}

Use this to substitute keys in a template string with values from the argument data. null or undefined values aren't printed in the output result.

The formatting of the values from data can be specified. By default the values will be formatted based on their native JavaScript type.

Internally substitute creates Intl formatter instances for the current locale. The formatters are cached using the options as a cache key. Reuse the same options objects for best performance.

Parameters:

template String Template string to use for substitution.

data Object Data object to be substituted.

options SubstituteOptions optional Options for determining how to substitute keys in the template string.

Returns:

Type	Description
String	The formatted string.

See also:

• Sample - Load portal items via drag and drop

Examples:

// Format a date
const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

const dateFormatOptions = intl.convertDateFormatToIntlOptions("short-date-short-time-24");

intl.substitute("Date: {time}", data, {
  format: {
    time: {
      type: "date",
      intlOptions: dateFormatOptions
    }
  }
});

// Format a number
const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

intl.substitute("Number: {value}", data, {
  format: {
    value: {
      type: "number",
      intlOptions: {
        maximumFractionDigits: 21
      }
    }
  }
});

const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

intl.substitute("Median income increased by {increasedValue} in {time:yearFormat}", data, {
  format: {
    increasedValue: {
      type: "number",
      intlOptions: {
        useGrouping: true,
        currency: "EUR",
        currencyDisplay: "symbol",
        maximumFractionDigits: 2
      }
    },
    yearFormat: {
      type: "date",
      intlOptions: {
        year: "numeric"
      }
    }
  }
});

Type Definitions

NumberFormat

The Web map definition for formatting numbers. This provides more detail about how a number value should be displayed.

Properties:

digitSeparator Boolean optional Indicates if the number should be formatted with a thousands separator. This is equivalent to useGrouping.

places Number optional Specifies the number of decimal places that should appear in the formatted number. Any places beyond this value are rounded. This is equivalent to defining minimumFractionDigits and maximumFractionDigits.

See also:

• FieldInfoFormat

• Web map specification - format

• FieldInfoFormat

SubstituteDateTimeFormatOptions

The formatting options for date values.

Properties:

type String The type of this format. The value is always "date". The value is always "date".

intlOptions Intl.DateTimeFormatOptions The date format options for the Intl.DateTimeFormat object.

See also:

• SubstituteOptions

Example:

const dateFormat = {
  type: "date",
  intlOptions: {
    year: "numeric",
    month: "numeric",
    day: "numeric",
    hour: "numeric",
    minute: "numeric"
  }
};

var data = {
  time: Date.now()
};

intl.substitute("Date: {time}", data, {
  format: {
    time: dateFormat
  }
});

SubstituteNumberFormatOptions

The formatting options for numeric values.

Properties:

type String The type of this format. The value is always "number". The value is always "number".

intlOptions Intl.NumberFormatOptions The Intl number format options for the Intl.NumberFormat object.

See also:

• SubstituteOptions

Examples:

// Formats a number with a fixed number of fraction digits
const numberFormat = {
  type: "number",
  intlOptions: {
    style: "decimal",
    useGrouping: true,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }
});

var data = {
  value: 10
};

intl.substitute("A number: {value}", data, {
  value: numberFormat
});

// Formats a number as currency, in Euros.
const currencyFormat = {
  type: "number",
  intlOptions: {
    style: "currency",
    currency: "EUR",
    currencyDisplay: "symbol"
  }
};

var data = {
  amount: 14
};

intl.substitute("Amount: {amount}", data, {
  amount: currencyFormat
});

// Formats a number as a percentage.
const percentFormat = {
  type: "number",
  intlOptions: {
    style: "percent"
  }
};

var data = {
  growth: 0.5
};

intl.substitute("Growth: {growth}", data, {
  growth: percentFormat
});

SubstituteOptions

An object to specify substitution options.

Use the format property to define the formatting for each value referenced in the string template. format is a key-value pair object. Each key can either be:

• a property of the data parameter or substitute()
• a named formatter than can be referenced in the template string.

In the following example, the time property from data will be formatted as a date with each component in numeric format.

const data = {
  time: Date.now()
};

intl.substitute("Date: {time}", data, {
  format: {
    time: {
      type: "date",
      intlOptions: {
        year: "numeric",
        month: "numeric",
        day: "numeric",
        hour: "numeric",
        minute: "numeric"
      }
    }
  }
});

The following example uses a named formatter to format the time property twice with different formatting options.

const data = {
  time: Date.now()
};

intl.substitute("In {time:monthFormat} of {time:yearFormat}", data, {
  format: {
    monthFormat: {
      type: "date",
      intlOptions: {
        month: "long"
      }
    },
    yearFormat: {
      type: "date",
      intlOptions: {
        year: "numeric"
      }
    }
  }
});

Property:

format HashMap<(SubstituteDateTimeFormatOptions|SubstituteNumberFormatOptions)> A hashmap of string keys to formatting options.

See also:

• substitute()