Developers

Omnis Technical Note TNJC0005Oct 2013

JavaScript Components: Device Control

for Omnis Studio 6.0 or above

The Device Control provides direct access to features and services on a mobile device, such as the Camera, location system (GPS) and Contacts information, which can be added to your mobile apps to greatly enhance their interactivity and usability. The application containing the device control must be compiled into one of the Application Wrappers we provide - you cannot access device features from an app running inside a standard web browser on a device. Find out about the wrappers here.

To access functionality on a device you need to add the Device Control to your remote form (note the control itself is invisible) and enable the appropriate event(s) in the $events property for the control. For example, if you want to use the "get Barcode" action you need to enable the evBarcodeReturned event for the control. To trigger a device function you need to assign an action to the $action property of the control, using one of following kJSDeviceAction... constants:

Beep	GetImage	TakePhoto
GetBarcode	MakeCall	Vibrate
GetContacts	SendEmail
GetGps	SendSms

 
Using the bar code example, you can use the following code to initialize the device control to scan a barcode by invoking the camera/QR scanner on the device - this code could be placed in the $construct method of the form (to initialize the scanner when the form opens) or it could be placed behind a "Scan" button:

Do $cinst.$objs.Device.$action.$assign(kJSDeviceActionGetBarcode)

When the action successfully completes on the device an event is generated, so whatever code you want to run in response to the action should be placed in the $event() method behind the device control itself. For example, the following method is called when the device scans a QR code - the camera reads the QR code image and converts it to a character string. The code searches a product list based on the string returned in the pDeviceBarcode parameter.

On evBarcodeReturned ## contains pDeviceBarcode Do iProducts.$search(iProducts.iProdQrCode=pDeviceBarcode,kTrue,kFalse,kFalse,kFalse) Do iProducts.$loadcols() # etc.

Add code to the event method behind the device control to process the action.

You should test your app thoroughly on the specific device functions you wish to support since not all actions are supported on all devices (e.g. the device must be GPS enabled to use the "get GPS" action).

The "get GPS" action could be used to get the location of the end user (the device) which could be plotted on a map. In this case the kJSDeviceActionGetGps action must be assigned to the $action property, which if successful should return the location as the latitude and longitude data (separated by ‘:’) in the pDeviceGps event parameter. The evGpsReturned event must be enabled in the $events property on the Device control. The following code can be used to trigger the action, and assign the location to a map control.

# $event method of ‘Get location’ button On evClick     Do $cinst.$objs.oDevice.$action.$assign(kJSDeviceActionGetGps) # $event method on the device control # evGpsReturned must be enabled in $events for device control On evGpsReturned    ## contains pDeviceGps 'latitude:longitude'     Calculate $cinst.$objs.oMap.$latlong as pDeviceGps

For more information about the Device Control, including details about all the possible actions (TakePhoto, Vibrate, GetContacts, etc), refer to the 'JavaScript Components' chapter in the 'Creating Web & Mobile Apps' manual which is available here on the Omnis website.

Click here to download a trial copy of Omnis Studio to try the Device Control or other components in design mode.