TBAWrapper Class
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
()
Item Index
Methods
- array2json
- Base64.decode
- Base64.encode
- beginTransaction
- cp
- createPDF
- currentOrientation
- didReceiveDeviceID
- downloadFile
- endTransaction
- executeSQLQuery
- getDirections
- getLanguageCodes
- getSharedPhoto
- getSharedPhotoThumbs
- isRecording
- isSpeaking
- jsonParse
- launchNativeDefaultBrowser
- log
- ls
- mkdir
- mv
- openEmailClient
- openGaldermaMarket
- openPDF
- pauseSpeech
- playRecording
- queryAPI
- readStringFromFile
- registerForCustomPushNotifications
- resumeSpeech
- rm
- speak
- startRecording
- stopPlaying
- stopRecording
- stopSpeech
- unzip
- uploadFiles
- writePNGSToPDF
- writeScreenShotToPath
- writeStringToFile
Properties
Methods
array2json
-
arr
Light weight, internal convenience method for creating JSON strings from Objects or from Arrays.
Parameters:
-
arrObject- (required), An Object or an Array to turn into a JSON string
Returns:
- The JSON string representing the Object or Array that was parsed as an argument
Base64.decode
-
input
Function to base64 decode a string; can be useful for transmitting formatted text as GET or POST data
Parameters:
-
inputString- The string to be decoded
Returns:
- The decoded string
Base64.encode
-
input
Function to base64 encode a string; can be useful for transmitting formatted text as GET or POST data
Parameters:
-
inputString- The string to be encoded
Returns:
- The encoded string
beginTransaction
()
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
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:
-
srcString- (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory
-
destString- (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory
createPDF
-
path -
callBack
Turns the current on screen visuals into PDF document
Parameters:
-
pathString- (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
-
callBackFunction- (required), The function to call when the PDF has finished creating. Shouldn't have any arguments
currentOrientation
-
callBack
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:
-
callBackFunction- Function that accepts one String argument; Portrait, PortraitUpsideDown, LandscapeLeft, LandscapeRight
didReceiveDeviceID
-
did
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:
-
didString- (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
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:
-
urlString- (required), the absolute address of the external file to download
-
progressCallBackFunction- (optional), a function with one decimal argument representing progress, and one string argument representing the file name; to execute when progress updates are received
-
completeCallBackFunction- (optional), a function with one string argument representing the file name; to execute if the file download completes
-
errorCallBackFunction- (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:
- A unique local file name with the same filetype extension of the file specified in the URL.
endTransaction
()
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
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:
-
queryString- (required), the query to be executed in SQL format
-
bindingsArray- (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
-
callBackFunction- (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
Function to open the default iOS directions view for locations
Parameters:
-
latNumberlat - (required), latitude of the destination
-
lonNumberlon - (required), longitude of the destination
getLanguageCodes
-
callBack
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:
-
callBackFunction- (required), Call back funciton that receives an array in the following format as its only argument: [{code : "US", display : "US English"}...];
isRecording
-
callBack
Function to check if an audio recording is underway
Parameters:
-
callBackFunction- (required), a call back function whose only argument is a boolean
isSpeaking
-
callBack
Function to ask if the iOS or Android operating system is currently speaking
Parameters:
-
callBackFunction- (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:
- Whether the answer could be given or not depending on whether the current execution environment supports this function
jsonParse
-
input
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:
-
inputString- (required), the JSON string to turn into an object
Returns:
- An Object or an Array depending on the format of the input string provided
launchNativeDefaultBrowser
-
url
Function to launch a web page in the user's default browser rather than inside the wrapper window
Parameters:
-
urlString- (required), the url of the page to load in a native browser
log
-
Message
Native console logging function; passes the argument to the console of the native system for ouput to the native console
Parameters:
-
MessageString- (required), the message to be echoed
ls
-
path -
callBack
List directory contents
Parameters:
-
pathString- (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)
-
callBackFunction- (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
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:
-
pathString- (required), The path to the directory that resides within the documents directory where '/' is the root of the documents directory
mv
-
src -
dest
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:
-
srcString- (required), The path to the file that resides within the documents directory where '/' is the root of the documents directory
-
destString- (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
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:
-
subjectString- (required), the subject line for the email
-
messageString- (required), the message body for the email
-
attachmentsArray- (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.
-
isMainBundleBoolean- (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.
-
toArray- (required), an array of strings representing the intended recipients of the email
-
ccString- (required), an array of strings representing the intended cc recipients of the email
-
bccString- (required), an array of strings representing the intended bcc recipients of the email
-
isHTMLBoolean- (required), whether the message body is given as HTML or plain text
openGaldermaMarket
()
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
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string></string>
<key>CFBundleURLSchemes</key>
<array>
<string>UINIQUEAPPID</string>
</array>
</dict>
</array>
openPDF
-
path -
isMainBundle
Open a PDF in a native viewer
Parameters:
-
pathString- (required), The path to the PDF that resides within the documents directory where '/' is the root of the documents directory
-
isMainBundleBoolean- (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
()
Function to pause current speech utterance - has no effect if not speaking already
playRecording
-
path -
callBack
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:
-
pathString- (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
-
callBackFunction- (optional), the call back funciton to call when the file has finished playing
queryAPI
-
url -
key -
value -
completeCallBack -
errorCallBack
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:
-
urlString- (required), the absolute address of the external API to query
-
keyString- (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
-
valueString- (required), the value that will accompany the key; use 'none' if you don't want this feature
-
completeCallBackFunction- (optional), a function that accepts one string argument to execute when API lookup is complete
-
errorCallBackFunction- (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
Read a a file into a string.
Parameters:
-
pathString- (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
-
callBackFunction- (required), The function to call when the string has been read. Should have only one argument that accepts the return string.
registerForCustomPushNotifications
-
query
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:
-
queryString- (required), a URL encoded post query that is to be appended to the URL registration HTTP request as a post query string
resumeSpeech
()
Function to resume current speech utterance - has no effect if not paused already
rm
-
path
Delete a file. All files are stored within the documents directory of app; which in this case equates to '/'; path must begin with '/'
Parameters:
-
pathString- (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
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:
-
textString- (required), the phrase to be spoken
-
pitchNumber- (required), a decimal number that controls the pitch of speech. 1 is normal
-
rateNumber- (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
-
accentString- (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)
-
completeCallbackFunction- (optional), to call when the speech utterance is completed
Returns:
- Whether the utterance will be spoken or not based on whether it is supported by the current environment
startRecording
-
path
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:
-
pathString- (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
()
Function to stop the playback of an audio file. Only supported on iOS
stopRecording
()
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
()
Function to stop current speech utterance - has no effect if not speaking already
unzip
-
path -
callBack
Unzips a zip file to the same directory that the zip file resides in
Parameters:
-
pathString- (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.
-
callBackFunction- (optional), a function to call when the unzipping is complete that accepts no arguments
uploadFiles
-
paths -
url -
headers -
callBackProgress -
callBackError
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:
-
pathsArray- (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 '/'
-
urlString- (required), the URL to upload to
-
headersArray- (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
-
callBackProgressFunction- (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
-
callBackErrorFunction- (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
Function to write a folder full of PNGs into a PDF (one per page). Only supported on desktop
Parameters:
-
srcString- (required), the directory path containing the PNGs to write (only png files will be written); must be a directory
-
destString- (required), the path to the PDF file name to be created and written to.
writeScreenShotToPath
-
path
Function to create a screen shot of the currently display application window - currently only supported on desktop
Parameters:
-
pathString- (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
Write a string to a file. Assumes this is a new file (e.g. doesn't append).
Parameters:
-
theStringString- (required), The string that is to be written to file
-
pathString- (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
This property can be used to discern the version of Android that is being run; 0 if not Android
Default: 0
iOSVersion
Number
This property can be used to discern the version of iOS that is being run; 0 if not iOS
Default: 0
isAndroid
Boolean
This property can be used to discern if the wrapper is currently running as an android app
Default: "the current execution environment"
isDesktop
Boolean
This property can be used to discern if the wrapper is currently running as a desktop app
Default: "the current execution environment"
isiOS
Boolean
This property can be used to discern if the wrapper is currently running as an iOS app
Default: "the current execution environment"
