Handling Device Ready

Contrary to the instructions given in in both the Cordova documentation AND “The Definitive Guide to Angular on Mobile”, here is my hard won advice for properly handling the all important device ready event and initializing AngularJS:

• Include cordova.js as your LAST script include (not first as instructed elsewhere!)
• Handle deviceready just before </body> as shown below:

    <script>
        function handleDeviceReady() {
            console.log("handleDeviceReady running...");

            console.log("handleDeviceReady configuring StatusBar...");
            StatusBar.overlaysWebView(false);
            StatusBar.backgroundColorByHexString('#009999');
            StatusBar.show();

            console.log("handleDeviceReady OAuth.initialize...");
            OAuth.initialize('BlahBlahBlahBlah');

            console.log("handleDeviceReady angular.boostrap...");
            angular.bootstrap(document, ['list']);

            console.log("handleDeviceReady hiding splashscreen...");
            navigator.splashscreen.hide();

            console.log("handleDeviceReady checking network connection...");
            if (navigator.network.connection.type == Connection.NONE) {
                navigator.notification.alert("No Internet connection", function() {}, 'Error Loading');
            }

            console.log("handleDeviceReady complete.");
        }

        document.addEventListener('DOMContentLoaded', function() {
            console.log("Adding deviceready event listener...");
            document.addEventListener('deviceready', handleDeviceReady, false);

            console.log("Configuring jquery plugins...");
            $(document).on('click', 'a[href^=http], a[href^=https]', function(e) {
                e.preventDefault();
                var $this = $(this);
                window.open($this.attr('href'), '_blank', 'location=yes', cordova_login_token);
            });
            $('.navbar .btn-navbar').css('display', 'block');

            $('.read-more').readmore();
            $('abbr.timeago').timeago();
            $("a[href='#top']").click(function() {
                $("html, body").animate({ scrollTop: 0 }, "slow");
                return false;
            });
        }, false);
    </script>

Note the following about the above code:

• No weirdness using promises to postpone initialization of AngularJS – just call angular.bootstrap in the deviceready handler (which is attached in the DOMContentLoaded handler)!
• I’ve included initialization code for other commonly used components such as jQuery controls and OAuth (more about these below).
• I’m showing you the best way I’ve found to show and hide the status bar if you want a splash screen

OAuth for Social Logins

Like a lot of apps, Jibebuy lets you login with Facebook, Twitter, etc.. Supporting OAuth and OAuth2 is straightforward (if tedious) for a web app, but these protocols weren’t designed for mobile apps. I looked into various social auth plugins for Cordova, but the serious ones required installing native SDKs for every platform (so developers would have to install and maintain Facebook SDK for both iOS and Android, for example), and the ones I looked at didn’t always support both iOS and Android with the same API. I ended up outsourcing to OAuth.io. Unfortunately, OAuth.io doesn’t completely insulate you from the tedious details of configuring app keys, URLs, etc. for every provider, but, at least from your app’s perspective, there is a single API to deal with.

Scrolling and other Touch Issues

Much has already been written about the 300ms click delay and I don’t have anything truly new to contribute on the subject. My advice is to test whatever solution you choose carefully on all your supported devices and platforms. Fortunately, it is easy to handle touch events in AngularJS or whatever.

I wanted scrolling and toolbars to work a particular way in our main window. This ended up taking a lot of time to get working OK (still not perfect) on both iOS and Android. One important scrolling related tip for AngularJS users: Make sure you avoid AngularJS digests if you are trying to handle rapidly fired events like scrolling! I used simple jQuery to handle scrolling in JavaScript.

Resize and Orientationchange Events

On iOS under Cordova, you won’t get a resize event when the orientation changes, but you do get an orientationchange event. I’m using Twitter Bootstrap CSS for responsive layout, but I still have some images that need to be resized when the window size changes. Here is the code I ended up with (don’t hate!):

    // The block of code below can be used in any scope to call $apply when the window is resized
    var timeoutPromise = null;
    var window = angular.element($window);
    var windowWidth = 0;
    window.on('resize orientationchange', function(e) {
        // console.log('resize or orientationchange: ' + e.type);
        if (timeoutPromise != null)
            $timeout.cancel(timeoutPromise);
        timeoutPromise = $timeout(function() {
            var newWidth = window.width();
            if (!website.isiOs() && windowWidth == 0) {
                windowWidth = newWidth;
                return;
            } else if (windowWidth == newWidth) {
                return;
            } else {
                windowWidth = newWidth;
                // console.log('resize or orientationchange: broadcast');
                $rootScope.$broadcast('newWindowWidth', newWidth);
            }
        }, 250);
    });

Twitter Bootstrap / Angular Boostrap Modals

In addition to Twitter Bootstrap, I also use Angular UI Bootstrap. Both of these libraries supply a modal component for creating popups. OK, I know modal dialogs are old fashioned, but I find that sometimes, the old, simple ways still work. The modal component supplied by both libraries doesn’t work well on mobile – or should I say doesn’t work at all. Online via Google, I found a lot of possible workarounds. Some were a couple of lines of CSS and others were a couple hundred lines of JavaScript. Though I spent a lot of time on these various ideas, none of them pleased me. In the end, I hacked up the Angular UI Bootstrap modal dialog code to get what I wanted. Since the result is kind of a mess and may eventually be rendered obsolete (Twitter Bootstrap 3.0 used a similar strategy to mine for modal dialogs on mobile), I’m not posting any code. But, if you need something like this, let me know and I’ll be happy to share my hacks.

The default Cordova InAppBrowser (WebView in iOS terminology) is pretty ugly (different kinds of ugly on iOS and Android) and, besides, we needed to add a Jibebuy toolbar icon so users can save their favorite houses, cars, etc., in Jibebuy. So I decided to figure out how to customize the Cordova InAppBrowser. This required a significant dive into Objective C and Java native code.

My favorite InAppBrowser is the one included with Twitter. It is small, simple and allows you to change orientation (take that Facebook!). The Cordova InAppBrowser is implemented as a plugin. Like many plugins that offer native functionality to Cordova apps, it has different implementations for various platforms. Not all the platforms are supported, but typically, iOS and Android. The Cordova InAppBrowser plugin supports both. As with other native plugins I’ve used the customization capabilities are limited and different on different platforms. I decided that the “quick and dirty” approach was to copy and modify the plugin source code. Fortunately, I had already setup a system to apply patches to Cordova plugins, so, though changing the code is a hack, at least it is repeatable and easy to use.

As you can see in the images above, I was able to add the Jibebuy icon and popup to the browser’s toolbar. The popup is another WebView that runs the same HTML, CSS and JavaScript as our Chrome Browser Extension!

One quirk about my design is that, because the address bar is editable, Jibebuy allows “unrestricted web access”  and is tagged with “You must be at least 17 years old to download this app” on the iOS App Store. Other apps like Facebook and Twitter avoid this designation by only allowing you to open URLs input into other parts of their app – the URL in their InAppBrowser’s toolbar is read only. Personally, I think this is a silly distinction, but Apple is the gatekeeper for their walled garden! If we get questions or complaints, I can change the control to be read only (as was the default for the stock Cordova InAppBrowser).

• The 1.0 version app was “Waiting for Review” for about 7 days, then “In Review” for about 4 hours.
• The 1.1 version update was “Waiting for Review” for about 7 days, then “In Review” for about 4 minutes.

The update was approved at 1:16pm today. 5 hours later, I could it on the app store and my phone (it might have been available earlier, but I checked at 6:18pm):

• https://itunes.apple.com/us/app/jibebuy/id886393887

I didn’t get any questions or comments from Apple – just an anonymous email saying the status had changed.

Cordova/PhoneGap App Background Info

The main Jibebuy  web app is a single page web app based on AngularJS. We were able to quickly turn our web app into mobile apps for iOS and Android with Apache Cordova. (We also have a 100% native iOS app, but that is another story.) We weren’t sure if we would get approved with a Cordova based app, but you can see that we did. I studied the App Store Review Guidelines pretty carefully and I felt like we did a pretty good job hitting all the key points. The Review Guidelines incorporate the iOS Human Interface Guidelines by reference. There are a few areas, like putting a logo in the header, where we went against the advice given and a few other areas where I wasn’t 100% sure but decided to submit and see what happens.

I don’t want to give anybody the wrong idea – even though our app is Cordova based and mostly uses the same code as our responsive Angular web app, we didn’t just wrap up an existing multi-page web site. We put a lot of effort into small but not inconsequential details like scrolling, properly sizing elements for different devices and handling orientation changes to make sure we had a great mobile experience.

You must be at least 17 years old to download this app

Also of note – we are tagged with “You must be at least 17 years old to download this app” due to “Unrestricted Web Access”. When I filled out the forms on the app store, it was clear to me that this would be the case, but I didn’t know this was going to happen during development of the app. The reason for this tag is because we incorporate a web browser that lets you type URLs directly into the address bar. In contrast, the app browsers in Facebook, Twitter, etc. do not let you type URLs directly – you have to type the URL a post or tweet, then click on the link in your post.

If you want to see a Cordova app in action (on iOS or Android), feel free to download Jibebuy and create a list. It is a free service, developed by your fellow NextSpacers. You might even find it useful!

Good luck with your own efforts!