API Docs for:
Show:

TBAWrapper Class

Defined in: TBAWrapper.js:1

Static class for accessing native functionality; the two publicly global variables exposed by this class and the desktop version of the JS bridge are tbaWrapper and tbaWrapperJ; so don't use these variable names elsewhere in your code Don't try accessing the tbaWrapperJ variable directly; always use tbaWrapper.

This class works in conjunction with a config.json file that handles certain things that need to be setup prior to the DOM being initialized. The config file has the following attributes:

  • window_title: The title to be given to the window; this is only applicable to the desktop version of the wrapper & will show in the window bar
  • open_full_screen: A boolean as to whether this app should open in full screen mode: only applicable to desktop version of the wrapper
  • background_color: A hex code string representing the color to show during loading of the window: only applicable to desktop verstion of the wrapper
  • preferred_width: A number representing the number of pixels in width this window should consume; is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • preferred_height: A number represenging the number of pixels in height this window should consume: is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • max_width: A number represenging the number of pixels in width this window is allowed to resize to: is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • max_height: A number represenging the number of pixels in height this window is allowed to resize to: is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • min_width: A number represenging the number of pixels in width this window is allowed to shrink to: is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • min_height: A number represenging the number of pixels in height this window is allowed to shrink to: is superseeded by open_full_screen if true: only applicable to desktop verstion of the wrapper
  • redirect_listeners: Array of Objects with the following string keys: listen_for, redir-params. When a url change is caught; it is sent back to index.html with the redir-params attached as GET data
  • registerForPushNotifications: Boolean, if true the following pushData array is taken into consideration: Only Applicable to iOS
  • pushData: Array with the following keys: registrationURL (String), the URL to send device id registration requests to. postDataString (string), url encoded post data to be sent along with the registration request. The post key deviceid is appended to the string automatically. pushRegistrationTypes (Array), array of strings representing the types of noticiations this device wants to receive. Can be "Badge", "Alert", "Sound", "NewsStandContentAvailability". Typically will just be Alert and Badge

    *Note: if you want to control the time signs up for push and send custom data with the device id (e.g. user id after they've logged in) set the registerForPushNotifications config to false, and use the registerForCustomPushNotifications function instead

Constructor

TBAWrapper

()

Defined in TBAWrapper.js:1

Methods

array2json

(
  • arr
)
String

Defined in TBAWrapper.js:1039

Light weight, internal convenience method for creating JSON strings from Objects or from Arrays.

Parameters:

  • arr Object
    • (required), An Object or an Array to turn into a JSON string

Returns:

String:
  • The JSON string representing the Object or Array that was parsed as an argument

Base64.decode

(
  • input
)
String

Defined in TBAWrapper.js:125

Function to base64 decode a string; can be useful for transmitting formatted text as GET or POST data

Parameters:

  • input String
    • The string to be decoded

Returns:

String:
  • The decoded string

Base64.encode

(
  • input
)
String

Defined in TBAWrapper.js:94

Function to base64 encode a string; can be useful for transmitting formatted text as GET or POST data

Parameters:

  • input String
    • The string to be encoded

Returns:

String:
  • The encoded string

beginTransaction

()

Defined in TBAWrapper.js:288

Begins an SQLite transaction; wrapping a series of inserts / updates in a transaction has significant performance increases for sqlite; don't forget to end your transaction.

cp

(
  • src
  • dest
)

Defined in TBAWrapper.js:454

Copy a file from source to dest. All files are stored within the documents directory of app; which in this case equates to '/'; src and dest paths must begin with '/'

Parameters:

  • src String
    • (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory
  • dest String
    • (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory

createPDF

(
  • path
  • callBack
)

Defined in TBAWrapper.js:528

Turns the current on screen visuals into PDF document

Parameters:

  • path String
    • (required), The path to the file that is to be created that resides within the documents directory where '/' is the root of the documents directory
  • callBack Function
    • (required), The function to call when the PDF has finished creating. Shouldn't have any arguments

currentOrientation

(
  • callBack
)

Defined in TBAWrapper.js:206

Function to get the current orientation of the device; helps in iOS landscape where the javascript screen.width/height still returns the portrait dimensions even if landscape If you want to listen for orientation changes; you are encouraged to use an event listener like the one below in conjunction with this method:
window.onresize = function(event) {
  tbaWrapper.currentOrientation(function(r){some change handler code...});
};

Parameters:

  • callBack Function
    • Function that accepts one String argument; Portrait, PortraitUpsideDown, LandscapeLeft, LandscapeRight

didReceiveDeviceID

(
  • did
)

Defined in TBAWrapper.js:1002

Function to receive the device ID back if the user accepts the request to allow push notifications. This function is not a call back to any other method; as the user may or may not allow push notifications.

Parameters:

  • did String
    • (required), this is the device ID returned for this app from iOS when the user accepts a request for push notifications

downloadFile

(
  • url
  • progressCallBack
  • completeCallBack
  • errorCallBack
)
String

Defined in TBAWrapper.js:312

Downloads a file from the internet asynchronously per the specified argument. Progress updates are sent to a call back function. Only 1 file can be downloading at a time

Parameters:

  • url String
    • (required), the absolute address of the external file to download
  • progressCallBack Function
    • (optional), a function with one decimal argument representing progress, and one string argument representing the file name; to execute when progress updates are received
  • completeCallBack Function
    • (optional), a function with one string argument representing the file name; to execute if the file download completes
  • errorCallBack Function
    • (optional), a function with two string arguments - one representing the file name; to execute if the download fails. The other the status code for the failure - 0 means that the download failed after the initial response from the server.

Returns:

String:
  • A unique local file name with the same filetype extension of the file specified in the URL.

endTransaction

()

Defined in TBAWrapper.js:300

Begins an SQLite transaction; wrapping a series of inserts / updates in a transaction has significant performance increases for sqlite; you must begin a transaction first

executeSQLQuery

(
  • query
  • bindings
  • callBack
)

Defined in TBAWrapper.js:235

Executes an sql query to interface with sqlite - consult http://sqlite.org/docs.html docs for syntax specifics. Subsequent queries are queued until the first one completes

Parameters:

  • query String
    • (required), the query to be executed in SQL format
  • bindings Array
    • (optional), an array of values to bind to any question marks in the query; this method uses prepared statements and automatically escapes strings so as to avoid SQL injection; e.g.: insert into foo(bar) values(?); could be a query, which would require a binding array with one value to bind to the ? place holder
  • callBack Function
    • (optional), the function to be executed when the query result is retured; Function should receive only one argument; an array of objects representing the resultset.

getDirections

(
  • lat
  • lon
)

Defined in TBAWrapper.js:979

Function to open the default iOS directions view for locations

Parameters:

  • lat Number

    lat - (required), latitude of the destination

  • lon Number

    lon - (required), longitude of the destination

getLanguageCodes

(
  • callBack
)

Defined in TBAWrapper.js:672

Function to derrive what language accents are available for the text to speech funcitonality; this list varies depending on the locale of the user and is determined at the OS level

Parameters:

  • callBack Function
    • (required), Call back funciton that receives an array in the following format as its only argument: [{code : "US", display : "US English"}...];

getSharedPhoto

(
  • photoName
  • callBack
)

Defined in TBAWrapper.js:958

Function to retrieve the base64 code for a full sized shared photo off of the device based off of the file name returned from the getSharedPhotoThumbs function

Parameters:

  • photoName String

    photoName - (required), the name of the photo as returned from the getSharedPhotoThumbs function

  • callBack Function

    callBack - (required), the call back function to execute; should only accept one argument which will be a string of the base64 code to use for the full size image

getSharedPhotoThumbs

(
  • callBack
)

Defined in TBAWrapper.js:938

Function to get a list of all photos from the shared photos on the device. The base64 data returned in the call back can be inserted into the src attribute of an image tag like this:
<img alt="Embedded Image" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..." />

Parameters:

  • callBack Function
    • (required), the call back function whose only argument is an array of key value pair objects with format: {name: "foo.png", base64data : "+tI4ZEgpzQn7RhIXia4uoX5Pl9mVtap"}

isRecording

(
  • callBack
)

Defined in TBAWrapper.js:791

Function to check if an audio recording is underway

Parameters:

  • callBack Function
    • (required), a call back function whose only argument is a boolean

isSpeaking

(
  • callBack
)
Boolean

Defined in TBAWrapper.js:688

Function to ask if the iOS or Android operating system is currently speaking

Parameters:

  • callBack Function
    • (required), the call back function to process the response from the native hook; the function should receive one boolean argument to pass the result through

Returns:

Boolean:
  • Whether the answer could be given or not depending on whether the current execution environment supports this function

jsonParse

(
  • input
)
Object

Defined in TBAWrapper.js:1029

Light weight, secure, internal convenience method for parsing JSON strings into objects; doesn't use eval; so its quite secure. https://code.google.com/p/json-sans-eval/

Parameters:

  • input String
    • (required), the JSON string to turn into an object

Returns:

Object:
  • An Object or an Array depending on the format of the input string provided

launchNativeDefaultBrowser

(
  • url
)

Defined in TBAWrapper.js:622

Function to launch a web page in the user's default browser rather than inside the wrapper window

Parameters:

  • url String
    • (required), the url of the page to load in a native browser

log

(
  • Message
)

Defined in TBAWrapper.js:582

Native console logging function; passes the argument to the console of the native system for ouput to the native console

Parameters:

  • Message String
    • (required), the message to be echoed

ls

(
  • path
  • callBack
)

Defined in TBAWrapper.js:411

List directory contents

Parameters:

  • path String
    • (required), the path relative to the documents directory for this app; '/' is the path for the root of the docs dir; everything else is relative to that. Path cannot be an empty string; must be '/' at the very list in order to list the root; or for example /mydir/ to list the contents of a directory called 'mydir' within the documents directory. All paths must contain a trailing / (e.g. /mydir/ rather than /mydir)
  • callBack Function
    • (optional), a funciton to call that accepts an array of JSON objects as its only argument containing the file names, as well as a URL that can be used to access the file from within the HTML view. e.g. [{"name" : "file.jpg", "url" : "file://docsdir/file.jpg"},...]

mkdir

(
  • path
)

Defined in TBAWrapper.js:481

Make a directory. All files are stored within the documents directory of app; which in this case equates to '/'; path must begin with '/'; this method will also create intermediate directoryies; so you can call mkdir('/some_parent/some_sub'); and if '/some_parent' doesn't exist, it will be created for you

Parameters:

  • path String
    • (required), The path to the directory that resides within the documents directory where '/' is the root of the documents directory

mv

(
  • src
  • dest
)

Defined in TBAWrapper.js:440

Move a file from source to dest. All files are stored within the documents directory of app; which in this case equates to '/'; src and dest paths must begin with '/'

Parameters:

  • src String
    • (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory
  • dest String
    • (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory

openEmailClient

(
  • subject
  • message
  • attachments
  • isMainBundle
  • to
  • cc
  • bcc
  • isHTML
)

Defined in TBAWrapper.js:1011

Function to open the native iOS email client & populate subject, message, and attachments. If the device is unable to send emails (e.g. mail app isn't setup yet) the user is notified with a generic alert.

Parameters:

  • subject String
    • (required), the subject line for the email
  • message String
    • (required), the message body for the email
  • attachments Array
    • (required), an array of JS objects with the following format: {path : "file/path.ext", mime : "type/ext", name : "foo.pdf"} where name is the desired file display name.
  • isMainBundle Boolean
    • (required), whether the supplied file path(s) from the attachment array are for the main bundle hard coded into the app; or the dynamic docs directory.
  • to Array
    • (required), an array of strings representing the intended recipients of the email
  • cc String
    • (required), an array of strings representing the intended cc recipients of the email
  • bcc String
    • (required), an array of strings representing the intended bcc recipients of the email
  • isHTML Boolean
    • (required), whether the message body is given as HTML or plain text

openGaldermaMarket

()

Defined in TBAWrapper.js:769

Function to open the Galderma Market from within the iDash framework. Most Galderma internal apps need to have an iDash button to link the user back to their main directory; firing this method will open this. Only supported on iOS Also, for the galderma market to be able to find this app in the other direction - you should add the folowing code to the node in the info.plist file - where UNIQUEAPPID = your own unique identifier that you can make up:
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string></string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>UINIQUEAPPID</string>
    </array>
  </dict>
</array>

openPDF

(
  • path
  • isMainBundle
)

Defined in TBAWrapper.js:541

Open a PDF in a native viewer

Parameters:

  • path String
    • (required), The path to the PDF that resides within the documents directory where '/' is the root of the documents directory
  • isMainBundle Boolean
    • (required), Whether this path is for the main bundle or not. If not the path is for the documents directory. The main bundle is the list of files that are dragged into the left hand file browser in Xcode and deployed at install time. Main bundle files are read only, whereas documents directory files can be written, read, and deleted.

pauseSpeech

()

Defined in TBAWrapper.js:706

Function to pause current speech utterance - has no effect if not speaking already

playRecording

(
  • path
  • callBack
)

Defined in TBAWrapper.js:837

Function to play an audio file - presumably one that has been created from the recording funcitonality; but may work for other local file types. Only supported on iOS

Parameters:

  • path String
    • (required), a path to the file to play from the documents directory; where '/' is the root of the documents directory; for iOS should end in a .m4a extension
  • callBack Function
    • (optional), the call back funciton to call when the file has finished playing

queryAPI

(
  • url
  • key
  • value
  • completeCallBack
  • errorCallBack
)

Defined in TBAWrapper.js:335

Queries a web based api to retrieve the response from that API; using native code to do this solves the crossdomain origin issue with JS. Queries are synchronous, hence this method can't be called again if the previous call hasn't returned yet.

Parameters:

  • url String
    • (required), the absolute address of the external API to query
  • key String
    • (required), a private key that can be sent to the remote server via POST - hence if its an https connection it will be secure; use 'none' if you don't want this feature
  • value String
    • (required), the value that will accompany the key; use 'none' if you don't want this feature
  • completeCallBack Function
    • (optional), a function that accepts one string argument to execute when API lookup is complete
  • errorCallBack Function
    • (optional), a function that accepts one integer argument containing the status code returned; a code of 0 means that the operation failed after the initial connection response

readStringFromFile

(
  • path
  • callBack
)

Defined in TBAWrapper.js:506

Read a a file into a string.

Parameters:

  • path String
    • (required), The path to the file that is to be created that resides within the documents directory where '/' is the root of the documents directory
  • callBack Function
    • (required), The function to call when the string has been read. Should have only one argument that accepts the return string.

registerForCustomPushNotifications

(
  • query
)

Defined in TBAWrapper.js:991

Function to customize the push notifications regsitration workflow; this allows you to control when the push notifications request is sent (e.g. not immediately upon app install). This function still uses all of the other push config options in the config.json file, but allows you to override the postDataString value with a dynamic value passed as the query argument. The onus is on the developer to ensure that they only call this function once per app install; or at sensible times (e.g. if the app has a settings panel for controlling push notifications outside of the iOS push notification settings view).

Parameters:

  • query String
    • (required), a URL encoded post query that is to be appended to the URL registration HTTP request as a post query string

resumeSpeech

()

Defined in TBAWrapper.js:718

Function to resume current speech utterance - has no effect if not paused already

rm

(
  • path
)

Defined in TBAWrapper.js:468

Delete a file. All files are stored within the documents directory of app; which in this case equates to '/'; path must begin with '/'

Parameters:

  • path String
    • (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory

speak

(
  • text
  • pitch
  • rate
  • accent
  • completeCallback
)
Boolean

Defined in TBAWrapper.js:649

Function for text to speech; only supported on iOS 7+ and Android 2.2+; speaks a text string only if a text string isn't already being spoken.

Parameters:

  • text String
    • (required), the phrase to be spoken
  • pitch Number
    • (required), a decimal number that controls the pitch of speech. 1 is normal
  • rate Number
    • (required), a decimal number that controls the rate of speech; 1 is normal, 2 is twice as fast, and 0.5 is half as fast
  • accent String
    • (required), the country code representing the accent of the phrase to be spoken (see getLanguageCodes for a list of these that are available on the user's device)
  • completeCallback Function
    • (optional), to call when the speech utterance is completed

Returns:

Boolean:
  • Whether the utterance will be spoken or not based on whether it is supported by the current environment

startRecording

(
  • path
)

Defined in TBAWrapper.js:816

Function to record a audio file from the mobile device's microphone. Won't do anything if a recording is already in progress - only supported on iOS

Parameters:

  • path String
    • (required), The path to the file to record; it is stored in the documents directory, where '/' is the root of the documents directory. For iOS; filenames must end in .m4a

stopPlaying

()

Defined in TBAWrapper.js:852

Function to stop the playback of an audio file. Only supported on iOS

stopRecording

()

Defined in TBAWrapper.js:827

Function to stop an audio recording from the mobile device's microphone. Won't do anything if a recording hasn't already been started. Only supported on iOS

stopSpeech

()

Defined in TBAWrapper.js:730

Function to stop current speech utterance - has no effect if not speaking already

unzip

(
  • path
  • callBack
)

Defined in TBAWrapper.js:558

Unzips a zip file to the same directory that the zip file resides in

Parameters:

  • path String
    • (required), the path to the zip file; path must begin with '/' which maps to the documents directory within this application. Only one unzip process can be underway at any given point in time.
  • callBack Function
    • (optional), a function to call when the unzipping is complete that accepts no arguments

uploadFiles

(
  • paths
  • url
  • headers
  • callBackProgress
  • callBackError
)

Defined in TBAWrapper.js:875

Function to upload one or more files to a server. If a current upload batch is under way; you cannot start another one until its completed. Only supported on iOS Sample PHP code to receive the file upload:
<?php
set_time_limit(2000);
if(isset($_FILES['userfile'])) {
  $directory = $_SERVER['DOCUMENT_ROOT'] . '/upload/';//where you want to store your file?
  $file = basename($_FILES['userfile']['name']);
  $uploadfile = $directory . $file;
  error_log('uptest: file=' . $file);
  if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo '{json: "to return to app"}';
    error_log('uptest: successful');
  } else {
    error_log('uptest: unsuccessful');
  }
} else {
  error_log('uptest: empty file data');
}
?>

Parameters:

  • paths Array
    • (required), of Strings representing the local files that need to be uploaded. Paths all reference the local documents directory as their base; the root of which is accessed by '/'
  • url String
    • (required), the URL to upload to
  • headers Array
    • (optional) Array of objects. Each object must have one key / value pair which will be used as HTTP headers to be sent to the server with the upload request
  • callBackProgress Function
    • (optional), the call back that will tell you when each file in the group has completed its upload. The function should accept three arguments; first is number of files completed; the second is the total number of files in this batch; the third is a string returned from the server upload page
  • callBackError Function
    • (optoinal), the call back to be executed if there is an error with this upload batch; should take no arguments; once an error is encountered the batch is automatically cancelled.

writePNGSToPDF

(
  • src
  • dest
)

Defined in TBAWrapper.js:608

Function to write a folder full of PNGs into a PDF (one per page). Only supported on desktop

Parameters:

  • src String
    • (required), the directory path containing the PNGs to write (only png files will be written); must be a directory
  • dest String
    • (required), the path to the PDF file name to be created and written to.

writeScreenShotToPath

(
  • path
)

Defined in TBAWrapper.js:595

Function to create a screen shot of the currently display application window - currently only supported on desktop

Parameters:

  • path String
    • (required ), path as to where to write the image within the documents directory. '/' is considered the root of the docs dir. Paths must end in .png; as the file written is PNG.

writeStringToFile

(
  • theString
  • path
)

Defined in TBAWrapper.js:494

Write a string to a file. Assumes this is a new file (e.g. doesn't append).

Parameters:

  • theString String
    • (required), The string that is to be written to file
  • path String
    • (required), The path to the file that is to be created that resides within the documents directory where '/' is the root of the documents directory

Properties

androidVersion

Number

Defined in TBAWrapper.js:68

This property can be used to discern the version of Android that is being run; 0 if not Android

Default: 0

iOSVersion

Number

Defined in TBAWrapper.js:61

This property can be used to discern the version of iOS that is being run; 0 if not iOS

Default: 0

isAndroid

Boolean

Defined in TBAWrapper.js:54

This property can be used to discern if the wrapper is currently running as an android app

Default: "the current execution environment"

isDesktop

Boolean

Defined in TBAWrapper.js:37

This property can be used to discern if the wrapper is currently running as a desktop app

Default: "the current execution environment"

isiOS

Boolean

Defined in TBAWrapper.js:47

This property can be used to discern if the wrapper is currently running as an iOS app

Default: "the current execution environment"