QuickConnectFamily Hybrid API: QuickConnectFamily Hybrid

QuickConnectFamily Hybrid Introduction

QCFamily Hybrid is a full framework not a library. Like other full frameworks it has done most of the design and coding work for you. You need only create the functionallity that you desire for your applications.
QCFamily Hybrid allows you to write your application in HTML, CSS, and JavaScript. Use the HTML and CSS to create the user interface and JavaScript to implement the logic. Use the web skills you already have to get your idea to market quickly.

When you want to learn more about native Objective-C iOS or Android Java development take a look at the source code available from sourceForge to find a whole series of 'how to' code sets in the QCFamily Hybrid framework. The source is open and liberally licensed (BSD license).

Downloading QuickConnectFamily Hybrid

Download QCFamily Hybrid from the sourceForge site. The QCFamily Hybrid download includes numerous examples for iOS and Android developers. Look in the downloaded file for these. Well over 30 examples are included on how to use specific QCFamily Hybrid functionalities.

Creating an QCF Hybrid application for iOS using Xcode

Do the following steps OR copy and existing example project.

Step 1: Use Xcode to create a new iOS application from one of the standard templates.

Step 2: Drag the contents of the QC Hybrid directory into the project. Copy them in.

Step 3: Add in the following standard frameworks:

Accelerate
AddressBook
AddressBookUI
AudioToolbox
AVFoundation
CoreLocation
GameKit
iAd
libsqlite3.dylib
MapKit
MediaPlayer
MessageUI
StoreKit
SystemConfiguration

Step 4: Add the following files to the 'Copy Bundle Resources' list if they aren't already there

Step 5: In your application delegate header file (.h file) Change NSObject to QuickConnectViewController in the inheritance declaration

Step 6: Add this line of code to the application:didFinishLaunchingWithOptions method of your application delegate

[self addWebViewToWindow:self.window];

Step 7: Modify the index.html, main.css, and the JavaScript files to create the logic for your app

Creating an QCF Hybrid application for iOS and Android using Xcode

Step 1: Under development now

Creating an QCF Hybrid application for Android using MotoDev

Do the following steps OR copy an existing example project.

Step 1: Use MotoDev or eclipse to create a new Android application using the Google APIs

Step 2: Add the contents of the libs directory to your application's Build Path

Step 3: Add maps.jar to the build path of your application for the API level of your application. It can be found at <Android SDK Installation>/add=ons/addon_google_apis_google_inc_<API level>/libs

Step 4: In the build path editor select the Export tab and select all of the jar files from the libs directory

Step 5: Copy the contents of the Web Files directory into your application's assets directory

Step 6: Replace your application's res -> layout -> main.xml file with the main.xml file in the QC Hybrid XML directory

Step 7: Drag balloon_overlay.xml into your application's res -> layout directory

Step 8: Replace the contents of your application's AndroidManifest.xml file with the contents of the AndroidManifest.xml file in the XML Files directory

Step 9: Drag the raw directory into the res directory of your application

Step 10: Drag the drawable directory into your application's res directory

Step 11: Change the Activity of your Application to extends QCAndroid

Step 12: Import the R class in your application's Activity Class.

Step 13: Replace splash.png in the drawable directory with a background image of your choice.

Step 14: Clean the project

Step 15: Modify the index.html, main.css, and the JavaScript files to create the logic for your app

Using the Framework: First ideas

If you want to take advantage of QCFamily Hybrid's built-in library of functionality there are two major components of QC applications that you need to understand to take full advantage of the framework, stacks and control functions.

Stacks: Laying out the application flow

Stacks consist of a series of control functions (discussed below) that map out a set of specific, sequential actions that you want your application to execute. Each stack is created by mapping the individual control functions for the stack to a unique command string you can use later to refer to the stack as a whole.

Example: A stack design

Imagine that you need to require your user to login using a user name and password. You might choose 'login' for the unique command string to represent the sequence of steps. Generally with a login attempt you would want to validate the user name and password, attempt to login using this information, store something regarding the user (often this is a unique identifier of some sort), and then display some new set of behaviors available for that user. In the case of a failed login attempt your applications would usually indicate to the user that login failed.

The image below is a graphical description of this desired behavior. The string 'login' has been selected as the command. The success stack is seen on the left and the error handling is shown on the right.

Choosing a descriptive command for the behavior scenario, deciding the discrete steps for this scenario, and deciding when and how to handle errors for the scenario are how QC Family applications are designed.

Control Functions: Discrete stack actions

Each of the discrete desired behaviors described in the design of a stack are known as control functions in QC applications. To cover the types of behavior found in all modern applications QC application control functions come in four distinct types each with a specific responsibility.

Validation Control Function: ValCF

ValCF's are used to validate information supplied to the application by the user.

Business Control Function: BCF

BCF's obtain, send, or manipulate data. They may obtain data from a local database, a remote web application or service, send data to such and application or service, or perform a calculation on data it is passed.

View Control Function: VCF

VCF's update the display. Usually after data is sent, received, or calculated the user needs to be notified. View Control Functions update the screen for the user. This may be as simple as turning on a hidden string or as complicated as animating the display of an entirely new view for the user.

Error Control Function: ECF

ECF's handle cleaning up when an error has happened. This usually includes resetting variables, resetting view components, and displaying error messages.

The image below reworks the design created earlier replacing the desired steps with names for the control function for each step.

As you can see from the image above each control function is intended to be a module. This means that it does one thing, does it well, and is complete. Being modular one control function should never call another control function directly since then un-needed dependencies would be created between them. The framework will call all of the control functions for your application.

Building Stacks: Mapping commands to control functions

Stacks, as seen above, consist of a series of control functions associated with a unique command. The QCFamily Hybrid framework provides a series of functions to make this easy. These are the qc.mapCommandTo***(aCommand, aControlFunction) functions found in the QCUtilities.js file. Each type of controle function has a matching mapCommandTo***(aCommand, aControlFunction) function.

ValCF -> qc.mapCommandToValCF(aCommand, aValidationControlFunction)
BCF -> qc.mapCommandToBCF(aCommand, aBusinessControlFunction)
VCF -> qc.mapCommandToVCF(aCommand, aViewControlFunction)
ECF -> qc.mapCommandToECF(aCommand, anErrorControlFunction)

Calls to these mappCommandTo***(aCommand, aValidationControlFunction) functions are always made in the mappings.js file to ensure they are executed after the control functions have been loaded.

Example: The login mappings

The code in the mappings.js file for the login example designed above is shown here.

Mappings of stacks also give you as an application developer one place to go to see the flow of your application. No more do you need to dig deeper and deeper into the code to find out what it does. If the stack is designed well this information is obvious in the mapping of the stack.

Another nice benefit is discovered when doing debugging. If there is a defect in a control function it is in the control function not in any of the others in the stack. Since the control functions are small and modular debugging becomes much easier.

Creating Control Functions: The behavior code

Each control function that is mapped in the mappings.js file is defined in the functions.js file to ensure proper handling of loading dependencies. The image below shows an example of how the functions mapped in the example might be defined. Each of these control functions returns one of four values.

qc.STACK_CONTINUE - This instructs the framework to execute the next control function in the stack.
qc.STACK_EXIT - This instructs the framework to terminate all further stack execution.
qc.WAIT_FOR_DATA - This instructs the framework that a call to database or remote data has been made or a call to device specific behavior such as showing a map.
any calculated data - If your BCF calculates data and that data is needed later in the stack return the value from the BCF function. The returned data will be sent by the framework to the remaining control functions in the stack.

Executing a Stack: The trigger for behavior

QC includes two functions to allow you to easily execute any stack you have already mapped and defined. qc.handleRequest(aCommand, requestParameters) is used to execute standard stacks. qc.handleError(aCommand, errorParameters) is used to execute error stacks as you have seen in the code example above. They can both be found in the QuickConnect.js file.

qc.handleRequest can be called directly from the HTML of you application if no parameters are needed but it is often called from within an onclick or other event listener. The example code below assumes that there is an HTML input of type button with its onclick listener set to 'loginFunc()'. The listener function accumulates everything the stack needs to do its work and then calls qc.handleRequest.

The code here shows an example. It collects the needed values and calls qc.handleRequest.

Assign the loginFunc function as the onclick listener for a button and the example is complete.

The QuickConnectFamily of tools has been a great deal of fun to create. QCFamily Hybrid is only one of these. I hope you will take time to look at some of the others at www.quickconnectfamily.org