iConcepts: 12 Myths About Concurrency in Objective-C By Jiva

12 Myths About Concurrency in Objective-C By Jiva 

There’s lots of cases where new Objective-C programmers incorrectly apply threads or misunderstand their use. I often see code from well intentioned folks who use threads where they absolutely don’t need them. Consequently, I thought I would put together this list of 12 myths to help guide you along the way to the proper use of threads in your apps.

Myth #1: Threads will make my app faster!

This is probably the most common newbie programmer mistake. Thinking that threads will make your app faster.

They won’t. Your code will execute at exactly the same rate regardless of whether it’s threaded or not. The key advantage that threads provide is that, in the case of a multiple-core machine, they allow you to do two things at once. This can speed processing of certain operations, but only in cases where the different operations are parallelizable. That is, in cases where the operations do not rely on each other for any portion of their calculations.

Even in cases where your operations are parallelizable, if you do not have multiple cores, your code will actually run slower if you add threads, since the processor will be doing more context switches to handle your threads.

https://i2.wp.com/www.random-ideas.net/Dropbox/Threading.png

So, in fact, the cases where threading will actually improve the performance of your app are confined to a relatively small subset. Still, this subset is important and encompasses many common use cases. Unfortunately, too often threads are applied in areas where they are not needed and where they will not significantly improve performance. The effort required to get threaded code right is substantial, and you need to weigh the benefit to bullshit ratio involved. You should also always profile your app before adding threads. You may find that the use case which you think is causing you problems in fact is not. Measure twice and cut once.

Myth #2: Threads will make my code simpler.

Writing thread safe code is hard. It’s seductive to think that if you could spin specific operations off into background threads, they become easier to manage because you no longer have to deal with things like callbacks, and asynchronicity.

The fact is, that adding threading to a complex app will only make it much, much more complicated. There’s an old saying that goes:

Without threads you have n problems. But with threads you have n+1 problems.

Or, as I like to say:

With threads you have n! problems!

Not only will you still have to deal with all your normal coding problems, you’ll also have to deal with things like locking, synchronization, queuing changes. Your code really becomes a lot more difficult to manage when you add threads.

Myth #3: I need threads to solve my problems with blocking I/O.

This common misconception comes from the fact that there are several synchronous methods on some of the foundation classes such as NSString and NSData which allow you to download content from the Internet. These methods, such as+stringWithContentsOfURL: are tremendously convenient, but block the current thread. Using them is as simple as:

NSString *myStr = [NSString 
                     stringWithContentsOfURL:urlToMyData];

Obviously, you’d never want to block the main thread, so a conscientious coder will often (wrongly) imagine that spinning this operation off into a background thread is a good way to still use these convenient methods. The fact is that this is a bad idea.

Threads can only be terminated when they are checking some kind of control variable and can thus be triggered to exit, such as:

while(keepRunning)
{
    NSString *myStr = [NSString 
                     stringWithContentsOfURL:urlToMyData];
}

Since the +stringWithContentsOfURL method blocks, the keepRunning variable will never get checked. So how do you stop this thread? The fact is, you don’t. There is simply no way to terminate a blocked thread.

This issue alone should be enough to make you walk away, but in case its not, consider that you also have no way to specify a timeout for these methods, you can no longer properly handle complex handshaking such as from authentication, and you lose the ability to interpret status codes that might be returned when accessing the resource.

Because of all this, you should never use these methods.

You might be saying to yourself right now “But I don’t need to worry about those things, I have a very simple use case, and my data will always be available.”

The answer is no. Never use these methods! there’s no need to! The Foundation classes, NSURLConnection and NSURLRequest provide more than enough functionality to do the job properly without blocking and without using threads.

Before I came to Objective-C I wrote a lot of C++, most of it networking code. I know how hard it is to get networking code right. One surprising lesson I learned is that even when writing services that had to handle many incoming connections, threads are almost always still the wrong answer. If you imagine a case where you’re handling hundreds of connections, you really don’t want to spawn and manage hundreds of threads. You’re really much better treating your sockets as a pool and handling I/O on them that way.

Much research has been done on this subject, but one of the best resources I have found is from Dan Kegel in his article, “The C10K problem.” You can go read those docs, and bleed yourself into socket code for the next 5 years of your career, or you can take my word for it: Apple knows what they’re doing here, and they got it right.NSURLConnection and NSURLRequest will handle 90% of the networking needs of most developers.

(How to handle the other 10%? That’s another post!)

A lot of developers will also make the mistake of prematurely optimizing networking code like this when they have large resources they have to download. They imagine that they need to run even NSURLConnection in a background thread. This couldn’t be further from the truth.

NSURLConnection is extremely efficient at downloading even very large files. I’ve never seen a file it couldn’t handle. It will not block your runloop. Your own code, processing those large files, may block the runloop and need to be threaded, but the actual downloading will not.

Myth #4: NSOperation means I don’t have to think about threading issues.

Just because you’re using NSOperation doesn’t mean your code is magically thread safe. NSOperation provides no thread safety facilities whatsoever. It simply provides an easier way to spawn and manage threads by abstracting away the details of the thread itself. All you need to provide is the code that actually does the work. NSOperation does the rest for you.

What this means in terms of our discussion here is that everything I’ve said about writing thread safe code still applies and code you write as part of your NSOperations still needs to be thread safe.

Myth #5: Atomic properties makes my code thread safe

As we’ve already seen, thread safety is a complex subject full of dark alleys and pitfalls. At it’s most fundamental level, even just reading a value from memory can be fraught with peril. When making your classes thread safe, you have to account for both these low level fundamental operations as well as higher logical level relationships, such as setting different variables within your class.

Atomic properties addresses only the issue of accessing your property values. An atomic property insures that the setter of a property cannot modify the property while it is being retrieved. Basically, when you use atomic properties, the accessors generated by the compiler wind up looking something (roughly) like the following:

 //@property(retain) UITextField *userName;
 //Generates roughly

 - (UITextField *) userName {
     UITextField *retval = nil;
     @synchronized(self) {
         retval = [[userName retain] autorelease];
     }
     return retval;
 } - (void) setUserName:(UITextField *)userName_ {
     @synchronized(self) {
       [userName_ retain];
       [userName release];
       userName = userName_;
     }
 }

(via objective c – Atomic vs nonatomic properties – Stack Overflow)

When using an atomic property, you will never run into the circumstance where you receive a corrupt value from the getter due to the setter changing the value while you are getting it. This doesn’t mean that the setter won’t change the value after you have received it, and so, thus, it does not fully insure thread safety. It only addresses one part of the full thread safety picture.

Myth #6: Serial operation queues are not threaded.

Just because you’ve made an NSOperationQueue serial by setting it’smaxConcurrentOperationCount to 1 doesn’t mean that the operations you add to that queue will not be run in a background thread. In fact, with the exception of the built-in queue you get from the NSOperationQueue class method, +mainQueue(NSOperationQueue Class Reference) all queues will run in a background thread. In the case of the +mainQueue it actually returns the queue associated with the main thread of your application and runs it on that queue. The main queue is serial.

Myth #7: GCD makes threading easy.

Along these same lines, GCD also does not make working with threads any safer or easier than any other thread mechanism. GCD’s role in Objective-C threading is actually for the purposes of managing thread pools. It’s job is to correctly determine the appropriate number of threads to use for your hardware based on the number of processors and cores your machine has. Although you can use the low level GCD API to add your operations directly to GCD, NSOperation provides a higher level abstraction to the very same mechanism, and is, generally, the preferred way to do it.

Myth #8: Threads Can Be Terminated Safely From Outside The Thread

It’s actually not possible to terminate a thread if the thread itself doesn’t want to be terminated. This is not entirely obvious, but it’s true. This is why most threaded operations utilize a flag to tell them when to exit prematurely. For example:

-(void)myThreadedOperation
{
    while(continueToRun && ![self allStuffIsDone])
    {
        // do some stuff...
    }
}

In this case, we have a background thread that is doing a series of operations. When all the operations are done, it sets the returns true from -allStuffIsDone and exits the loop. However, it also has a flag called continueToRun which its checking on each loop. This flag can be set by an external thread to cause this thread to exit after any iteration. If your background operations will take a long time, you probably want to include a similar design pattern.

Myth #9: I can safely throw exceptions in threads.

What happens when an exception is thrown in Objective-C and not caught? Usually, a crash. 1 What happens when an exception is thrown in a background thread and not caught? The answer is, the one thing worse than a crash: undefined behavior. It might crash… It might crash the whole app… It might crash just the thread… No one knows! It’s undefined. Your thread might even crash, and your app continue running. What do you think your app will do if it expected that thread to later either still be running or have finished?

Although I wouldn’t say that you can’t throw exceptions in threads at all, the important thing to know is that if you do, and it doesn’t get caught, the end result for your app is very bad.

Fortunately, Objective-C doesn’t use a lot of exceptions. So I don’t advocate putting generic exception handlers at the top of all your threaded operations. I point this out more as a “thing to know”. That exceptions can be dangerous in threads, and to be careful when working with code that does throw exceptions.

Myth #10: I can update my gui from background threads.

This one is fairly well known, but worth mentioning anyway. Cocoa and CocoaTouch, the GUI frameworks used on Mac OS and iOS respectively, are not thread safe. You must never update your GUI from a background thread. Whenever you need to trigger a GUI update from a background thread, you should do so on the main thread. Here’s an example of how to do this using the main queue and a block:

[[NSOperationQueue mainQueue] addOperationWithBlock:^
    {
        [self.tableView reloadData];
    }];

Myth #11: Notifications from background threads are executed on the main thread.

Notifications are nothing more than a set of method calls. So when a notification occurs, your notification handler will be called from the thread upon which the notification was triggered. This has some interesting implications.

For example, when you’re saving Core Data objects in a background thread, this notification will be sent from that background thread. Ordinarily, this is a great notification to watch for to update your UI when changes occur. Of course, we already talked about how you can’t update your UI from a background thread, but in addition to this, most of Core Data itself is also not thread safe2. In this case, the objects sent with the notification using the NSInsertedObjectsNSUpdatedObjects, andNSDeletedObjects keys in the userInfo dictionary cannot cross threads, so you can’t use them directly, even if you forward the notification to the main thread.

To handle this problem, you need to use the NSManagedObjectContext method, -mergeChangesFromDidSaveNotification: in the thread of the context which is receiving the notification so it can merge the changes. To do this, you can use themainQueue again like I showed you before:

[[NSOperationQueue mainQueue] addOperationWithBlock:^
    {
        [self.ctx mergeChangesFromContextDidSaveNotificaton:
                                     inNotification];
    }];

Myth #12: I shouldn’t use threads

Given all these hazards, you might think that you should never use threads. This is not the case. Threads are a useful tool, but like any tool, they have to be respected.

Threads are like the tablesaw of the Objective-C wood shop. They cause more application injuries than all other technologies combined. There’s times, however, when they’re really the best tool for the job! The important things to remember when using threads are:

  • Keep your thread’s data isolated.
  • Simplify the algorithms you intend to use in threads. Make them the “simplest thing that can possibly work.”
  • Learn the API used for insuring thread safety like it’s the back of your hand. Things like NSLock, @synchronized, NSRecursiveLock, etc.

  1. You can install an unhanded exception handler to change this behavior. 
  2. NSManagedObjectContext for example, can’t cross threads either. This is probably worthy of a post all of it’s own someday! 

Reference : Go Here

Advertisements

iDiscussion: REST vs SOAP Web Services

Hi Friends,

download (2) download (1)

I am seeing a lot of new web services are implemented using a REST style architecture these days rather than a SOAP one. Lets step back a second and explain what REST is.

What is a REST Web Service

download

The acronym REST stands for Representational State Transfer, this basically means that each unique URL is a representation of some object. You can get the contents of that object using an HTTP GET, to delete it, you then might use a POST, PUT, or DELETE to modify the object (in practice most of the services use a POST for this).

Who’s using REST?

All of Yahoo’s web services use REST, including Flickr, del.icio.us API uses it, pubsub, bloglines, technorati, and both eBay, and Amazon have web services for both REST and SOAP.

Who’s using SOAP?

Google seams to be consistent in implementing their web services to use SOAP, with the exception of Blogger, which uses XML-RPC. You will find SOAP web services in lots of enterprise software as well.

REST vs SOAP

images (1)

As you may have noticed the companies I mentioned that are using REST api’s haven’t been around for very long, and their apis came out this year mostly. So REST is definitely the trendy way to create a web service, if creating web services could ever be trendy (lets face it you use soap to wash, and you rest when your tired). The main advantages of REST web services are:

  • Lightweight – not a lot of extra xml markup
  • Human Readable Results
  • Easy to build – no toolkits required

SOAP also has some advantages:

  • Easy to consume – sometimes
  • Rigid – type checking, adheres to a contract
  • Development tools

REST and SOAP are not equivalent concepts and Point are :

REST:

  • Depends on one transport protocol (HTTP).
  • Makes full use of the specific features of that protocol (verbs GET, POST, PUT, DELETE, caching, headers, and predefined error codes).
  • Says nothing about the format of the messages passed back and forth. However, since the HTTP verb and URL already define the action to take, the message body must therefore contain only the data.
  • Message security is provided by the transport protocol (HTTPS), and is point-to-point only. If you want to secure the message end-to-end, you have to do it yourself.
  • Originally intended for simple CRUD operations on objects.

SOAP:

  • Independent of the transport protocol (could be HTTP, FTP, TCP, UDP, named pipes, shared memory or even email).
  • Requires only that the transport protocol be able to send and receive text (e.g. on HTTP, only the POST verb is used).
  • Strictly defines the format of the messages passed back and forth. A SOAP message contains the data, the action to perform on it, the headers, and the error details in case of failure.
  • Message security is provided by the WS-* standards, and is end-to-end.
  • Originally intended for arbitrary RPC calls.

Items 2 and 3 in the above lists are the main points of incompatibility.

For consuming web services, its sometimes a toss up between which is easier. For instance Google’s AdWords web service is really hard to consume (in CF anyways), it uses SOAP headers, and a number of other things that make it kind of difficult. On the converse, Amazon’s REST web service can sometimes be tricky to parse because it can be highly nested, and the result schema can vary quite a bit based on what you search for.

Which ever architecture you choose make sure its easy for developers to access it, and well documented.

images

Reference : Click Here

Thanks, Keep Coding 🙂

iDev: Using iOS 4′s IBOutletCollection

Using IBOutletCollection

Cocoa has long defined the IBAction and IBOutlet keywords. These keywords provide metadata hints to Interface Builder providing it some understanding of your underlying code so you can graphically wire instance variables and properties and set target-action behaviors. For instance, whenever you need a pointer to NIB-defined object you would create a property defined as:

1
2
3
4
5
@interface MainViewController : UIViewController {
    UIButton *saveButton;
}
@property (nonatomic, retain) <strong>IBOutlet</strong> UIButton *saveButton;
@end

The inclusion of the IBOutlet keyword in the saveButton’s property definition makes it visible to Interface Builder allowing this connection to be wired graphically as show below:

Interface Builder

Using IBOutlet makes it very easy to define your UI in Interface Builder and simply “wire” the object references to your code. However, it does come with one major drawback in that the relationship from a NIB-defined object to property/ivar is always 1-to-1; there was no way to define a collection of components as a single property in your code. Thankfully, Apple quietly introduced a new keyword in iOS4+ called IBOutletCollection allowing you to do just this. Let’s take a closer look at an example where this can be useful.

IBOutletCollection

Like the other keywords previously mentioned, you’ll find the IBOutletCollection keyword in UINibDeclarations.h, which is part of the UIKit framework. The new keyword is defined as follows:

1
2
3
#ifndef IBOutletCollection
#define IBOutletCollection(ClassName)
#endif

You’ll notice that IBOutletCollection takes a class name parameter. This allows you specify what are considered valid values for the collection such as UIView or UIButton. If you’d prefer you can change the “type” argument to id to allow for a heterogeneous collection. So how could this be useful?

Putting IBOutletCollection To Work

I’ve often found times where I needed references to certain components, but really only in an aggregate way so I could change state on them as a group. To do this I’d first need to define separate ivar/property combinations for each component, wire them up in Interface Builder, and then manually collect each pointer into an NSArray and store the collection for later use. Although this works, it is rather tedious and does add unnecessary bloat to your code. A better way to handle this type of scenario is to make use of the IBOutletCollection keyword and wire up this relationship in IB.

In the example below I’ve defined two unique ivars/properties to hold references to my on & off buttons and then an NSArray to hold a collection of other buttons. The on/off buttons are used to change the enabled state of the group of “otherButtons”.

1
2
3
4
5
6
7
8
9
10
11
12
13
@interface MainViewController : UIViewController {
    UIButton *onButton;
    UIButton *offButton;
    NSArray  *otherButtons;
}
@property (nonatomic, retain) IBOutlet UIButton *onButton;
@property (nonatomic, retain) IBOutlet UIButton *offButton;
@property (nonatomic, retain) IBOutletCollection(UIButton) NSArray *otherButtons;
– (IBAction)toggleButtons:(id)sender;
@end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
@implementation MainViewController
– (void)setButtonsState:(BOOL)state {
   for (id button in self.otherButtons) {
      [button setEnabled:state];
   }
   self.onButton.enabled = !state;
   self.offButton.enabled = state;
}
– (void)viewDidLoad {
   [super viewDidLoad];
   [self setButtonsState:YES];
}
– (IBAction)toggleButtons:(id)sender {
   [self setButtonsState:sender == onButton];
}
– (void)dealloc {
   self.onButton = nil;
   self.offButton = nil;
   self.otherButtons = nil;
   [super dealloc];
}
@synthesize onButton, offButton, otherButtons;
@end

I can now easily wire this together in Interface Builder without the need to write any code to collect and store the references to my group of buttons. This is clearly a contrived example, but I hope you can see the benefit of this small addition to iOS 4.

Reference : Press Here

Thanks , Keep Coding 🙂

iPhonegap: Developing a PhoneGap Application

Tutorial: Developing a PhoneGap Application

Reference : Here

In this tutorial, you create a fully functional employee directory application with PhoneGap. You will learn:

  • How to use different local data storage strategies.
  • How to use several PhoneGap APIs such as Geolocation, Contacts, and Camera.
  • How to handle specific mobile problems such as touch events, scrolling, styling, page transitions, etc.
  • How to build an application using a single page architecture and HTML templates.
  • How to build (compile and package) an application for 6 platforms using PhoneGap Build.

To complete this tutorial, all you need is a code editor, a modern browser, and a connection to the Internet. A working knowledge of HTML and JavaScript is assumed, but you don’t need to be a JavaScript guru.

Setting Up

  1. Download the assets for the workshop here.
  2. Unzip the file anywhere on your file system.
  3. If your code editor allows you to “open a directory”, open the phonegap-workshop-master directory.
  4. Follow the instructions below.
Step-by-step solution files are also available here.

Part 1: Choosing a Local Storage Option


Step 1: Explore different persistence mechansisms

Open the following files in phonegap-workshop-master/js/storage, and explore the different persistence stores they define:

  1. memory-store.js (MemoryStore)
  2. ls-store.js (LocalStorageStore)
  3. websql-store.js (WebSqlStore)

Step 2: Test the application with different persistence mechanisms

To change the local persistence mechanism for the application:

  1. In index.html: add a script tag for the corresponding .js file: memory-store.jsls-store.js, or websql-store.js.
  2. In js/main.js: Instantiate the specific store in the initialize() function of the app object: MemoryStoreLocalStorageStore, or WebSqlStore.
  3. To test the application, open index.html in your browser, or simply double-click index.html on your file system. Type a few characters in the search box to search employees by name. Clicking an employee link doesn’t produce any result at this time.

Part 2: Building with PhoneGap Build


  1. If you don’t already have one, create an account on http://build.phonegap.com.
  2. Click the “new app” button to create a new application on PhoneGap Build.
  3. Either point to a GitHub repository where you push your code for this workshop, or zip up your phonegap-workshop directory and upload it to PhoneGap Build.
  4. Click the Ready to build button.
    The iOS button will immediately turn red because the iOS build requires that you upload your Apple Developer certificate and an application provisioning profile. You can find more information here if you haven’t already signed up for the Apple Developer Program. If you don’t have an iOS device, or if you are not ready to upload your developer certificate, you can skip step 5 and keep running the application in the browser or a non iOS device.
  5. To upload your Apple developer certificate and your application provisioning profile:
    • Click the red iOS button.
    • Select “add a key” in the “No key selected” dropdown.
    • Provide a title for your developer certificate/provisioning profile combination (for example: EmployeeDirectory), select your developer certificate and provisioning profile, enter your developer certificate password, and click “submit key”.
    • Go back to the list of apps. Click the iOS button for your application again. Select your newly added key in the iOS dropdown. The iOS build will start automatically.
  6. When the build process completes, use a QR Code reader app to install the Employee Directory application on your device.

To fine tune your build preferences:

  1. In the phonegap-workshop directory, create a file namedconfig.xml file defined as follows (make the necessary adjustments for id, author, etc.):
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    <?xml version="1.0" encoding="UTF-8"?>
    <widget xmlns       = "http://www.w3.org/ns/widgets"
            xmlns:gap   = "http://phonegap.com/ns/1.0"
            id          = "org.coenraets.employeedirectory"
            versionCode = "10"
            version     = "1.1.0">
        <name>Employee Directory</name>
        <description>
            A simple employee directory application
        </description>
        <author href="http://coenraets.org" email="ccoenraets@gmail.com">
            Christophe Coenraets
        </author>
        <feature name="http://api.phonegap.com/1.0/camera"/>
        <feature name="http://api.phonegap.com/1.0/contacts"/>
        <feature name="http://api.phonegap.com/1.0/file"/>
        <feature name="http://api.phonegap.com/1.0/geolocation"/>
        <feature name="http://api.phonegap.com/1.0/media"/>
        <feature name="http://api.phonegap.com/1.0/network"/>
    </widget>
  2. If you used the GitHub approach, sync with GitHub and click the Update Code button in PhoneGap Build.
    If you used the zip file approach, zip up your phonegap-workshop directory and upload the new version to PhoneGap Build
There are many other parameters you can specify in config.xml to configure the build process. See the documentation for config.xmlhere.

Part 3: Using Native Notification


A default webview alert gives away the fact that your application is not native. In this section, we set up the basic infrastructure to display native alerts when the application is running on a device, and fall back to default browser alerts when running in the browser.

  1. In index.html, add the following script tag (as the first script tag at the bottom of the body):
    1
    <script src="phonegap.js"></script>

    This instructs PhoneGap Build to inject a platform specific version of phonegap.js at build time. In other words, phonegaps.js doesn’t need to be (and shouldn’t be) present in your project folder.

  2. In main.js, define a function named showAlert() inside the app object. If navigator.notification is available, use its alert() function. Otherwise, use the default browser alert() function.
    1
    2
    3
    4
    5
    6
    7
    showAlert: function (message, title) {
        if (navigator.notification) {
            navigator.notification.alert(message, null, title, 'OK');
        } else {
            alert(title ? (title + ": " + message) : message);
        }
    },
  3. Test the notification logic by displaying a message when the application store has been initialized: Pass an anonymous callback function as an argument to the constructor of the persistence store (the store will call this function after it has successfully initialized). In the anonymous function, invoke the showAlert() function.
    1
    2
    3
    4
    5
    6
    7
    initialize: function() {
        var self = this;
        this.store = new MemoryStore(function() {
            self.showAlert('Store Initialized', 'Info');
        });
        $('.search-key').on('keyup', $.proxy(this.findByName, this));
    }
  4. Test the application: When you run the application in the browser, you should see a standard browser alert. When you run the application on your device, you should see a native alert.

Part 4: Setting Up a Single Page Application


A single page application is a web application that lives within a single HTML page. The “views” of the application are injected into- and removed from the DOM as needed as the user navigates through the app. A single page application architecture is particularly well suited for mobile apps:

  • The absence of continual page refreshes provides a more fluid / closer to native experience.
  • The UI is entirely created at the client-side with no dependency on a server to create the UI, making it an ideal architecture for applications that work offline.

In this section, we set up the basic infrastructure to turn Employee Directory into a single page application.

  1. In index.html: remove the HTML markup inside the body tag (with the exception of the script tags).
  2. In main.js, define a function named renderHomeView() inside the app object. Implement the function to programmatically add the Home View markup to the body element.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    renderHomeView: function() {
        var html =
                "<div class='header'><h1>Home</h1></div>" +
                "<div class='search-view'>" +
                "<input class='search-key'/>" +
                "<ul class='employee-list'></ul>" +
                "</div>"
        $('body').html(html);
        $('.search-key').on('keyup', $.proxy(this.findByName, this));
    },
  3. Modify the initialize() function of the app object. In the anonymous callback function of the store constructor, call the renderHomeView() function to programmatically display the Home View.
    1
    2
    3
    4
    5
    6
    initialize: function() {
        var self = this;
        this.store = new MemoryStore(function() {
            self.renderHomeView();
        });
    }

Part 5: Using Handlebar Templates


Writing HTML fragments in JavaScript and programmatically inserting them into the DOM is tedious. It makes your application harder to write and harder to maintain. HTML templates address this issue by decoupling the UI definition (HTML markup) from your code. There are a number of great HTML template solutions: Mustache.js, Handlebar.js, and Underscore.js to name a few.

In this section, we create two templates to streamline the code of the Employee Directory application. We use Handlebar.js but the smae result can be achieved using the other HTML template solutions.

Modify index.html as follows:

  1. Add a script tag to include the handlebar.js library:
    1
    <script src="lib/handlebars.js"></script>
  2. Create an HTML template to render the Home View. Add this script tag as the first child of the body tag:
    1
    2
    3
    4
    5
    <script id="home-tpl" type="text/x-handlebars-template">
        <div class='header'><h1>Home</h1></div>
        <div class='search-bar'><input class='search-key' type="text"/></div>
        <ul class='employee-list'></ul>
    </script>
  3. Create an HTML template to render the employee list items. Add this script tag immediately after the previous one:
    1
    2
    3
    4
    5
    <script id="employee-li-tpl" type="text/x-handlebars-template">
        {{#.}}
        <li><a href="#employees/{{this.id}}">{{this.firstName}} {{this.lastName}}<br/>{{this.title}}</a></li>
        {{/.}}
    </script>

Modify main.js as follows:

  1. In the initialize() function of the app object, add the code to compile the two templates defined above:
    1
    2
    this.homeTpl = Handlebars.compile($("#home-tpl").html());
    this.employeeLiTpl = Handlebars.compile($("#employee-li-tpl").html());
  2. Modify renderHomeView() to use the homeTpl template instead of the inline HTML:
    1
    2
    3
    4
    renderHomeView: function() {
        $('body').html(this.homeTpl());
        $('.search-key').on('keyup', $.proxy(this.findByName, this));
    },
  3. Modify findByName() to use the employeeLiTpl template instead of the inline HTML:
    1
    2
    3
    4
    5
    6
    findByName: function() {
        var self = this;
        this.store.findByName($('.search-key').val(), function(employees) {
            $('.employee-list').html(self.employeeLiTpl(employees));
        });
    },
  4. Test the application.

Part 6: Creating a View Class


It’s time to provide our application with some structure. If we keep adding all the core functions of the application to the app object, it will very quickly grow out of control. In this section we create a HomeView object that encapsulates the logic to create and render the Home view.

Step 1: Create the HomeView Class

  1. Create a file called HomeView.js in the js directory, and define a HomeView class implemented as follows:
    1
    2
    3
    4
    var HomeView = function(store) {
    }
  2. Add the two templates as static members of HomeView.
    1
    2
    3
    4
    5
    6
    7
    var HomeView = function(store) {
    }
    HomeView.template = Handlebars.compile($("#home-tpl").html());
    HomeView.liTemplate = Handlebars.compile($("#employee-li-tpl").html());
  3. Define an initialize() function inside the HomeView class. Define a div wrapper for the view. The div wrapper is used to attach the view-related events. Invoke the initialize() function inside the HomeView constructor function.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    var HomeView = function(store) {
        this.initialize = function() {
            // Define a div wrapper for the view. The div wrapper is used to attach events.
            this.el = $('<div/>');
            this.el.on('keyup', '.search-key', this.findByName);
        };
        this.initialize();
    }
    HomeView.template = Handlebars.compile($("#home-tpl").html());
    HomeView.liTemplate = Handlebars.compile($("#employee-li-tpl").html());
  4. Move the renderHomeView() function from the app object to the HomeView class. To keep the view reusable, attach the html to the div wrapper (this.el) instead of the document body. Because the function is now encapsulated in the HomeView class, you can also rename it from renderHomeView() to just render().
    1
    2
    3
    4
    this.render = function() {
        this.el.html(HomeView.template());
        return this;
    };
  5. Move the findByName() function from the app object to the HomeView class.
    1
    2
    3
    4
    5
    this.findByName = function() {
        store.findByName($('.search-key').val(), function(employees) {
            $('.employee-list').html(HomeView.liTemplate(employees));
        });
    };

Step 2: Using the HomeView class

  1. In index.html, add a script tag to include HomeView.js (just before the script tag for main.js):
    1
    <script src="js/HomeView.js"></script>
  2. Remove the renderHomeView() function from the app object.
  3. Remove the findByName() function from the app object.
  4. Modify the initialize function() to display the Home View using the HomeView class:
    1
    2
    3
    4
    5
    6
    initialize: function() {
        var self = this;
        this.store = new MemoryStore(function() {
            $('body').html(new HomeView(self.store).render().el);
        });
    }

Part 7: Adding Styles and Touch-Based Scrolling


Step 1: Style the Application

  1. Add the Source Sans Pro font definition to the head of index.html
    1
    <script src="css/source-sans-pro.js"></script>

    Source Sans Pro is part of the free Adobe Edge Web Fonts.

  2. Add styles.css to the head of index.html
    1
    <link href="css/styles.css" rel="stylesheet">
  3. In index.html, modify the home-tpl template: change the search-key input type from text to search.
  4. Test the application. Specifically, test the list behavior when the list is bigger than the browser window (or the screen)

Step 2: Native Scrolling Approach

  1. Modify the home-tpl template in index.html. Add a div wrapper with a scroll class around the ul element with a scroll:
    1
    2
    3
    4
    5
    <script id="home-tpl" type="text/x-handlebars-template">
        <div class='header'><h1>Home</h1></div>
        <div class='search-bar'><input class='search-key' type="search"/></div>
        <div class="scroll"><ul class='employee-list'></ul></div>
    </script>
  2. Add the following class definition to css/styles.css:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    .scroll {
        overflow: auto;
        -webkit-overflow-scrolling: touch;
        position: absolute;
        top: 84px;
        bottom: 0px;
        left: 0px;
        right: 0px;
    }
If the platforms you target support touch-based scrolling of fixed regions, this approach is all you need (you can skip step 3 below). If not, you’ll need to implement a programmatic approach, typically with the help of a library such as iScroll.

Step 3: iScroll Approach

  1. Add a script tag to include the iscroll.js library:
    1
    <script src="lib/iscroll.js"></script>
  2. In HomeView.js, modify the findByName() function: Instantiate an iScroll object to scroll the list of employees returned. If the iScroll object already exists (), simply refresh it to adapt it to the new size of the list.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    this.findByName = function() {
        store.findByName($('.search-key').val(), function(employees) {
            $('.employee-list').html(HomeView.liTemplate(employees));
            if (self.iscroll) {
                console.log('Refresh iScroll');
                self.iscroll.refresh();
            } else {
                console.log('New iScroll');
                self.iscroll = new iScroll($('.scroll', self.el)[0], {hScrollbar: false, vScrollbar: false });
            }
        });
    };
More information on iScroll is available here.

Part 8: Highlighting Tapped or Clicked UI Elements


  1. In styles.css, add a tappable-active class definition for tapped or clicked list item links. The class simply highlights the item with a blue background:
    1
    2
    3
    4
    li>a.tappable-active {
        color: #fff;
        background-color: #4286f5;
    }
  2. In main.js, define a registerEvents() function inside the app object. Add a the tappable_active class to the selected (tapped or clicked) list item:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    registerEvents: function() {
        var self = this;
        // Check of browser supports touch events...
        if (document.documentElement.hasOwnProperty('ontouchstart')) {
            // ... if yes: register touch event listener to change the "selected" state of the item
            $('body').on('touchstart', 'a', function(event) {
                $(event.target).addClass('tappable-active');
            });
            $('body').on('touchend', 'a', function(event) {
                $(event.target).removeClass('tappable-active');
            });
        } else {
            // ... if not: register mouse events instead
            $('body').on('mousedown', 'a', function(event) {
                $(event.target).addClass('tappable-active');
            });
            $('body').on('mouseup', 'a', function(event) {
                $(event.target).removeClass('tappable-active');
            });
        }
    },
  3. Invoke the registerEvents() function from within the app object’s initialize() function.
  4. Test the application.

Part 9: View Routing


In this section, we add an employee details view. Since the application now has more than one view, we also add a simple view routing mechanism that uses the hash tag to determine whether to display the home view or the details view for a specific employee.

Step 1: Create the employee template

Open index.html and add a template to render a detailed employee view:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script id="employee-tpl" type="text/x-handlebars-template">
    <div class='header'><a href='#' class="button header-button header-button-left">Back</a><h1>Details</h1></div>
    <div class='details'>
        <img class='employee-image' src='img/{{firstName}}_{{lastName}}.jpg' />
        <h1>{{firstName}} {{lastName}}</h1>
        <h2>{{title}}</h2>
        <span class="location"></span>
        <ul>
            <li><a href="tel:{{officePhone}}">Call Office<br/>{{officePhone}}</a></li>
            <li><a href="tel:{{cellPhone}}">Call Cell<br/>{{cellPhone}}</a></li>
            <li><a href="sms:{{cellPhone}}">SMS<br/>{{cellPhone}}</a></li>
        </ul>
    </div>
</script>

Step 2: Create the EmployeeView class

  1. Create a file called EmployeeView.js in the js directory, and define an EmployeeView class implemented as follows:
    1
    2
    3
    4
    var EmployeeView = function() {
    }
  2. Add the template as a static member of EmployeeView.
    1
    2
    3
    4
    5
    6
    var EmployeeView = function() {
    }
    EmployeeView.template = Handlebars.compile($("#employee-tpl").html());
  3. Define an initialize() function inside the HomeView class. Define a div wrapper for the view. The div wrapper is used to attach the view related events. Invoke the initialize() function inside the HomeView constructor function.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    var EmployeeView = function(employee) {
        this.initialize = function() {
            this.el = $('<div/>');
        };
        this.initialize();
     }
    EmployeeView.template = Handlebars.compile($("#employee-tpl").html());
  4. Define a render() function implemented as follows:
    1
    2
    3
    4
    this.render = function() {
        this.el.html(EmployeeView.template(employee));
        return this;
    };
  5. In index.html, add a script tag to include EmployeeView.js (just before the script tag for main.js):
    1
    <script src="js/EmployeeView.js"></script>

Step 3: Implement View Routing

  1. In the app’s initialize() function, define a regular expression that matches employee details urls.
    1
    this.detailsURL = /^#employees\/(\d{1,})/;
  2. In the app’s registerEvents() function, add an event listener to listen to URL hash tag changes:
    1
    $(window).on('hashchange', $.proxy(this.route, this));
  3. In the app object, define a route() function to route requests to the appropriate view:
    • If there is no hash tag in the URL: display the HomeView
    • If there is a has tag matching the pattern for an employee details URL: display an EmployeeView for the specified employee.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    route: function() {
        var hash = window.location.hash;
        if (!hash) {
            $('body').html(new HomeView(this.store).render().el);
            return;
        }
        var match = hash.match(app.detailsURL);
        if (match) {
            this.store.findById(Number(match[1]), function(employee) {
                $('body').html(new EmployeeView(employee).render().el);
            });
        }
    }
  4. Modify the initialize() function to call the route() function:
    1
    2
    3
    4
    5
    6
    7
    8
    initialize: function() {
        var self = this;
        this.detailsURL = /^#employees\/(\d{1,})/;
        this.registerEvents();
        this.store = new MemoryStore(function() {
            self.route();
        });
    }
  5. Test the application.

Part 10: Using the Location API


In this section, we add the ability to tag an employee with his/her location information. In this sample application, we display the raw information (longitude/latitude) in the employee view. In a real-life application, we would typically save the location in the database as part of the employee information and show it on a map.

The code below works when running the application as a PhoneGap app on your device. It should also work in Chrome on the desktop when the page is served with the http:// protocol, and in Firefox, regardless of the protocol (http:// or file://).
  1. In index.html, add the following list item to the employee-tpl template:
    1
    <li><a href="#" class="add-location-btn">Add Location</a></li>
  2. In the initialize() function of EmployeeView, register an event listener for the click event of the Add Location list item:
    1
    this.el.on('click', '.add-location-btn', this.addLocation);
  3. In EmployeeView, define the addLocation event handler as follows:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    this.addLocation = function(event) {
        event.preventDefault();
        console.log('addLocation');
        navigator.geolocation.getCurrentPosition(
            function(position) {
                $('.location', this.el).html(position.coords.latitude + ',' + position.coords.longitude);
            },
            function() {
                alert('Error getting location');
            });
        return false;
    };
  4. Test the Application

Part 11: Using the Contacts API


In this section, we use the PhoneGap Contacts API to provide the user with the ability to add an employee to the device’s contact list.

The code below only works when running the application on your device as a PhoneGap app. In other words, you can’t test it in a browser on the desktop.
  1. In index.html, add the following list item to the employee template:
    1
    <li><a href="#" class="add-contact-btn">Add to Contacts</a></li>
  2. In the initialize() function of EmployeeView, register an event listener for the click event of the Add to Contacts list item:
    1
    this.el.on('click', '.add-contact-btn', this.addToContacts);
  3. In EmployeeView, define the addToContacts event handler as follows:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    this.addToContacts = function(event) {
        event.preventDefault();
        console.log('addToContacts');
        if (!navigator.contacts) {
            app.showAlert("Contacts API not supported", "Error");
            return;
        }
        var contact = navigator.contacts.create();
        contact.name = {givenName: employee.firstName, familyName: employee.lastName};
        var phoneNumbers = [];
        phoneNumbers[0] = new ContactField('work', employee.officePhone, false);
        phoneNumbers[1] = new ContactField('mobile', employee.cellPhone, true); // preferred number
        contact.phoneNumbers = phoneNumbers;
        contact.save();
        return false;
    };
  4. Test the Application

Part 12: Using the Camera API


In this section, we use the PhoneGap Camera API to provide the user with the ability to take a picture of an employee, and use that picture as the employee’s picture in the application. We do not persist that picture in this sample application.

The code below only works when running the application on your device as a PhoneGap app. In other words, you can’t test it in a browser on the desktop.
  1. In index.html, add the following list item to the employee template:
    1
    <li><a href="#" class="change-pic-btn">Change Picture</a></li>
  2. In the initialize() function of EmployeeView, register an event listener for the click event of the Change Picture list item:
    1
    this.el.on('click', '.change-pic-btn', this.changePicture);
  3. In EmployeeView, define the changePicture event handler as follows:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    this.changePicture = function(event) {
        event.preventDefault();
        if (!navigator.camera) {
            app.showAlert("Camera API not supported", "Error");
            return;
        }
        var options =   {   quality: 50,
                            destinationType: Camera.DestinationType.DATA_URL,
                            sourceType: 1,      // 0:Photo Library, 1=Camera, 2=Saved Photo Album
                            encodingType: 0     // 0=JPG 1=PNG
                        };
        navigator.camera.getPicture(
            function(imageData) {
                $('.employee-image', this.el).attr('src', "data:image/jpeg;base64," + imageData);
            },
            function() {
                app.showAlert('Error taking picture', 'Error');
            },
            options);
        return false;
    };
  4. Test the Application

Part 13: Sliding Pages with CSS Transitions


  1. Add the following classes to styles.css:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    .page {
        position: absolute;
        width: 100%;
        height: 100%;
        -webkit-transform:translate3d(0,0,0);
    }
    .stage-center {
        top: 0;
        left: 0;
    }
    .stage-left {
        left: -100%;
    }
    .stage-right {
        left: 100%;
    }
    .transition {
        -moz-transition-duration: .375s;
        -webkit-transition-duration: .375s;
        -o-transition-duration: .375s;
    }
  2. Inside the app object, define a slidePage() function implemented as follows:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    slidePage: function(page) {
        var currentPageDest,
            self = this;
        // If there is no current page (app just started) -> No transition: Position new page in the view port
        if (!this.currentPage) {
            $(page.el).attr('class', 'page stage-center');
            $('body').append(page.el);
            this.currentPage = page;
            return;
        }
        // Cleaning up: remove old pages that were moved out of the viewport
        $('.stage-right, .stage-left').not('.homePage').remove();
        if (page === app.homePage) {
            // Always apply a Back transition (slide from left) when we go back to the search page
            $(page.el).attr('class', 'page stage-left');
            currentPageDest = "stage-right";
        } else {
            // Forward transition (slide from right)
            $(page.el).attr('class', 'page stage-right');
            currentPageDest = "stage-left";
        }
        $('body').append(page.el);
        // Wait until the new page has been added to the DOM...
        setTimeout(function() {
            // Slide out the current page: If new page slides from the right -> slide current page to the left, and vice versa
            $(self.currentPage.el).attr('class', 'page transition ' + currentPageDest);
            // Slide in the new page
            $(page.el).attr('class', 'page stage-center transition');
            self.currentPage = page;
        });
    },
  3. Modify the route() function as follows:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    route: function() {
        var self = this;
        var hash = window.location.hash;
        if (!hash) {
            if (this.homePage) {
                this.slidePage(this.homePage);
            } else {
                this.homePage = new HomeView(this.store).render();
                this.slidePage(this.homePage);
            }
            return;
        }
        var match = hash.match(this.detailsURL);
        if (match) {
            this.store.findById(Number(match[1]), function(employee) {
                self.slidePage(new EmployeeView(employee).render());
            });
        }
    },

    Thanks , Keep Coding 🙂