Package com.oorian.html.containers

Class Deck

java.lang.Object
com.oorian.html.Element<Deck>
com.oorian.html.VisualElement<Deck>
com.oorian.html.StyledElement<Deck>
com.oorian.html.StyledContainerElement<Deck>
com.oorian.html.elements.Div<Deck>
com.oorian.html.containers.Deck
public class Deck extends Div<Deck>
A deck container that displays one child element at a time from a collection.

This container class extends Div to provide a card-deck style interface where multiple elements are added but only one is visible at any given time. The visible element can be changed programmatically by index, ID, or reference, with support for navigation methods like next/previous and default element tracking.

Lazy Loading Modes:

  • Default (not lazy): All elements are in the DOM, visibility toggled via CSS.
  • Lazy + Persist: Elements added to DOM only when first shown, then hidden/shown via CSS.
  • Lazy + No Persist: Only one element in DOM at a time; content swapped on switch.

Hash Navigation: When enabled via setHashNavigation(boolean), the deck synchronizes the displayed view with the browser's URL hash fragment.

Since:
2007
Version:
1.1
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • Deck

      public Deck()
      Constructs a new Deck with default (non-lazy) behavior.

    • Deck

      public Deck(boolean lazy, boolean persist)
      Constructs a new Deck with configurable lazy loading behavior.
      Parameters:
      lazy - true to enable lazy loading (elements added to DOM only when shown)
      persist - when lazy, true to keep shown elements in DOM; false to swap content

  • Method Details

    • addElement

      public Deck addElement(String id, Element element)
      Adds an element to the deck with the specified ID.

      Sets the element's ID before adding it to the deck.

      Parameters:
      id - the ID to assign to the element
      element - the element to add
      Returns:
      this Deck for method chaining

    • addElement

      public final Deck addElement(Element element)
      Adds an element to the deck.

      The element is wrapped in a DeckElement container. The first element added becomes the default and is initially visible; all subsequent elements are hidden.

      In lazy mode, elements are stored but not added to the DOM until first shown.

      Overrides:
      addElement in class StyledContainerElement<Deck>
      Parameters:
      element - the element to add to the deck
      Returns:
      this element for method chaining

    • setLoadingElement

      public Deck setLoadingElement(Element loadingElement)
      Sets the element to display as a loading indicator while lazy-loaded content is being initialized.

      When set, switching to a new view in lazy mode will immediately display this element while the actual view content is added in a background thread via OorianWorkerThread. Once the content is ready, the loading element is replaced and the update is pushed to the client.

      This has no effect in default (non-lazy) mode since all elements are already in the DOM.

      Parameters:
      loadingElement - the element to display during lazy loading transitions
      Returns:
      this Deck for method chaining

    • setMinLoadTime

      public Deck setMinLoadTime(int millis)
      Sets the minimum time in milliseconds that the loading indicator is displayed.

      When a lazy-loaded view's content is ready before this duration has elapsed, the swap is delayed until the minimum time is met. This prevents quick flashes of the loading indicator for fast-loading content.

      A value of 0 (the default) means no minimum — the content replaces the loader as soon as it is ready.

      Parameters:
      millis - the minimum display time in milliseconds
      Returns:
      this Deck for method chaining

    • setHashNavigation

      public Deck setHashNavigation(boolean hashNavigation)
      Enables or disables URL hash navigation for this deck.

      When enabled, switching views updates the browser's URL hash to the displayed element's ID (e.g., #my-section). If the URL hash changes (via browser back/forward or direct navigation), the deck automatically switches to the matching view.

      For readable URLs, assign meaningful IDs using addElement(String, Element).

      Parameters:
      hashNavigation - true to enable hash-based navigation
      Returns:
      this Deck for method chaining

    • show

      public final void show(int index)
      Shows the element at the specified index.

      Hides all other elements and displays only the element at the given index. Triggers the onChange callback if the displayed element changes.

      Parameters:
      index - the zero-based index of the element to display

    • show

      public void show(String childId)
      Shows the element with the specified ID.

      Searches for a child element with the given ID and displays it while hiding all others.

      Parameters:
      childId - the ID of the child element to display

    • show

      public void show(Element child)
      Shows the specified element.

      Displays the given element by finding its ID and calling show(String).

      Parameters:
      child - the element to display

    • showDefault

      public void showDefault()
      Shows the default element (the first element added to the deck).

    • showNext

      public void showNext()
      Shows the next element in the deck.

      Cycles to the first element if currently showing the last element.

    • showPrev

      public void showPrev()
      Shows the previous element in the deck.

      Cycles to the last element if currently showing the first element.

    • getDisplayedIndex

      public int getDisplayedIndex()
      Returns the index of the currently displayed element.
      Returns:
      the zero-based index of the visible element

    • getDisplayedElement

      public Element getDisplayedElement()
      Returns the currently displayed element.
      Returns:
      the visible element, or null if the deck is empty

    • getDisplayedId

      public String getDisplayedId()
      Returns the ID of the currently displayed element.
      Returns:
      the ID of the visible element, or null if the deck is empty

    • initialize

      protected final void initialize()
      Description copied from class: Element
      Hook method called during element initialization.

      Override this method to set up the element's structure by adding child elements. This is called before Element.create() and only once during the element's lifecycle.

      Overrides:
      initialize in class StyledElement<Deck>

    • onCreated

      protected void onCreated()
      Description copied from class: Element
      Hook method called after the element has been created.

      Override this method to perform actions after creation is complete.

      Overrides:
      onCreated in class Element<Deck>

    • onPageLoaded

      protected void onPageLoaded()
      Description copied from class: Element
      Hook method called when the page has finished loading.

      Override this method to perform actions after the page is fully loaded in the browser.

      Overrides:
      onPageLoaded in class Element<Deck>

    • onChange

      protected void onChange()
      Called when the displayed element changes.

      Override this method to perform custom actions when a different element is shown.

    • onHashChange

      protected void onHashChange(String hash)
      Description copied from class: Element
      Hook method called when the URL hash fragment changes.

      Override this method to respond to hash-based navigation changes within the page.

      Overrides:
      onHashChange in class Element<Deck>
      Parameters:
      hash - The new hash fragment value.

    • getHtml

      public void getHtml(StringBuilder buffer)
      Description copied from class: StyledElement
      Generates the HTML representation of this element, including state-based styles and interactive cursor attributes.
      Overrides:
      getHtml in class StyledElement<Deck>
      Parameters:
      buffer - The StringBuilder to append the HTML output to.