QuickConnect iPhone: an iPhone UIWebView hybrid framework

May 28, 2008

QuickConnect iPhone: an iPhone UIWebView hybrid framework

Having seen the interest in the UIWebView post I made a while back, a followup posting on the framework that includes the class discussed in that posting seems to be needed. I created this framework so that you don’t have to reinvent the wheel when you start creating iPhone hybrid applications. An Objective-C version of this framework is also in the works. I look forward to receiving feedback from you.

A new version of QuickConnectiPhone is now available.  To see the new functionality that is in the current shipping versions look here. 

For a QuickStart on how to use QuickConnect look here. 

This posting is just a brief overview of the framework to give you an idea of how you can use it. The download of the framework, select the iPhone download out of the family, includes a simple example application. The framework is open source and is licensed under lgpl so you can use it in your free application or one you decide to charge for.

The QuickConnect iPhone framework is designed to make iPHone hybrid applications easy to create and yet use as little processing power and memory as possible. The framework is distributed as Xcode and Dashcode projects that you can drop into each of those applications. When you do they become available in the gallery of project types.

These two new project types allow you to create and test your application from within Dashcode and then move it into Xcode, compile it, run it, and install it directly onto your device. No internet connection is then required to use your application.

The framework includes a javascript wrapper to the SQLite database that is embedded in WebKit, the engine used by the UIWebView class. This wrapper, called a Data Access Object (DAO), allows you to make calls to the database using two simple methods, getData and setData. You use getData to do queries and setData to do updates, insertions, and other modifications to the database. The result of a query is returned to you as a standard JavaScript array and other information is stored in the DAO such as any error numbers, error messages, the field names and their indices, etc. If you have inserted a record into a table and the table has an auto incrementing primary key field the DAO also stores the newly created key value. All of this is done without you needing to know the peculiarities of interacting with SQLite. For example,in WebKit all of the actual API calls to the database are asynchronous. You don’t need to worry about this since the framework and the DAO take care of this for you.

It must be noted that beta 5 of the iPhone OS 2.0 does not yet have the capability to interact with the SQL database from within JavaScript. It does work from within the simulators accessible from Xcode and Dashcode. A defect has been reported to Apple and I am hoping the functionality will be included in an upcoming beta release.

If you choose to retrieve remote data from a web server the QuickConnect iPhone framework supplies you with a Server Access Object (SAO). This SAO behaves like the DAO but wraps AJAX calls instead of database calls. You use it the same way as the DAO. It has a getData function that uses a GET type of request and a setData that is a POST type of request.

Since your application is running as a hybrid application you can use the SAO to make calls to any number of servers in any number of locations in your application. This is different than if you were making an AJAX call from within a browser. In that case you can only request data from the server that the current page originated from. Since you can now request data from any server you wish you will need to make sure the data you received is secure. The framework supplies you with security functions to make this easy for you.

The QuickConnect iPhone framework allows you to create what are called control functions. The types of these control functions are:

• Validation Control Functions (ValCF’s) – You use these to validate user input. You can have zero, one or more ValCF’s for each user interaction with your application.
• Business Control Functions(BCF’s) – This is where you make a call the Data Access Objects’ (DAO) methods to query or modify the database. There is one of these per user interaction.
• View Control Functions (VCF’s) – These are where the screen is updated for the user and other ‘view’ type functionality is defined. For example you may want to update some number of global variables or the client-side Session object supplied by the framework. You can have one or more VCF’s per user interaction.
• Error Control Functions(ECF’s) – Zero, one, or more of these functions can be applied to a command. This is where error handling is done. These errors may be due to user interaction or, if you choose to retrieve data from a web server, from a web server.
• Security Control Functions(SCF’s) – Zero, one, or more of these functions can be applied to a request to a web server to ensure that the data received has not been interfered with via something like a man-in-the-middle attack. The example application doesn’t access a remote server so there are none created or mapped.

The framework uses a Command/Behavior paradigm. This allows you to create each of these type of functions in the provided functions.js file, or any other file you wish, and then place a call to the mapping function that will map your command to the control function. Below are the example mappings and control functions from the example application included in the QuickConnect iPhone download. This is just a partial example. To see the full example please download the framework.

/*
*
* This file is organized by the command being handled.
*/

mapCommandToValidation("setName",validateNameInputValCF);
mapCommandToBCF('setName', setNameBCF);
mapCommandToView('setName', displayNameVCF);
mapErrorToControl('setName', dbError);

mapCommandToBCF('getName', getNameBCF);
mapCommandToView('getName', displayNameVCF);
mapErrorToControl('getName', dbError);

 

mapCommandToBCF('clearName', dropTableBCF);
mapCommandToView('clearName', displayPromptVCF);
mapErrorToControl('clearName', dbError);


/*
* This validation function ensures that the name field is not empty
*/
function validateNameInputValCF(){
if(document.getElementById('nameInput') != null){
//retrieve the name and remove any white space
//from the beginning and end of the field values if any
var name = trim(document.getElementById('nameInput').value);
if(name != ''){
return true;
}
}
return false;
}

/*
*
*
* Business Control Functions
*
*
*/

function setNameBCF(){

//retrieve the welcome name and remove any white space
//from the beginning and end of the fields' values
var userName = trim(document.getElementById('nameInput').value);
var params = [userName];
//insert the name into the database
database.setData('INSERT OR REPLACE INTO names (id, name) values( 1, ?)', params);
}

function getNameBCF(){
//document.getElementById('displayName').innerHTML = database.getData;
//document.getElementById('nameDisplay').innerHTML = 'getting Name '+window['openDatabase'];
database.getData('SELECT name FROM names WHERE id=1');
//return nothing since database query results are handled asynchronously
}

function dropTableBCF(){
database.setData("DROP TABLE names");
}

/*
*
*
* View Control Functions
*
*
*/

/*
* This function displays a name if one was found in the database or
* if a name was just inserted into the database.
*/
function displayNameVCF(result){
var aName = "";
var data = result.getData();
//if the result has data then this data must have been retrieved from the database
if(data){
if(data.length > 0){
aName = data[0][0];
}
//no name was found in the database
else{
displayPromptVCF(data);
return;
}
}
//there must have been an update done
else{
aName = trim(document.getElementById('nameInput').value);
}
document.getElementById('nameDisplay').innerHTML = aName;
document.getElementById('nameInput').value = "";
}
/*
* This function displays to the user that they need to enter a name for display since no
* stored value could be found.
*/
function displayPromptVCF(data){
aName = "Please enter a name to be displayed.";
document.getElementById('nameDisplay').innerHTML = aName;
document.getElementById('nameInput').value = "";
}

/*
*
*
* Security Control Functions
*
*
*/

//Since no there is no accessing of data from servers there are no security control functions in this example

/*
*
*
* Error Control Functions
*
*/

 

function dbError(){
displayPromptVCF();
}

To see the full example and how the framework is embedded in an Objective-C application and what the other parts of the framework are please download the framework.

Permalink