December 30, 2008

A Quick Reference for how to create QuickConnectiPhone applications

Posted in iPhone development tagged JavaScript, module, QuickConnect, tutorial at 8:24 pm by tetontech

This posting is also available as a page on the QuickConnect wiki

Because QuickConnectiPhone, like the other members of the QuickConnectFamily, is an application framework much of what you would normally need to do to create and application is already done for you.  It is modular in nature and handles all of the communication between the modules.  You create your functionality as discrete mini-modules that either interact with, get, or set data, display information, or do validation of data.  These mini-modules are then called by the framework in the order that you state in response to ahandleRequest function call.  Below are the three steps followed when adding or creating functionality for your application.  These steps are the same for all members of the QuickConnectFamily of frameworks.  Follow these steps.

1. Call the handleRequest function as the result of an event.  You can either make the linkage between the event directly or from within an event handler that Dashcode creates for you.  There are two parameters for the handleRequest function.
   1. aCmd – a string that is a command indicator.  These should be unique to the functionality you desire to be executed.
   2. paramArray – an array of parameters that you want to be available later in the code that will handle the request.  These could be, but are not limited to, the object triggering the event, an event object, or anything else you may need.
   3. An example of calling this function would be handleRequest(‘userData’) which could cause data to be retrieved and displayed.
2. Create one or more mappings of the command to specific functions you want called every time handleRequest is passed the command.  These mapping calls are made in the mappings.js file included in the framework.  There is a different mapping function for each type of mini-module.  All of these mapping functions have two parameters.
   1. aCmd – a string that is the command the mini-module is to be mapped to.  This corresponds with the aCmd parameter ofhandleRequest.
   2. aControlFunction – a mini-module of the correct type, see below, that the framework is to call when the command is passed to handleRequest.
      1. mapCommandToBCF – maps your command to a mini-module that will get, set, or manipulate data called a Business Control Function (BCF).  You can have any number of these mappings in a row for a command.  The framework calls them in the order that you put them in the file.
      2. mapCommandToVCF – maps your command to a min-module that displays data or modifies the user interface in some way called a View Control Function (VCF).  You can have any number of these mappings in a row for a command.  The framework calls them in the order that you put them in the file.
      3. mapCommandToValCF – maps your command to a mini-module that you use to validate the parameters passed to the handleRequest function called a Validation Control Function (ValCF).  You can have any number of these mappings in a row for a command.  The framework calls them in the order that you put them in the file. an example of a ValCF would be one for a login command that validated the user name and password included in the paramArray of thehandleRequest function.
      4. mapCommandToECF – maps your command to a mini-module used to handle errors called an Error Control Function (ECF).You can have any number of these mappings in a row for a command.  The framework calls them in the order that you put them in the file.  To follow the login command example used in #3, if the user name or password failed validation for some reason any ECF’s that you map to the login command will be called by the framework on validation failure.  You could then display some helpful message for the user.
3. Create the mini-modules to be called as listed in the mappings for the command.  These are implemented in the functions.js file as standard JavaScript functions.  There is a suggested naming convention.  The name should end with the shorthand for the type of mini-module it is.  For example, a Business Control Function doing a login check would be called loginBCF.  Each one of these functions should do one thing.  Remember that you can have any number of them and the framework will call them for you in the sequence you defined the mappings in the mappings.js file.  BCF’s and ValCF’s are always created with one parameter.  The framework uses this parameter to pass your BCF the parameters array you created and passed to the handleRequest function.  VCF’s are always created with two parameters.  The first will be the data accumulated by the calls to your BCF’s and the second is the same parameters array that was passed to your BCF’s and ValCF’s.  ECF’s also have one parameter.  It is a descriptor string for the error.  You con choose to use it in your control function or not. Examples of these types of control functions are available in the Examples directory of the download.

Permalink 5 Comments