Namespace bc.ui

Defined in: ui.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	bc.ui bc.ui provides functions that interact with the DOM.

Property Summary
Property Attributes	Property Name and Description
	bc.ui.currentPage The currently active page, meaning the page that is currently in view.
	bc.ui.inTransition Tracks whether or not the current view is in transition.
	bc.ui.pageStack An array that keeps track of the page history.

Function Summary
Function Attributes	Function Name and Description
	bc.ui.backPage(options) Transitions from the current page back to the previous page.
	bc.ui.enableScrollers($page) Note that the App Cloud SDK automatically manages the construction and destruction of these scrollers for you.
	bc.ui.forwardPage(toPage, options) Transitions to the `toPage` parameter from the current page.
	bc.ui.height() Returns the current height of the viewport.
	bc.ui.refreshScrollers(options) DEPRECATED This function is no longer necessary.
	bc.ui.scrollToTop($scroller) Scroll to the top of the provided momentum scroller.
	bc.ui.setCurrentPage(elem)
	bc.ui.spinner() Returns an HTML snippet that can be used to inject a CSS3 animated spinner into the DOM.
	bc.ui.width() Returns the current width of the viewport.

Namespace Detail

bc.ui

bc.ui provides functions that interact with the DOM. This includes initializing and managing elements for momentum scrolling, functions to help transition between pages, and helper functions to draw common UI elements (for example an AJAX loader).

Property Detail

bc.ui.currentPage

The currently active page, meaning the page that is currently in view.

bc.ui.inTransition

Tracks whether or not the current view is in transition.

bc.ui.pageStack

An array that keeps track of the page history. For example, if our first page is a list of videos and then when we click on a item it transitions (using the bc.ui.forwardPage function) to a video detail page, we would have two pages in our bc.ui.pageStack: The first item being the original page and the second the new page we transitioned to, $detailsPage in this example.

Function Detail

bc.ui.backPage(options)

Transitions from the current page back to the previous page. The type of transition can be specified, but by default the current page will slide off the page to the right. Once the transition has completed, the previous page is removed from the DOM if the page was injected into the DOM via the forwardPage API. We remove these pages from the DOM in order to minimize memory use. The backPage function triggers a pageshow event once the transition has completed and a pagehide event once the current page has been hidden. Note that the pagehide event is only fired if the page was not removed.

bc.ui.backPage() is associated with the bc.ui.forwardPage() function. After a previous use of bc.ui.forwardPage() to transition to a page, call the bc.ui.backPage() function to transition back to the original page. A common use would be when a user taps on a back button. You would call bc.ui.backPage() to transition back to the original page.

 
   $( bc ).on( 'pageshow', function( $firstPage ) {
     //Got the pageshow event and the page we transitioned to.
     //In this example the first page we started on.
   });
   
   bc.ui.backPage(); //transitions back to the first page
   
   //The above line is equivalent to calling
   // bc.ui.backPage( { 
   //  "transitionType": bc.ui.transitions.SLIDE_RIGHT
   // })

Parameters:

options

An object that contains the options that can be provided to the transition function. The possible values are:

transitionType - defines the type of transition to use when moving back to the previous page and must correspond to a value defined in bc.ui.transitions. The default value is bc.ui.transitions.SLIDE_RIGHT, which will slide the current page off to the right.
toPage - If you would like to inject a new page into the DOM and transition to this page you can pass in the DOM element to inject into the page. Note If there is more then one page in the page stack this value is ignored
transitionTime specifies how the long the transition should take. Smaller = faster. The time is in milliseconds.

bc.ui.enableScrollers($page)

Note that the App Cloud SDK automatically manages the construction and destruction of these scrollers for you. Therefore by default you should not have to call enableScrollers. The App Cloud SDK calls enableScrollers when it first loads and any time we transition to a new page.

This function can be called to enable momentum scrolling for any element with a class of scroller that is a direct child of the page that was passed in. If no page is passed to the function, then it defaults to the currently active page.

   bc.ui.enableScrollers(); //Will initialize momentum scrolling for this current page.

Parameters:
$page: An optional jQuery object that either has a class of scroller on it or is a parent of an element(s) that has the class scroller on it.

bc.ui.forwardPage(toPage, options)

Transitions to the toPage parameter from the current page. The type of transition to be applied can be passed as parameter; otherwise it defaults to SLIDE_LEFT. The toPage parameter can be passed as either a CSS selector, DOM Element, or jQuery Object. The passed toPage can already be part of the Document or can be independent. If it is independent, then this function will dynamically insert the toPage into the DOM. If this function inserts the page into the Document, then when the back function is called, it will automatically remove the associated page. Generally speaking, it is recommended to allow pages to be dynamically inserted and removed from the DOM so as to keep the DOM in-memory as small as possible.

Both the current page and the new page should have a CSS class of page as defined in the theme file. This function triggers a pageshow and a pagehide event once the transition has completed. The pageshow event passes the new page as data parameter, while the pagehide event passes the page we transitioned from as data parameter.

bc.ui.forwardPage should be used when logically transitioning from one page to the next. In addition to providing a visual transition, it will add pages to the bc.ui.pageStack so that a history stack of pages can be maintained. To return to the original page (the from page) call bc.ui.backPage().

 
   $( bc ).on( 'pageshow', function( $secondPage ) {
     //Got the pageshow event and the page we transitioned to.
   });
   
   $(bc ).on( 'pagehide', function( $firstPage ) {
     //Got the pagehide event and the page we transition from.
   });
   
   bc.ui.forwardPage( $( '.second_page' ) ); //transitions to the new page

Parameters:

toPage

The page we want to transition to.

options

An object that overrides the default values of the forwardPage function. The possible values are:

transitionType specifies the direction of the type of transition to use during the transition. Defaults to SLIDE_LEFT
transitionTime specifies how the long the transition should take. Smaller = faster. The time is in milliseconds.

bc.ui.height()

Returns the current height of the viewport.

    var height = bc.ui.height(); //sets height to the current height of the viewport

Returns:: The height of the viewport as a number, in pixels.

bc.ui.refreshScrollers(options)

DEPRECATED This function is no longer necessary.

Parameters:
options

bc.ui.scrollToTop($scroller)

Scroll to the top of the provided momentum scroller.

   bc.ui.scrollToTop( $( '.scroller' ) ); //Scrolls the page to the top of the page.

Parameters:
$scroller: A jQuery object that represents the scroller element to scroll to the top of the provided scroller.

bc.ui.setCurrentPage(elem)

Parameters:
elem

bc.ui.spinner()

Returns an HTML snippet that can be used to inject a CSS3 animated spinner into the DOM. The size and color are controlled in the theme file.

   $( 'body' ).append( bc.ui.spinner() ); //Injects an HTML spinner into the body of the page.

Returns:: An HTML snippet that represents a CSS3 animated spinner. (AJAX loader)

bc.ui.width()

Returns the current width of the viewport.

    var width = bc.ui.width(); //sets width to the current width of the viewport.

Returns:: The width of the viewport as a number, in pixels.

Classes

Namespace bc.ui