jDeck

jDeck is a small JavaScript library in front of a powerful but simple structural concept for writing web apps. Especially mobile apps.

The concept is borrowed from Mozilla XUL, with which I have shared many intimacies over the years. As with Mozilla's deck, this implementation of the deck also allows to display any one of a number of children of any HTML element using one of several commands implemented in the library.

While it was originally written as a stand-alone library, I rewrote it using jQuery to make it compatible with more browsers.

Here is some sample HTML using a <div> element as the deck.

<div id="mydeck">
   <label id="mylabel">This is the first card</label>
   <div id="mydiv">
      input some stuff to show as the second card
   </div>
   <input id="myinput" type="button" label="third card"/>
      more cards as needed...
</div>
    

The sample deck contains three cards: the label, the div, and the input. Using the deck interface, you can control which card to display with a single call. You can have as many decks as you need by using the library with different elements identified by their id attributes, and each deck can have as many cards as you need.

Here are the commands:

   bool  = initDeck(deckid);
   void  = initPath(deckid=cardid[,deckid=cardid]);
   jNode = gotoCard(deckid, cardid);
   jNode = gotoNextCard(deckid);
   jNode = gotoPreviousCard(deckid);
   int   = whichCard(deckid);
   int   = cardCount(deckid);

Each deck within the web page must first be initialized by calling initDeck(), which initializes the specified deck by adding a couple of attributes to control the display. Alternately, the deck can be initialized by calling initPath().

To initialize the sample using initDeck(), use

    initDeck("mydeck");

This will initialize the parent <div> as the deck, and will display the label, hiding the other two elements.

Be sure not to call initDeck() until you are sure that the target HTML has been loaded.

To initialize a path from the root to a leaf, using the initPath() API,

After the deck has been initialized, you can then use the gotoCard(), gotoNextCard(), and gotoPreviousCard() commands to navigate among the cards within an initialized deck. For example, to display the input element, use either of the following commands:

    gotoCard("mydeck", 2);
or
    gotoCard("mydeck", "myinput");

The gotoCard() command allows the second parameter to be specified as the id of the desired card or as an index to the desired card, starting with the first cardas the zero-th card. So that the gotoCard() command can distinguish a card id from a card index, the card id cannot start with a digit.

The gotoNextCard() command takes no action if the last card is the visible card. Likewise, the gotoPreviousCard() command takes no action if the first cardis the visible card. To display the <div> card, given that the last cardis visible, you could use one of the following commands:

    gotoCard("mydeck", 1);

    gotoCard("mydeck", "mydiv");
or
    gotoPreviousCard("mydeck");

Each of the goto* commands return the jQuery node that the command made visible.
  
The library uses the data-card attribute in the deck element to track which card is visible, and uses the hidden attribute in the card elements to control their visibility.

Since the library identifies deck elements simply by their id attribute, any number of decks, both nested and otherwise, can be used. Note that any HTML grouping element can be used as a deck, as well as for any card; although I have only tested it with <div>'s.

Please note that this library does depend on jQuery, so you do have to include the script request for jQuery when you use this library.

While this version is complete as it stands, I would like to take advantage of jQuery's ability to style the display in the next version to make it even more user-interactive in mobile apps. Alternately, feel free to enhance it as you will.

As with jQuery, this library and documentation are released under the terms of the MIT License. Please leave the copyright header intact.