Cordova is a platform for building hybrid mobile applications using HTML, CSS and JavaScript.
The official documentation gives us the definition of the Cordova −
"Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies such as HTML5, CSS3, and JavaScript for crossplatform development, avoiding each mobile platform native development language. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's sensors, data, and network status."
Let us now understand the features of Cordova in brief.
This tool can be used for starting projects, building processes for different platforms, installing plugins and lot of other useful things that make the development process easier. You will learn how to use the Command Line Interface in the subsequent chapters.
Cordova offers a set of core components that every mobile application needs. These components will be used for creating base of the app so we can spend more time to implement our own logic.
Cordova offers API that will be used for implementing native mobile functions to our JavaScript app.
Cordova is licensed under the Apache License, Version 2.0. Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
We will now discuss the advantages of Cordova.
Cordova offers one platform for building hybrid mobile apps so we can develop one app that will be used on different mobile platforms – IOS, Android, Windows Phone, Amazon-fireos, blackberry, Firefox OS, Ubuntu and tizien.
It is faster to develop hybrid app then native app so Cordova can save on the development time.
Since we are using JavaScript when working with Cordova, we don't need to learn platform specific programming languages.
There are many community add-ons that can be used with Cordova, these have several libraries and frameworks, which are optimized for working with it.
Following are the limitations of Cordova.
Hybrid apps are slower than native ones so it is not optimal to use Cordova for large apps that require lots of data and functionality.
Cross browser compatibility can create lots of issues. Most of the time we are building apps for different platforms so the testing and optimizing can be time consuming since we need to cover large number of devices and operating systems.
Some plugins have compatibility issues with different devices and platforms. There are also some native APIs that are not yet supported by Cordova.
In this chapter, we will understand the Environment Setup of Cordova. To begin with the setup, we need to first install a few components. The components are listed in the following table.
S.No | Software & Description |
---|---|
1 | NodeJS and NPM NodeJS is the platform needed for Cordova development. Check out our NodeJS Environment Setup for more details. |
2 | Android SDK For Android platform, you need to have Android SDK installed on your machine. Check out Android Environment Setup for more details. |
3 | XCode For iOS platform, you need to have xCode installed on your machine. Check out iOS Environment Setup for more details |
Before we start, you need to know that we will use Windows command prompt in our tutorial.
Even if you don't use git, it should be installed since Cordova is using it for some background processes. You can download git here. After you install git, open your environment variable.
Copy the following at the end of the variable value field. This is default path of the git installation. If you installed it on a different path you should use that instead of our example code below.
;C:\Program Files (x86)\Git\bin;C:\Program Files (x86)\Git\cmd
Now you can type git in your command prompt to test if the installation is successful.
This step will download and install Cordova module globally. Open the command prompt and run the following −
C:\Users\username>npm install -g cordova
You can check the installed version by running −
C:\Users\username>cordova -v
This is everything you need to start developing the Cordova apps on Windows operating system. In our next tutorial, we will show you how to create first application.
We have understood how to install Cordova and set up the environment for it. Once everything is ready, we can create our first hybrid Cordova application.
Open the directory where you want the app to be installed in command prompt. We will create it on desktop.
C:\Users\username\Desktop>cordova create CordovaProject io.cordova.hellocordova CordovaApp
CordovaProject is the directory name where the app is created.
io.cordova.hellocordova is the default reverse domain value. You should use your own domain value if possible.
CordovaApp is the title of your app.
You need to open your project directory in the command prompt. In our example, it is the CordovaProject. You should only choose platforms that you need. To be able to use the specified platform, you need to have installed the specific platform SDK. Since we are developing on windows, we can use the following platforms. We have already installed Android SDK, so we will only install android platform for this tutorial.
C:\Users\username\Desktop\CordovaProject>cordova platform add android
There are other platforms that can be used on Windows OS.
C:\Users\username\Desktop\CordovaProject>cordova platform add wp8
C:\Users\username\Desktop\CordovaProject>cordova platform add amazon-fireos
C:\Users\username\Desktop\CordovaProject>cordova platform add windows
C:\Users\username\Desktop\CordovaProject>cordova platform add blackberry10
C:\Users\username\Desktop\CordovaProject>cordova platform add firefoxos
If you are developing on Mac, you can use −
$ cordova platform add IOS
$ cordova platform add amazon-fireos
$ cordova platform add android
$ cordova platform add blackberry10
$ cordova platform add firefoxos
You can also remove platform from your project by using −
C:\Users\username\Desktop\CordovaProject>cordova platform rm android
In this step we will build the app for a specified platform so we can run it on mobile device or emulator.
C:\Users\username\Desktop\CordovaProject>cordova build android
Now we can run our app. If you are using the default emulator you should use −
C:\Users\username\Desktop\CordovaProject>cordova emulate android
If you want to use the external emulator or real device you should use −
C:\Users\username\Desktop\CordovaProject>cordova run android
NOTE − We will use the Genymotion android emulator since it is faster and more responsive than the default one. You can find the emulator here. You can also use real device for testing by enabling USB debugging from the options and connecting it to your computer via USB cable. For some devices, you will also need to install the USB driver.
Once we run the app, it will install it on the platform we specified. If everything is finished without errors, the output should show the default start screen of the app.
In our next tutorial, we will show you how to configure the Cordova Application.
The config.xml file is the place where we can change the configuration of the app. When we created our app in the last tutorial, we set reverse domain and name. The values can be changed in the config.xml file. When we create the app, the default config file will also be created.
The following table explains configuration elements in config.xml.
S.No | Element & Details |
---|---|
1 | widget The app reverse domain value that we specified when creating the app. |
2 | name The name of the app that we specified when creating the app. |
3 | description Description for the app. |
4 | author Author of the app. |
5 | content The app's starting page. It is placed inside the www directory. |
6 | plugin The plugins that are currently installed. |
7 | access Used to control access to external domains. The default origin value is set to * which means that access is allowed to any domain. This value will not allow some specific URLs to be opened to protect information. |
8 | allow-intent Allows specific URLs to ask the app to open. For example, <allow-intent href = "tel:*" /> will allow tel: links to open the dialer. |
9 | platform The platforms for building the app. |
We can use storage API available for storing data on the client apps. This will help the usage of the app when the user is offline and it can also improve performance. Since this tutorial is for beginners, we will show you how to use local storage. In one of our later tutorials, we will show you the other plugins that can be used.
We will create four buttons in the index.html file. The buttons will be located inside the div class = "app" element.
<button id = "setLocalStorage">SET LOCAL STORAGE</button> <button id = "showLocalStorage">SHOW LOCAL STORAGE</button> <button id = "removeProjectFromLocalStorage">REMOVE PROJECT</button> <button id = "getLocalStorageByKey">GET BY KEY</button>
It will produce the following screen −
Cordova security policy doesn't allow inline events so we will add event listeners inside index.js files. We will also assign window.localStorage to a localStorage variable that we will use later.
document.getElementById("setLocalStorage").addEventListener("click", setLocalStorage); document.getElementById("showLocalStorage").addEventListener("click", showLocalStorage); document.getElementById("removeProjectFromLocalStorage").addEventListener ("click", removeProjectFromLocalStorage); document.getElementById("getLocalStorageByKey").addEventListener ("click", getLocalStorageByKey); var localStorage = window.localStorage;
Now we need to create functions that will be called when the buttons are tapped. First function is used for adding data to local storage.
function setLocalStorage() { localStorage.setItem("Name", "John"); localStorage.setItem("Job", "Developer"); localStorage.setItem("Project", "Cordova Project"); }
The next one will log the data we added to console.
function showLocalStorage() { console.log(localStorage.getItem("Name")); console.log(localStorage.getItem("Job")); console.log(localStorage.getItem("Project")); }
If we tap SET LOCAL STORAGE button, we will set three items to local storage. If we tap SHOW LOCAL STORAGE afterwards, the console will log items that we want.
Let us now create function that will delete the project from local storage.
function removeProjectFromLocalStorage() { localStorage.removeItem("Project"); }
If we click the SHOW LOCAL STORAGE button after we deleted the project, the output will show null value for the project field.
We can also get the local storage elements by using the key() method which will take the index as an argument and return the element with corresponding index value.
function getLocalStorageByKey() { console.log(localStorage.key(0)); }
Now when we tap the GET BY KEY button, the following output will be displayed.
When we use the key() method, the console will log the job instead of the name even though we passed argument 0 to retrieve the first object. This is because the local storage is storing data in alphabetical order.
The following table shows all the available local storage methods.
S.No | Methods & Details |
---|---|
1 | setItem(key, value) Used for setting the item to local storage. |
2 | getItem(key) Used for getting the item from local storage. |
3 | removeItem(key) Used for removing the item from local storage. |
4 | key(index) Used for getting the item by using the index of the item in local storage. This helps sort the items alphabetically. |
5 | length() Used for retrieving the number of items that exists in local storage. |
6 | clear() Used for removing all the key/value pairs from local storage. |
There are various events that can be used in Cordova projects. The following table shows the available events.
S.No | Events & Details |
---|---|
1 | deviceReady This event is triggered once Cordova is fully loaded. This helps to ensure that no Cordova functions are called before everything is loaded. |
2 | pause This event is triggered when the app is put into background. |
3 | resume This event is triggered when the app is returned from background. |
4 | backbutton This event is triggered when the back button is pressed. |
5 | menubutton This event is triggered when the menu button is pressed. |
6 | searchbutton This event is triggered when the Android search button is pressed. |
7 | startcallbutton This event is triggered when the start call button is pressed. |
8 | endcallbutton This event is triggered when the end call button is pressed. |
9 | volumedownbutton This event is triggered when the volume down button is pressed. |
10 | volumeupbutton This event is triggered when the volume up button is pressed. |
All of the events are used almost the same way. We should always add event listeners in our js instead of the inline event calling since the Cordova Content Security Policy doesn't allow inline Javascript. If we try to call event inline, the following error will be displayed.
The right way of working with events is by using addEventListener. We will understand how to use the volumeupbutton event through an example.
document.addEventListener("volumeupbutton", callbackFunction, false); function callbackFunction() { alert('Volume Up Button is pressed!'); }
Once we press the volume up button, the screen will display the following alert.
We should use the Android back button for app functionalities like returning to the previous screen. To implement your own functionality, we should first disable the back button that is used to exit the App.
document.addEventListener("backbutton", onBackKeyDown, false); function onBackKeyDown(e) { e.preventDefault(); alert('Back Button is Pressed!'); }
Now when we press the native Android back button, the alert will appear on the screen instead of exiting the app. This is done by using the e.preventDefault() command.
You will usually want to use Android back button for some app functionality like returning to previous screen. To be able to implement your own functionality, you first need to disable exiting the app when the back button is pressed.
document.addEventListener("backbutton", onBackKeyDown, false); function onBackKeyDown(e) { e.preventDefault(); alert('Back Button is Pressed!'); }
Now when we press the native Android back button, the alert will appear on the screen instead of exiting the app. This is done by using e.preventDefault().
Cordova Plugman is a useful command line tool for installing and managing plugins. You should use plugman if your app needs to run on one specific platform. If you want to create a cross-platform app you should use cordova-cli which will modify plugins for different platforms.
Open the command prompt window and run the following code snippet to install plugman.
C:\Users\username\Desktop\CordovaProject>npm install -g plugman
To understand how to install the Cordova plugin using plugman, we will use the Camera plugin as an example.
C:\Users\username\Desktop\CordovaProject>plugman install --platform android --project platforms\android --plugin cordova-plugin-camera plugman uninstall --platform android --project platforms\android --plugin cordova-plugin-camera
We need to consider three parameters as shown above.
--platform − platform that we are using (android, ios, amazon-fireos, wp8, blackberry10).
--project − path where the project is built. In our case, it is platforms\android directory.
--plugin − the plugin that we want to install.
If you set valid parameters, the command prompt window should display the following output.
You can use the uninstall method in similar way.
C:\Users\username\Desktop\CordovaProject>plugman uninstall --platform android --project platforms\android --plugin cordova-plugin-camera
The command prompt console will display the following output.
Plugman offers some additional methods that can be used. The methods are listed in the following table.
S.No | Method & Details |
---|---|
1 | install Used for installing Cordova plugins. |
2 | uninstall Used for uninstalling Cordova plugins. |
3 | fetch Used for copying Cordova plugin to specific location. |
4 | prepare Used for updating configuration file to help JS module support. |
5 | adduser Used for adding user account to the registry. |
6 | publish Used for publishing plugin to the registry. |
7 | unpublish Used for unpublishing plugin from the registry. |
8 | search Used for searching the plugins in the registry. |
9 | config Used for registry settings configuration. |
10 | create Used for creating custom plugin. |
11 | platform Used for adding or removing platform from the custom created plugin. |
If you are stuck, you can always use the plugman -help command. The version can be checked by using plugman -v. To search for the plugin, you can use plugman search and finally you can change the plugin registry by using the plugman config set registry command.
Since Cordova is used for cross platform development, in our subsequent chapters we will use Cordova CLI instead of Plugman for installing plugins.
This Cordova plugin is used for monitoring device's battery status. The plugin will monitor every change that happens to device's battery.
To install this plugin, we need to open the command prompt window and run the following code.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-pluginbattery-status
When you open the index.js file, you will find the onDeviceReady function. This is where the event listener should be added.
window.addEventListener("batterystatus", onBatteryStatus, false);
We will create the onBatteryStatus callback function at the bottom of the index.js file.
function onBatteryStatus(info) { alert("BATTERY STATUS: Level: " + info.level + " isPlugged: " + info.isPlugged); }
When we run the app, an alert will be triggered. At the moment, the battery is 100% charged.
When the status is changed, a new alert will be displayed. The battery status shows that the battery is now charged 99%.
If we plug in the device to the charger, the new alert will show that the isPlugged value is changed to true.
This plugin offers two additional events besides the batterystatus event. These events can be used in the same way as the batterystatus event.
S.No | Event & Details |
---|---|
1 | batterylow The event is triggered when the battery charge percentage reaches low value. This value varies with different devices. |
2 | batterycritical The event is triggered when the battery charge percentage reaches critical value. This value varies with different devices. |
This plugin is used for taking photos or using files from the image gallery.
Run the following code in the command prompt window to install this plugin.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugincamera
Now, we will create the button for calling the camera and img where the image will be displayed once taken. This will be added to index.html inside the div class = "app" element.
<button id = "cameraTakePicture">TAKE PICTURE</button> <img id = "myImage"></img>
The event listener is added inside the onDeviceReady function to ensure that Cordova is loaded before we start using it.
document.getElementById("cameraTakePicture").addEventListener ("click", cameraTakePicture);
We will create the cameraTakePicture function that is passed as a callback to our event listener. It will be fired when the button is tapped. Inside this function, we will call the navigator.camera global object provided by the plugin API. If taking picture is successful, the data will be sent to the onSuccess callback function, if not, the alert with error message will be shown. We will place this code at the bottom of index.js.
function cameraTakePicture() { navigator.camera.getPicture(onSuccess, onFail, { quality: 50, destinationType: Camera.DestinationType.DATA_URL }); function onSuccess(imageData) { var image = document.getElementById('myImage'); image.src = "data:image/jpeg;base64," + imageData; } function onFail(message) { alert('Failed because: ' + message); } }
When we run the app and press the button, native camera will be triggered.
When we take and save picture, it will be displayed on screen.
The same procedure can be used for getting image from the local file system. The only difference is the function created in the last step. You can see that the sourceType optional parameter has been added.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugincamera
<button id = "cameraGetPicture">GET PICTURE</button>
document.getElementById("cameraGetPicture").addEventListener("click", cameraGetPicture);
function cameraGetPicture() { navigator.camera.getPicture(onSuccess, onFail, { quality: 50, destinationType: Camera.DestinationType.DATA_URL, sourceType: Camera.PictureSourceType.PHOTOLIBRARY }); function onSuccess(imageURL) { var image = document.getElementById('myImage'); image.src = imageURL; } function onFail(message) { alert('Failed because: ' + message); } }
When we press the second button, the file system will open instead of the camera so we can choose the image that is to be displayed.
This plugin offers lots of optional parameters for customization.
S.No | Parameter & Details |
---|---|
1 | quality Quality of the image in the range of 0-100. Default is 50. |
2 | destinationType DATA_URL or 0 Returns base64 encoded string. FILE_URI or 1 Returns image file URI. NATIVE_URI or 2 Returns image native URI. |
3 | sourceType PHOTOLIBRARY or 0 Opens photo library. CAMERA or 1 Opens native camera. SAVEDPHOTOALBUM or 2 Opens saved photo album. |
4 | allowEdit Allows image editing. |
5 | encodingType JPEG or 0 Returns JPEG encoded image. PNG or 1 Returns PNG encoded image. |
6 | targetWidth Image scaling width in pixels. |
7 | targetHeight Image scaling height in pixels. |
8 | mediaType PICTURE or 0 Allows only picture selection. VIDEO or 1 Allows only video selection. ALLMEDIA or 2 Allows all media type selection. |
9 | correctOrientation Used for correcting orientation of the image. |
10 | saveToPhotoAlbum Used to save the image to the photo album. |
11 | popoverOptions Used for setting popover location on IOS. |
12 | cameraDirection FRONT or 0 Front camera. BACK or 1 Back camera. ALLMEDIA |
This plugin is used for accessing the contacts database of the device. In this tutorial we will show you how to create, query and delete contacts.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugincontacts
The button will be used for calling the createContact function. We will place it in the div class = "app" in index.html file.
<button id = "createContact">ADD CONTACT</button> <button id = "findContact">FIND CONTACT</button> <button id = "deleteContact">DELETE CONTACT</button>
Open index.js and copy the following code snippet into the onDeviceReady function.
document.getElementById("createContact").addEventListener("click", createContact); document.getElementById("findContact").addEventListener("click", findContact); document.getElementById("deleteContact").addEventListener("click", deleteContact);
Now, we do not have any contacts stored on the device.
Our first callback function will call the navigator.contacts.create method where we can specify the new contact data. This will create a contact and assign it to the myContact variable but it will not be stored on the device. To store it, we need to call the save method and create success and error callback functions.
function createContact() { var myContact = navigator.contacts.create({"displayName": "Test User"}); myContact.save(contactSuccess, contactError); function contactSuccess() { alert("Contact is saved!"); } function contactError(message) { alert('Failed because: ' + message); } }
When we click the ADD CONTACT button, new contact will be stored to the device contact list.
Our second callback function will query all contacts. We will use the navigator.contacts.find method. The options object has filter parameter which is used to specify the search filter. multiple = true is used since we want to return all contacts from device. The field key to search contacts by displayName since we used it when saving contact.
After the options are set, we are using find method to query contacts. The alert message will be triggered for every contact that is found.
function findContacts() { var options = new ContactFindOptions(); options.filter = ""; options.multiple = true; fields = ["displayName"]; navigator.contacts.find(fields, contactfindSuccess, contactfindError, options); function contactfindSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { alert("Display Name = " + contacts[i].displayName); } } function contactfindError(message) { alert('Failed because: ' + message); } }
When we press the FIND CONTACT button, one alert popup will be triggered since we have saved only one contact.
In this step, we will use the find method again but this time we will set different options. The options.filter is set to search that Test User which has to be deleted. After the contactfindSuccess callback function has returned the contact we want, we will delete it by using the remove method that requires its own success and error callbacks.
function deleteContact() { var options = new ContactFindOptions(); options.filter = "Test User"; options.multiple = false; fields = ["displayName"]; navigator.contacts.find(fields, contactfindSuccess, contactfindError, options); function contactfindSuccess(contacts) { var contact = contacts[0]; contact.remove(contactRemoveSuccess, contactRemoveError); function contactRemoveSuccess(contact) { alert("Contact Deleted"); } function contactRemoveError(message) { alert('Failed because: ' + message); } } function contactfindError(message) { alert('Failed because: ' + message); } }
Now, we have only one contact stored on the device. We will manually add one more to show you the deleting process.
We will now click the DELETE CONTACT button to delete the Test User. If we check the contact list again, we will see that the Test User does not exist anymore.
This plugin is used for getting information about the user’s device.
To install this plugin, we need to run the following snippet in the command prompt.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-device
We will be using this plugin the same way we used the other Cordova plugins. Let us add a button in the index.html file. This button will be used for getting information about the device.
<button id = "cordovaDevice">CORDOVA DEVICE</button>
Cordova plugins are available after the deviceready event so we will place the event listener inside the onDeviceReady function in index.js.
document.getElementById("cordovaDevice").addEventListener("click", cordovaDevice);
The following function will show how to use all possibilities the plugin provides. We will place it in index.js.
function cordovaDevice() { alert("Cordova version: " + device.cordova + "\n" + "Device model: " + device.model + "\n" + "Device platform: " + device.platform + "\n" + "Device UUID: " + device.uuid + "\n" + "Device version: " + device.version); }
When we click the CORDOVA DEVICE button, the alert will display the Cordova version, device model, platform, UUID and device version.
The Accelerometer plugin is also called the device-motion. It is used to track device motion in three dimensions.
We will install this plugin by using cordova-CLI. Type the following code in the command prompt window.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-device-motion
In this step, we will add two buttons in the index.html file. One will be used for getting the current acceleration and the other will watch for the acceleration changes.
<button id = "getAcceleration">GET ACCELERATION</button> <button id = "watchAcceleration">WATCH ACCELERATION</button>
Let us now add event listeners for our buttons to onDeviceReady function inside index.js.
document.getElementById("getAcceleration").addEventListener("click", getAcceleration); document.getElementById("watchAcceleration").addEventListener( "click", watchAcceleration);
Now, we will create two functions. The first function will be used to get the current acceleration and the second function will watch the acceleration and the information about the acceleration will be triggered every three seconds. We will also add the clearWatch function wrapped by the setTimeout function to stop watching acceleration after the specified time frame. The frequency parameter is used to trigger the callback function every three seconds.
function getAcceleration() { navigator.accelerometer.getCurrentAcceleration( accelerometerSuccess, accelerometerError); function accelerometerSuccess(acceleration) { alert('Acceleration X: ' + acceleration.x + '\n' + 'Acceleration Y: ' + acceleration.y + '\n' + 'Acceleration Z: ' + acceleration.z + '\n' + 'Timestamp: ' + acceleration.timestamp + '\n'); }; function accelerometerError() { alert('onError!'); }; } function watchAcceleration() { var accelerometerOptions = { frequency: 3000 } var watchID = navigator.accelerometer.watchAcceleration( accelerometerSuccess, accelerometerError, accelerometerOptions); function accelerometerSuccess(acceleration) { alert('Acceleration X: ' + acceleration.x + '\n' + 'Acceleration Y: ' + acceleration.y + '\n' + 'Acceleration Z: ' + acceleration.z + '\n' + 'Timestamp: ' + acceleration.timestamp + '\n'); setTimeout(function() { navigator.accelerometer.clearWatch(watchID); }, 10000); }; function accelerometerError() { alert('onError!'); }; }
Now if we press the GET ACCELERATION button, we will get the current acceleration value. If we press the WATCH ACCELERATION button, the alert will be triggered every three seconds. After third alert is shown the clearWatch function will be called and we will not get any more alerts since we set timeout to 10000 milliseconds.
Compass is used to show direction relative to geographic north cardinal point.
Open the command prompt window and run the following.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugindevice-orientation
This plugin is similar to the acceleration plugin. Let us now create two buttons in index.html.
<button id = "getOrientation">GET ORIENTATION</button> <button id = "watchOrientation">WATCH ORIENTATION</button>
Now, we will add event listeners inside the onDeviceReady function in index.js.
document.getElementById("getOrientation").addEventListener("click", getOrientation); document.getElementById("watchOrientation").addEventListener("click", watchOrientation);
We will create two functions; the first function will generate the current acceleration and the other will check on the orientation changes. You can see that we are using the frequency option again to keep a watch on changes that occur every three seconds.
function getOrientation() { navigator.compass.getCurrentHeading(compassSuccess, compassError); function compassSuccess(heading) { alert('Heading: ' + heading.magneticHeading); }; function compassError(error) { alert('CompassError: ' + error.code); }; } function watchOrientation(){ var compassOptions = { frequency: 3000 } var watchID = navigator.compass.watchHeading(compassSuccess, compassError, compassOptions); function compassSuccess(heading) { alert('Heading: ' + heading.magneticHeading); setTimeout(function() { navigator.compass.clearWatch(watchID); }, 10000); }; function compassError(error) { alert('CompassError: ' + error.code); }; }
Since the compass plugin is almost the same as the acceleration plugin, we will show you an error code this time. Some devices do not have the magnetic sensor that is needed for the compass to work. If your device doesn't have it, the following error will be displayed.
The Cordova Dialogs plugin will call the platform native dialog UI element.
Type the following command in the command prompt window to install this plugin.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-dialogs
Let us now open index.html and add four buttons, one for every type of dialog.
<button id = "dialogAlert">ALERT</button> <button id = "dialogConfirm">CONFIRM</button> <button id = "dialogPrompt">PROMPT</button> <button id = "dialogBeep">BEEP</button>
Now we will add the event listeners inside the onDeviceReady function in index.js. The listeners will call the callback function once the corresponding button is clicked.
document.getElementById("dialogAlert").addEventListener("click", dialogAlert); document.getElementById("dialogConfirm").addEventListener("click", dialogConfirm); document.getElementById("dialogPrompt").addEventListener("click", dialogPrompt); document.getElementById("dialogBeep").addEventListener("click", dialogBeep);
Since we added four event listeners, we will now create the callback functions for all of them in index.js. The first one is dialogAlert.
function dialogAlert() { var message = "I am Alert Dialog!"; var title = "ALERT"; var buttonName = "Alert Button"; navigator.notification.alert(message, alertCallback, title, buttonName); function alertCallback() { console.log("Alert is Dismissed!"); } }
If we click the ALERT button, we will get see the alert dialog box.
When we click the dialog button, the following output will be displayed on the console.
The second function we need to create is the dialogConfirm function.
function dialogConfirm() { var message = "Am I Confirm Dialog?"; var title = "CONFIRM"; var buttonLabels = "YES,NO"; navigator.notification.confirm(message, confirmCallback, title, buttonLabels); function confirmCallback(buttonIndex) { console.log("You clicked " + buttonIndex + " button!"); } }
When the CONFIRM button is pressed, the new dialog will pop up.
We will click the YES button to answer the question. The following output will be displayed on the console.
The third function is the dialogPrompt function. This allows the users to type text into the dialog input element.
function dialogPrompt() { var message = "Am I Prompt Dialog?"; var title = "PROMPT"; var buttonLabels = ["YES","NO"]; var defaultText = "Default" navigator.notification.prompt(message, promptCallback, title, buttonLabels, defaultText); function promptCallback(result) { console.log("You clicked " + result.buttonIndex + " button! \n" + "You entered " + result.input1); } }
The PROMPT button will trigger a dialog box as in the following screenshot.
In this dialog box, we have an option to type the text. We will log this text in the console, together with a button that is clicked.
The last one is the dialogBeep function. This is used for calling the audio beep notification. The times parameter will set the number of repeats for the beep signal.
function dialogBeep() { var times = 2; navigator.notification.beep(times); }
When we click the BEEP button, we will hear the notification sound twice, since the times value is set to 2.
This plugin is used for manipulating the native file system on the user's device.
We need to run the following code in the command prompt to install this plugin.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-file
In this example, we will show you how to create file, write to file, read it and delete it. For this reason, we will create four buttons in index.html. We will also add textarea wherein, the content of our file will be shown.
<button id = "createFile">CREATE FILE</button> <button id = "writeFile">WRITE FILE</button> <button id = "readFile">READ FILE</button> <button id = "removeFile">DELETE FILE</button> <textarea id = "textarea"></textarea>
We will add event listeners in index.js inside the onDeviceReady function to ensure that everything has started before the plugin is used.
document.getElementById("createFile").addEventListener("click", createFile); document.getElementById("writeFile").addEventListener("click", writeFile); document.getElementById("readFile").addEventListener("click", readFile); document.getElementById("removeFile").addEventListener("click", removeFile);
The file will be created in the apps root folder on the device. To be able to access the root folder you need to provide superuser access to your folders. In our case, the path to root folder is \data\data\com.example.hello\cache. At the moment this folder is empty.
Let us now add a function that will create the log.txt file. We will write this code in index.js and send a request to the file system. This method uses WINDOW.TEMPORARY or WINDOW.PERSISTENT. The size that will be required for storage is valued in bytes (5MB in our case).
function createFile() { var type = window.TEMPORARY; var size = 5*1024*1024; window.requestFileSystem(type, size, successCallback, errorCallback) function successCallback(fs) { fs.root.getFile('log.txt', {create: true, exclusive: true}, function(fileEntry) { alert('File creation successfull!') }, errorCallback); } function errorCallback(error) { alert("ERROR: " + error.code) } }
Now we can press the CREATE FILE button and the alert will confirm that we successfully created the file.
Now, we can check our apps root folder again and we can find our new file there.
In this step, we will write some text to our file. We will again send a request to the file system, and then create the file writer to be able to write Lorem Ipsum text that we assigned to the blob variable.
function writeFile() { var type = window.TEMPORARY; var size = 5*1024*1024; window.requestFileSystem(type, size, successCallback, errorCallback) function successCallback(fs) { fs.root.getFile('log.txt', {create: true}, function(fileEntry) { fileEntry.createWriter(function(fileWriter) { fileWriter.onwriteend = function(e) { alert('Write completed.'); }; fileWriter.onerror = function(e) { alert('Write failed: ' + e.toString()); }; var blob = new Blob(['Lorem Ipsum'], {type: 'text/plain'}); fileWriter.write(blob); }, errorCallback); }, errorCallback); } function errorCallback(error) { alert("ERROR: " + error.code) } }
After pressing the WRITE FILE button, the alert will inform us that the writing is successful as in the following screenshot.
Now we can open log.txt and see that Lorem Ipsum is written inside.
In this step, we will read the log.txt file and display it in the textarea element. We will send a request to the file system and get the file object, then we are creating reader. When the reader is loaded, we will assign the returned value to textarea.
function readFile() { var type = window.TEMPORARY; var size = 5*1024*1024; window.requestFileSystem(type, size, successCallback, errorCallback) function successCallback(fs) { fs.root.getFile('log.txt', {}, function(fileEntry) { fileEntry.file(function(file) { var reader = new FileReader(); reader.onloadend = function(e) { var txtArea = document.getElementById('textarea'); txtArea.value = this.result; }; reader.readAsText(file); }, errorCallback); }, errorCallback); } function errorCallback(error) { alert("ERROR: " + error.code) } }
When we click the READ FILE button, the text from the file will be written inside textarea.
And finally we will create function for deleting log.txt file.
function removeFile() { var type = window.TEMPORARY; var size = 5*1024*1024; window.requestFileSystem(type, size, successCallback, errorCallback) function successCallback(fs) { fs.root.getFile('log.txt', {create: false}, function(fileEntry) { fileEntry.remove(function() { alert('File removed.'); }, errorCallback); }, errorCallback); } function errorCallback(error) { alert("ERROR: " + error.code) } }
We can now press the DELETE FILE button to remove the file from the apps root folder. The alert will notify us that the delete operation is successful.
If we check the apps root folder, we will see that it is empty.
This plugin is used for uploading and downloading files.
We need to open command prompt and run the following command to install the plugin.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-file-transfer
In this chapter, we will show you how to upload and download files. Let's create two buttons in index.html
<button id = "uploadFile">UPLOAD</button> <button id = "downloadFile">DOWNLOAD</button>
Event listeners will be created in index.js inside the onDeviceReady function. We are adding click events and callback functions.
document.getElementById("uploadFile").addEventListener("click", uploadFile); document.getElementById("downloadFile").addEventListener("click", downloadFile);
This function will be used for downloading the files from server to device. We uploaded file to postimage.org to make things more simple. You will probably want to use your own server. The function is placed in index.js and will be triggered when the corresponding button is pressed. uri is the server download link and fileURI is the path to the DCIM folder on our device.
function downloadFile() { var fileTransfer = new FileTransfer(); var uri = encodeURI("http://s14.postimg.org/i8qvaxyup/bitcoin1.jpg"); var fileURL = "///storage/emulated/0/DCIM/myFile"; fileTransfer.download( uri, fileURL, function(entry) { console.log("download complete: " + entry.toURL()); }, function(error) { console.log("download error source " + error.source); console.log("download error target " + error.target); console.log("download error code" + error.code); }, false, { headers: { "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==" } } ); }
Once we press the DOWNLOAD button, the file will be downloaded from the postimg.org server to our mobile device. We can check the specified folder and see that myFile is there.
The console output will look like this −
Now let's create a function that will take the file and upload it to the server. Again, we want to simplify this as much as possible, so we will use posttestserver.com online server for testing. The uri value will be linked for posting to posttestserver.
function uploadFile() { var fileURL = "///storage/emulated/0/DCIM/myFile" var uri = encodeURI("http://posttestserver.com/post.php"); var options = new FileUploadOptions(); options.fileKey = "file"; options.fileName = fileURL.substr(fileURL.lastIndexOf('/')+1); options.mimeType = "text/plain"; var headers = {'headerParam':'headerValue'}; options.headers = headers; var ft = new FileTransfer(); ft.upload(fileURL, uri, onSuccess, onError, options); function onSuccess(r) { console.log("Code = " + r.responseCode); console.log("Response = " + r.response); console.log("Sent = " + r.bytesSent); } function onError(error) { alert("An error has occurred: Code = " + error.code); console.log("upload error source " + error.source); console.log("upload error target " + error.target); } }
Now we can press the UPLOAD button to trigger this function. We will get a console output as confirmation that the uploading was successful.
We can also check the server to make sure that the file was uploaded.
Geolocation is used for getting info about device's latitude and longitude.
We can install this plugin by typing the following code to command prompt window.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-geolocation
In this tutorial we will show you how to get current position and how to watch for changes. We first need to create buttons that will call these functions.
<button id = "getPosition">CURRENT POSITION</button> <button id = "watchPosition">WATCH POSITION</button>
Now we want to add event listeners when the device is ready. We will add the code sample below to onDeviceReady function in index.js.
document.getElementById("getPosition").addEventListener("click", getPosition); document.getElementById("watchPosition").addEventListener("click", watchPosition);
Two functions have to be created for two event listeners. One will be used for getting the current position and the other for watching the position.
function getPosition() { var options = { enableHighAccuracy: true, maximumAge: 3600000 } var watchID = navigator.geolocation.getCurrentPosition(onSuccess, onError, options); function onSuccess(position) { alert('Latitude: ' + position.coords.latitude + '\n' + 'Longitude: ' + position.coords.longitude + '\n' + 'Altitude: ' + position.coords.altitude + '\n' + 'Accuracy: ' + position.coords.accuracy + '\n' + 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' + 'Heading: ' + position.coords.heading + '\n' + 'Speed: ' + position.coords.speed + '\n' + 'Timestamp: ' + position.timestamp + '\n'); }; function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } } function watchPosition() { var options = { maximumAge: 3600000, timeout: 3000, enableHighAccuracy: true, } var watchID = navigator.geolocation.watchPosition(onSuccess, onError, options); function onSuccess(position) { alert('Latitude: ' + position.coords.latitude + '\n' + 'Longitude: ' + position.coords.longitude + '\n' + 'Altitude: ' + position.coords.altitude + '\n' + 'Accuracy: ' + position.coords.accuracy + '\n' + 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' + 'Heading: ' + position.coords.heading + '\n' + 'Speed: ' + position.coords.speed + '\n' + 'Timestamp: ' + position.timestamp + '\n'); }; function onError(error) { alert('code: ' + error.code + '\n' +'message: ' + error.message + '\n'); } }
In example above we are using two methods − getCurrentPosition and watchPosition. Both functions are using three parameters. Once we click CURRENT POSITION button, the alert will show geolocation values.
If we click WATCH POSITION button, the same alert will be triggered every three seconds. This way we can track movement changes of the user's device.
This plugin is using GPS. Sometimes it can't return the values on time and the request will return timeout error. This is why we specified enableHighAccuracy: true and maximumAge: 3600000. This means that if a request isn't completed on time, we will use the last known value instead. In our example, we are setting maximumAge to 3600000 milliseconds.
This plugin is used for getting information about users’ locale language, date and time zone, currency, etc.
Open command prompt and install the plugin by typing the following code
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-globalization
We will add several buttons to index.html to be able to call different methods that we will create later.
<button id = "getLanguage">LANGUAGE</button> <button id = "getLocaleName">LOCALE NAME</button> <button id = "getDate">DATE</button> <button id = "getCurrency">CURRENCY</button>
Event listeners will be added inside getDeviceReady function in index.js file to ensure that our app and Cordova are loaded before we start using it.
document.getElementById("getLanguage").addEventListener("click", getLanguage); document.getElementById("getLocaleName").addEventListener("click", getLocaleName); document.getElementById("getDate").addEventListener("click", getDate); document.getElementById("getCurrency").addEventListener("click", getCurrency);
The first function that we are using returns BCP 47 language tag of the client's device. We will use getPreferredLanguage method. The function has two parameters onSuccess and onError. We are adding this function in index.js.
function getLanguage() { navigator.globalization.getPreferredLanguage(onSuccess, onError); function onSuccess(language) { alert('language: ' + language.value + '\n'); } function onError(){ alert('Error getting language'); } }
Once we press the LANGUAGE button, the alert will be shown on screen.
This function returns BCP 47 tag for the client's local settings. This function is similar as the one we created before. The only difference is that we are using getLocaleName method this time.
function getLocaleName() { navigator.globalization.getLocaleName(onSuccess, onError); function onSuccess(locale) { alert('locale: ' + locale.value); } function onError(){ alert('Error getting locale'); } }
When we click the LOCALE button, the alert will show our locale tag.
This function is used for returning date according to client's locale and timezone setting. date parameter is the current date and options parameter is optional.
function getDate() { var date = new Date(); var options = { formatLength:'short', selector:'date and time' } navigator.globalization.dateToString(date, onSuccess, onError, options); function onSuccess(date) { alert('date: ' + date.value); } function onError(){ alert('Error getting dateString'); } }
We can now run the app and press DATE button to see the current date.
The last function that we will show is returning currency values according to client's device settings and ISO 4217 currency code. You can see that the concept is the same.
function getCurrency() { var currencyCode = 'EUR'; navigator.globalization.getCurrencyPattern(currencyCode, onSuccess, onError); function onSuccess(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 onError(){ alert('Error getting pattern'); } }
The CURRENCY button will trigger alert that will show users currency pattern.
This plugin offers other methods. You can see all of it in the table below.
method | parameters | details |
---|---|---|
getPreferredLanguage | onSuccess, onError | Returns client's current language. |
getLocaleName | onSuccess, onError | Returns client's current locale settings. |
dateToString | date, onSuccess, onError, options | Returns date according to client's locale and timezone. |
stringToDate | dateString, onSuccess, onError, options | Parses a date according to client's settings. |
getCurrencyPattern | currencyCode, onSuccess, onError | Returns client's currency pattern. |
getDatePattern | onSuccess, onError, options | Returns client's date pattern. |
getDateNames | onSuccess, onError, options | Returns an array of names of the months, weeks or days according to client's settings. |
isDayLightSavingsTime | date, successCallback, errorCallback | Used to determine if the daylight saving time is active according to client's time zone and calendar. |
getFirstDayOfWeek | onSuccess, onError | Returns the first day of the week according to client settings. |
numberToString | number, onSuccess, onError, options | Returns number according to client's settings. |
stringToNumber | string, onSuccess, onError, options | Parses a number according to client's settings. |
getNumberPattern | onSuccess, onError, options | Returns the number pattern according to client's settings. |
This plugin is used for opening web browser inside Cordova app.
We need to install this plugin in command prompt window before we are able to use it.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-inappbrowser
We will add one button that will be used for opening inAppBrowser window in index.html.
Now let's add event listener for our button in onDeviceReady function in index.js.
document.getElementById("openBrowser").addEventListener("click", openBrowser);
In this step we are creating function that will open browser inside our app. We are assigning it to the ref variable that we can use later to add event listeners.
function openBrowser() { var url = 'https://cordova.apache.org'; var target = '_blank'; var options = "location = yes" var ref = cordova.InAppBrowser.open(url, target, options); ref.addEventListener('loadstart', loadstartCallback); ref.addEventListener('loadstop', loadstopCallback); ref.addEventListener('loaderror', loaderrorCallback); ref.addEventListener('exit', exitCallback); function loadstartCallback(event) { console.log('Loading started: ' + event.url) } function loadstopCallback(event) { console.log('Loading finished: ' + event.url) } function loaderrorCallback(error) { console.log('Loading error: ' + error.message) } function exitCallback() { console.log('Browser is closed...') } }
If we press BROWSER button, we will see the following output on screen.
Console will also listen to events. loadstart event will fire when URL is started loading and loadstop will fire when URL is loaded. We can see it in console.
Once we close the browser, exit event will fire.
There are other possible options for InAppBrowser window. We will explain it in the table below.
S.No | option & details |
---|---|
1 | location Used to turn the browser location bar on or off. Values are yes or no. |
2 | hidden Used to hide or show inAppBrowser. Values are yes or no. |
3 | clearCache Used to clear browser cookie cache. Values are yes or no. |
4 | clearsessioncache Used to clear session cookie cache. Values are yes or no. |
5 | zoom Used to hide or show Android browser's zoom controls. Values are yes or no. |
6 | hardwareback yes to use the hardware back button to navigate back through the browser history. no to close the browser once back button is clicked. |
We can use ref (reference) variable for some other functionalities. We will show you just quick examples of it. For removing event listeners we can use −
ref.removeEventListener(eventname, callback);
For closing InAppBrowser we can use −
ref.close();
If we opened hidden window, we can show it −
ref.show();
Even JavaScript code can be injected to the InAppBrowser −
var details = "javascript/file/url" ref.executeScript(details, callback);
The same concept can be used for injecting CSS −
var details = "css/file/url" ref.inserCSS(details, callback);
Cordova media plugin is used for recording and playing audio sounds in Cordova apps.
Media plugin can be installed by running the following code in command prompt window.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-media
In this tutorial, we will create simple audio player. Let's create buttons that we need in index.html.
<button id = "playAudio">PLAY</button> <button id = "pauseAudio">PAUSE</button> <button id = "stopAudio">STOP</button> <button id = "volumeUp">VOLUME UP</button> <button id = "volumeDown">VOLUME DOWN</button>
Now we need to add event listeners for our buttons inside onDeviceReady function inside index.js.
document.getElementById("playAudio").addEventListener("click", playAudio); document.getElementById("pauseAudio").addEventListener("click", pauseAudio); document.getElementById("stopAudio").addEventListener("click", stopAudio); document.getElementById("volumeUp").addEventListener("click", volumeUp); document.getElementById("volumeDown").addEventListener("click", volumeDown);
The first function that we are going to add is playAudio. We are defining myMedia outside of the function because we want to use it in functions that are going to be added later (pause, stop, volumeUp and volumeDown). This code is placed in index.js file.
var myMedia = null; function playAudio() { var src = "/android_asset/www/audio/piano.mp3"; if(myMedia === null) { myMedia = new Media(src, onSuccess, onError); function onSuccess() { console.log("playAudio Success"); } function onError(error) { console.log("playAudio Error: " + error.code); } } myMedia.play(); }
We can click PLAY button to start the piano music from the src path.
The next functions that we need is pauseAudio and stopAudio.
function pauseAudio() { if(myMedia) { myMedia.pause(); } } function stopAudio() { if(myMedia) { myMedia.stop(); } myMedia = null; }
Now we can pause or stop the piano sound by clicking PAUSE or STOP buttons.
To set the volume, we can use setVolume method. This method takes parameter with values from 0 to 1. We will set starting value to 0.5.
var volumeValue = 0.5; function volumeUp() { if(myMedia && volumeValue < 1) { myMedia.setVolume(volumeValue += 0.1); } } function volumeDown() { if(myMedia && volumeValue > 0) { myMedia.setVolume(volumeValue -= 0.1); } }
Once we press VOLUME UP or VOLUME DOWN we can change the volume value by 0.1.
The following table shows other methods that this plugin provides.
S.No | Method & Details |
---|---|
1 | getCurrentPosition Returns current position of an audio. |
2 | getDuration Returns duration of an audio. |
3 | play Used for starting or resuming audio. |
4 | pause Used for pausing audio. |
5 | release Releases the underlying operating system's audio resources. |
6 | seekTo Used for changing position of an audio. |
7 | setVolume Used for setting volume for audio. |
8 | startRecord Start recording an audio file. |
9 | stopRecord Stop recording an audio file. |
10 | stop Stop playing an audio file. |
This plugin is used for accessing device's capture options.
To install this plugin, we will open command prompt and run the following code −
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-media-capture
Since we want to show you how to capture audio, image and video, we will create three buttons in index.html.
<button id = "audioCapture">AUDIO</button> <button id = "imageCapture">IMAGE</button> <button id = "videoCapture">VIDEO</button>
The next step is adding event listeners inside onDeviceReady in index.js.
document.getElementById("audioCapture").addEventListener("click", audioCapture); document.getElementById("imageCapture").addEventListener("click", imageCapture); document.getElementById("videoCapture").addEventListener("click", videoCapture);
The first callback function in index.js is audioCapture. To start sound recorder, we will use captureAudio method. We are using two options − limit will allow recording only one audio clip per single capture operation and duration is number of seconds of a sound clip.
function audioCapture() { var options = { limit: 1, duration: 10 }; navigator.device.capture.captureAudio(onSuccess, onError, options); function onSuccess(mediaFiles) { var i, path, len; for (i = 0, len = mediaFiles.length; i < len; i += 1) { path = mediaFiles[i].fullPath; console.log(mediaFiles); } } function onError(error) { navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); } }
When we press AUDIO button, sound recorder will open.
Console will show returned array of objects that users captured.
The function for capturing image will be the same as the last one. The only difference is that we are using captureImage method this time.
function imageCapture() { var options = { limit: 1 }; navigator.device.capture.captureImage(onSuccess, onError, options); function onSuccess(mediaFiles) { var i, path, len; for (i = 0, len = mediaFiles.length; i < len; i += 1) { path = mediaFiles[i].fullPath; console.log(mediaFiles); } } function onError(error) { navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); } }
Now we can click IMAGE button to start the camera.
When we take picture, the console will log the array with image object.
Let's repeat the same concept for capturing video. We will use videoCapture method this time.
function videoCapture() { var options = { limit: 1, duration: 10 }; navigator.device.capture.captureVideo(onSuccess, onError, options); function onSuccess(mediaFiles) { var i, path, len; for (i = 0, len = mediaFiles.length; i < len; i += 1) { path = mediaFiles[i].fullPath; console.log(mediaFiles); } } function onError(error) { navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); } }
If we press VIDEO button, the camera will open and we can record the video.
Once the video is saved, the console will return array once more. This time with video object inside.
This plugin provides information about device's network.
To install this plugin, we will open command prompt and run the following code −
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-network-information
Let's create one button in index.html that will be used for getting info about network.
<button id = "networkInfo">INFO</button>
We will add three event listeners inside onDeviceReady function in index.js. One will listen for clicks on the button we created before and the other two will listen for changes in connection status.
document.getElementById("networkInfo").addEventListener("click", networkInfo); document.addEventListener("offline", onOffline, false); document.addEventListener("online", onOnline, false);
networkInfo function will return info about current network connection once button is clicked. We are calling type method. The other functions are onOffline and onOnline. These functions are listening to the connection changes and any change will trigger the corresponding alert message.
function networkInfo() { var networkState = navigator.connection.type; var states = {}; states[Connection.UNKNOWN] = 'Unknown connection'; states[Connection.ETHERNET] = 'Ethernet connection'; states[Connection.WIFI] = 'WiFi connection'; states[Connection.CELL_2G] = 'Cell 2G connection'; states[Connection.CELL_3G] = 'Cell 3G connection'; states[Connection.CELL_4G] = 'Cell 4G connection'; states[Connection.CELL] = 'Cell generic connection'; states[Connection.NONE] = 'No network connection'; alert('Connection type: ' + states[networkState]); } function onOffline() { alert('You are now offline!'); } function onOnline() { alert('You are now online!'); }
When we start the app connected to the network, onOnline function will trigger alert.
If we press INFO button the alert will show our network state.
If we disconnect from the network, onOffline function will be called.
This plugin is used to display a splash screen on application launch.
Splash screen plugin can be installed in command prompt window by running the following code.
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-splashscreen
Adding splash screen is different from adding the other Cordova plugins. We need to open config.xml and add the following code snippets inside the widget element.
First snippet is SplashScreen. It has value property which is the name of the images in platform/android/res/drawable- folders. Cordova offers default screen.png images that we are using in this example, but you will probably want to add your own images. Important thing is to add images for portrait and landscape view and also to cover different screen sizes.
<preference name = "SplashScreen" value = "screen" />
Second snippet we need to add is SplashScreenDelay. We are setting value to 3000 to hide the splash screen after three seconds.
<preference name = "SplashScreenDelay" value = "3000" />
The last preference is optional. If value is set to true, the image will not be stretched to fit screen. If it is set to false, it will be stretched.
<preference name = "SplashMaintainAspectRatio" value = "true" />
Now when we run the app, we will see the splash screen.
This plugin is used for connecting to device's vibration functionality.
We can install this plugin in command prompt window by running the following code −
C:\Users\username\Desktop\CordovaProject>cordova plugin add cordova-plugin-vibration
Once the plugin is installed we can add buttons in index.html that will be used later to trigger the vibration.
<button id = "vibration">VIBRATION</button> <button id = "vibrationPattern">PATTERN</button>
Now we are going to add event listeners inside onDeviceReady in index.js.
document.getElementById("vibration").addEventListener("click", vibration); document.getElementById("vibrationPattern").addEventListener("click", vibrationPattern);
This plugin is very easy to use. We will create two functions.
function vibration() { var time = 3000; navigator.vibrate(time); } function vibrationPattern() { var pattern = [1000, 1000, 1000, 1000]; navigator.vibrate(pattern); }
The first function is taking time parameter. This parameter is used for setting the duration of the vibration. Device will vibrate for three seconds once we press VIBRATION button.
The second function is using pattern parameter. This array will ask device to vibrate for one second, then wait for one second, then repeat the process again.
This plugin allows us to implement whitelist policy for app's navigation. When we create a new Cordova project, the whitelist plugin is installed and implemented by default. You can open the config.xml file to see allow-intent default settings provided by Cordova.
In the simple example below we are allowing links to some external URL. This code is placed in config.xml. Navigation to file:// URLs is allowed by default.
<allow-navigation href = "http://example.com/*" />
The asterix sign, *, is used to allow navigation to multiple values. In the above example, we are allowing navigation to all sub-domains of the example.com. The same can be applied to protocol or prefix to the host.
<allow-navigation href = "*://*.example.com/*" />
There is also the allow-intent element which is used to specify which URLs are allowed to open the system. You can see in the config.xml that Cordova already allowed most of the needed links for us.
When you look inside config.xml file, there is <access origin="*" /> element. This element allows all network requests to our app via Cordova hooks. If you want to allow only specific requests, you can delete it from the config.xml and set it yourself.
The same principle is used as in previous examples.
<access origin = "http://example.com" />
This will allow all network requests from http://example.com.
You can see the current security policy for your app inside the head element in index.html.
<meta http-equiv = "Content-Security-Policy" content = "default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
This is default configuration. If you want to allow everything from the same origin and example.com, then you can use −
<meta http-equiv = "Content-Security-Policy" content = "default-src 'self' foo.com">
You can also allow everything, but restrict CSS and JavaScript to the same origin.
<meta http-equiv = "Content-Security-Policy" content = "default-src *; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'">
Since this is a beginners’ tutorial, we are recommending the default Cordova options. Once you get familiar with Cordova, you can try some different values.
Cordova is used for creating hybrid mobile apps, so you need to consider this before you choose it for your project. Below are the best practices for Cordova apps development.
This is the recommended design for all Cordova apps. SPA is using client-side router and navigation loaded on the single page (usually index.html). The routing is handled via AJAX. If you have followed our tutorials, you probably noticed that almost every Cordova plugin needs to wait until the device is ready before it can be used. SPA design will improve loading speed and overall performance.
Since Cordova is used for mobile world it is natural to use touchstart and touchend events instead of click events. The click events have 300ms delay, so the clicks don’t feel native. On the other hand, touch events aren't supported on every platform. You should take this into consideration before you decide what to use.
You should always use hardware accelerated CSS Transitions instead of JavaScript animations since they will perform better on mobile devices.
Use storage caching as much as possible. Mobile network connections are usually bad, so you should minimize network calls inside your app. You should also handle offline status of the app, since there will be times when user's devices are offline.
Most of the time the first slow part inside your app will be scrolling lists. There are couple of ways to improve scrolling performance of the app. Our recommendation is to use native scrolling. When there are lots of items in the list, you should load them partially. Use loaders when necessary.
Images can also slow the mobile app. You should use CSS image sprites whenever possible. Try to fit the images perfectly instead of scaling it.
You should avoid shadows and gradients, since they slow the rendering time of the page.
Browser's DOM is slow, so you should try to minimize DOM manipulation and number of DOM elements.
Ensure that you test your app on as many devices and operating system versions as possible. If app works flawlessly on one device, it doesn't necessary mean that it will work on some other device or platform.