Class: Viewport

Viewport

new Viewport(options)

Viewport - manages visual (DOM) components
Parameters:
Name Type Description
options Object options for viewport initialization
Properties
Name Type Description
animator Object Animator object
config Object Configuration object
emitter Emitter | Object Emitter instance or options object
itemCollection ItemCollection ItemCollection instance
layout Layout Layout instance
frame Frame Frame instance
canvas Canvas Canvas instance
Source:

Mixes In

Members

customRenderAnimationCount

Keeps track of the number of custom renders being drawn
Source:

customRenders

Keyed object of custom render objects. The key is the custom Render id. A custom render is an object with an element/transform/etc., which is drawn on the Canvas, but is not associated with an Item in the ItemCollection. This might be a custom divider line, label, etc.
Source:
Example
Internal Viewport custom renders data structure
{
 "0": {
   element: ...,
   transform: {
     ...
   },
   animateOptions: {
     ...
   },
   someOtherProperty: {
     ...
   }
 }
}

debouncedLoadOrUnloadRenders

Debounced version of Viewport#onGestureElementMoved
Source:

defaultOptions

Default options for instances of Viewport
Source:

drawOnDeckReady

Whether to run a draw cycle when the deck:ready event is handled
Source:

gestureHandlerGroups

Keeps track of GestureHandlerGroups
Source:

isDeckReady

Flag that indicates if the deck is ready. Drawing actions are suppressed until the deck is signaled as ready
Source:

isDrawingEnabled

Whether drawing is enabled
Source:

layoutMethodOptions

Object of properties to pass to all Layout methods invoked by the Viewport This is to provide the Layout methods with more context for their logic.
Source:

renderAnimationCount

Keeps track of how many renders are currently being drawn
Source:

renders

Data structure for storing the items and corresponding renders The data structure is a 2-level tree. At the first level, the key is the item.id. The value at the first level is an object with render.ids as keys. The value At the second level is the render object, e.g.
Source:
Example
Internal Viewport renders data structure
{
 // Item 1
 "item-id-1": {
   // Render "0" for Item 1
   "0": {
     "id": "0",
     "index": 0,
     "transform": {
       "top": 120,
       "left": 140
       ...
     },
     "animateOptions": {
       ...
     }
   },
   // Render "1" for Item 1
   "1": {
     "id": "1",
     "index": 1,
     "transform": {
       "top": 120,
       "left": 140
       ...
     },
     "animateOptions": {
       ...
     }
   }
 },
 // Item 2
 "item-id-2": {
   // Render "0" for Item 2
   "0": {
     "id": "0",
     "index": 1,
     "transform": ...
   }
 }
}

useAnimationStopping

Whether to stop animations when a new cycle starts while one is already running
Source:

Methods

addRenderGestureHandler(render) → {undefined}

Adds a GestureHandler for the render, and puts it in a GestureHandlerGroup according to the render.gestureHandlerGroupId.
Parameters:
Name Type Description
render
Source:
Returns:
Type
undefined

bind() → {undefined}

Binds all Viewport event handlers
Source:
Returns:
Type
undefined

bindGestures() → {undefined}

Binds all GestureHandlerGroups managed by the Viewport
Source:
Returns:
Type
undefined

canDraw(canDrawCondition) → {boolean}

Indicates whether the Viewport can draw. This check is based on the isDeckReady flag, the isDrawingEnabled flag, and possibly other conditions.
Parameters:
Name Type Argument Default Description
canDrawCondition boolean <optional>
 undefined extra condition to check
Source:
Returns:
- true if drawing can be done, otherwise false
Type
boolean

cleanErasedCustomRenders()

Removes all custom render elements which have been hidden (completed the hide animation).
Source:

cleanErasedRendersAndItems()

Finds all renders marked as isErasing and removes them. Then if all renders have been removed for an item, and the item is marked as isErasing, the Item is removed too.
Source:

configureAllRenderGestures() → {undefined}

Configures gestures for all renders
Source:
Returns:
Type
undefined

configureRenderGestures(render) → {undefined}

Configures gestures for a single render.
Parameters:
Name Type Description
render
Source:
Returns:
Type
undefined

createCustomRenderElement(customRender) → {undefined}

Helper function for creating a custom render element with a default position.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

createRenderElement() → {HTMLElement}

Creates a container element for an individual render
Source:
Returns:
detached DOM element which will become the container for a render element.
Type
HTMLElement

destroy() → {undefined}

Destroys the Viewport
Source:
Returns:
Type
undefined

destroyRenderGestures() → {undefined}

Destroys gestures for all renders.
Source:
Returns:
Type
undefined

disableDrawing() → {undefined}

Disables drawing
Source:
Returns:
Type
undefined

drawCustomRender(customRender) → {undefined}

Draws a custom render by initiating its animation.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

drawCustomRenders() → {undefined}

Calls the Layout to get custom renders, and initiates the drawing cycle for all of them.
Source:
Returns:
Type
undefined

drawItem(item, options) → {undefined}

Starts the drawing (animation) process for an Item. 1. Get one or more "render" objects from the Layout for the Item. A "render" is an object that specifies where to place an item in the canvas, along with animation options to animate the positioning/transform/delay/druation/etc. A Layout can provide zero, one, or more renders for an single Item, if the Item needs to be displayed multiple times within the Canvas (e.g. if one Item should have multiple visual representations on the screen). 2. Initiate the async draw (animation) process for each render.
Parameters:
Name Type Argument Description
item Item item to draw
options Object <nullable>
 additional options for drawing
Source:
Returns:
Type
undefined

drawItems() → {undefined}

Starts the drawing process for all Items in the ItemCollection.
Source:
Returns:
Type
undefined

drawRender(options) → {undefined}

Starts the drawing process for a render. A render is an object which contains a DOM element - the render "container" element, a "transform" - a hash of CSS properties and values to animate/set, and an "animateOptions" which is a hash of animation properties, like duration, easing, etc. A render is drawn by executing the transform on the element, using a compatible animation function like VelocityJS. The drawing/animation process is asynchronous - this method starts the process, and callbacks are used to track completion of the animation.
Parameters:
Name Type Description
options Object animation options
Properties
Name Type Description
render Object render object
Properties
Name Type Description
element HTMLElement render element
transform Object hash of CSS style properties to animate
animateOptions Object animation options
Source:
Returns:
Type
undefined

drawRenders(item, renders) → {undefined}

Draws the specified renders for the given Item. The Layout getRenders method does not specify an element in the render object, because the Layout has no knowledge of elements - it merely provides the transform and animateOptions that it wants to apply the the element(s) for an Item. The Viewport keeps track of the Items and renders in a tree data structure. When new renders are retrieved from teh Layout, this method will merge the new renders with any existing renders, add new elements where needed, and mark other elements for removal, and applies the new render transforms for any existing elements.
Parameters:
Name Type Description
item Item Item for which to draw renders
renders Object keyed object of renders to draw for the item
Source:
Returns:
Type
undefined

enableDrawing() → {undefined}

Enables drawing
Source:
Returns:
Type
undefined

eraseCustomRender(customRender) → {undefined}

Marks a custom render as needing to be erased, and starts the erase animation.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

eraseCustomRenders() → {undefined}

Erases all the custom renders.
Source:
Returns:
Type
undefined

eraseItem(item) → {undefined}

Starts the erasing process for an Item. All of the renders for the Item will be "erased" (removed from the DOM), possibly with an removal animation. Once each render is "erased" the actual render object is removed from the renders data structure. Once all of the Item's renders are removed, the item itself will be removed from the renders data structure.
Parameters:
Name Type Description
item Item item for which to remove renders
Source:
Returns:
Type
undefined

eraseItems() → {undefined}

Starts the erasing process for all the Items in the ItemCollection.
Source:
Returns:
Type
undefined

eraseRender(render, options) → {undefined}

Starts the erasing process for a render. The erasing or hiding of a render is animated, and the actual removal of the render is done after the animation completes.
Parameters:
Name Type Argument Description
render Object render to remove
options Object <nullable>
 additional options
Source:
Returns:
Type
undefined

eraseRenders(item, index, options) → {undefined}

Removes all the renders for an item, or all renders if no item is specified
Parameters:
Name Type Argument Description
item Item <nullable>
 item from which to remove all renders, or undefined to remove all renders
index Number <nullable>
 index of item, if known
options Object <nullable>
 additional options
Source:
Returns:
Type
undefined

getCustomRender(id) → {undefined}

Gets a custom render by id
Parameters:
Name Type Description
id
Source:
Returns:
Type
undefined

getCustomRenders() → {undefined}

Gets the custom renders
Source:
Returns:
Type
undefined

getEmitterEvents()

Event to method mapping for binding to the decks emitter.
Source:

getRender(item, renderIdOrIndex) → {Object}

Gets a single render object for an Item.
Parameters:
Name Type Argument Default Description
item Item Item for which t o get render
renderIdOrIndex String | Number <optional>
 0 render id or index
Source:
Returns:
- the render object (if exists)
Type
Object

getRenders(item) → {Object[]}

Gets the renders object for the given Item. This returns the renders currently stored in the Viewport instance, it does not request new renders from the Layout.
Parameters:
Name Type Argument Description
item Item <nullable>
 item for which to get renders, or if not specified, get all renders
Source:
Returns:
array of renders for the given item
Type
Object[]

hasCustomRenders() → {undefined}

Indicates if there are any custom renders.
Source:
Returns:
Type
undefined

hasRenders(item) → {boolean}

Checks if an Item currently has any renders stored in the Viewport items/renders data structure.
Parameters:
Name Type Argument Description
item Item <nullable>
 Item for which to check for the existence of renders (or undefined to see if any renders exist)
Source:
Returns:
true if the Item has renders, otherwise false
Type
boolean

initializeRender()

Called when a new element is created for use as a render. This gives the Layout the opportunity to customize the initial state of the render. If an element already exists for a previous render, and the element will be re-used for a transition, this method is not called.
Source:

loadOrUnloadRender(render) → {undefined}

Loads or unloads a render depending on factors like whether its visible in the frame element, etc.
Parameters:
Name Type Description
render Object render to load or unload
Source:
Returns:
Type
undefined

loadOrUnloadRenders() → {undefined}

Loads or unloads all the renders managed by the Viewport.
Source:
Returns:
Type
undefined

loadRender(render) → {undefined}

Delegates to the Layout instance to load the render contents.
Parameters:
Name Type Description
render Object render to load
Source:
Returns:
Type
undefined

onAllCustomRenderAnimationsComplete() → {undefined}

Called when all the custom render animations have been completed.
Source:
Returns:
Type
undefined

onAllRenderAnimationsComplete() → {undefined}

Called when all the animations in a render cycle have been completed.
Source:
Returns:
Type
undefined

onCanvasElementMoved() → {undefined}

Called when the Canvas element is moved via a touch gesture, or scrolled.
Source:
Returns:
Type
undefined

onCustomRenderAnimationComplete(customRender) → {undefined}

Called when a custom render animation completes. Adds the custom render to the internal data structure, or removes it if the custom render was being erased. This also checks for the end of the drawing cycle for all custom renders, and may perform additional logic at the end of the cycle.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

onDeckDraw() → {undefined}

Called when a draw request is made on the Deck. Triggers a redraw/reload cycle.
Source:
Returns:
Type
undefined

onDeckLayoutSet() → {undefined}

Called when a new layout is set on the Deck. Triggers a redraw/reload cycle.
Source:
Returns:
Type
undefined

onDeckLayoutSetting() → {undefined}

Called before the Deck Layout is about to be set.
Source:
Returns:
Type
undefined

onDeckReady() → {undefined}

Called when the Deck is ready. Triggers a draw/load cycle. This draw cycle can be prevented from happening by setting the drawOnDeckReady to false in the Viewport options.
Source:
Returns:
Type
undefined

onFrameBoundsSet() → {undefined}

Called when the Frame bounds are set. Triggers a redraw cycle.
Source:
Returns:
Type
undefined

onFrameBoundsSetting() → {undefined}

Called before the Frame bounds are about to be set.
Source:
Returns:
Type
undefined

onGestureElementMoved(e) → {undefined}

Called when an element is moved via a gesture.
Parameters:
Name Type Description
e
Source:
Returns:
Type
undefined

onItemChanged(e) → {undefined}

Called when an Item is changed
Parameters:
Name Type Description
e
Source:
Returns:
Type
undefined

onRenderAnimationComplete(render) → {undefined}

Called when an individual render animation completes. This updates the render data in the internal data structure, or removes the render if it was being erased. It also checks for the completion of a full render cycle, which might trigger additional events.
Parameters:
Name Type Description
render
Source:
Returns:
Type
undefined

onRenderElementMoved() → {undefined}

Called when a render element is moved (e.g. row layout where rows scroll independently)
Source:
Returns:
Type
undefined

panToItem(item, renderIdOrIndex) → {undefined}

Pans the Canvas to the Item's render element specified by renderIdOrIndex.
Parameters:
Name Type Argument Default Description
item Item item to pan to
renderIdOrIndex string | number <optional>
<nullable>
 0 render id or index to pan to
Source:
Returns:
Type
undefined

removeCustomRender(customRender) → {undefined}

Removes a custom render from the internal data structure.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

removeItem(item) → {undefined}

Removes an item from the internal items/renders data structure. This is called automatically after eraseItem, once all the renders have been erased and removed. This should not be called directly.
Parameters:
Name Type Description
item Item Item to remove
Source:
Returns:
Type
undefined

removeRender(render) → {undefined}

Removes the given render from the Viewport's internal items/renders data structure. This is called automatically after a render has been erased (after the erase animation). This should not be called directly.
Parameters:
Name Type Description
render Object render to remove
Source:
Returns:
Type
undefined

removeRenderGestureHandler(render) → {undefined}

Removes the GestureHandler for a render.
Parameters:
Name Type Description
render
Source:
Returns:
Type
undefined

setAnimator(animator) → {undefined}

Sets the animator instance
Parameters:
Name Type Description
animator
Source:
Returns:
Type
undefined

setCanvas(canvas) → {undefined}

Sets the Canvas instance
Parameters:
Name Type Description
canvas
Source:
Returns:
Type
undefined

setConfig(config) → {undefined}

Sets the configuration object
Parameters:
Name Type Description
config
Source:
Returns:
Type
undefined

setCustomRender(customRender) → {undefined}

Sets a custom render in the internal data structure
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

setDeck(deck) → {undefined}

Sets the deck instance.
Parameters:
Name Type Description
deck
Source:
Returns:
Type
undefined

setDefaultCustomRenderAnimateOptions(customRender) → {undefined}

Sets the default animation options for a custom render animation.
Parameters:
Name Type Description
customRender
Source:
Returns:
Type
undefined

setDefaultRenderAnimateOptions(options) → {Object}

Gets the default animation options, extended with the options.render.animateOptions
Parameters:
Name Type Description
options Object object to pass to callback methods, like complete
Source:
Returns:
hash of animation options
Type
Object

setFrame(frame) → {undefined}

Sets the Frame instance
Parameters:
Name Type Description
frame
Source:
Returns:
Type
undefined

setItemCollection(itemCollection) → {undefined}

Sets the ItemCollection instance
Parameters:
Name Type Description
itemCollection
Source:
Returns:
Type
undefined

setLayout(layout) → {undefined}

Sets the Layout instance
Parameters:
Name Type Description
layout
Source:
Returns:
Type
undefined

setRender(render) → {undefined}

Stores the given render object in the Viewports internal items/renders data structure. This is called automatically after a render has been drawn (after the animation completes). This should not be called directly.
Parameters:
Name Type Description
render Object render to store
Source:
Returns:
Type
undefined

shouldLoadRender(render) → {boolean}

Returns a boolean indicating whether this render should be loaded at this time. The Layout can implement a method "shouldLoadRender" to specifiy whether any given render should be loaded. If the Layout#shouldLoadRender method returns false, the Viewport will call the Layout#shouldUnloadRender method to see if the render should be unloaded.
Parameters:
Name Type Description
render Object render to check whether it needs to be loaded
Source:
Returns:
Type
boolean

shouldUnloadRender(render) → {boolean}

Returns a boolean indicating whether this render should be unloaded at this time. The Layout can implement a method "shouldUnloadRender" to specifiy whether any given render should be loaded. Layout#shouldUnloadRender is only called if Layout#shouldLoadRender returns false;
Parameters:
Name Type Description
render Object render to check whether it needs to be loaded
Source:
Returns:
Type
boolean

stopRenderAnimation(render) → {undefined}

Stops the animation for a render. This does not call the "complete" callback for the animation.
Parameters:
Name Type Description
render
Source:
Returns:
Type
undefined

unbind() → {undefined}

Unbinds all Viewport event handlers
Source:
Returns:
Type
undefined

unbindGestures() → {undefined}

Unbinds all GestureHandlerGroups managed by the Viewport
Source:
Returns:
Type
undefined

unloadRender(render) → {undefined}

Delegates to the layout instance to unload the render contents.
Parameters:
Name Type Description
render Object render to unload
Source:
Returns:
Type
undefined