Client Framework API

Namespace: Starlet

Starlet

Handles loading of Starlet-specific content, ensuring all necessary information is present. Provide starlet identifier (directory) to html counterpart via hash, e.g. "starlet.html#/starletname". Ghost-chasing note: if seeing errors emanating from deep within jQuery (particularly its append method), it's likely a syntax error within the starlet/widget index.html/js. Starlet-specific content is loaded via ajax and errors in it will surface when the html/js is parsed. Logs won't indicate the actual script and line number because the content is "anonymous".

Source:

Members

<static, readonly> $body :jQuery

Reference to body element.

Type:
  • jQuery
Source:

<static, readonly> $content :jQuery

Reference to main content area (section#content element).

Type:
  • jQuery
Source:

<static, readonly> $footer :jQuery

Reference to footer element.

Type:
  • jQuery
Source:

<static, readonly> $header :jQuery

Reference to header element.

Type:
  • jQuery
Source:

<static, readonly> $html :jQuery

Reference to html element (root node).

Type:
  • jQuery
Source:

<static, readonly> $menus :jQuery

Reference to dropdown menu container (div#menus element).

Type:
  • jQuery
Source:
See:

<static, readonly> $minishoebox :jQuery

Reference to minishoebox container (div#minishoebox element).

Type:
  • jQuery
Source:
See:

<static, readonly> $modal :jQuery

Reference to modal dialog container (div#modal) element.

Type:
  • jQuery
Source:
See:

<static, readonly> $spinner :jQuery

Reference to initial loading spinner (div.spinner element).

Type:
  • jQuery
Source:

<static, readonly> $tint :jQuery

Reference to overlay tint (div#tint element).

Type:
  • jQuery
Source:
See:

<static, readonly> $title :jQuery

Reference to title element.

Type:
  • jQuery
Source:

<static, readonly> apiServerName :String

API server name.

Type:
Source:
See:
To Do:
  • Create API_HOST constant.

<static, readonly> connectivity :Object

Hashlike object of connectivity states.

Type:
Source:

<static, readonly> footerData :Object

Whether the starlet layout includes a footer, and what variables were passed to the footer template. Override in custom starlet definition.

Type:
Source:
See:

Whether the starlet layout includes a header, override in custom starlet definition.

Type:
Source:
See:

<static, readonly> height :Number

Height of starlet's WebView (px).

Type:
Source:

<static, readonly> identifier :String

Current starlet directory.

Type:
Source:

<static, readonly> loaded :Number

Time that starlet controller was loaded (ms timestamp).

Type:
Source:

<static, readonly> mode :String

Will be 'prod', 'qa', or 'test', depending on the environment.

Type:
Source:
To Do:
  • Create QA constant.

<static, readonly> name :String

Framework's WebView handle.

Type:
Source:

<abstract, static> onActive :callbackFrameworkEvent

Developer callback. Fired on change of whether Starlet has primary focus. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onDisconnect :callbackGeneric

Developer callback. Fired on termination of User Server XMPP connection. Use this event to disable user interfaces that are not usable when offline. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onExit :callbackGeneric

Developer callback. Fired before unloading Starlet, but only when Framework is about to exit. Expect no more than ~200ms before WebView stops. Use this event to save state or preferences, and to perform cleanup. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onFocused :callbackFrameworkEvent

Developer callback. Fired on change of whether Starlet's application window has focus. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onHidden :callbackFrameworkEvent

Developer callback. Fired on change of whether Starlet's application window is hidden. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onMinimized :callbackFrameworkEvent

Developer callback. Fired on change of whether Starlet's application window is minimized. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onMouse :callbackFrameworkEvent

Developer callback. Fired on change of whether Starlet's WebView contains the mouse pointer. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onReconnect :callbackGeneric

Developer callback. Fired on reestablishment of User Server XMPP connection. Use this event to refresh lists of data, and to reenable user interfaces that were disabled while offline. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onRun :callbackGeneric

Developer callback. Behavioral starting point, fired on successful initialization of Starlet controller. This includes complete loading of templates and scripts, but not multimedia or styles. Will not be retriggered by network reconnection, see Starlet.onReconnect for this functionality. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onUnload :callbackGeneric

Developer callback. Fired before unloading Starlet, expect no more than ~200ms before WebView stops. Use this event to save state or preferences, and to perform cleanup. Override in custom Starlet definition.

Type:
Source:
See:

<abstract, static> onVisible :callbackFrameworkEvent

Developer callback. Fired on change of visibility of Starlet to the user. Override in custom Starlet definition.

Type:
Source:
See:

<static, readonly> order :Number

Order of last use. Used internally for restoring Framework state.

Type:
Source:

<static, readonly> production :Boolean

Indicates whether resources are to be loaded from Test server.

Type:
Deprecated:
  • since version 2.0.2, use constant PRODUCTION instead.
Source:

<static, readonly> root :String

Server path to current starlet directory.

Type:
Source:

<static, readonly> state :Number

Represents the successful loading, registration, and readiness of starlet to receive instructions and data.

Type:
Source:

<static, readonly> states :Object

Hashlike grouping of flags relating to user interactions.

Type:
Properties:
Name Type Description
main Boolean

Whether current starlet is anchored in the main application window.
overlay Boolean

Whether current starlet is an overlay with specific behavior and extended permissions (shoebox, navigation, notification).
lightbox Boolean

Whether current starlet is anchored in a lightbox. See Starlet.lightbox.
ordered Boolean

Whether current starlet is part of the normal navigation cycle (anchored in main window, not an overlay or lightbox).
tearoff Boolean

Whether current starlet has been switched from being anchored in the main window to a dedicated one. See Starlet.tearoff.
minitearoff Boolean

Whether current starlet was initially loaded in a dedicated window.
visible Boolean

Whether current starlet is considered visible to the user. See Starlet.onVisible, Starlet~onVisibleWrapper.
active Boolean

Whether current starlet is in a frontmost window and is the primary focus. See Starlet.onActive, Starlet~onActiveWrapper.
focused Boolean

Whether current starlet's anchoring window has focus. See Starlet.onFocused, Starlet~onFocusedWrapper.
minimized Boolean

Whether current starlet's anchoring window is minimized. See Starlet.onMinimized, Starlet~onMinimizedWrapper.
hidden Boolean

Whether current starlet's anchoring window is hidden. See Starlet.onHidden, Starlet~onHiddenWrapper.
mouse Boolean

Whether current starlet's WebView contains the mouse pointer. See Starlet.onMouse, Starlet~onMouseWrapper.
Source:

<static, readonly> title :String

Display name of starlet shown in header. Override in custom starlet definition.

Type:
Source:
See:

<static, readonly> type :String

Represents Framework-given permissions and behavior of WebView.

Type:
Source:

<static, readonly> url :String

Location of WebView.

Type:
Source:

<static, readonly> widgets :Array

References to all Widget controller instances within Starlet.

Type:
Source:

<static, readonly> width :Number

Width of starlet's WebView (px).

Type:
Source:

<private, inner> flagCovered :Boolean

Starlet synchronizer flag, indicates whether content has been hidden from view for setup.

Type:
Source:
See:

<private, inner> flagDefined :Boolean

Starlet synchronizer flag, indicates readiness of starlet behaviors to run.

Type:
Source:
See:

<private, inner> flagDom :Boolean

Starlet synchronizer flag, indicates (safe) dom alterability.

Type:
Source:
See:

<private, inner> flagFramework :Boolean

Starlet synchronizer flag, indicates receipt of framework args.

Type:
Source:
See:

<private, inner> flagLoaded :Boolean

Starlet synchronizer flag, indicates presence of essential assets (structure/style/behavior, !media).

Type:
Source:
See:

<private, inner> loadArguments :Array

Temporary array of args passed to synchronizer from Framework (name only).

Type:
Deprecated:
  • since version 2.0.2
Source:
See:

<private, inner> loadSpinner :Object

Initial load spinner instance. A curtain to hide the page layout until onRun.

Type:
Source:
See:

<private, inner> loadTimer :Object

Instance of TimerClass, measures time from Starlet creation to load event.

Type:
Source:
See:

<private, inner> near1 :Number

Threshold of first overlay handle mouse proximity effect (px).

Type:
Source:
See:

<private, inner> near2 :Number

Threshold of second overlay handle mouse proximity effect (px).

Type:
Source:
See:

<private, inner> nearNav1 :Boolean

Whether mouse is within first mouse proximity threshold for navigation.

Type:
Source:
See:

<private, inner> nearNav2 :Boolean

Whether mouse is within second mouse proximity threshold for navigation.

Type:
Source:
See:

<private, inner> nearSb1 :Boolean

Whether mouse is within first mouse proximity threshold for shoebox.

Type:
Source:
See:

<private, inner> nearSb2 :Boolean

Whether mouse is within second mouse proximity threshold for shoebox.

Type:
Source:
See:

<private, inner> onActiveWrapper :callbackFrameworkEvent

Fired on change of Starlet active state (input focus or switch). The Starlet is active when its WebView has primary focus in its application window, and that window is frontmost.

Type:
Source:
See:

<private, inner> onConnectivity :callbackData

Fired on change of connectivity status, fires appropriate developer callbacks.

Type:
Source:

<private, inner> onDragBubble :callbackEvent

Fired on start of drag events, cancels if not marked with class ui-draggable.

Type:
Source:
See:

<private, inner> onFocusedWrapper :callbackFrameworkEvent

Fired on change of Starlet focused state. The Starlet is focused when its WebView is in a foreground application window.

Type:
Source:
See:

<private, inner> onHiddenWrapper :callbackFrameworkEvent

Fired on change of Starlet hidden state. The Starlet is hidden when its WebView is in a hidden application window.

Type:
Source:
See:

<private, inner> onLinkBubble :callbackEvent

Fired on click of anchor tags, prevents location change and determines whether and how to open externally.

Type:
Source:
See:

<private, inner> onMinimizedWrapper :callbackFrameworkEvent

Fired on change of Starlet minimized state. The Starlet is minimized when its WebView is in a minimized application window.

Type:
Source:
See:

<private, inner> onModal :callbackData

Fired on receipt of instruction to create modal dialog.

Type:
Source:
See:

<private, inner> onMouseMove :callbackEvent

Fired on mouse movement within the Starlet's WebView.

Type:
Source:
See:

<private, inner> onMouseWrapper :callbackFrameworkEvent

Fired on change of Starlet mouse state. The Starlet "has" mouse when the mouse pointer is within its WebView.

Type:
Source:
See:

<private, inner> onOffset :callbackData

Fired on change of frontmost WebView's horizontal position during transition animation. Currently unused due to synchronization issue.

Type:
Source:

<private, inner> onOverlayState :callbackData

Fired on change of overlay visibility states (shoebox|navigation|lightbox), controls tint opacity.

Type:
Source:

<private, inner> onPageView :callbackFrameworkEvent

Fired on activation (input focus or switch) of Starlet.

Type:
Source:
See:

<private, inner> onProximity :callbackData

Fired on movement of mouse through overlay handle proximity thresholds.

Type:
Source:

<private, inner> onStarletData :callbackData

Fired on change of any Starlet properties.

Type:
Source:

<private, inner> onTintClick :callbackEvent

Fired on click of tint layer.

Type:
Source:
See:

<private, inner> onTrack :callbackEvent

Fired on click of trackable elements, records with Google Analytics.

Type:
Source:
See:

<private, inner> onVisibleWrapper :callbackGeneric

Fired on need of recalculation of Starlet visibility state (whether Starlet is onscreen).

Type:
Source:
See:

<private, inner> pageViewTimeout :Number

Google Analytics page tracking timeout identifier.

Type:
Source:
See:

<private, inner, readonly> synchronizer :Object

Deferred object handling foundational bindings and property population when loading as aspects of the WebView become available, finally calling Starlet.onRun.

Type:
Source:
See:

Methods

<static> alertDialog(title, description, isError, okText) → {Object}

Displays a modal alert dialog with custom content and configuration, but no HTML or cancel button.

Parameters:
Name Type Description
title String

Display title of modal dialog
description String

Body text of dialog.
isError Boolean

Whether dialog should be styled as an error.
okText String

Text to fill confirmation button with.
Source:
See:
To Do:
  • Return promise instead of deferred, since it needs to be turned into one to attach callbacks anyway. Only the creator of the deferred should have control of it, promise holders only "take a number".
Returns:

Deferred.

Type
Object

<static> broadcastWidget(packetName, data) → {Object}

Emit data under a specific packet name to any Widget listening for it. Listening Widgets will be triggered as if by another Widget so they needn't prepend 'Starlet_' to the packet name. Alternatively, trigger listeners in a way that signifies the origin is Starlet by using Starlet.speakWidget.

Parameters:
Name Type Description
packetName String

Topic to target specific listeners.
data Object | Array

The item to broadcast.
Source:
See:
Returns:

Starlet

Type
Object

<static> confirmDialog(title, description, okText) → {Object}

Displays a modal confirmation dialog with custom content and configuration, but no HTML or error styling.

Parameters:
Name Type Description
title String

Display title of modal dialog
description String

Body text of dialog.
okText String

Text to fill confirmation button with.
Source:
See:
To Do:
  • Return promise instead of deferred, since it needs to be turned into one to attach callbacks anyway. Only the creator of the deferred should have control of it, promise holders only "take a number".
Returns:

Deferred.

Type
Object

<static> define(definition) → {Object}

Extends Starlet with custom properties, methods, and callbacks. Call this in your Starlet directory's index.js, it signifies to the synchronizer that fundamental custom Starlet resources have been loaded and parsed.

Parameters:
Name Type Description
definition Object

Structure with which to extend Starlet, must include override for onRun to initiate any behavior.
Source:
See:
To Do:
  • Document definition.
Returns:

Starlet

Type
Object

<static> dialog(title, description, isHTMLDescription, isError, showCancel, okText) → {Object}

Displays a modal dialog with custom content and configuration.

Parameters:
Name Type Description
title String

Display title of modal dialog
description String

Body text of dialog.
isHTMLDescription Boolean

Whether provided description contains HTML.
isError Boolean

Whether dialog should be styled as an error.
showCancel Boolean

Whether to include a cancel button.
okText String

Text to fill confirmation button with.
Source:
See:
To Do:
  • Return promise instead of deferred, since it needs to be turned into one to attach callbacks anyway. Only the creator of the deferred should have control of it, promise holders only "take a number". Also fix replacement behavior when called successively.
Returns:

Deferred.

Type
Object

<static> freeformDialog(content, customClass) → {jQuery}

Displays a modal freeform dialog with completely custom content.

Parameters:
Name Type Description
content String

HTML content of dialog.
customClass String

Unique classname allowing for custom styling.
Source:
See:
Returns:

Starlet.$modal

Type
jQuery

<static> ignoreBroadcast(widgetType, packetName) → {Object}

Stop listening for data of a specific packet name.

Parameters:
Name Type Description
widgetType String

Type of Widget to stop listening for data from (see todo).
packetName String

Topic to stop listening for.
Source:
See:
To Do:
  • Eliminate widgetType as an argument. How broadcast differs from speak is that no type filter is needed.
Returns:

Starlet

Type
Object

<static> ignoreWidget(widgetType, packetName) → {Object}

Stop listening for data from a specific Widget type and of a specific packet name.

Parameters:
Name Type Description
widgetType String

Type of Widget to stop listening for data from.
packetName String

Topic to stop listening for.
Source:
See:
Returns:

Starlet

Type
Object

Opens a lightbox overlay with specific location and dimensions.

Parameters:
Name Type Description
name String

Framework name of new WebView.
url String

Location to open in lightbox.
width Number

Width at which to open lightbox.
height Number

Height at which to open lightbox.
Source:
See:
Returns:

Starlet

Type
Object

Closes a lightbox overlay by name.

Parameters:
Name Type Description
name String

Framework name of WebView to close.
Source:
See:
Returns:

Starlet

Type
Object

<static> listenBroadcast(packetName, callback) → {Object}

Listen for data of a specific packet name.

Parameters:
Name Type Description
packetName String

Topic to listen for.
callback function

Function to respond to incoming data.
Source:
See:
Returns:

Starlet

Type
Object

<static> listenWidget(widgetType, packetName, callback) → {Object}

Listen for data from a specific Widget type and of a specific packet name.

Parameters:
Name Type Description
widgetType String

Type of Widget to listen for data from.
packetName String

Topic to listen for.
callback function

Function to respond to incoming data.
Source:
See:
Returns:

Starlet

Type
Object

<static> load() → {Object}

Fetches custom Starlet index.html and notifies synchronizer.

Source:
See:
To Do:
  • Verify that occasional bad root was due to location hash being changed, remove relevant code here.
Returns:

Starlet

Type
Object

Replaces a select element with a styled Bootstrap dropdown.

Parameters:
Name Type Description
select Element | jQuery

Element to replace.
Source:
See:
Returns:

Starlet

Type
Object

Initializes a Bootstrap dropdown defined with custom structure and associates it with an element.

Parameters:
Name Type Description
anchor Element | jQuery

Element to toggle menu.
structure Object

Definition of menu structure.
Source:
See:
To Do:
  • Document structure.
Returns:

Starlet

Type
Object

Closes menu if open.

Source:
See:
Returns:

Starlet

Type
Object

Internal variation for toggling menus that have already been initialized. Filler arguments are only to make arguments.length 3, differentiating the behavior of this method.

Parameters:
Name Type Description
anchor Element | jQuery

Element that has been initialized as a menu toggling button.
filler1 Mixed

Filler.
filler2 Mixed

Filler.
Source:
See:
Returns:

Starlet

Type
Object

<static> minishoebox(anchor, placement, session, participants) → {Object}

Manages a centralized, preloaded minishoebox Widget within a Bootstrap popover in a manner that forces a consistent z-index.

Parameters:
Name Type Argument Default Description
anchor Element | jQuery

Element with which to align popover.
placement String <optional>
 'bottom'

Direction in which to align popover.
session String <optional>
 ''

Session id for minishoebox to pass to target after selection.
participants Array:.<Number:> <optional>
 []

Array of user ids to preselect.
Source:
See:
Returns:

Starlet

Type
Object

<static> minishoebox() → {Object}

Closes minishoebox if open.

Source:
See:
Returns:

Starlet

Type
Object

Creates a Bootstrap modal dialog in a manner that forces a consistent z-index.

Parameters:
Name Type Argument Default Description
html String

Raw html to pass through to Bootstrap modal method.
options Object <optional>
 {}

Additional options.

Properties
Name Type Argument Default Description
className String <optional>

Custom CSS class name to add to modal element.
backdrop Boolean | String <optional>
 'static'

Whether to include backdrop, and to allow click to dismiss.
keyboard Boolean <optional>
 true

Whether to allow esc to dismiss.
show Boolean <optional>
 true

Whether to show immediately.
remote Boolean | String <optional>
 false

Remote content URL.
Source:
See:
Returns:

Starlet.$modal

Type
jQuery

Controls Bootstrap modal dialog.

Parameters:
Name Type Description
action String

Action (show|hide|toggle) to pass through to Bootstrap modal method.
Source:
See:
Returns:

Starlet.$modal

Type
jQuery

<static> repaint() → {Object}

Momentarily alters the DOM in a way that causes a repaint of the entire WebView.

Source:
Returns:

Starlet

Type
Object

<static> showError(userErrorMessage, logErrorMessage, logErrorObject) → {Boolean}

Displays a modal error dialog and logs a separate message and object for debugging.

Parameters:
Name Type Description
userErrorMessage String

Message to be displayed to the user.
logErrorMessage String

Message to log.
logErrorObject String

Object to log.
Source:
See:
Returns:

true

Type
Boolean

<static> speakWidget(packetName, data) → {Object}

Emit data under a specific packet name to any Widget listening for it. Listening Widgets must prepend 'Starlet_' to the packet name to differentiate between broadcasts originating from Starlet versus another Widget. Alternatively, trigger listeners as a Widget would using Starlet.broadcastWidget.

Parameters:
Name Type Description
packetName String

Topic to target specific listeners.
data Object | Array

The item to broadcast.
Source:
See:
Returns:

Starlet

Type
Object

<static> tearoff(mode) → {Object}

Toggles whether the Starlet's WebView is in the main application window, does not cause a reload.

Parameters:
Name Type Argument Description
mode Boolean <optional>

Whether to take WebView out of the main application window or restore it. Toggles if omitted.
Source:
See:
Returns:

Starlet

Type
Object

<static> tint(state, callback) → {jQuery}

Shows or hides the mouse-blocking tint layer.

Parameters:
Name Type Description
state Boolean

Whether to show or hide tint.
callback function

Function to call when transition is complete.
Source:
Returns:

Starlet.$tint

Type
jQuery