The globalization plugin can be used in order to get the user locale and language and to perform operations specific to the user's locale and time zone.
In order to use the globalization plugin in our Apache Cordova project, we need to use the following cordova plugin add command:
> cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git
In order to access the globalization demo, you can click on the Globalization list item. You will be introduced to the Globalization page. You can click on the Get Locale Name button in order to get the user's locale name or the Get Preferred Language button in order to get the user's preferred language, as shown in the following screenshot:
Getting the user's locale and preferred language
The following code snippet shows the "globalization" page:
<div data-role="page" id="globalization">
<div data-role="header">
<h1>Globalization</h1>
<a href="#" data-role="button" data-rel="back" data-icon="back">Back</a>
</div>
<div data-role="content">
<h1>Welcome to the Globalization Gallery</h1>
<p>Click the buttons below to explore globalization.</p>
<input type="button" id="getLocaleName" value="Get Locale Name"/>
<input type="button" id="getPreferredLanguage" value="Get Preferred Language"/><br/>
<div id="globInfo">
</div>
</div>
</div>As shown in the preceding "globalization" page code snippet, it contains the following:
- A page header that includes a back button
- Page content that includes a
"getLocaleName"button to get the user locale, a"getPreferredLanguage"button to get the user preferred language, and a"globInfo"div in order to display the results
The following code snippet shows the "globalization" page view controller JavaScript object that includes the event handlers of the page (globalization.js):
(function() {
var globalizationManager = GlobalizationManager.getInstance();
$(document).on("pageinit", "#globalization", function(e) {
e.preventDefault();
$("#getLocaleName").on("tap", function(e) {
e.preventDefault();
var callback = {};
callback.onSuccess = handleLocaleSuccess;
callback.onError = handleLocaleError;
globalizationManager.getLocaleName(callback);
});
$("#getPreferredLanguage").on("tap", function(e) {
e.preventDefault();
var callback = {};
callback.onSuccess = handleLangSuccess;
callback.onError = handleLangError;
globalizationManager.getPreferredLanguage(callback);
});
});
function handleLocaleSuccess(locale) {
$("#globInfo").html("Locale Name: " + locale.value + "<br/>");
}
function handleLocaleError() {
$("#globInfo").html("Unable to get Locale name<br/>");
}
function handleLangSuccess(language) {
$("#globInfo").html("Preferred language name: " + language.value + "<br/");
}
function handleLangError() {
$("#globInfo").html("Unable to get preferred language name<br/>");
}
})();As shown in the preceding code snippet, the "pageinit" event handler registers the "tap" event handler on the "getLocaleName" button. In the "tap" event handler of the "getLocaleName" button, the user locale is retrieved by calling the globalizationManager.getLocaleName() method.
The globalizationManager.getLocaleName(callback) method takes a callback object as a parameter that contains two attributes (onSuccess and onError) that refer to the following callbacks in order:
handleLocaleSuccess(locale): This callback will be called if the operation succeeds; it receives a locale object that represents the user's current locale as a parameter. In the success callback, the locale value is displayed in the"globInfo"div.handleLocaleError(): This callback will be called if the operation fails.
The "pageinit" event handler also registers the "tap" event handler on the "getPreferredLanguage" button. In the "tap" event handler of the "getPreferredLanguage" button, the user's preferred language is retrieved by calling the globalizationManager.getPreferredLanguage() method.
The globalizationManager.getPreferredLanguage(callback) method takes a callback object as a parameter that contains two attributes (onSuccess and onError) that refer to the following callbacks in order:
handleLangSuccess(language): This callback will be called if the operation succeeds; it receives a language object that represents the user's preferred language as a parameter. In the success callback, the preferred language value is displayed in the"globInfo"div.handleLangError(): This callback will be called if the operation fails.
The following code snippet shows the globalization manager JavaScript object that interacts with the Apache Cordova Globalization API (GlobalizationManager.js):
var GlobalizationManager = (function () {
var instance;
function createObject() {
return {
getLocaleName: function (callback) {
navigator.globalization.getLocaleName(callback.onSuccess, callback.onError);
},
getPreferredLanguage: function (callback) {
navigator.globalization.getPreferredLanguage(callback.onSuccess,
callback.onError);
}
};
};
return {
getInstance: function () {
if (!instance) {
instance = createObject();
}
return instance;
}
};
})();As shown, GlobalizationManager is a singleton object that has two methods as highlighted in the preceding code. The first one is getLocaleName(callback), which uses the Cordova navigator.globalization.getLocaleName() method in order to retrieve the user's current locale.
The navigator.globalization.getLocaleName(successCallback, errorCallback) method has the following parameters:
successCallback: This represents the successful callback that will be called when the operation succeeds. It receives a locale object that holds the current locale information as a parameter. InGlobalizationManager,sucessCallbackis set tocallback.onSuccess.errorCallback: This represents the error callback that will be called when the operation fails. It receives aGlobalizationErrorobject that holds the error information (the code that represents the error code and the message that represents the error message) as a parameter. InGlobalizationManager,errorCallbackis set tocallback.onError.
The second method is getPreferredLanguage(callback) that uses the Cordova navigator.globalization.getPreferredLanguage() method in order to retrieve the user's preferred language.
The navigator.globalization.getPreferredLanguage(successCallback, errorCallback) method has the following parameters:
successCallback: This represents the successful callback that will be called when the operation succeeds. It receives alanguageobject that holds the user's preferred language information as a parameter. InGlobalizationManager,sucessCallbackis set tocallback.onSuccess.errorCallback: This represents the error callback that will be called when the operation fails. It receives aGlobalizationErrorobject that holds the error information (the code that represents the error code and the message that represents the error message). InGlobalizationManager,errorCallbackis set tocallback.onError.Tip
The
navigator.globalizationobject has more methods that you can check out in the Apache Cordova documentation at https://github.com/apache/cordova-plugin-globalization/blob/master/doc/index.md.
We are now done with the globalization functionality in the Cordova Exhibition app.