Showing posts with label mobile. Show all posts
Showing posts with label mobile. Show all posts

Thursday, July 25, 2013

PhoneGap 3.0

PhoneGap 3.0 was released at PhoneGap day in Portland, OR last week. There are some great changes with this new release. Historically PhoneGap and Cordova, the open source project behind PhoneGap, were almost identical. This has changed with the release of 3.0.

Prior to 3.0, PhoneGap was distributed as an archive which was downloaded and unzipped to install. Now, both PhoneGap and Cordova are distributed as command line tools, which are installed via the node.js package manager, npm. Both Cordova and PhoneGap can be installed on your machine at the same time.

$ npm install phonegap -g
$ npm install cordova -g

The command line tools provide scripts to create projects, add platforms (iOS, Android, BlackBerry, Windows Phone, etc), compile and deploy projects. The new structure makes it easier to support multiple platforms with one project.

$ cordova create hello com.example.hello Hello
$ cd hello
$ cordova platform add ios
$ cordova platform add android
$ cordova emulate

With 3.0, the Cordova distribution provides the core functionality to embed a webview (browser) into a native application. Cordova is distributed without any of the plugins installed. This allows you to only install the functionality you need, simplifies your code base, and reduces the amount of code in your app.

To use the Camera APIs, we'd install the camera plugin.

$ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git

Raymond Camden's blog post about Cordova 3.0 for a list of core plugins.

PhoneGap is a distribution of Cordova, similar to how Safari and Chrome are based on Webkit. The PhoneGap distribution of Cordova come with all of the core plugins installed. Additionally the PhoneGap command line adds features like PhoneGap build support. If you don't have a native SDK installed, the compiling the project can be delegated to PhoneGap Build.

$ phonegap create example
$ cd example
$ phonegap run wp7

Overall these are great changes for PhoneGap, but may require a changes to your workflow. The payoff is that it's easier to create projects, manage plugins, and support multiple platforms.

Thursday, April 25, 2013

Setting Realistic Expectations For Mobile App Development

This article was originally seen in the May issue of SmartCEO. It was written by Mike Rappaport, CEO of Chariot Solutions.

One common misconception about mobile application development is that it's much easier and less expensive than traditional software creation.  We've all heard stories about an app that was developed overnight, released in the app store, with the app quickly becoming a big success. This is usually not the case.  In reality, developing a mobile solution is sometimes more costly and difficult to implement for most businesses.

Since mobile applications are delivered on smaller screens and tend to have a more focused purpose, the thought is that they should be less expensive to develop than traditional applications. So why isn't that the case?

The main reason is that mobile application development still needs to adhere to the same processes as traditional software development. All software development should include planning, requirements definition, design, development, testing, delivery and support.  Along with an effective development process, delivering a quality solution requires having the right people in the right roles.

Since mobile applications have a more focused purpose than traditional applications, it is even more important that business, creative and development resources work together to clearly define and deliver a successful application.

Moreover, mobile development faces additional challenges that most traditional applications may not experience.  The most significant challenges include: variety of devices, user interface paradigm shifts, network connectivity, testing and distribution.

Mobile devices come in a variety of sizes, shapes, and platforms.  The type of devices to be supported will have a direct impact on the cost of development.  The major platforms are iOS (iPhone and iPad) and Android. But what if the user base includes Windows Phone or BlackBerry? What about tablets versus phones? Even within tablets or phones, device sizes can vary from a design, development and testing perspective.

User interfaces on mobile devices rely on the user touching a small screen with their finger or thumb.  This is a very different experience from traditional applications.  This not only forces designers to rethink how users interact with applications, but it requires a design that is intuitive.  These designs also need to adapt to varying screen sizes and take into account the size of a finger as opposed to the point of a cursor.  A poorly designed (yet typical) web form in a traditional application might include 15 or more fields with descriptions on what acceptable values might be.

How does that fit on a 3.5 inch screen?  Challenges like this require more creative solutions, which subsequently have a direct impact on cost.

Imagine entering 15 fiels of data using thumbs, only to find that the network suddenly became unavailable during the submission.  How does the application handle that? As with traditional applications, data integrity and security are a major concern on mobile devices. However, network availability is much more variable on mobile devices.  Also, data can be more vulnerable on mobile devices, simply due to the fact that devices are mobile. Accessing and handling mobile data introduces additional complexity into the design and implementation of mobile applications.

As features are developed, testing of mobile applications becomes even more important.  How a touch-based application looks, feels and reacts can vary significantly from device to device.  It is critical to get the applications deployed onto devices and in the hands of users early and often.  Depending on the size of the application, this can lead to longer testing cycles.

Finally, once development is complete, it must be distributed.  This process varies from platform to platform.  There may be additional effort required to prepare the application for submission to an App Store. The time for submission and potential rejection need to be accounted for when planning the project.

The bottom line is that developing mobile applications is much like developing software for other platforms, with some additional complexities.  But the recipe for success is the same: It takes the right people and an effective process to be successful.  When all of this is done properly, it has been proven that mobile applications have the ability to dramatically improve, and in some cases transform businesses.  Business leaders need to understand that though the cost of mobile application development may be high, the ROI can be much higher.

Wednesday, March 13, 2013

Take (and Manipulate!) a Photo with a Web Page

So not that long ago, if you wanted an app to take a photo, it had to be a native app -- such as a Windows/Mac app or a native mobile application.  But HTML5 has brought a number of new APIs that allow not only taking photos, but analyzing and manipulating them all within a browser.

Sadly, there is still inconsistent support for these features across browsers (both desktop and mobile).  So in practice, the best approach may be to target the APIs supported by iOS 6, which is more or less the minimal feature set across browsers that support any of this at all.

The three pieces we'll need are:
  • The Canvas
  • File I/O
  • Changes to the File Upload input and Media Capture
    • Note that Media Capture has been superceded by getUserMedia (more info) but we don't use that here because iOS doesn't support getUserMedia yet

The Canvas is a space on the page to draw into, using either 2-D or 3-D APIs.  Conveniently, it also lets you draw images into it, inspect and alter the pixel data, and export its content as an image. Canvas is supported by IE 9 and modern versions of Firefox, WebKit/Safari/iOS 6, Opera, and Chrome.  However, not all browsers support 3-D (via WebGL), and browsers don't generally support ALL of the Canvas spec (which has continued to evolve even after initial browser support).  Still, the parts we need are supported across browsers.

The additional "accept" and "capture" attributes on the file upload input element let us specify that the user should be able to select an image file, getting it from an attached camera if possible.  Crucially, on iOS you are given the option to select a photo from the photo library or take a photo on the spot (though some desktop browsers only let you browse for an image file, even if a Webcam is attached). Then the "files" property on the input element lets us access the selected files (unfortunately, not supported in IE < 10).

So the formula for taking and manipulating a photo is:
  1. Configure a file input using the new attributes
  2. When an image file is selected (or photo taken), access the image file
  3. Check the image EXIF data for rotation using File I/O
  4. Decide what size to scale the image to (if needed)
  5. Configure a Canvas for the selected image dimensions
  6. Draw the image to the Canvas, rotating and scaling as appropriate
  7. Access and manipulate the pixel data for the Canvas
  8. Write the pixel data back to the Canvas
  9. Export the image on the Canvas as an image file

Taking these one step at a time (and note that I use jQuery for convenience, but it is not needed for this to work):

1. Configure a file input using the new attributes

There are two ways to configure the input (and it makes no difference to desktop browsers). An input configured like this will prompt the user to take a photo or select a saved impage on either iOS or Android:
<input type="file" id="PhotoPicker"
       accept="image/*" />
With the additional capture="camera" attribute, Android goes directly to the camera without giving the option to use a saved photo (though the iOS behavior is the same):
<input type="file" id="PhotoPicker"
       accept="image/*" capture="camera" />
Note that if you don't like the default appearance, you can conceal the input widget and connect a button or link (styled any way you like) to activate it.  The input doesn't work if set to display: 'none', but we can put it inside a div of size 0 to effectively hide it:
<div style="width: 0; height: 0; overflow: hidden;">
    <input type="file" id="PhotoPicker" 
           accept="image/*" capture="camera" />
</div>
<button class="lovely" id="PhotoButton">1. Select Photo</button>
$('#PhotoButton').click(function() {
    $('#PhotoPicker').trigger('click');
    return false;
});

2. When an image file is selected (or photo taken), access the image file

We just use the new files property on the input:
$('#PhotoPicker').on('change', function(e) {
    e.preventDefault();
    if(this.files.length === 0) return;
    var imageFile = this.files[0];
    ...
});

3. Check the image EXIF data for rotation using File I/O:

All images may have a rotation recorded by the camera, such that no matter how the camera was oriented when the photo was taken, the image can be displayed appropriately on screen.  In particular, an iPad considers the landscape orientation to be normal (though it can still be upside-down), and the portrait orientation takes photos with a 90 degree rotation.  The EXIF header in an image records this rotation, so we can read it in order to display the image appropriately.

This part uses two open source (MPL) EXIF-reading scripts:
<script src="http://www.nihilogic.dk/labs/exif/exif.js"
       type="text/javascript"></script>
<script src="http://www.nihilogic.dk/labs/binaryajax/binaryajax.js"
       type="text/javascript"></script>
Then we use the new File API to read the image data (and there's a nice image here describing the EXIF Orientation codes):
var width;
var height;
var binaryReader = new FileReader();
binaryReader.onloadend=function(d) {
    var exif, transform = "none";
    exif=EXIF.readFromBinaryFile(createBinaryFile(d.target.result));

    if(exif.Orientation === 8) {
        width = img.height;
        height = img.width;
        transform = "left";
    } else if(exif.Orientation === 6) {
        width = img.height;
        height = img.width;
        transform = "right";
    }
    ...
};

binaryReader.readAsArrayBuffer(imageFile);

4. Decide what size to scale the image to (if needed)

If you want to limit the size of the image, you can scale the height and width accordingly. With mobile devices with high-resolution cameras, this may be necessary to limit memory usage:
var MAX_WIDTH = 1024;
var MAX_HEIGHT = 768;
if (width/MAX_WIDTH > height/MAX_HEIGHT) {
    if (width > MAX_WIDTH) {
        height *= MAX_WIDTH / width;
        width = MAX_WIDTH;
    }
} else {
    if (height > MAX_HEIGHT) {
        width *= MAX_HEIGHT / height;
        height = MAX_HEIGHT;
    }
}

5. Configure a Canvas for the selected image dimensions

If the canvas is on the page, you can just grab it:
var canvas = $('#PhotoEdit')[0];
Otherwise, you can use an offscreen canvas:
var canvas = document.createElement('canvas');
And then size it accordingly:
canvas.width = width;
canvas.height = height;

6. Draw the image to the Canvas, rotating and scaling as appropriate

In order to draw the image to a Canvas, first we have to load it in an <img />, and a convenient way is to create a URL to assign as the img.src from the selected file (using part of the File API):
var img = new Image();
var url = window.URL ? window.URL : window.webkitURL;
img.src = url.createObjectURL(imageFile);
img.onload = function(e) {
    url.revokeObjectURL(this.src);
    ...
};
Then inside the onload handler, we can draw the image to the canvas. (In practice, I put most of the logic we're discussing inside the onload handler.) A transformation matrix on the context handles rotating the image (if needed) and shifting it back into the viewable area.
var ctx = canvas.getContext("2d");
ctx.fillStyle = 'white';
ctx.fillRect(0, 0, 700, 600);
if(transform === 'left') {
    ctx.setTransform(0, -1, 1, 0, 0, height);
    ctx.drawImage(img, 0, 0, height, width);
} else if(transform === 'right') {
    ctx.setTransform(0, 1, -1, 0, width, 0);
    ctx.drawImage(img, 0, 0, height, width);
} else if(transform === 'flip') {
    ctx.setTransform(1, 0, 0, -1, 0, height);
    ctx.drawImage(img, 0, 0, width, height);
} else {
    ctx.setTransform(1, 0, 0, 1, 0, 0);
    ctx.drawImage(img, 0, 0, width, height);
}
ctx.setTransform(1, 0, 0, 1, 0, 0);

7. Access and manipulate the pixel data for the Canvas

The getImageData method returns an array of pixel data, with one byte each for red, green, blue, and alpha. This example applies a "green screen" effect, setting pixels to transparent (alpha = 0) if they are mainly green.
var pixels = ctx.getImageData(0, 0, canvas.width, canvas.height);
var r, g, b, i;
for (var py = 0; py < pixels.height; py += 1) {
    for (var px = 0; px < pixels.width; px += 1) {
        i = (py*pixels.width + px)*4;
        r = pixels.data[i];
        g = pixels.data[i+1];
        b = pixels.data[i+2];
        if(g > 100 && g > r*1.35 && g > b*1.6) pixels.data[i+3] = 0;
    }
}
There are of course other possibilities for filtering the image.

8. Write the pixel data back to the Canvas

Then we use putImageData to write the array of pixel data back to the canvas.
ctx.putImageData(pixels, 0, 0);

9. Export the image on the Canvas as an image file

Finally, the whole content of the canvas can be exported as an image. There may be a way to do this through the browser (in Firefox, for instance, right-clicking on any Canvas lets you view it as an image), but there is a canvas API call as well. Every browser supports saving the image as a PNG, and some may support other formats:
var data = canvas.toDataURL('image/png');
The resulting data URL looks like this:
data:image/png;base64,...
Where the "..." is the base 64 encoded version of the binary image file. So you can, for instance, upload the data URL to a server as a form field, and the server can strip off the data:image/png;base64, prefix and base 64 decode the rest and save it to a file like mycanvas.png.

Summary

So there you have it -- a Web page that takes a photograph, scales and orients it as appropriate, processes the image as desired, and then displays it to the user and/or uploads it to a server.
Unfortunately, there is not yet a way to present a "Save As" dialog to the user to save the file directly to their local disk -- the FileSystem and FileWriter APIs are not widely supported across browsers. But you can of course upload the image to the server and then redirect the user to a server URL to save it...

Consolidated Sample Code

Here's a single page with a working example using the code we've gone through here.

You can also use this sample image to see the green screen replacement effect.

Platform Support

Bold entries work fully:

Desktop Browsers:
  • Firefox 18
  • Safari 6
  • Chrome 25
  • IE 10
  • IE 9 (does not support getting selected files from file input)

Mobile Browsers:
  • iOS 6
  • iOS 5 (file input doesn't work)
  • BlackBerry 10
  • Android 4.1 (built-in browser)
  • Android 4.1 with Chrome from Play store
  • Android 2 (native browser; does not take photo)
  • Windows Phone 8 (file input doesn't work)
  • Surface RT (doesn't work)

Thursday, November 15, 2012

Installing PhoneGap Plugins with pluginstall

Phonegap applications can be extended with plugins to add additional functionality. Historically, installing plugins meant copying a bunch of files into the correct places in your project.

Andrew Lunny wrote the Cordova Plugin Specification and pluginstall. Pluginstall is a tool that automates the installation of plugins which conform to the plugin specification.

In addition to demonstrating pluginstall, we’ll also use the PhoneGap create script to make a new project. The cordova build scripts will be used for compiling and installing the binary. Using these tools it’s possible to develop PhoneGap apps with a text editor, instead of an IDE.

Prerequisites

I’ll assume that you have Phonegap 2.2.0 and the Android SDK installed.

Pluginstall requires node.js and is installed through npm. If you’re on a mac and use homebrew, install node and npm with brew install node.

Setup

Install pluginstall

$ npm install -g pluginstall

Create a new Android project using the PhoneGap create script. Create takes the new project path, package name and activity name as arguments.

$ cd /usr/local/phonegap-2.2.0/lib/android
$ ./bin/create ~/foo com.example.foo Foo

The create script built a new PhoneGap project in directory ~/foo. Inside the project there is a cordova directory with some command line tools.

Let’s ensure the generated project works before we modify anything. Start the emulator.

$ cd ~/foo
$ corodova/emulate

Patiently wait for the emulator to start. Unlock the screen and keep the emulator running. Compile, build, install, and launch your app.

$ cordova/BOOM

The application should launch and say “Device is ready”.

Install the plugin

Get a local copy of the Child Browser Plugin.

$ cd /tmp
$ git clone git://github.com/alunny/ChildBrowser.git

Install the plugin using pluginstall. Pluginstall takes the platform, project directory and plugin directory as arguments.

$ pluginstall android ~/foo /tmp/ChildBrowser

The Child Browser plugin is now installed. Pluginstall used to the information in the plugin.xml manifest to update the project. It added an Activity to the Android manifest, listed the plugin in config.xml, added java source code, and added javascript code and images to our project.

Write some code to use the plugin

Edit ~/foo/assets/www/index.html

Include the javascript after cordova.js

<script type="text/javascript" src="cordova-2.2.0.js"></script>
<script type="text/javascript" src="childbrowser.js"></script>
<script type="text/javascript" src="js/index.js"></script>

Edit ~/foo/assets/www/js/index.js

In onDeviceReady, add a call that will open a web page in the Child Browser after 3 seconds

onDeviceReady: function() {
    app.receivedEvent('deviceready');
    setTimeout( function() {
        window.plugins.childBrowser.showWebPage(
            'http://phonegap.com', { showLocationBar: true }
        );
    }, 3000 );        
},

Compile, build, install, and launch your app into the running emulator.

$ cordova/BOOM

The sample application should run and open http://phonegap.com in the Child Browser Plugin.

Tuesday, August 14, 2012

Going mobile? The key to any successful project is asking tough questions before you write code

The following is an article written by Don Coleman, Director of Mobile Development, which was originally published in the July issue of NJ Tech News.


About half of U.S. businesses will be in the mobile market by the end of 2012, according to a recent survey by Robert Half Technology (“Mad for Mobile.” New Jersey TechNews, April 2012). Nearly a quarter of the CIOs surveyed said they planned to develop a mobile application for the first time this year. The mobile boom is in full swing. Developing mobile apps can be scary and exciting, especially for managers who must make difficult business decisions in a rapidly changing technology landscape. Asking tough questions before you begin mobile development can save a lot of headaches down the road.

Are you focused?
It’s a good strategy to kick off a project with some blue-sky brainstorming. Sometimes ignoring reality is the best way to get all the ideas on the table. But the hard part is taking your big ideas and breaking them down into much smaller ideas that you can actually execute.

Do you have a clear idea of what you’re going to build? There is a wide spectrum of possibilities. You could be building a mobile version of your website. You could be building a task-specific app for clients or customers. Perhaps you are building a set of tools to help your employees work smarter and more efficiently.

Make sure you are not trying to do too much. Often it’s a good idea to start with the minimum number of features you need to satisfy your users. You can always add features later.

Probably the biggest thing to keep in mind is this: it’s not an effective use of resources to go mobile just for the sake of it. The rush to mobile now feels a bit like the dot com boom in the late 90s—building websites just to build websites. Be thoughtful. Focus.

Have you considered your audience?
This might seem like an obvious one, but managers and developers often make assumptions without really understanding their users.

If you are building something for your customers, do you know what they want or need? What is you target market? Do you have any studies to back this up? What devices do your users have? Android and iPhone are the most popular, but you might also have to consider other devices, such as the Blackberry or Windows Phone.

It’s also important to be realistic about how much time your customers will spend using your app. Some product managers have this fantasy that they will hold a user’s attention for an hour and a half. Try five minutes.


If you are building tools for your employees, do you understand their workflow? Do you know what kind of hardware they are using? Does the tool need to work offline and online? You want to build something that your employees will easily (and willingly) adopt. It’s important to understand how these mobile tools will be integrated with other software and hardware systems in your company.

Also, don’t forget about the bigger picture for your users. How are you making their lives better or easier? In addition to solving problems and meeting needs, you might consider ways to bring a little fun into their mobile experience. Create something that delights them.

Is your team ready?
This is a tough question, in part because it may force you to consider longer-term business strategies. Is your mobile project a one-time endeavor or do you intend to make mobile development part of your company’s skillset? Is it better to hire someone to build the app for you? Or are you willing to spend time and money training your existing team?

If you have good software developers they can become mobile developers. A consultant can help you plan the project and get your team up to speed. This could be a good strategy if you have developers willing and excited to learn. If your developers aren’t willing and excited to learn new technologies, you have much bigger problems.

Which technologies will you use?
In some ways, choosing technologies is the easy part—easier, at least, than understanding your users and getting developers up to speed. It’s also easy to get into the trap of using shiny, new, cool tools without putting people first.

The first decision you’ll have to make is whether to develop a native app or a web app. With a native app—for instance, one developed specifically for the iPhone or Android platforms—you can easily access each phone’s built-in devices, like the camera, microphone, and file system.

If you are going to build native applications for multiple platforms, start with one platform first, instead of trying to develop on multiple platforms in parallel. Your applications won't launch at the same time, but you can take what you learned on the first platform and apply it to the others.

The mobile web allows you to build applications that are not platform specific and can run in the browser on any phone. But browser capabilities vary across devices. Geolocation support is good. Camera support exists in newer Android and Blackberry but is unavailable on the iPhone.

One solution is to use a framework like PhoneGap that will allow you to build cross-platform native apps using HTML5. PhoneGap provides access to device features (camera and file system) that are not yet available in all web browsers. PhoneGap applications are packaged like native apps and delivered to users through the app stores.


The good news is that the line between web apps and native apps is blurring, and a year from now this distinction might not be a sticking point.

How much are you willing to invest in the project?
Obviously, developer and designer time will be the most expensive resource. All of the plumbing around the project—planning, marketing, and managing—can also add up. Building custom software is expensive, and your first mobile project could be more expensive than you think, especially if you have to train your team. The scope of the project and your vision for your business will likely determine the cost of going mobile.

A consultant could set you on a good path, but only if you do your legwork first. Although there’s no silver bullet here, asking tough questions before you dive in could lead to a more successful mobile app, one that makes your users happy and won’t break the bank.



Bio: Don Coleman, director of consulting at Chariot Solutions, helps businesses put together clear roadmaps for mobile development. He loves equally solving interesting technical problems and making businesses work better.

Tuesday, August 7, 2012

Android Unit Testing With Robolectric

Are you interested in adding Robolectric to your development process? Here's a quick introduction to the most common types of test cases and some best practices to consider when deciding your testing strategy.

I've created two example apps for your reference. The first is a glorified Hello World and the other is a simple animation app. If you are unfamiliar with Robolectric, I'd start with my introductory blog that details how to integrate IntelliJ, Robolectric, and Maven into your project.

What To Test

You should focus your unit testing on business logic, basic view validation, and functionality. You can validate certain requirements very well with unit testing (e.g. "when I click this bell image, it whistles" or "all activities have a logo on the screen").

Here are some common examples:
  • Ensure the activity and view elements are not null.
  • Ensure expected view elements are visibile on the screen.
  • Ensure that the proper resources are used for view elements.
  • Ensure items are hidden when expected.
  • Ensure that your intent starts the correct thing.
  • Ensure that fragments are present.

What Not To Test

I don't recommend investing much time in verifying less important styling details and XML attributes. Your user interface is likely to change many times a week, but typically the basic view elements and their behavior remain the same. If you updated a test each time a button had new padding, that would get very tedious indeed!

Example: The app logo is 250dp high with a proportional width, the file name is "main_logo.png", it has a 20dp left margin and 12dp right margin, has a content description of "Text," and is centered vertically on every screen.

You are likely able to test all of the attributes above (I haven't tried), but your time is best spent on items that are most important to the business. From this example, likely the most bang for your buck will come from testing that the proper image is used and making sure that it appears on all expected screens.

Returns start diminishing pretty quickly when you verify every possible XML attribute - unless that detail has an important business outcome for your app. Many of the attributes you don't test can be caught by designers, quality assurance, business, product, and/or the engineers. A better stategy is to sweep the app near deployment with a designer to make sure the app appears as expected on a wide range of devices.

Best Practices

  • Simplify your architecture. As with most object oriented realms, attempt to simplify the architecture as much as possible. Do this by creating abstract or base objects or interfaces. This way you can test shared behavior in one place instead of several, which simplifies tests and reduces code duplication.
  • Mock/stub functionality. Often we want to ensure that a certain action was performed but not actually run the code. To do this, you create a test class which extends the class under test and override/mock out/track that a particular function was called. For example, if you want a particular click to make an API call, there is no need to make the actual call (since this would be an integration level test). You can use this strategy to track that the function that invokes the call has been called, but avoid making the actual call. This is also helpful when an operation crashes the unit testing framework (e.g. specialty library that causes funky side effects), doesn't play nice, or is otherwise unnecessary to invoke directly.
  • Create a custom test runner. Create a helper test runner to gives your entire unit test suite access to handy functionality. My simplest version includes string, drawable, and color resource fetching as well as view visibility helper functions. I also add a helper function to start fragments without a hosting activity. Finally, this is a good place to bind custom shadows you create and set up any external library configurations that you may need.
  • Centralize test constants. Android strongly encourages the use of abstracting string resources into one place over using hard-coded string constants. Use a test constants class when you have lots of test data (e.g. When creating a user with lots of fields to mock out a JSON response).
  • Have a robust testing strategy. Don't rely solely on unit tests to ensure the proper implementation of your app. These tests, though quite useful, only give you a small window into your app and it's behavior. At minimum, you should include integration level tests and have some level of manual QA in the process to ensure your app is everything that you want it to be.

Notes

  • Unit testing Android apps is not as simple as with other platforms and Robolectric is still a work in progress. You will find things that you'd like to test that the library doesn't suport. It's up to your organization to determine how much they would like to invest to give back the the community by writing and fleshing out shadow classes.
  • When running the sample tests you may notice a few warnings about binding map-related shadow classes (because the library is not available in the maven central repository). To solve this issue use the maven android SDK deployer.
    Warning: an error occurred while binding shadow class: ShadowGeoPoint
    Warning: an error occurred while binding shadow class: ShadowItemizedOverlay
    Warning: an error occurred while binding shadow class: ShadowMapController
    Warning: an error occurred while binding shadow class: ShadowMapActivity
    Warning: an error occurred while binding shadow class: ShadowMapView
    Warning: an error occurred while binding shadow class: ShadowOverlayItem
I hope you found this blog useful for getting started with Robolectric! If you are already using it, what do you find most useful or helpful? How does it fit into your testing strategy?

Friday, August 3, 2012

Integrating Robolectric with IntelliJ

Unit testing is a best practice, but has been particularly difficult in Android. One library that makes this process much simpler is Robolectric. Integration into your project can be tricky and most methods start with maven and create an Android project from scratch.

I'm a huge fan of living in IDE-land as much as possible, so this approach minimizes command line work and manual project configuration. This tutorial will walk you through using IntelliJ to generate the project and maven integration to make installation of Robolectric simpler.
After creating an Android project with the wizard, you move the source files into a mvn-like structure. Then you configure module settings in IntelliJ. To install Robolectric, you will add a pom file (maven dependency file) into the project. Finally, you will write your first test and run it inside the IDE.

Note: There are other projects and methods out there, but this is what I found to be the most effective way to get up and running. If you'd prefer an all in one solution, check out this project.

Assumptions:

  • You are starting a new project.
  • You are familiar with the IntelliJ and the Android wizard (CE edition is fine).
  • You have installed the Android SDK and configured IntelliJ to use it.
  • You have maven installed.

Step 1: Create Android project using IntelliJ wizard

Use the IntelliJ Android wizard to create a Hello World project.

Step 2: Set up directories for maven

Use IntelliJ or the command line to move files into the following structure:

src/main/java/com/...
src/test/java/com/...

After you are done, your project should look something like this (minus the test files):
Note: IntelliJ might not like it when you add subdirectories to the folder marked as source. If you are having trouble setting up the directory structure, open the screen shown in the next step and remove the old source folder before adding new subfolders.

Step 3: Configure IntelliJ source and test folders

Update module settings in IntelliJ to recognize the source and test directories (below: blue folder is source and test folder is green).


Step 4: Install Robolectric

Use this sample pom.xml to get you started. Change the groupId, artifactId, version, and name tags to suit your project. The file should live in the root of the project.
And some of my environment set up (zsh):
# Shell Settings (one long line, broken for view online)
export ANDROID_HOME="/usr/bin/android-sdk-macosx"
export PATH="/usr/bin/android-sdk-macosx/platform-tools:/usr/bin:
             /usr/bin/android-sdk-macosx/tools:
             /usr/local/apache-maven-2.1.2/bin:$PATH"
After updating the pom and environment variables, check the project in IntelliJ to make sure the "Maven Projects" view looks something like this (you may need to refresh):


If you see errors, you may just need to wait for it to finish indexing and importing your libraries. If you have git configured, once you see this dialog, you should be moments away from running your first test.

Step 5: Create test

I use the IDE to generate a test. On a Mac, the key combination is Apple+Shift+T.

Step 6: Write test & run

Right click on the test file name to run the test or use keyboard shortcut. TODO - resolve - If you are seeing issues similar to this, rebuild your project a few times to convince IntelliJ to generate the R.java file (which links to all your applications resources) and/or run "mvn install" from the command line.

If you are still having issues, update your Android facet here:
Success!

Optional Step 7: Create a run config for all tests

You could run each test individually as you work with new classes, however it should be a common task to run all the unit tests (e.g. prior to commit). I create a run configuration for the whole project:  


Next Steps

Now that you've got it integrated into your project, why not try adding a few tests? Check out the next blog in the series that shows you how to write test for your project.

Monday, July 30, 2012

Using Cocoapods to Manage Private Libraries

Introduction

Cocoapods (http://cocoapods.org/) is a dependency management framework for XCode. It allows you to declaratively define project dependencies and have them included in the build of your project. It's like Apache Maven or Ruby Gems for XCode. There are many tutorials on getting started with Cocoapods, so in this blog post I will present a simple case where we have a project that depends upon two internally developed projects or private libraries.
We will start by creating two projects, each with a simple UI screen and some 3rd party dependency. Each of these projects will contain a file known as a Podspec that defines what gets included when another project depends upon it. Next, we will create a third project that depends upon these internally developed libraries and see how everything gets tied together.
In my contrived example, I'll create two projects, each with a dependency on AFNetworking (a nice network abstraction layer). AFNetworking is already available via the public cocoapods spec library. Cocoapods will be used to add this dependency. Each project will also use YQL to query a weather service (Yahoo versus Wunderground) and present the forecast for a given zip code. The master project, which I like to call the Weather Comparator, will pull in the Yahoo and Wunderground projects and use their code to present a comparison of the services.

The Private Libraries

We start by creating the first project, Yahoo Weather. Once we have Cocoapods installed on our system, we create an XCode project for our first framework. I started using the Empty iOS application template. Once the XCode project is created, exit XCode. Create a text file called "Podfile" at the root directory of the project. The contents of the Podfile looks like the following:
platform :ios, '5.1'

xcodeproj 'YahooWeather.xcodeproj'

pod 'AFNetworking'
The first line defines the platform and SDK version, the next line defines the name of the XCode project file, and subsequent lines define the dependencies for this project. Podfiles can be much more complex, but this post will keep things simple. Check out the Cocoapods site for more information. Once the Podfile is complete, drop to a terminal and execute pod install at the root of the project directory. You'll see some messages about the dependencies being downloaded and configured and when the process is complete, there will be a message indicating NOT to use the YahooWeather.xcodeproj anymore, but use the YahooWeather.xcworkspace file now. This is a workspace that includes your project and the Pods project.
Under the Pods project, there is a Pods directory, which contains the libraries specified in the Podfile (AFNetworking in this case). Besides creating the workspace, Cocoapods configures your project to include a static library called libPods. This is the output of the Pods project build. Essentially it includes the compiled version of the pods for which you asked to be included in the project. We can now use the AFNetworking classes within our code. The source code for the YahooWeather project can be found on my github account: https://github.com/stevenpsmith/YahooWeatherService. The finished app can actually be run and looks like this (I know, gorgeous, right):
Following the same steps, we create a second project called WunderWeather. Much of the code is similar, except now we are using the Wunderground weather API. There are some other small changes, but for simplicity sake I reused much of the same code, just using different names for the classes (notice the class name prefix). Again, remember this is a contrived example, so reusing the code was merely for time efficiency. The source code for WunderWeather can be also be found on my github at https://github.com/stevenpsmith/WunderWeatherService. And for your viewing pleasure, here is what it looks like:
One important thing to note here, is that each of our frameworks uses a slightly different class prefix. This ensures that when both of these projects get used in a third project (the WeatherComparator), there are no name collisions. Wouldn't namespaces be nice?
When we are done coding each of these projects, we can commit them to our "private" git repository. In this case I am using github public repositories, but these projects can reside anywhere that is accessible from the projects that will depend upon them. That could a private repo, file system, etc. Cocoapods also support SVN and Mercurial, but git is what all the cool kids are using, so that is what this example will use.

Creating the Podspec

The next step is to configure a podspec for each of our frameworks. The podspec defines the source files, resources, etc. that our libraries/frameworks expose for use by other projects. In our case, we need to expose all the classes in the API, Model, and ViewController directories within our projects. We also want to expose our XIB files. Those are resources which need to get compiled and added to our final ".app" file. In a similar way, resources might include images that will get added into the ".app" file during the final build process. To create a podspec, execute pod spec create projectname at the root of the project directory. In our case, it would be pod spec create YahooWeather or pod spec create WunderWeather
The file that gets created has comments and examples of all the properties that can be set. For our projects, the podpsec looks like this (with all the extraneous comments and unused attributes removed):
Pod::Spec.new do |s|
  s.name         = "YahooWeather"
  s.version      = "0.0.1"
  s.summary      = "Provides a Yahoo weather forecast, with basic UI, for a given zip code."
  s.homepage     = "https://github.com/stevenpsmith/YahooWeatherService"
  s.license      = 'MIT'
  s.author       = { "stevenpsmith" => "ssmith@chariotsolutions.com" }
  s.source       = { :git => "https://github.com/stevenpsmith/YahooWeatherService.git", :tag => 'v0.0.3' }
  s.platform     = :ios, '5.1'
  s.source_files = 'YahooWeather/API/*.{h,m}', 'YahooWeather/Model/*.{h,m}', 'YahooWeather/ViewController/*.{h,m}'
  s.resources = "YahooWeather/ViewController/*.{xib}"
  s.requires_arc = true
  s.dependency 'AFNetworking'
end
Notice the source property. This points to our "private" repo. You can also access local repositories (instead of server based repos) by using a URI like this: '/Users/steve/projects/foo', which points to the root directory of your version controlled code. Also note the use of the tag key (which could also be a :commit). If consumers of this library do not specify a tag or commit, this specifies the snapshot of the code that will be provided. Without specifying anything, the latest commit of the master branch will be used. The source_files and resources specify the assets within this project that will be provided to the consuming projects. The dependency property specifies any pods that this pods would depend upon (in our case, AFNetworking). This file needs to be committed to the repository, and if a tag or commit is specified, that must exist within the repo as well. It's a good practice to validate the podspec by executing pod spec lint <podspec_name>
This will save a lot of grief with typos, incorrect source directories, etc. Once your podspec is clean, commit it to the repository and tag if needed. The podspec for WunderWeather looks eerily similar.

Using the private libraries

The next step is to use these libraries in a new project. This is the WeatherComparator project, and it's source can be found at https://github.com/stevenpsmith/WeatherComparator. We get started like we did before, creating the project within XCode, then exiting and creating a Podfile that references the dependencies. Except this Podfile will look a little different, as shown below:
platform :ios, '5.1'

xcodeproj 'WeatherComparator.xcodeproj'

pod "YahooWeather", :git => 'https://github.com/stevenpsmith/YahooWeatherService.git', :tag => 'v0.0.3'
pod "WunderWeather", :git => 'https://github.com/stevenpsmith/WunderWeatherService.git', :tag => 'v0.0.2'
Here we are adding the :git key to the pod declaration. Again, this could be subversion, mercurial, and even a filesystem reference. Notice there are no dependencies on AFNetworking. Our new project doesn't directly depend upon those, but since the pods do, it will get pulled into our new workspace as it did in the other projects. Execute pod install in a terminal at the root of the new project directory, open the workspace as we did before, and we are good to go. Here is a screen shot of our weather comparator:
If you take a look at the code in the WeatherComparator project, it is very simple. One interesting thing to look at is the Pods-resources.sh script located in the TargetsSupportFiles/Pods directory within the Pods project. Cocoapods generates this script file based on the contents of the podspec for the libraries. This script actually compiles the XIB files and adds them to the projects final build. As you can see, pods can use storyboards as well. This provides a nice way to create modules that include UIs and then combine them into applications.
Even though we used github public repositories, this post shows how to use Cocoapods to manage your project's public and private dependencies. To try out the project, install Cocoapods, download the WeatherComparator project, execute pod install at the root, open the workspace, run the project, and see how different Yahoo and Wunderground weather forecasts can be. Pretty surprising actually :).

Friday, May 25, 2012

Read and Write NFC Tags with PhoneGap

The phonegap-nfc plugin allows you to read and write NFC tags from a PhoneGap application using JavaScript.

The plugin originally supported Android. The latest release adds support for Blackberry 7.0.

After installing the plugin into your PhoneGap app (See README) it is easy to start scanning tags.

Create a function that will handle the NFC events.

function onNfc(nfcEvent) {
    // display the tag as JSON
    alert(JSON.stringify(nfcEvent.tag));
}

Create the optional success and failure callbacks. These callbacks are for success and failure of adding the listener.

function success(result) {
    console.log("Listening for NFC Messages");
}

function failure(reason) {
    alert("Failed to add NDEF listener");
}

Register listener. When the listener is added, the plugin will generate an NFC Event whenever a tag is scanned.

nfc.addNdefListener(onNfc, success, failure);

Deploy the application and scan a tag.

Example Project

The NFC Reader example project has been updated for Blackberry.

More info

The PhoneGap NFC API is documented in the README file.

Kevin wrote Building NFC applications with Android last year. Most of that information still applies.

Friday, May 4, 2012

Camera Access from Android Browser

The browser in Android 4 is able to take pictures from a web page and display them without any plugins or server interaction. This demo uses the Device API and File API to take and display a picture on a phone using the browser.

Try it on your Android phone http://don.github.com/html-cam/.

I wrote this demo after reading David Calhoun’s post about Android implementing device APIs.

This works on my Google Nexus S running Ice Cream Sandwich (4.0.4). The Device API works on Samsung Galaxy Tab 10.1 with Honeycomb (3.2) but the File APIs do not. YMMV.

Loading images from the gallery is finicky. Images load from the device but fail to load from Picasa albums. I had to alter the image blob and change data:base64 to data:image/jpeg;base64 to get photos from galleries to display.

I kludge the photo orientation based on the device orientation, clearly there is a better solution.

It's possible to run the browser out of memory. I'm guessing this is because a huge photo is encoded into a base64 string. Maybe window.URL.createObjectURL(file) would work better than reading the image with FileReader?

Adjusting the input tag can control the input types:

<input type="file" />
Browser prompts for camera, camcorder, sound recorder, 
  music track, or gallery

<input type="file" accept="image/*" />          
Browser prompts for camera or gallery   

<input type="file" accept="image/*;capture=camera" />           
Browser goes directly to the camera

For more info see the github project.

UPDATE 2012-05-06
It looks like Facebook's mobile website allows camera access from a browser on Android.

Friday, April 27, 2012

Securing Data in iOS

There are numerous ways to secure data that you are storing on an iOS device.

The Simple/Built-in Way

The simplest way is to take advantage of the iOS Data Protection (iOS 4+). This can be accomplished by setting an attribute on a file like this:

    [[NSFileManager defaultManager] createFileAtPath:[self filePath]
                    contents:[@"super secret file contents" dataUsingEncoding:NSUTF8StringEncoding]
                    attributes:[NSDictionary dictionaryWithObject:NSFileProtectionComplete
                                                           forKey:NSFileProtectionKey]];

There are several different levels of file protection. The following was taken from the NSFileManager class reference from Apple:

  • NSFileProtectionNone - no file protection
  • NSFileProtectionComplete - file is encrypted when the device is locked or booting
  • NSFileProtectionCompleteUnlessOpen - file is encrypted and can only be opened when the device is unlocked. Once open, the file can continue to accessed even if the user locks the device.
  • NSFileProtectionCompleteUntilFirstUserAuthentication - The file is stored in an encrypted format on disk and cannot be accessed until after the device has booted. After the user unlocks the device for the first time, your application can access the file and continue to access it even if the user subsequently locks the device.

A Core Data sqlite store can also be encrypted by setting the NSFileProtectionKey file attribute to one of the above values (after you create your persistent store coordinator).

However, an important thing to realize is that this type of data protection requires the device to have a passcode set on it (http://support.apple.com/kb/HT4175).

CommonCrypto

What if you really need to insure that your data is protected regardless of whether the device has a passcode set? One way is to use the CommonCrypto libraries from Apple. This can be fairly complex. There is a great write up here from Rob Napier on what's involved. Fortunately, he has also provided a wrapper that greatly simplifies this process here. Using this library (or writing your own), you can encrypt your data and store it wherever you need. If you are using Core Data, you could write an NSValueTransformer for the Core Data entity attributes that require encryption using CommonCrypto or the RNCrypto library to encrypt/decrypt the attribute values.

SQLCipher

One more way to protect your data, specifically data that you want to store in a SQLite database, would be to use SQLCipher. SQLCipher encrypts/decrypts data at the page level and is transparent to your application code. You still use the standard SQLite APIs, with one additional method call when accessing the database (passing your key to sqlite). There are excellent instructions on setting it up for use in an iOS project here.

You can build SQLCipher as a set of static libraries by following the same iOS instructions with some modifications and additions. Here are the high level steps:

  1. Instead of creating a view based iOS project, create a static library project
  2. Follow the balance of the steps for including SQLCipher in your project
  3. Add a new "Aggregate" build target
  4. Add a "Run Script" build phase and paste the following script into it. This will build both the simulator and iOS based targets for the libcrypto, libsqlcipher, and libssl libraries.
  5. xcodebuild -project ${PROJECT_NAME}.xcodeproj -sdk iphonesimulator -target ${PROJECT_NAME} -configuration ${CONFIGURATION} clean build CONFIGURATION_BUILD_DIR=${BUILD_DIR}/${CONFIGURATION}-iphonesimulator
    
    xcodebuild -project ${PROJECT_NAME}.xcodeproj -sdk iphoneos -target ${PROJECT_NAME} -configuration ${CONFIGURATION} clean build CONFIGURATION_BUILD_DIR=${BUILD_DIR}/${CONFIGURATION}-iphoneos
    
  6. Add another "Run Script" build phase and paste the following script into it. This will merge the simulator and iOS builds into one for each library. These three libraries are what would be added to a project using SQLCipher.
  7. CRYPTO_LIB="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/libcrypto.a" &&
    SQLCIPHER_LIB="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/libsqlcipher.a" &&
    SSL_LIB="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/libssl.a" &&
    
    DEVICE_CRYPTO_LIB="${BUILD_DIR}/${CONFIGURATION}-iphoneos/libcrypto.a" &&
    DEVICE_SQLCIPHER_LIB="${BUILD_DIR}/${CONFIGURATION}-iphoneos/libsqlcipher.a" &&
    DEVICE_SSL_LIB="${BUILD_DIR}/${CONFIGURATION}-iphoneos/libssl.a" &&
    
    UNIVERSAL_LIBRARY_DIR="${BUILD_DIR}/${CONFIGURATION}-iphoneuniversal" &&
    
    
    # Create framework directory structure.
    rm -rf "${UNIVERSAL_LIBRARY_DIR}" &&
    mkdir -p "${UNIVERSAL_LIBRARY_DIR}" &&
    
    # Generate universal binary for the device and simulator.
    lipo "${CRYPTO_LIB}" "${DEVICE_CRYPTO_LIB}" -create -output "${UNIVERSAL_LIBRARY_DIR}/libcrypto" &&
    lipo "${SQLCIPHER_LIB}" "${DEVICE_SQLCIPHER_LIB}" -create -output "${UNIVERSAL_LIBRARY_DIR}/libsqlcipher" &&
    lipo "${SSL_LIB}" "${DEVICE_SSL_LIB}" -create -output "${UNIVERSAL_LIBRARY_DIR}/libssl"
    

Once completed, you can build your new aggregate target and there should be 3 libraries located in a subdirectory within your project build directory. Just add these to your XCode project as you would any other library and you are good to go.

Wednesday, February 15, 2012

Sencha Touch 2 - NavigationView, Templates and Forms

This post will build on the example application from the Introduction to Sencha Touch post. We will look at sorting, templates, navigation and forms.

Sorting

In the existing code new items appear at the bottom of the list. I’d prefer to see the newest items first. After a Sorter is added to the Store, Sencha displays records in the proper order.
var store = Ext.create('Ext.data.Store', {
    storeId: "activityStore",
    model: "Activity",
    proxy: {
        type: 'ajax',
        url: 'exercise.json'
    },
    sorters: [
        {
            property: 'date',
            direction: 'DESC'
        }
    ],
    autoLoad: true
});

Detail View

The user should able to drill into an Activity on the list to see the details.

Template

We will create an XTemplate that will be populated with the data from the Model. Templates can be created in Javascript or externalized. I prefer to put more complex templates in HTML rather than inline Javascript. Sencha recommends external templates are defined in a hidden textarea.
<textarea id="detail-template" style="display:none">
  <div>
    Date: {date:date("m/d/Y")} <br/>
    Type: {type} <br/>
    Distance: {distance} <br/>
    Time: {minutes} minutes <br/> 
    Notes: {comments} <br/>
  </div>    
</textarea>
The template is created once in code.
var template = Ext.XTemplate.from(Ext.get('detail-template'));

List item disclosure

Sencha displays a disclosure icon for each row when a function is assigned to the onItemDisclosure property of the list. Clicking on this icon allows the user to drill into the details for a row.
The onItemDisclosure function
  • receives the selected record as an argument
  • populates the template with the model’s data
  • creates a new panel
  • pushes the panel onto the navigation view
   {
       xtype: 'list',
       title: 'Activities',
       itemTpl: '{date:date("m/d/Y")} - {type}',
       store: store,
       onItemDisclosure: function (record, btn, index) {
           view.push({
               xtype: 'panel',
               title: 'Activity',
               html: template.apply(record.data),
               styleHtmlContent: true
           });
       }
   }

Pushing the panel onto the NavigationView handles a lot of stuff. The view becomes visible, the navigation bar title is set, a back button is displayed, navigation is handled automatically. This is a nice new feature in Sencha Touch 2.0.

Disclosure icon Record detail

Showing and hiding buttons

When the user is viewing the details, the Add button should disappear. We can manually hide the button in the onItemDisclosure before pushing the view.
onItemDisclosure: function (record, btn, index) {
                      view.down('#addButton').hide();
                      view.push({
                      // ...
The Add button needs to be shown again when the user navigates from the detail back to the main screen. Since the NavigationView handles the navigation automatically, we listen for the pop event and make the Add button is visible.
var onNavigationPop = function(v, item) {
   v.down('#addButton').show();
};

var view = Ext.create("Ext.NavigationView", {
   fullscreen: true,
   items: [
      // ...
   ],
   listeners: {
       pop: onNavigationPop
   }
});
Similarly, we can add onNavigationPush to hide the Add button whenever we push a new view on the stack. This is better than hiding the button in onItemDisclosure.
var onNavigationPush = function(v, item) {
    v.down('#addButton').hide();
};

var view = Ext.create("Ext.NavigationView", {
   fullscreen: true,
   items: [
      // ...
   ],
   listeners: {
       pop: onNavigationPop,
       push: onNavigationPush
   }
});

Record detail with button Record detail without button

Finally, instead of word Add on the button, I think it looks better with an icon.
view.getNavigationBar().add([
  {
      xtype: 'button',
      id: 'addButton',
      align: 'right',
      ui: 'action',
      iconCls: 'compose',
      iconMask: true, 
      handler: addNewRow
  }
]);

Add button text Add button icon

Adding new records with a form

The current implementation puts a fake row into the store when the Add button is pressed. We want to display a form to collect the user input.
We are going to change the implementation of addNewRow to create a FormPanel and push it onto the view. The NavigationView destroys components as they are popped, so we recreate the form every time. Alternately we could set autoDestroy to false on the NavigationView.
var addNewRow = function() {
    view.push(Ext.create('Ext.form.Panel', formBase));
};
The formBase object contains the form fields.
var formBase = {
    title: "Activity",
    itemId: "form",
    items: [
        {
            xtype: 'datepickerfield',
            name: 'date',
            label: 'Date',
            value: new Date()
        },
        {
            xtype: 'selectfield',
            name: 'type',
            label: 'Type',
            options: [
                { text: "" },
                { text: "Run", value: "Run" },
                { text: "Bike", value: "Bike" },
                { text: "Swim", value: "Swim" },
                { text: "Walk", value: "Walk" }
            ]
        },
        {
            xtype: 'textfield',
            name: 'distance',
            label: 'Distance'
        },
        {
            xtype: 'numberfield',
            name: 'minutes',
            label: 'Minutes'
        },
        {
            xtype: 'textfield',
            name: 'comments',
            label: 'Notes'
        }
    ]
};

Saving data

The navigation bar needs a save button. Initially this button will be hidden.
{
    xtype: 'button',
    id: 'saveButton',
    text: 'Save',
    align: 'right',
    ui: 'action',
    handler: save,
    hidden: true
}
The addNewRow function makes the save button visible.
var addNewRow = function() {
    view.push(Ext.create('Ext.form.Panel', formBase));
    view.down('#saveButton').show();
};
The save button is hidden in onNavigationPop.
var onNavigationPop = function(v, item) {
    v.down('#addButton').show();
    v.down('#saveButton').hide();
};
The save function
  • gets the form using the item id
  • creates an new Activity model from the form data
  • adds the new model to the store
  • navigates back to the list view
var save = function() {
   var form = view.down('#form');
   var record = Ext.create('Activity', form.getValues());
   store.add(record);
   // TODO validation and error handling
   view.pop();
};

Note that Sencha automatically displays the new data in the list without any effort on our part.

Form New row

Additional enhancements to improve this example could include things like validating form data, editing existing rows, sending data back to the server, converting to MVC.

The source code is available on github.

Monday, January 23, 2012

Introduction to Sencha Touch

Steve Smith recently looked at jQuery Mobile and Backbone using a simple application that allowed a user to track their daily exercise. I'm going to duplicate his example using Sencha Touch.

Sencha Touch is a framework for building mobile applications using HTML5, CSS3, and Javascript.  This example uses the Developer Preview of Sencha Touch 2.0.

Here's what our project looks like.

A Sencha Touch application is loaded from an HTML page. The HTML loads CSS and Javascript. Sencha Touch applications typically build the UI using Javascript so the index.html is very simple.

The touch/ directory contains the Sencha Javascript and CSS from the SDK.  Since this is an example, all if the application code is in one file, app.js. Larger applications will break the code up into more files and directories.

Sencha Application

Sencha Touch has a global namespace, Ext, that holds the framework and application code. The Ext.application helper function takes a configuration object where we define our application.

Ext.application({
    launch: function() {
        // define our app here
    }
});

Model

We extend Ext.data.Model to define a Model object describing our data. The data is supplied by the server in a JSON file, exercise.json. The fields in the model, match the properties in the JSON file.

Ext.define("Activity", {
    extend: "Ext.data.Model",
    fields: [
        {name: 'id', type: 'int'},
        {name: 'date', type: 'date'},    
        {name: 'type', type: 'string'},    
        {name: 'distance', type: 'string'},    
        {name: 'minutes', type: 'int'},  
        {name: 'comments', type: 'string'}
    ]
});
/* exercise.json */
[
    {
        "id":3,
        "date": "12/10/2011",
        "type": "Walk",
        "distance": "2.5 miles",
        "comments": "Shouldn't have taken the dog",
        "minutes": 45
    },
    ...
]  

Store

A Store is used to load and manage data. The Activity model we created is associated with the store. We define a proxy to load the JSON data from a URL. Finally, we tell the store to automatically load the data when the store is created.

var store = Ext.create('Ext.data.Store', {
    storeId: "activityStore",
    model: "Activity",
    proxy: {
        type: 'ajax',
        url: 'exercise.json'
    },
    autoLoad: true
});

Once the store is created, we can use the Javascript console to interact with the data.

User Interface

Now we need to display the data. A NavigationView shows a navigation bar and holds the List component. The list is defined in the code using the object literal syntax. The data store we created is assigned to the list so it can display the records. The itemTmp property defines how to display each item of data. This can be a template or a string.

var view = Ext.create("Ext.NavigationView", {
    fullscreen: true,
    items: [
        {
            xtype: 'list',
            title: 'Activities',
            itemTpl: '{date} - {type}',
            store: store
        }
    ]
});
Unformatted Date

This works but the date doesn't display very well. A format can be added to the template definition. {date} in the itemTpl becomes {date:date("m/d/Y")}.

var view = Ext.create("Ext.NavigationView", {
    fullscreen: true,
    items: [
        {
            xtype: 'list',
            title: 'Activities',
            itemTpl: '{date:date("m/d/Y")} - {type}',
            store: store
        }
    ]
});
Formatted Date

Adding New Data

Let's add a button to the header to add a new row of data.

view.getNavigationBar().add({
    xtype: 'button',
    text: 'Add',
    align: 'right',
    handler: addNewRow
});

The handler property of the button defines the function that is called whenever the button is pressed. Eventually we need a form so the user can add new data. For now, let's define a function addNewRow that will create a new row and add it to the store.

var addNewRow = function() {
    // future versions should display a form for adding a record
    var fakeRecord = Ext.create('Activity', {
        date: new Date(), 
        type: 'Walk', 
        distance: '2 miles', 
        minutes: 28, 
        comments: 'Auto generated record.'
    });

    store.add(fakeRecord);
};

Now when the button is pressed a new row appears in the UI.  The store notifies the list, so rows appear as records are added to the store.

Add Button

New Row

That should be enough to get you started. In future posts we'll look at features like sorting, detail views, navigation, and forms. The source code is available on github.