The trick is, once you select that option a project is created and opened just fine, but you MUST actually Run the application first to cause the special www folder (specific to PhoneGap projects and containing the main .js file PhoneGap needs to work) to be created in the same folder as the .xcodeproject file just created.

The instructions do mention executing the project and that you will get an error at that point, but don’t make it entirely clear that the important www folder will actually be created at that step. If you’re like me, you might decide to skip that instruction because you know it’s not going to work yet anyway since PhoneGap needs the www folder copied in. Yes, I can admit I did this the first time . Then you will probably try to follow the rest of the instructions to copy that www folder in and find that it’s not there. My personal assumption when I did this the first time is that the www folder was getting created for me when I selected the new Cordova-based Application option. Now that I have more experience, I can see how you may not ALWAYS want that www folder created upon project creation, such as the case where you are copying an existing one in, however I will have to follow-up more on this to see if there are changes coming in this workflow.

To illustrate, after creating your Cordova-based Application in XCode, if you right click on the root of the project in XCode and say Show in Finder, you will see this:

But after you actually Run the project in XCode and receive errors, then stop and right-click again on that root project in XCode to Show in Finder, you will the www folder was in fact created and is ready to copy in to XCode:

If you’re a developer that has run into this yourself (not one of those that always follows specific directions and never makes ANY assumptions ) then I hope this helped you quickly get to the bottom of it .

NOTE: This is specific to creating a brand new project, not porting over an existing www folder that already had the necessary contents where there is no need for a default one to be created.

What is it?

The crux of PhoneGap is essentially a big ‘ol .js file (per platform, separate one for iOS vs Android etc) along with some simple native code to enable it to work. In the main JavaScript file (phonegap.js or cordova.js) are a bunch of functions that give you access to native features including the camera, compass, accelerometer, file system, storage access, media capture, audio playback, notifications, contacts and network connection status etc, similar to what Adobe AIR APIs offer, with the addition of a couple more. You write your applications in HTML/JavaScript and use CSS to style them. PhoneGap apps are wrapped in a native web container component, which is why your HTML/JS/CSS work. This also means there is a dependency for your phone’s browser to be based on the WebKit engine. This really isn’t an issue though since WebKit is the default for iOS, Android, BlackBerry Tablet OS and webOS currently. A great overview of commonly asked questions about PhoneGap can be found on my teammate Andy Trice’s blog, as well as a bunch of other great PhoneGap posts, so definitely check out his blog for heaps of good content.

How Does it Work?

The API functions in the phonegap.js (or most recently cordova.js) files call native plugin/extension code to provide the access to the native features through JavaScript exec calls. If you’re an AIR developer, it’s similar to the AIR Native Extensions model, except in PhoneGap they’re called plugins, and the set of APIs listed above (notifications, compass etc) are included and set up for you by default in the PhoneGap download. There are a bunch of other open source plugins available too which can easily be added to your project, or if you don’t find one you need, they’re easy to write. Here you can find instructions on how to write one for Android, and here for iOS. You can see that the JavaScript exec calls for iOS use .h/.m files for the actual native implementation, and .java for Android.

When you’re ready to use one of the APIs in your application, it’s very straightforward and easy to use. Here’s an example of adding a notification to your application:

Code Example

...
    function showAlert() {
        navigator.notification.alert(
            'You are the winner!',  // message
            alertDismissed,         // callback
            'Game Over',            // title
            'Done'                  // buttonName
        );
    }
...

Here’s the result:

You will find that all of the APIs are accessed through a navigator variable (declared in the phonegap.js file). To see examples of how to use all of them, check out the nicely done API reference docs.

If you’re curious of how this works underneath, here’s the notification code snippet straight out of the cordova.js file (NOTE: remember phonegap and cordova are currently the same library, so if you download it now you may find that your main API files are named cordova.js file instead of phonegap.js):

phonegap.js Source for Notifications

...
/**
 * Open a native alert dialog, with a customizable title and button text.
 *
 * @param {String} message              Message to print in the body of the alert
 * @param {Function} completeCallback   The callback that is called when user clicks on a button.
 * @param {String} title                Title of the alert dialog (default: Alert)
 * @param {String} buttonLabel          Label of the close button (default: OK)
 */
Notification.prototype.alert = function(message, completeCallback, title, buttonLabel) {
    var _title = title;
    if (title == null || typeof title === 'undefined') {
        _title = "Alert";
    }
    var _buttonLabel = (buttonLabel || "OK");
    <strong>Cordova.exec(completeCallback, null, "org.apache.cordova.notification", "alert", [message,{ "title": _title, "buttonLabel": _buttonLabel}]);</strong>
};

The above code shows the notification alert function definition to use for performing a native alert notification on iOS. The important line there is the Cordova.exec(…) call, which will use the native plugin code for iOS or Java to perform the notification. If you’re extra curious and want to see what the native code looks like for this, you can open the Notification.java or CDVNotification.m files such as shown (note: you need to download the actual cordova/phonegap project source from github here to view the source files for the core plugins. This is only necessary if you wish to view them or want to make your own custom changes to them, typically you would just install from here). I pasted a couple snippets from the native code files below to give an idea:

Java Source for Notifications

public PluginResult execute(String action, JSONArray args, String callbackId) {
    PluginResult.Status status = PluginResult.Status.OK;
    String result = "";   

    try {
      ...
      else if (action.equals("alert")) {
        this.alert(args.getString(0),args.getString(1),args.getString(2), callbackId);
        PluginResult r = new PluginResult(PluginResult.Status.NO_RESULT);
        r.setKeepCallback(true);
        return r;
      }
...

Objective-C Source for Notifications

...
- (void) alert:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options
{
    int argc = [arguments count];

	NSString* callbackId = argc > 0? [arguments objectAtIndex:0] : nil;
	NSString* message = argc > 1? [arguments objectAtIndex:1] : nil;
	NSString* title   = argc > 2? [arguments objectAtIndex:2] : nil;
	NSString* buttons = argc > 3? [arguments objectAtIndex:3] : nil;

	if (!title) {
        title = NSLocalizedString(@"Alert", @"Alert");
    }
	if (!buttons) {
        buttons = NSLocalizedString(@"OK", @"OK");
    }

	CDVAlertView *alertView = [[CDVAlertView alloc]
							  initWithTitle:title
							  message:message
							  delegate:self
							  cancelButtonTitle:nil
							  otherButtonTitles:nil];

	alertView.callbackId = callbackId;

	NSArray* labels = [buttons componentsSeparatedByString:@","];
	int count = [labels count];

	for(int n = 0; n < count; n++)
	{
		[alertView addButtonWithTitle:[labels objectAtIndex:n]];
	}

	[alertView show];
	[alertView release];
}
...

Common Questions

• What kind of UI Components does PhoneGap offer? PhoneGap does not offer UI Components, they leave that implementation up to you with your choice of HTML/JS/CSS or some other UI frameworks available like Twitter Bootstrap, jQuery Mobile, Kendo UI etc…
• How can I consume data in a PhoneGap app? The same way you consume data from a web application – REST, JSON, SOAP etc.
• What’s the difference between PhoneGap and Cordova? Cordova is the Apache Open Source project behind PhoneGap. If this is confusing to you, please read this post!
• What kind of development environment do I need? You can develop in your editor of choice on any platform. There are some workflow tips I can provide and will do so in the next post with my choices for editing, debugging etc. Once you have created your app in your platform of choice, you can just upload the source directly from your source control system or via zip file to PhoneGap Build as the screenshot below shows and it will create a ready to install package for all of the different platforms.

More Resources

Details on the events are below:

Tampa Meetup
Orlando Meetup

There were only 10 spots left in the Tampa meetup when I last checked, so if you’re interested, be sure to sign up now !!

Secondly, if you’re in or around the Dallas area, be sure to visit Greg Wilson and Jon Campos at the Flex User Group meeting on April 19, 2012. Details about the event can be found here!

dpi
minResolution
aspectRatio

You can combine these attributes as well to get the best possible image selected. It’s very easy to implement, you simple create an MXML component based on the SplashScreenImage property and include as many SplashScreenImageSource objects to cover the number of situations needed. For example, in the following code I’m setting different images depending on both dpi and aspectRatio properties. Note that this example makes an assumption about tablets generally being 160 DPI (thus needing the bigger image), the 320 DPI being the iPhone 4 and above and most android phones at 240 and setting the image based on that. It also assumes that I want to use the landscape version of the image when the aspectRatio happens to be landscape on startup. You could also use the minResolution to further ensure that the 160 DPI is indeed a tablet etc and that will cause the the stage width and stage height to be compared on startup to find the largest number of the two. If it’s equal to or greater than your minResolution setting, it will select that image for the splash screen.

DynamicSplashScreen.mxml

<?xml version="1.0" encoding="utf-8"?>
<s:SplashScreenImage xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark">
	<s:SplashScreenImageSource dpi="160" aspectRatio="portrait" source="@Embed('assets/texas-768x1024.jpg')"/>
	<s:SplashScreenImageSource dpi="240" aspectRatio="portrait" source="@Embed('assets/texas-480x810.jpg')"/>
	<s:SplashScreenImageSource dpi="320" aspectRatio="portrait" source="@Embed('assets/texas-640x960.jpg')"/>
        <s:SplashScreenImageSource dpi="160" aspectRatio="landscape" source="@Embed('assets/texas-1024x768.jpg')"/>
	<s:SplashScreenImageSource dpi="240" aspectRatio="landscape" source="@Embed('assets/texas-810x480.jpg')"/>
	<s:SplashScreenImageSource dpi="320" aspectRatio="landscape" source="@Embed('assets/texas-960x640.jpg')"/>
>/s:SplashScreenImage>

Now in your main application root, you simply specify the name of your component defined above in the splashScreenImage property as follows:

<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
							xmlns:s="library://ns.adobe.com/flex/spark"
							firstView="views.FrontView"
							splashScreenImage="DynamicSplashScreen">
...
</s:ViewNavigatorApplication>

Adobe Flex to Apache Flex
Adobe Flex is now Apache Flex (in case you’ve been under a rock lately or perhaps just discovered Flex ). It’s been contributed to the Apache community and is in incubator status. Incubator status is a holding place for a new Apache project and basically a gateway to it becoming a full-fledged project after a release or two. It was great news that it was accepted recently and I have no doubt it will quickly move out of this stage into a full-fledged project. The project has an amazing amount of traction so far, and it’s awesome to see all the activity! If you want to stay on top of the latest, subscribe to the mailing list here, (note that your inbox will be flooded so you might want to use a separate email to track it, it’s a high traffic mailing list ). There are a bunch of extremely talented, well-known developers behind this project as well, which is huge and makes all the difference, in my opinion. The Open Spoon Foundation is also actively behind this project and if you aren’t aware of it, definitely make a point of checking it out. I attended the Flex Summit in December and learned a lot about the Apache process from Roy Fielding (Apache Co-Founder), with the biggest takeaway being that Apache projects are run as a meritocracy, so there is equal opportunity amongst all and that contributions of any kind, including code, bug fixes and documentation are welcome.

The State of Things…
So the big question everyone has been asking us, should we continue to build apps with Flex? I think the general consensus to be made is yes. There’s still a viable need for this technology and with the dedication and energy of the community so far I feel very positive about things. As I’ve stated before and will continue to state, as a developer you shouldn’t put all of your eggs in any one basket, and should be learning the latest technologies along with continuing your Flex development to ensure your relevance and development diversity, but Flex remains an excellent choice for the right type of application.

Here are some related links you should check out that I found very useful as a meter for what other great developers are thinking and doing:

Joseph Labrecque – Questioning the viability of Flex
Joao Saleiro – After 6 years doing Flex, am I moving to HTML5?
The Flex Show – Discussing the Future of Flex with Joseph Labrecque and Mark Ehlert

Hot Topics…
One big topic on the mailing list right now centers around a new logo for Apache Flex. The community held a contest (over 50 entries submitted!) and the submissions can be found here. The contest ended yesterday and now the voting process has begun. To vote you will need to start by subscribing to the mailing list. Once subscribed you can cast your votes with a point system defined in the mailing list. There are also some excellent summaries of what’s going on with the project being posted to this blog by Michael Schmalle (a current contributor). I would definitely make a point to skim those summaries to get a quick read on the status of things since it can be hard to keep up with the mailing list.

The following links are also useful to check out for more info:
The Flex Incubator Project
Contributors
JIRA Bug Tracking
Flex Incubator Status Page
The initial proposal from Adobe
Getting Involved

This Blog…
As far as me and my evangelism are concerned, I plan to continue to use Flex and blog about it as I have been. The 2012 Flex User Group Tour is about to start and my team will be visiting many locations over the next couple of months where we’ll discuss all the recent activity and announcements and talk about the latest 4.6 release. You can also plan on seeing some posts on other technologies as I’m exploring them myself. I will make a point of comparing them to Flex as I go along where possible. I’m also really looking forward to seeing what Adobe has in store this year to help utilize these other technologies like HTML5, JavaScript/jQuery etc and already excited by what I’ve heard! I will post information on these topics as I’m allowed .

The Game of Flex consists of 16 questions which if answered correctly, will qualify you to win a free copy of Flash Builder 4.6! Ultimately though, it’s a learning tool, where we’ve included samples and source code for all of the new 4.6 features and other useful mobile features. Click the ‘Snippet’ button to get the source code for the sample within the app, and the ‘Tutorial’ button to link to tutorials with more details on how to use a certain feature.

Be sure to check out Michael’s post about the game, and visit the official website for it here!

Sample Question

Sample Code Snippet

To get started, first check out this sample application I’ve included the source and fxp for that was written by my friend Darin Weakley over at MapQuest. He’s done a great job of showcasing the fun cool features available in this app. I’ve included some screen shots below to give an idea of what it entails:

If you have an Android device, be sure to download the showcase application for free to your device!

To implement this in your own app you will need to create yourself an app key and join the developer program here before using the APIs. It’s fast and easy. Click ‘Join Now’. Also, don’t forget to include the latest MapQuest Flash API 7.07 mobile swc file in your project (see the sample for reference). This link also has documentation and other examples on the right side of the page to check out for more info!

MapQuest Flash Maps API Quick Links

Mobile Flash Maps API
Web/Desktop Flash Maps API
OpenStreetMap Mobile Flash Maps API – more information about OpenStreetMap (OSM)
OpenStreetMap Web/Desktop Flash Maps API

Now we can build applications with this type of layout simply using built-in Flex 4.6 features! The SplitViewNavigator extends ViewNavigatorBase, so it does not reside at the root level of the application but rather at the child level similar to ViewNavigator. Note that this component can only be used in a blank Application or within a TabbedViewNavigatorApplication. Here’s an example:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark" applicationDPI="160">

	<s:SplitViewNavigator id="svn" width="100%" height="100%">
		<s:ViewNavigator id="leftNav" width="30%" height="100%" firstView="views.LeftView"/>
		<s:ViewNavigator id="rightNav" width="100%" height="100%" firstView="views.RightView"/>
	</s:SplitViewNavigator>
</s:Application>

In this case my left view and right view are simple View classes showing a list of cities to click on and some dummy data about that particular city in the detail. I’ve included the code below for reference:

LeftView.mxml

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
		xmlns:s="library://ns.adobe.com/flex/spark" title="Left View">

	<fx:Script>
		<![CDATA[
			protected function list_clickHandler(event:MouseEvent):void
			{
				(this.parentDocument as Sample).rightNav.activeView.data=list.selectedItem;
			}
		]]>
	</fx:Script>

	<s:List id="list" width="100%" height="100%" click="list_clickHandler(event)">
		<s:dataProvider>
			<s:ArrayCollection>
				<fx:String>Atlanta, GA</fx:String>
				<fx:String>Baltimore, MD</fx:String>
				<fx:String>Boston, MA</fx:String>
				<fx:String>Chicago, IL</fx:String>
				<fx:String>Dallas, TX</fx:String>
				<fx:String>Detroit, MI</fx:String>
				<fx:String>Honolulu, HI</fx:String>
				<fx:String>Los Angeles, CA</fx:String>
				<fx:String>Minneapolis, MA</fx:String>
				<fx:String>New Orleans, LA</fx:String>
				<fx:String>New York, NY</fx:String>
				<fx:String>Richmond, VA</fx:String>
				<fx:String>San Francisco, CA</fx:String>
				<fx:String>San Jose, CA</fx:String>
				<fx:String>St. Louis, MO</fx:String>
				<fx:String>Washington, DC</fx:String>
			</s:ArrayCollection>
		</s:dataProvider>
	</s:List>
</s:View>

RightView.mxml

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" title="Detail View">
	<s:layout>
		<s:VerticalLayout paddingTop="15" paddingBottom="15" paddingLeft="15" paddingRight="15" gap="5"
						  horizontalAlign="center" verticalAlign="top"/>
	</s:layout>
	<s:Label text="Click on a location on the left to explore!" visible="{data==null?true:false}"/>
	<s:Label text="Information about {this.data}" visible="{data!=null?true:false}"/>

	<s:TextArea text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur accumsan felis ac tortor aliquam iaculis. Phasellus hendrerit viverra enim, sit amet scelerisque lectus dictum at. Aenean sodales nisi sed leo congue et porttitor ligula vehicula.
Pellentesque turpis massa, suscipit vel fermentum quis, dignissim sed ipsum. Nulla aliquet libero adipiscing risus lobortis eleifend quis at velit. Duis at leo urna.
Praesent facilisis faucibus neque, ut ullamcorper lacus gravida a. Donec vel iaculis sapien."  width="90%" editable="false" visible="{data!=null?true:false}"/>
</s:View>

The resulting application:

You could also set a layout on the SplitViewNavigator container so if you wanted it to split vertically for instance, you would simply set a VerticalLayout, and adjust the height percentages with the width set to 100%, such as:

<s:SplitViewNavigator id="svn" width="100%" height="100%">
	<s:layout>
	     <s:VerticalLayout/>
	</s:layout>
	<s:ViewNavigator id="leftNav" width="100%" height="30%" firstView="views.LeftView"/>
	<s:ViewNavigator id="rightNav" width="100%" height="70%" firstView="views.RightView"/>
</s:SplitViewNavigator>

Here’s the updated layout:

This split view approach works well for landscape mode, however, in portrait mode you may want to display it a little differently since the screen width is much less to work with. There are some built-in features to help you do this. There’s an autoHideFirstViewNavigator property on the SplitViewNavigator that will automatically hide the left side view when the application receives an orientation change event to portrait.

<s:SplitViewNavigator id="svn" width="100%" height="100%" autoHideFirstViewNavigator="true">
	<s:ViewNavigator id="leftNav" width="30%" height="100%" firstView="views.LeftView"/>
	<s:ViewNavigator id="rightNav" width="100%" height="100%" firstView="views.RightView"/>
</s:SplitViewNavigator>

Now when we run it, we will see the following:

Not very useful yet though since there’s no way to navigate to a different item in our list! So we need to take this one step further and use the showViewNavigatorInPopUp function from the SplitViewNavigator to pop up our list in a Callout while in portrait mode. We can call this function from a button in the right ViewNavigator’s actionBar navigationContent for instance such as the following:

<s:SplitViewNavigator id="svn" width="100%" height="100%" autoHideFirstViewNavigator="true">
		<s:ViewNavigator id="leftNav" width="30%" height="100%" firstView="views.LeftView"/>
		<s:ViewNavigator id="rightNav" width="100%" height="100%" firstView="views.RightView" >
			<s:navigationContent>
				<s:Button id="listButton" label="List" click="svn.showFirstViewNavigatorInPopUp(listButton)"/>
			</s:navigationContent>
		</s:ViewNavigator>
</s:SplitViewNavigator>

Note: Just to clarify, in the above we are using the actionBar already implicitly defined as part of the Spark ViewNavigator container and setting the parent for the popup to the listButton, so the Callout or popup arrow will stem from that button. Here’s what the above code will look like when run in portrait mode:

At this point, we probably don’t want this button to show though when going back into landscape mode, so we’ll need to add states management to set visible to false when in landscape. One way to determine when to update the state would be to add a resize event handler and check the width and height and update the state accordingly. Our code now looks like the following:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark" applicationDPI="160" resize="application1_resizeHandler(event)">
	<fx:Script>
		<![CDATA[
			import mx.events.ResizeEvent;

			protected function application1_resizeHandler(event:ResizeEvent):void
			{
				if (width>height)
					this.currentState="landscape";
				else this.currentState="portrait";
			}
		]]>
	</fx:Script>

	<s:states>
		<s:State name="portrait"/>
		<s:State name="landscape"/>
	</s:states>

	<s:SplitViewNavigator id="svn" width="100%" height="100%" autoHideFirstViewNavigator="true">
		<s:ViewNavigator id="leftNav" width="30%" height="100%" firstView="views.LeftView"/>
		<s:ViewNavigator id="rightNav" width="100%" height="100%" firstView="views.RightView" >
			<s:navigationContent>
				<s:Button id="listButton" label="List" click="svn.showFirstViewNavigatorInPopUp(listButton)" visible.landscape="false"/>
			</s:navigationContent>
		</s:ViewNavigator>
	</s:SplitViewNavigator>
</s:Application>

Now when we run the application in landscape mode, we can see the List button is not showing in the actionBar:

You can download the source and project file for this sample application here!

Also, if you haven’t looked at this yet, Christophe and I created an extensive SplitViewNavigator-based expense tracking tablet application called XpenseIt that includes a bunch of other Flex 4.6 features as well and can be downloaded here. Here is a screenshot from that application: