Namespace bc.device

Defined in: device.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	bc.device bc.device provides functions to interact with the native capabilities of a device.

Function Summary
Function Attributes	Function Name and Description
	bc.device.alert(message, successCallback, errorCallback) Shows an alert in a native dialog.
	bc.device.enterFullScreen(successCallback, errorCallback, options) Make the application go full screen, hiding any other visible parts of the application except for the active view.
	bc.device.exitFullScreen(successCallback, errorCallback) Exit full screen of the application.
	bc.device.fetchContentsOfURL(url, successCallback, errorCallback) Fetches the content of a given URL and returns the contents as a string.
	bc.device.getLocation(successCallback, errorCallback) Gets the current location of the user and calls into the success handler with the results.
	bc.device.getPhoto(successCallback, errorCallback) Get an existing photo from the user's photo library.
	bc.device.getQRCode(successCallback, errorCallback) Brings up a native QR scanner to read 2D QR codes.
	bc.device.isCameraAvailable(successCallback, errorCallback) Checks to see if this device has a camera available.
	bc.device.isFullScreen(successCallback, errorCallback) Returns a boolean indicating whether or not the application is in full screen.
	bc.device.navigateToMoreMenu(successCallback, errorCallback) Changes the active view to the 'more' menu, which is the view that appears on iOS if there are more then 5 views in the template.
	bc.device.navigateToView(uri, successCallback, errorCallback, options) Allows a developer to programmatically switch between views.
	bc.device.setAutoRotateDirections(direction, successCallback, errorCallback) Specify which directions the application can be rotated to.
	bc.device.takePhoto(successCallback, errorCallback) Opens the camera and allows the user to take a picture.
	bc.device.vibrate(successCallback, errorCallback) Vibrates the device if the current device supports it.

Namespace Detail

bc.device

bc.device provides functions to interact with the native capabilities of a device. Note that all functions take an optional success and error handler.

Function Detail

bc.device.alert(message, successCallback, errorCallback)

Shows an alert in a native dialog. This is useful to use instead of a JavaScript alert function call, because the JavaScript alert will show the name of the page (for example, videos.html) which is not always desirable. The success handler will be called after the user has dismissed the alert. Note: If called from the browser, then a default JavaScript alert will be used. The successCallback is then called once the alert has been interacted with.

    bc.device.alert( "Many turkeys are a rafter",
                      function() {
                        // my success handler
                      },
                      function( data ) {
                        bc.utils.warn( data.errorCode );
                      }
              });

Parameters:
message: The message to show in the native alert dialog.
successCallback: The function to be called after the dialog alert has been dismissed.
errorCallback: The function to be called if an error occurs. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.enterFullScreen(successCallback, errorCallback, options)

Make the application go full screen, hiding any other visible parts of the application except for the active view. For example, if running in the iOS container, this will hide the tab bar. Note: If called from the browser, the successCallback is called.

    bc.device.enterFullScreen( 
                          function() {
                            alert("I'm fullscreen!");
                          },
                          function( data ) {
                            bc.utils.warn( data.errorCode );
                          },
                          {
                            "hideStatusBar":"true"
                          }
              );

Parameters:

successCallback

The function to be called once the application goes into full screen.

errorCallback

The function to be called if there is an error going into full screen. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

options

An object with a set of optional parameters that can be passed in to control behavior.

hideStatusBar: A boolean indicating whether on iOS devices the status bar should be hidden when going full screen. This defaults to false.

bc.device.exitFullScreen(successCallback, errorCallback)

Exit full screen of the application. Note: If called from the browser, the successCallback is called.

    bc.device.exitFullScreen( function() {
                            alert("I'm not fullscreen!");
                          },
                          function( data ) {
                            bc.utils.warn( data.errorCode );
                          }
                        );

Parameters:
successCallback: The function that is called once we have exited full screen.
errorCallback: The function that is called if we hit an issue exiting full screen. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.fetchContentsOfURL(url, successCallback, errorCallback)

Fetches the content of a given URL and returns the contents as a string. Making a call to any domain is allowed. This is useful if you need to make calls that would normally not be allowed via an AJAX call because of cross-domain policy. Upon success, an object will be passed to the success handler that looks like: "URL contents"

If fetchContentsOfURL is called from within the browser, we will use the browser XHR object to make the request. This means that the request is now subject to cross-domain restrictions. To circumvent this during development, you can use the Chrome browser and start it from the command line with the following command: chrome.exe --disable-web-security

 
    bc.device.fetchContentsOfURL( 
        'http://my.sweet.feed/blob.xml',
        function( data ) {
        //data is equal to the contents of http://my.sweet.feed/blob.xml as a string.
        },
        function( data ) {
            bc.utils.warn( data.errorCode );
        }
    );

Parameters:
url: The URL that the request should be made to.
successCallback: The function that is called once the contents of the URL have been fetched. The callback is passed a string which is the contents of the URL.
errorCallback: The function that is called if there is an error fetching the contents of the URL. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.getLocation(successCallback, errorCallback)

Gets the current location of the user and calls into the success handler with the results. What is returned to the success handler is an object that looks like: {"latitude":70.35, "longitude":40.34} If this API is called in a browser and the browser supports geolocation, then we will use the JavaScript API to get the user location.

  
  bc.device.getLocation( function( locationInfo ) {
                          if ( locationInfo.latitude > 80 ) {
                            alert("Brrrrr...");
                          }
                        },
                        function( data ) {
                          bc.utils.warn( data.errorCode );
                        }
                      );

Parameters:
successCallback: A function to be called with the results of the location lookup. This includes latitude and longitude properties, which have values that are of type float.
errorCallback: An optional function that will be called if there is an error getting the location. This callback is passed an object containing the property errorCode, which maps one of the values specified in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.getPhoto(successCallback, errorCallback)

Get an existing photo from the user's photo library. When this function is called, the device will bring up the photo gallery. After the user chooses an image, the success handler is called. If you want the user to take a picture with the camera instead, use the takePhoto function instead. If getPhoto is called from the browser we will call the errorCallback with the

errorCode:
bc.device.codes.CAMERA_UNAVAILABLE

The success callback will be called with an object whose result value is a string pointing to the local path of the image. Here is an example of that object:
"/a/path/to/an/image.jpg"

Note: When using the Workshop application, the returned path will actually be a data-uri. In either case, you can set the resulting string to be the source of an image.

 
  bc.device.getPhoto( function( data ) {
                        //data is the path to the image on the file system.
                      },
                      function( data ) {
                        bc.utils.warn( data.errorCode );
                      }
                    );

Parameters:
successCallback: A function to be called with the URL to the image.
errorCallback: An optional function that will be called if an error is encountered, the device does not support getPhoto, or the user cancels the action. The errorCallback function is passed an object that contains a property of errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.getQRCode(successCallback, errorCallback)

Brings up a native QR scanner to read 2D QR codes. On success, this will call the successCallback, passing to the function the string that is represented by reflects the scanned QR code.

Note: If getQRCode is called from the browser, we will call the errorCallback with the errorCode: bc.device.codes.CAMERA_UNAVAILABLE.

Parameters:
successCallback: The function that is called once the QR code has been read. The successCallback is passed a string that reflects the QR code.
errorCallback: The function that is called if an error occurs. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.isCameraAvailable(successCallback, errorCallback)

Checks to see if this device has a camera available. The success handler will be called with an object that looks like: true if the camera is available or false if it is not Note: If this is called from within a browser, we will call the success callback function and return false.

 
    bc.device.isCameraAvailable( function( data ) {
                                   alert( "Camera available? " + data );
                                   if( data ) {
                                     alert( "Camera is available!" );
                                   } else {
                                     alert( "No camera :( ");
                                   }
                                 },
                                 function( data ) {
                                   bc.utils.warn( data.errorCode );
                                 }
                              );

Parameters:
successCallback: The function to be called with a boolean specifying whether or not a camera is available.
errorCallback: The function that is called if an error is encountered. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.isFullScreen(successCallback, errorCallback)

Returns a boolean indicating whether or not the application is in full screen. The returned object is true if we are in full screen or false if not. Note: If called from the browser, the successCallback is called passing the value of true.

bc.device.isFullScreen( function( data ) {
                                        if( data ) {
                                          alert( "I am in fullscreen" );
                                        } else {
                                          alert( "I am NOT in fullscreen" )
                                        }
                                     },
                                     function( data ) {
                                       bc.utils.warn( data.errorCode );
                                     }
               );

Parameters:
successCallback: The function to be called with data specifying whether or not the application is in full screen mode.
errorCallback: The function to be called if there is an error. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.navigateToMoreMenu(successCallback, errorCallback)

Changes the active view to the 'more' menu, which is the view that appears on iOS if there are more then 5 views in the template. This command is most often used by views that fall under the "more menu" list, so that user can navigate back to the list.

   //The back button on a static page, such as an about page in a more section.
   $( ".back-button" ).bind( "tap", function() {

     //Make sure we are in a more navigation view
     if( bc.context.moreNavigationView ) {

       //Transition back the more menu.
       bc.device.navigateToMoreMenu();
     }
   });

Parameters:
successCallback: The function to be called once the 'more' menu has been navigated to.
errorCallback: The function to be called if there is an error.

bc.device.navigateToView(uri, successCallback, errorCallback, options)

Allows a developer to programmatically switch between views. Just as in web development, the API allows a developer to navigate to a URI and also provide a fragmentID to append to that URL. (fragmentID is the technical term for a '#' in a URL.) If you are using the fragmentID to pass contextual data then you should simply register an event listener for the hashchangeevent. An example use case would be if you had a photo on your home page, and when the user clicks a photo, you open the photo view and navigate to that particular photo.

   //home.html
   bc.device.navigateToView( "photo.html", successCallback,
                    errorCallback, { "fragmentID": "id-of-photo" } );
   
   //photo.html
   $( window ).bind( "hashchange", function( evt ) {
     var photoID = window.location.hash;
     //do something photoID.
   })

Parameters:
uri: The URI of the view to navigate to. This is the URI that was specified in the manifest.json file.
successCallback: The callback function that is called if the view is successfully navigated to.
errorCallback: The callback function that is called if the container is unable to navigate to the view.
options: An options object. We look for the fragmentID to see if the fragmentID of the URL should be set.

bc.device.setAutoRotateDirections(direction, successCallback, errorCallback)

Specify which directions the application can be rotated to. Note that all of the views in a given template should allow for the device to be rotated in the same directions. In future releases this will be enforced by the App Cloud containers. The directions should be passed in as an array and can take in five different values:

bc.ui.orientation.PORTRAIT
bc.ui.orientation.LANDSCAPE_LEFT
bc.ui.orientation.LANDSCAPE_RIGHT
bc.ui.orientation.PORTRAIT_UPSIDEDOWN
all

 
   bc.device.setAutoRotateDirections ( 
            [bc.ui.orientation.PORTRAIT, bc.ui.orientation.LANDSCAPE_RIGHT],
            function() {
              //my success handler
            },
            function( data ) {
               bc.utils.warn( data.errorCode );
            }
        );

Parameters:
direction: An array of directions that the device can rotate to. Possible values are: bc.ui.orientation.PORTRAIT, bc.ui.orientation.LANDSCAPE_LEFT, bc.ui.orientation.LANDSCAPE_RIGHT, bc.ui.orientation.PORTRAIT_UPSIDEDOWN or simply all.
successCallback: The function to be called if this registration successfully happens.
errorCallback: The function to be called if there is an error. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.takePhoto(successCallback, errorCallback)

Opens the camera and allows the user to take a picture. Once the picture has been taken, the success handler is called. If you want to access an image from the photo gallery, use the getPhoto function instead. Here is an example of what the return object will look like:
"/a/path/to/an/image.jpg"

Note: When using the Workshop app, the returned path will actually be a data-uri. In either case, you can set the resulting string to be the source of an image.

Note: If takePhoto is called from the browser, we will call the errorCallback with the errorCode: bc.device.codes.CAMERA_UNAVAILABLE.

 
    bc.device.takePhoto( function( data ) {
                          //my success handler
                         },
                         function( data ) {
                           if( data.errorCode === bc.device.codes.USER_CANCEL ) {
                             //Convince them not to cancel.
                           }
                          
                         }
                      );

Parameters:
successCallback: The function to be called with the URL to the image the user just took with their camera.
errorCallback: The function that is called if an error is encountered, the device does not support taking a picture, or the user cancels the action. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

bc.device.vibrate(successCallback, errorCallback)

Vibrates the device if the current device supports it.

 
    bc.device.vibrate( function( ) {
                         //my success handler
                       },
                       function( data ) {
                         bc.utils.warn( data.errorCode );
                       }
                     );

Parameters:
successCallback: The function to be called if the phone successfully vibrates.
errorCallback: The function to be called if there is an error vibrating the phone. The errorCallback function is passed an object that contains a property named errorCode, which maps to one of the codes defined in bc.device.codes, and a property named errorMessage, which provides additional information about this error.

Classes

Namespace bc.device