Pagestack

Overview

Usually, Ubuntu HTML5 applications have one Pagestack. Pagestack manages pages with a stack data structure, hence the name of the class. A pagestack can contain a toolbar for all its pages, however, pages can also have their own toolbar. The pagestack has methods to show and hide pages. Only one page and its toolbar can be displayed at the same time. Each time a page is shown, its global DOM id is added on the stack of pages. The pop method removes a page from the stack and shows the preceding page instead.

Pagestack is defined in the file /usr/share/ubuntu-html5-theme/0.1/ambiance/js/pagestacks.js

Markup declaration

This declares an empty pagestack containing no pages and no toolbar. html <div data-role="pagestack"> </div>

The following markup declares a pagestack with a main footer for the whole pagestack. It contains two pages: html <div data-role="pagestack"> <div id="firstPage" data-role="page"> </div> <div id="secondPage" data-role="page"> </div> <footer data-role="footer"></footer> </div> html

Javascript access method

Accessing the pagestack is made as follows:

var UI = new UbuntuUI();
UI.init(); // initalizes the pagestack
var pagestack = UI.pagestack;

Interface definition

interface Pagestack {
  void push(DOMString domId);
  DOMString pop();
  void clear();
  boolean isEmpty();
  DOMString currentPage();
  unsigned long depth();
};

Javascript access method

  • void push(DOMString domId). displays the page having the global id domId and its associated footer. All other pages are made invisible. Additionally, domId is added on the internal stack of pages maintained by the pagestack object.

  • DOMString pop(). hides the page which is actually shown, and removes it from the top of the internal stack of pages. Instead, the preceding page, which global id is now on the top of the stack, is shown. If the internal stack is empty, nothing happens.

  • void clear(). makes all pages invisible and clears the internal stack of pages (used by the push() and and pop() methods).

  • boolean isEmpty(). returns true if the internal stack of pages is empty. Else, false is returned.

  • DOMString currentPage(). returns the global id of the currently displayed page. If no page is displayed (i.e. if the internal stack of pages is empty), null is returned.

  • unsigned long depth(). returns the size of the stack of pages.

Written on July 9, 2010