Zimlet JavaScript API Reference - ZmAppViewMgr

Class ZmAppViewMgr


This class performs view and layout management. It expects there to be an HTML "skin" with containers for various components. A container is an empty DIV with a known ID, so that we can use it to place the corresponding component's content. A component is a widget; it is the widget's HTML element that is positioned and sized based on the container's location and size. The containers are part of the flow (they are positioned relatively), so their location and size should be adjusted when necessary by the browser. The components are not children of their containers within the DOM tree; they are children of the shell, and are positioned absolutely. There appears to be a performance gain in keeping our HTML elements closer to the top of the DOM tree, possibly because events do not propagate as far. A handful of components are positioned statically. Those are generally the ones that appear in the top row: banner, user info, etc. The positioning style is set through skin hints.

The following containers/components are supported:

  • banner: displays logo
  • user info: user name
  • quota: quota bar
  • search bar: a text input and a few buttons
  • search results toolbar: search tab only
  • app chooser: a toolbar with buttons for changing apps
  • new button: button for creating something new (email, contact, etc)
  • tree: area on left that usually shows overview (folders, calendars, etc)
  • tree footer: optionally displays mini-calendar
  • top toolbar: a view-specific toolbar
  • app content: used to present data to the user
  • sash: a thin moveable vertical bar for resizing tree width


In general, the app view manager responds to changes in the skin by having each of the affected components adapt to its container's new location and/or size. That means that we are dependent on the browser to relocate and resize the containers within the skin properly.

The top and bottom toolbars and the app content are treated somewhat differently: they come under the purview of "app view management". In general, an application represents a view with a toolbar and a content area (which is often a list view). App view management allows these views to be pushed and popped as if they were in a stack. That way, the views only need be constructed once each.

The app view components are hidden and shown using two methods: z-index and relocation. Since every component hangs off the shell, it must have a z-index of at least Z_VIEW (300) to be visible. It can be hidden by setting its z-index to Z_HIDDEN (100). Since both IE and Firefox have display bugs related to the use of z-index, we use relocation as well: a hidden component is positioned way off the screen. (In IE, SELECT fields don't obey z-index, and in Firefox, the cursor bleeds through.) Note: the above was true in 2005, and we haven't rewritten the app view manager substantially since then. Some day we may just append the elements to their parent containers within the DOM, but until then we'll do absolute positioning.

A view can open in a tab (in the row of app buttons) rather than replacing the current view. Those are handled in essentially the same way (view push and pop), but they also manage the app button. We currently manage only a single view in a tab.

Defined in: ZmAppViewMgr.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ZmAppViewMgr(shell, controller, isNewWindow, hasSkin)
Creates a layout manager from the given components.
Method Summary
Method Attributes Method Name and Description
 
createView(params)
Registers a set of elements comprising an app view.
 
displayComponent(cid, show, doFit, comp, noReflow)
Handles several tasks needed to make sure a component is actually visible.
 
Fits all components to the container.
 
Gets the current top-level view for the given app.
 
getContainer(cid, comp)
Returns the requested container.
 
Gets the main content object of the given view.
 
Gets the ID of the view currently being displayed.
 
Gets the type of the view currently being displayed.
 
Gets the ID of the app view last displayed.
 
Gets the currently pending view waiting to get pushed.
 
getViewComponent(cid, viewId)
Returns the requested component (widget) for the given view.
 
getViewsByType(type, visible)
Returns a list of views of the given type.
 
isAppView(viewId)
Checks if the view is the app view.
 
isFullScreen(viewId)
Returns true if the view is full screen.
 
isHidden(cid, viewId)
Returns true if the given component should be hidden.
 
Checks if it is OK to unload the app (for example, user logs out, navigates away, closes browser).
 
isVisible(viewId)
Returns true if the given view is visible to the user.
 
popView(force, viewId, skipHistory)
Hides the currently visible view, and makes the view on top of the hidden stack visible.
 
pushView(viewId, force)
Makes the given view visible, pushing the previously visible one to the top of the hidden stack.
 
setAppView(app, viewId)
Sets the current top-level view for the given app.
 
setHiddenComponents(viewId, cidList, hide, app)
Sets whether the given components should be hidden.
 
setTabTitle(viewId, text)
Sets the tab title.
 
setView(viewId, force)
Makes the given view visible, and clears the hidden stack.
 
setViewComponents(viewId, components, show, app)
Registers the given components with the app view manager, and optionally displays them.
 
showComponent(cid, show, comp)
Shows or hides the given component.
 
Shows the view that was waiting for return from a popped view's callback.
 
showSkinElement(cid, show, noReflow)
Shows or hides the skin element (not always the same as the container) for a given component.
 
stageView(viewId)
Moves the given view to the top of the hidden stack, so that it will appear when the current view is popped.
 
Updates and shows the current view title in the title bar.
Class Detail
ZmAppViewMgr(shell, controller, isNewWindow, hasSkin)
Creates a layout manager from the given components.
Author: Conrad Damon.
Parameters:
{DwtShell} shell
the outermost containing element
{ZmController} controller
the app controller
{Boolean} isNewWindow
if true, we are a child window of the main app
{Boolean} hasSkin
if true, the app has provided containing HTML
Method Detail
createView(params)
Registers a set of elements comprising an app view.
Parameters:
{Hash} params
a hash of parameters
{string} params.viewId
the view ID
{string} params.viewType
the view type
{String} params.appName
the name of the owning app
{Hash} params.elements
a hash of elements
{ZmController} params.controller
controller responsible for this view
{Hash} params.callbacks
a hash of functions to call before/after this view is shown/hidden
{Boolean} params.isAppView
if true, this view is an app-level view
{Boolean} params.isTransient
if true, this view does not go on the hidden stack
{Hash} params.tabParams
the tab button params; view is opened in app tab instead of being stacked
{Hash} params.hide
components that aren't displayed in this view

displayComponent(cid, show, doFit, comp, noReflow)
Handles several tasks needed to make sure a component is actually visible.
Parameters:
{constant} cid
the component ID
{boolean} show
if true, show the component; otherwise hide it
{boolean} doFit
if true, fit component to container
{object} comp
if provided, pass this to showComponent, so it does not just look for the cid in the current view (useful for previous view. see ZmAppViewMgr.prototype._setViewVisible)
{boolean} noReflow
if true, tell skin to not refit all components

fitAll()
Fits all components to the container.

{string} getAppView(app)
Gets the current top-level view for the given app.
Parameters:
{String} app
the name of an app
Returns:
{string} ID of the app's current view

getContainer(cid, comp)
Returns the requested container.
Parameters:
cid
comp

{Object} getCurrentView(view)
Gets the main content object of the given view.
Parameters:
view
Returns:
{Object} the current main content view object

{string} getCurrentViewId()
Gets the ID of the view currently being displayed.
Returns:
{string} the view id

{string} getCurrentViewType()
Gets the type of the view currently being displayed.
Returns:
{string} the view type

{Object} getLastViewId()
Gets the ID of the app view last displayed.
Returns:
{Object} the last view

{Object} getPendingViewId()
Gets the currently pending view waiting to get pushed.
Returns:
{Object} the pending view id

getViewComponent(cid, viewId)
Returns the requested component (widget) for the given view. The search is done in the following order: 1. A component particular to that view 2. A component associated with the view's app 3. A global component
Parameters:
{constant} cid
component ID
{constant} viewId
view ID

getViewsByType(type, visible)
Returns a list of views of the given type. The views are the anonymous view objects used by the app view mgr.
Parameters:
{string} type
a view type
{boolean} visible
if true, only return visible views

{Boolean} isAppView(viewId)
Checks if the view is the app view.
Parameters:
{int} viewId
the view id
Returns:
{Boolean} true if the view is the app view

{boolean} isFullScreen(viewId)
Returns true if the view is full screen.
Parameters:
{constant} viewId
the view id
Returns:
{boolean} true if full screen

isHidden(cid, viewId)
Returns true if the given component should be hidden. Checks local, app, and then global levels. At any level, the presence of a component trumps whether it is supposed to be hidden.
Parameters:
{constant} cid
component ID
{constant} viewId
view ID

{Boolean} isOkToUnload()
Checks if it is OK to unload the app (for example, user logs out, navigates away, closes browser).
Returns:
{Boolean} true if OK to unload the app

{boolean} isVisible(viewId)
Returns true if the given view is visible to the user.
Parameters:
{string} viewId
a view ID
Returns:
{boolean} true if the given view is visible to the user

{Boolean} popView(force, viewId, skipHistory)
Hides the currently visible view, and makes the view on top of the hidden stack visible.
Parameters:
{Boolean} force
if true, do not run callbacks (which check if popping is OK)
{int} viewId
the view ID. Only pop if this is current view
skipHistory
Returns:
{Boolean} true if the view was popped

{Boolean} pushView(viewId, force)
Makes the given view visible, pushing the previously visible one to the top of the hidden stack.
Parameters:
{int} viewId
the ID of the app view to push
{Boolean} force
if true, do not run callbacks
Returns:
{Boolean} true if the view was pushed (is now visible)

setAppView(app, viewId)
Sets the current top-level view for the given app. Should be called by an app (or controller) that changes the top-level view of the app.
Parameters:
{String} app
the name of an app
{string} viewId
the view ID

setHiddenComponents(viewId, cidList, hide, app)
Sets whether the given components should be hidden. That setting can appear at any of three levels: global, app, or local.
Parameters:
{constant} viewId
the view id
{array} cidList
list of component IDs
{boolean} hide
if true, hide the components
{constant} app
name of app (for view ZmAppViewMgr.APP)

setTabTitle(viewId, text)
Sets the tab title.
Parameters:
{int} viewId
the view id
{String} text
the title

{Boolean} setView(viewId, force)
Makes the given view visible, and clears the hidden stack.
Parameters:
{int} viewId
the ID of the view
{Boolean} force
if true, ignore pre-emption callbacks
Returns:
{Boolean} true if the view was set

setViewComponents(viewId, components, show, app)
Registers the given components with the app view manager, and optionally displays them.
Parameters:
{constant} viewId
the view id
{hash} components
a hash of component IDs and matching objects
{boolean} show
if true, show the components
{constant} app
name of app (for view ZmAppViewMgr.APP)

showComponent(cid, show, comp)
Shows or hides the given component. It may still need to be positioned.
Parameters:
{constant} cid
the component ID
{boolean} show
if true, show the component; otherwise hide it
{DwtControl} comp
component (optional)

showPendingView(show)
Shows the view that was waiting for return from a popped view's callback. Typically, the popped view's callback will have put up some sort of dialog, and this function would be called by a listener on a dialog button.
Parameters:
{Boolean} show
if true, show the pending view

showSkinElement(cid, show, noReflow)
Shows or hides the skin element (not always the same as the container) for a given component.
Parameters:
{constant} cid
the component ID
{boolean} show
if true, show the skin element; otherwise hide it
{boolean} noReflow
if true, tell skin to not refit all components

stageView(viewId)
Moves the given view to the top of the hidden stack, so that it will appear when the current view is popped.
Parameters:
{int} viewId
the ID of the view

updateTitle()
Updates and shows the current view title in the title bar.

Documentation generated by JsDoc Toolkit 2.3.0 on Tue Jun 28 2016 21:01:35 GMT-0400 (EDT)