Phonegap Bridge – Globalization CIS 136 Building Mobile Apps

Globalization API Plugin: org.apache.cordova.globalization obtains information and performs operations specific to the user's locale, language, and timezone Locale: controls how numbers, dates, and times are displayed for a region Language: what the language text appears as, independently of locale settings Relevance: there is no reason a user couldn't set their language to "English" but locale to "French", so that text is displayed in English but dates, times, etc., are displayed as they are in France global scope, but not available until after the deviceready event Globalization API is available thru the navigator object

Globalization API Object Methods GlobalizationError navigator.globalization.getPreferredLanguage navigator.globalization.getLocaleName navigator.globalization.dateToString navigator.globalization.stringToDate navigator.globalization.getDatePattern navigator.globalization.getDateNames navigator.globalization.isDayLightSavingsTime navigator.globalization.getFirstDayOfWeek navigator.globalization.numberToString navigator.globalization.stringToNumber navigator.globalization.getNumberPattern navigator.globalization.getCurrencyPattern

GlobalizationError Object If there is an error in any of the globalization methods, then the errorCallback executes with a GlobalizationError object as a parameter Properties code: One of the following codes representing the error type (Number) GlobalizationError.UNKNOWN_ERROR: 0 GlobalizationError.FORMATTING_ERROR: 1 GlobalizationError.PARSING_ERROR: 2 GlobalizationError.PATTERN_ERROR: 3 message: A text message that includes the error's explanation and/or details (String)

getPreferredLanguage Syntax: navigator.globalization.getPreferredLanguage(s uccessCallback, errorCallback); Returns the BCP-47 compliant language identifier tag to the successCallback with a properties object as a parameter for example, en for English. A language tag is composed of one or more subtags separated by hyphens For example fr-CA Language tag syntax is defined by the IETF's BCP 47 standard

getPreferredLanguage example If the language is set to the en-US language, this should display a popup dialog with the text language: en-US (might also be en or US) navigator.globalization.getPreferredLanguage(s,e); function s(language) {alert('language: ' + language.value); } function e() { alert('Error getting language);

getLocaleName Syntax: navigator.globalization.getLocaleName(successC allback, errorCallback); Returns the BCP 47 compliant locale identifier setting Locale will consist of a two-letter lower case language code, two-letter upper case country code, and (unspecified) variant code, separated by a hyphen.

getLocaleName example If the language is set to the en-US language, this should display a popup dialog with the text language: en-US (might also be en or US) navigator.globalization.getLocaleName(s,e); function s(language) {alert('locale: ' + locale.value); } function e() { alert('Error getting locale);

dateToString Syntax: navigator.globalization.dateToString(date, successCallback, errorCallback, options); The inbound date parameter should be of type Date Returns a formatted date options parameter is optional, and its default values are: {formatLength:'short', selector:'date and time'} The options.formatLength can be short, medium, long, or full The options.selector can be date, time or date and time. Note: expected error code is GlobalizationError.FORMATTING_ERROR.

dateToString example If the language is set to the en-US language, this should display a popup dialog with the text similar to date: 9/25/2012 4:21PM using the default options var o = ‘{ formatLength: 'short', selector: 'date and time' }’; navigator.globalization.dateToString(new Date,s,e,o); function s(language) {alert(‘date: ' + date.value); } function e() { alert('Error getting dateString: ‘ + );

getCurrencyPattern Syntax: navigator.globalization.getCurrencyPattern(currencyCode, successCallback, errorCallback); pattern string to format and parse currency values according to the client's user preferences and ISO 4217 currency code (i.e.USD). Returns a properties object to the successCallback pattern: The currency pattern to format and parse currency values. The patterns follow Unicode Technical Standard #35. (String) code: The ISO 4217 currency code for the pattern. (String) fraction: The number of fractional digits to use when parsing and formatting currency. (Number) rounding: The rounding increment to use when parsing and formatting. (Number) decimal: The decimal symbol to use for parsing and formatting. (String) grouping: The grouping symbol to use for parsing and formatting. (String) Note: expected error code is GlobalizationError.FORMATTING_ERROR.

getCurrencyPattern example If the device is set to the en-US locale, and the selected currency is USD, this should display a popup dialog with the text similar to that shown below navigator.globalization.getCurrencyPattern('USD',success,fa il); function success (pattern) { alert('pattern: ' + pattern.pattern + '\n' + 'code: ' + pattern.code + '\n' + 'fraction: ' + pattern.fraction + '\n' + 'rounding: ' + pattern.rounding + '\n' + 'decimal: ' + pattern.decimal + '\n' + 'grouping: ' + pattern.grouping); } function fail() { alert('Error getting pattern); } ); Expected result: pattern: $#,##0.##;($#,##0.##) code: USD fraction: 2 rounding: 0 decimal: . grouping: ,

getDateNames Syntax: navigator.globalization.getDateNames(success, fail, options); Returns an array of the names of the months or days of the week, depending on the client's user preferences and calendar. The array features names starting from either the first month in the year or the first day of the week, depending on the option selected The options parameter is optional, and its default values are: {type:'wide', item:'months'} The value of options.type can be narrow or wide The value of options.item can be months or days Note: expected error code is GlobalizationError.UNKNOWN_ERROR.

getDateNames example If the device is set to the en-US locale, this example displays a series of twelve popup dialogs, one per month, with text similar to month: January var opts = “{type:’wide’, item:’months’)”; navigator.globalization.getDateNames(success,fail,opts); function success (names) { for (var i = 0; i < names.value.length; i++) { alert('month: ' + names.value[i] ); } function fail() { alert('Error getting pattern); } );

getDatePattern Syntax: navigator.globalization.getDatePattern(success, fail, options); Options: formatLength: short|full‘ selector: date and time|timezone Returns a pattern object to format and parse dates according to the client's user preferences pattern: The date and time pattern to format and parse dates. The patterns follow Unicode Technical Standard #35. (String) timezone: The abbreviated name of the time zone on the client. (String) utc_offset: The current difference in seconds between the client's time zone and coordinated universal time. (Number) dst_offset: The current daylight saving time offset in seconds between the client's non-daylight saving's time zone and the client's daylight saving's time zone. (Number) Note: expected error code is GlobalizationError.PATTERN_ERROR.

getDatePattern example If the device is set to the en-US locale, this example displays a popup dialog with text such as pattern: M/d/yyyy h:mm a: var opts = “{formatLength:’short’, selector:’date and time’)”; navigator.globalization.getDatePattern(success,fail,op ts); function success (date) { alert(‘pattern: ' + date.pattern ); } function fail() { alert('Error getting pattern); } );

getFirstDayOfWeek Syntax: navigator.globalization.getFirstDayOfWeek(success, fail); Returns the first day of the week according to the client's user preferences days of the week are numbered starting from 1, where 1 is assumed to be Sunday. Note: expected error code is GlobalizationError.UNKNOWN_ERROR.

getFirstDayOfWeek example If the device is set to the en-US locale, this example displays a popup dialog with text similar to day: 1. navigator.globalization.getFirstDayOfWeek(success,fail); function success (day) { alert(‘pattern: ' + day.value ); } function fail() { alert('Error getting day); } );

getNumberPattern Syntax: navigator.globalization.getNumberPattern(success, fail,option); Option: type: decimal|percent|currency Returns a pattern string to format and parse numbers according to the client's user preferences Properties returned are: pattern: The number pattern to format and parse numbers. The patterns follow Unicode Technical Standard #35. (String) symbol: The symbol to use when formatting and parsing, such as a percent or currency symbol. (String) fraction: The number of fractional digits to use when parsing and formatting numbers. (Number) rounding: The rounding increment to use when parsing and formatting. (Number) positive: The symbol to use for positive numbers when parsing and formatting. (String) negative: The symbol to use for negative numbers when parsing and formatting. (String) decimal: The decimal symbol to use for parsing and formatting. (String) grouping: The grouping symbol to use for parsing and formatting. (String) Note: expected error code is GlobalizationError.PATTERN_ERROR.

getNumberPattern example If the device is set to the en-US locale, this example displays a popup dialog with text similar to that shown below var o = ‘decimal’; navigator.globalization.getNumberPattern(success,fail,o); function success (pattern) { alert(‘pattern: ' + pattern.pattern ); alert(‘pattern: ' + pattern.symbol ); alert(‘pattern: ' + pattern.fraction ); alert(‘pattern: ' + pattern.rounding ); alert(‘pattern: ' + pattern.positive ); alert(‘pattern: ' + pattern.negative ); alert(‘pattern: ' + pattern.decimal ); alert(‘pattern: ' + pattern.grouping ); } function fail() { alert('Error getting pattern); } ); pattern: #,##0.### symbol: . fraction: 0 rounding: 0 positive: negative: - decimal: . grouping: ,

isDayLightSavingsTime Syntax: navigator.globalization.isDayLightSavingsTime(date, success, fail); Indicates whether daylight savings time is in effect for a given date using the client's time zone and calendar inbound parameter date should be of type Date A true value indicates that daylight savings time is in effect for the given date, and false indicates that it is not Note: expected error code is GlobalizationError.UNKNOWN_ERROR.

getNumberPattern example During the summer, and if the browser is set to a DST-enabled timezone, this should display a popup dialog with text similar to dst: true: var o = ‘decimal’; navigator.globalization.isDayLightSavingsTime(new Date(),success,fail); function success (date) { alert(‘dst: ' + date.dst ); } function fail() { alert('Error getting pattern); } );

numberToString Syntax: navigator.globalization.numberToString(number, successCallback, errorCallback, option); Returns a number formatted as a string according to the client's user preferences. option parameter is optional, and its default values are: type: decimal, percent, or currency Note: expected error code is GlobalizationError.FORMATTING_ERROR.

numberToString example If the language is set to the en-US language, this displays a popup dialog with text similar to number: 3.142: var o = “{ type: ‘decimal’}”; var num = 3.1415926; navigator.globalization.numberToString(num,s,e,o); function s(number) {alert(‘number: ' + number.value); } function e() { alert('Error getting number: ‘ + );

stringToDate Syntax: navigator.globalization.stringToDate(dateString, successCallback, errorCallback, options); Parses a date formatted as a string, according to the client's user preferences and calendar using the time zone of the client, and returns the corresponding date object Inbound dateString should be a data type String options parameter is optional, and its default values are: {formatLength:'short', selector:'date and time'} The options.formatLength can be short, medium, long, or full The options.selector can be date, time or date and time.

stringToDate (cont.) Returns the date to the success callback with a properties object with the following properties: year: The four digit year. (Number) month: The month from (0-11). (Number) day: The day from (1-31). (Number) hour: The hour from (0-23). (Number) minute: The minute from (0-59). (Number) second: The second from (0-59). (Number) millisecond: The milliseconds (from 0-999), not available on all platforms. (Number) Note: expected error code is GlobalizationError.FORMATTING_ERROR.

stringToDate example If the language is set to the en-US language, this should display a popup dialog with the text similar to month:8 day:25 year:2015 Note that the month integer is one less than the string, as the month integer represents an array index. var opt=“{selector: ‘date’}”; navigator.globalization.stringToDate(‘9/25/2015’,s,e,opt); function s(date) {alert(‘month: ' + date.month); alert(‘day: ' + date.day); alert(‘year: ' + date.year); } function e() { alert('Error getting date' );

stringToNumber Syntax: navigator.globalization.stringToNumber(string, successCallback, errorCallback, option); Parses a number formatted as a string according to the client's user preferences and returns the corresponding number. option parameter is optional, and its default values are: type: decimal, percent, or currency Note: expected error code is GlobalizationError.PARSING_ERROR.

stringToNumber example If the language is set to the en-US language, this displays a popup dialog with text similar to number: 1234.56: var o = “{ type: ‘decimal’}”; var num = ‘1234.56’; navigator.globalization.stringToNumber(str,s,e,o); function s(number) {alert(‘number: ' + number.value); } function e() { alert('Error getting number: ‘ + );