{"id":1722,"date":"2015-12-01T12:30:10","date_gmt":"2015-12-01T07:00:10","guid":{"rendered":"http:\/\/ramkulkarni.com\/blog\/?p=1722"},"modified":"2015-12-01T12:30:10","modified_gmt":"2015-12-01T07:00:10","slug":"using-javascript-promises-with-cordova","status":"publish","type":"post","link":"http:\/\/ramkulkarni.com\/blog\/using-javascript-promises-with-cordova\/","title":{"rendered":"Using JavaScript Promises with Cordova"},"content":{"rendered":"

JavaScript Promises<\/h2>\n

JavaScript Promises could make asynchronous programming a bit easier. Most of the APIs of Cordova are asynchronous. So when you want to call one asynchronous API after the other, you have to nest API in the callback functions of the previous API. Many\u00a0APIs also take error handler as one of the parameter to API function. At some point the whole code could become very difficult to read and maintain.<\/p>\n

JS Promises \u00a0could make this a bit simpler. Promise is an object, which takes a function callback with two arguments, resolve and reject.\u00a0Promise represent a value that would be resolved sometime in future, it is is not already resolved or rejected. The promise can be rejected explicitly or when any JavaScript exception is thrown. See\u00a0https:\/\/promisesaplus.com\/<\/a> and\u00a0Promises on MDN<\/a>\u00a0for details on JS Promises. Advantages of Promises is realized when you need to chain multiple asynchronous calls. Promises can also be useful if you want to guarantee then a piece of code is executed only once.\u00a0Promises are executed only once.<\/p>\n

Before we see how Promises can simplify usage of Cordova APIs, let’s see a simple example of Promises. Let’s say there are three asynchronous functions and they need to be called one after the other.<\/p>\n

\n
<!DOCTYPE html><\/span>\n<html><\/span>\n\t<head><\/span>\n\t\t<title><\/span>JavaScript Promises Test<\/title><\/span>\n\t<\/head><\/span>\n\t<body><\/span>\n\t\t<script><\/span>\n\t\t\tfunction<\/span> asyncFunc1(throwError, successCallback, errorCallback) {\n\t\t\t\twindow<\/span>.setTimeout(function<\/span>(){\n\t\t\t\t\tconsole.log(\"Executed asyncFunc1\"<\/span>);\n\t\t\t\t\tif<\/span> (throwError)\n\t\t\t\t\t\terrorCallback({error:<\/span>'Error from asyncFunc1'<\/span>});\n\t\t\t\t\telse<\/span>\n\t\t\t\t\t\tsuccessCallback({retValue :<\/span> 'asyncFunc1 return value'<\/span>});\n\t\t\t\t}, 1000<\/span>);\n\t\t\t}\n\n\t\t\tfunction<\/span> asyncFunc2(throwError, successCallback, errorCallback) {\n\t\t\t\twindow<\/span>.setTimeout(function<\/span>(){\n\t\t\t\t\tconsole.log(\"Executed asyncFunc2\"<\/span>);\n\t\t\t\t\tif<\/span> (throwError)\n\t\t\t\t\t\terrorCallback({error:<\/span>'Error from asyncFunc2'<\/span>});\n\t\t\t\t\telse<\/span>\n\t\t\t\t\t\tsuccessCallback({retValue :<\/span> 'asyncFunc2 return value'<\/span>});\n\t\t\t\t}, 1000<\/span>);\n\t\t\t}\n\n\t\t\tfunction<\/span> asyncFunc3(throwError, successCallback, errorCallback) {\n\t\t\t\twindow<\/span>.setTimeout(function<\/span>(){\n\t\t\t\t\tconsole.log(\"Executed asyncFunc3\"<\/span>);\n\t\t\t\t\tif<\/span> (throwError)\n\t\t\t\t\t\terrorCallback({error:<\/span>'Error from asyncFunc3'<\/span>});\n\t\t\t\t\telse<\/span>\n\t\t\t\t\t\tsuccessCallback({retValue :<\/span> 'asyncFunc3 return value'<\/span>});\n\t\t\t\t}, 1000<\/span>);\n\t\t\t}\n\n\t\t\tfunction<\/span> genericErrorHandler (err) {\n\t\t\t\tconsole.log(\"Error : \"<\/span>, err);\n\t\t\t}\n\t\t<\/script><\/span>\n\n\t<\/body><\/span>\n<\/html><\/span><\/pre>\n<\/div>\n
Without using Promises, you would call the functions as follows –<\/p>\n
\n
asyncFunc1(false<\/span>, function<\/span>(ret1){\n \tasyncFunc2(false<\/span>, function<\/span>(ret2){\n \t\tasyncFunc3(false<\/span>, function<\/span>(ret3){\n \t\t\tconsole.log(ret3);\n \t\t}, genericErrorHandler);\n \t}, genericErrorHandler);\n}, genericErrorHandler);\n<\/pre>\n<\/div>\n
Notice nesting of function calls in the callback of previous call. This may not look too complicated in this example, but if you have large block of code in callback functions then it might become difficult to read and understand the code.<\/p>\n
Now let’s see how we can use JS Promises to call the same three async functions.\u00a0We will use PromiseJS<\/a> polyfill. Include following script –<\/p>\n
<\/p>\n
\n
<script <\/span>src=<\/span>\"https:\/\/www.promisejs.org\/polyfills\/promise-7.0.4.min.js\"<\/span>><\/script><\/span>\n<\/pre>\n<\/div>\n
Here is the code to call async functions sequentially using JS Promises –
\n<\/p>\n
\n
new<\/span> Promise(function<\/span>(resolve, reject){\n\tasyncFunc1(false<\/span>, resolve, reject);\n}).then (function<\/span>(ret1) {\n\treturn<\/span> new<\/span> Promise(function<\/span>(resolve,reject){\n\t\tasyncFunc2(false<\/span>, resolve, reject);\n\t});\n}).then (function<\/span>(ret2){\n\treturn<\/span> new<\/span> Promise(function<\/span>(resolve,reject){\n\t\tasyncFunc3(false<\/span>, resolve, reject);\n\t});\n}).then(function<\/span>(ret3) {\n\tconsole.log(ret3);\n}, genericErrorHandler);\n<\/pre>\n<\/div>\n
Notice that the error handler is handled in the last ‘then’ call. Any error occurred in any of the chained promises would be caught by this error handler. A couple of other notes about Promises –<\/p>\n
    \n
  1. As mentioned earlier, Promise is executed only once. However, you can call ‘then’ method multiple times. If the promise is already executed then appropriate callback function passed in the ‘then’ would be called – i.e. if promise was executed with success then resolve callback would be called and if error had occurred then reject callback method would be called. ‘then’ takes two arguments – the first one is success callback and the second one is error callback.<\/li>\n
  2. If you return a value from ‘then’ method that is a Promise object then the next ‘then’ method is called only after the Promise is executed. If the value returned from ‘then’ is not a Promise, the next ‘then’ method is called immediately<\/li>\n
  3. Value passed to resolved callback method (first argument to ‘then’ method) is either the value with which earlier Promise was resolved or value returned directly from the previous Promise\/’then’ method<\/li>\n<\/ol>\n
    Cordova Example<\/h2>\n
    Let’s take an example from Cordova APIs. Let’s say we want to take a picture using camera, and copy\u00a0it to applications data directory. Following async calls are involved in this example<\/p>\n
      \n
    1. Call Camera API to take picture. It will return path of the image file (which would be in temp cache folder of the application)<\/li>\n
    2. Resolve the path to get FileEntry object<\/li>\n
    3. Resolve path to application’s data directory<\/li>\n
    4. Copy the image file to application’s data directory<\/li>\n<\/ol>\n
      Here is the code snippet without using Promises –<\/p>\n
      \n
      \/\/Get picture from Camera and save to application's data folder.<\/span>\n\/\/success callback returns path of the copied image file <\/span>\nfunction<\/span> getPictureWithoutPromises(successCallback, errorCallback) {\n\t\/\/Call Camera API to get Picture<\/span>\n\tnavigator.camera.getPicture(function<\/span> (imagePath) {\n\t\t\/\/resolve the image path, to get FileEntry object<\/span>\n\t\twindow<\/span>.resolveLocalFileSystemURL(imagePath, function<\/span> (imageFileEntry) {\n\t\t\t\/\/now get path to applications data folder<\/span>\n\t\t\twindow<\/span>.resolveLocalFileSystemURL(cordova.file.dataDirectory, function<\/span> (appDataDirEntry) {\n\t\t\t\t\/\/copy image file to the data directory<\/span>\n\t\t\t\timageFileEntry.copyTo(appDataDirEntry, null<\/span>, function<\/span> (newImageFileEntry) {\n\t\t\t\t\t\/\/call success callback handler<\/span>\n\t\t\t\t\tsuccessCallback(newImageFileEntry);\n\t\t\t\t}, errorCallback);\n\t\t\t}, errorCallback);\n\t\t}, errorCallback);\n\t}, errorCallback);\n}\n<\/pre>\n<\/div>\n
      And this is how you would call this function –<\/p>\n
      \n
      getPictureWithoutPromises(function<\/span> (imageFileEntry) {\n\t\/\/set src of an <img> tag, assuming we got reference to <img> DOM element before<\/span>\n\timage.src =<\/span> imageFileEntry.toURL();\n}, function<\/span> (err) {\n\tconsole.log(\"Error : \"<\/span>, err);\n});<\/pre>\n<\/div>\n
      The same could be written using Promises as follows –
      \n<\/p>\n
      \n
      \/\/Get picture from Camera and save to application's data folder.<\/span>\n\/\/Returns a Promise, whose resolve method returns path to the copied image file <\/span>\nfunction<\/span> getPictureWithPromises() {\n\tvar<\/span> sourceImageFileEntry;\n\n\t\/\/return a Promise<\/span>\n\treturn<\/span> new<\/span> Promise(function<\/span> (returnResolve, returnReject) {\n\t\tnew<\/span> Promise(function<\/span> (resolve, reject) {\n\t\t\t\/\/Call Camera API to get Picture\t\t\t\t<\/span>\n\t\t\tnavigator.camera.getPicture(resolve, reject);\n\t\t}).then(function<\/span> (imagePath) {\n\t\t\treturn<\/span> new<\/span> Promise(function<\/span> (resolve, reject) {\n\t\t\t\t\/\/resolve the image path, to get FileEntry object<\/span>\n\t\t\t\twindow<\/span>.resolveLocalFileSystemURL(imagePath, resolve, reject);\n\t\t\t});\n\t\t}).then(function<\/span> (imageFileEntry) {\n\t\t\t\/\/save this file entry in a local variable, this will be used when copying the file\t<\/span>\n\t\t\tsourceImageFileEntry =<\/span> imageFileEntry;\n\t\t\treturn<\/span> new<\/span> Promise(function<\/span> (resolve, reject) {\n\t\t\t\t\/\/now get path to applications data folder<\/span>\n\t\t\t\twindow<\/span>.resolveLocalFileSystemURL(cordova.file.dataDirectory, resolve, reject);\n\t\t\t});\n\t\t}).then(function<\/span> (appDataDirEntry) {\n\t\t\treturn<\/span> new<\/span> Promise(function<\/span> (resolve, reject) {\n\t\t\t\t\/\/copy image file to the data directory<\/span>\n\t\t\t\tsourceImageFileEntry.copyTo(appDataDirEntry, null<\/span>, resolve, reject);\n\t\t\t});\n\t\t}).then(function<\/span> (newImageFileEntry) {\n\t\t\t\t\/\/resolve the first Promise (which is returned form this method)\t <\/span>\n\t\t\t\treturnResolve(newImageFileEntry)\n\t\t});\n\t});\n}\n<\/pre>\n<\/div>\n
      And can be called as follows –<\/p>\n
      \n
      getPictureWithPromises().then(function<\/span> (imageFileEntry) {\n\timage.src =<\/span> imageFileEntry.toURL();\n}, function<\/span> (err) {\n\tconsole.log(\"Error : \"<\/span>, err);\n});<\/pre>\n<\/div>\n
      Promises do not completely remove nested callbacks, but you can limit them to one or max two level.<\/p>\n
      -Ram Kulkarni<\/p>\n","protected":false},"excerpt":{"rendered":"
      JavaScript Promises JavaScript Promises could make asynchronous programming a bit easier. Most of the APIs of Cordova are asynchronous. So when you want to call one asynchronous API after the other, you have to nest API in the callback functions of the previous API. Many\u00a0APIs also take error handler as one of the parameter to … <\/p>\n
      Continue reading “Using JavaScript Promises with Cordova”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"Using JavaScript Promises with Cordova","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false}}},"categories":[120,20,17,1],"tags":[121,5,13,122],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p2g9O8-rM","jetpack-related-posts":[],"_links":{"self":[{"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/posts\/1722"}],"collection":[{"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/comments?post=1722"}],"version-history":[{"count":0,"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/posts\/1722\/revisions"}],"wp:attachment":[{"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/media?parent=1722"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/categories?post=1722"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/ramkulkarni.com\/blog\/wp-json\/wp\/v2\/tags?post=1722"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}