Using Keys

Zen Mojo provides a system of keys (introduced in the first chapter) that you can use to drive user interaction. This chapter describes how to use this system. It discusses the following topics:

At an early stage in development, make sure to define a naming convention for your keys; see “Naming Conventions,” earlier in this book.

Possible Approaches

You can use keys in different ways. This section describes two primary approaches. A hybrid approach and other approaches are also possible.

Driving One documentView from Another documentView

In this approach, the pageContents area contains two documentView components and one of them (typically, the left or top one) drives the other one (typically the right or bottom one).

The typical scenario is that one documentView (A) contains a set of buttons or menus, each with a unique key. When the user selects an item in that documentView, the onselect() event handler does the following:

It obtains the current data key, layout key, or both from documentView A.
Based on that key or keys, it then sets the data key, layout key, or both for the other documentView (B).
Note that within onselect(), the current value of the selected item is also available, so the logic could use that information as well.
It then updates the layout of documentView B.

Note that not all page managers support multiple documentViews.

Using a Document Stack

Zen Mojo also provides support for document stacks; see the section “Working with Document Stacks.”

In the document stack approach, the pageContents area contains a single documentView component. In a typical scenario, when the user selects an item, the onselect() event handler does the following:

It obtains the current data key, layout key, or both.
Based on that key or keys, it calls pushDocument() to add a new version onto the document stack and display it within the documentView. Zen Mojo automatically provides a header that includes a back button, which the user can return to the previous stack level of the application.
Note that within onselect(), the current value of the selected item is also available, so the logic could use that information as well.

Note that document stacks are different from the browser history stack. Zen Mojo provides a separate set of tools that you can use to manage the browser history stack.

For information on pushDocument() and related methods, see the section “Working with Document Stacks.”

Specifying the Initial Keys for a documentView

To specify the initial keys for a documentView, specify either or both of the following properties of the <mojo:documentView> element in the page class:

initialLayoutKey — Initial layout key of this documentView
initialDocumentKey — Initial data key of this documentView

For both properties, home is the default value.

For example:

<:mojo:documentView id="mainView"
developerMode="true" 
initialDocumentKey="initialKey"
initialLayoutKey="initialKey"
ongetlayout = "return zenPage.getContent('layout',key,criteria);"
ongetdata = "return zenPage.getContent('data',key,criteria);">
...
<:/mojo:documentView>

Setting Keys and Updating the Layout

To set the keys for a documentView instance and then update the layout of that documentView, do the following within a suitable client method:

Use the syntax zen('docViewId') to refer to the documentView that has the given id.
Call the setDocumentKey() method, the setLayoutKey() method, or both of that documentView.
Call the updateLayout() method of that documentView.

For example:

    var docView = zen('mainView');
    docView.setDocumentKey(key);
    docView.updateLayout();

The following list gives the details for these methods:

setDocumentKey()

ClientMethod setDocumentKey(key, criteria, level) [ Language = javascript ]

Sets the key and optional criteria for the data object (for the given level of the document stack). The arguments are as follows:

key is a short, unique name that indicates the specific version of the content.
criteria is either a string or an object that contains any additional information for the template to use. For example, this can be a search string entered by the user. Or it could be an object containing multiple properties used internally in your code.
Zen Mojo does not directly use the criteria argument. You can use this argument within your client methods, typically in methods called by your ongetdata and ongetlayout callbacks. For examples, see “Using the Criteria Argument,” later in this chapter.
level is the level (of the document stack) for which you are setting the key and criteria. (For each documentView, each level in the document stack can have its own key and criteria for its data object.)
If you are not using methods such as pushDocument() or popDocument(), you can simply ignore this argument. For information on the document stack, see the chapter “Working with Document Stacks.”

This method also invalidates the cache (for the given level of the document stack). To update the layout, use updateLayout(), described later.

setLayoutKey()

ClientMethod setLayoutKey(key, criteria, level) [ Language = javascript ]

Sets the key and optional criteria for the layout graph (for the given level of the document stack). The arguments are similar to those used by setDocumentKey(); the difference is that setLayoutKey() affects the key and criteria used by the layout graph, rather than by the data object.

This method also invalidates the cache (for the given level of the document stack). To update the layout, use updateLayout(), described next.

updateLayout()

ClientMethod updateLayout(effect) [ Language = javascript ]

Invokes the ongetdata and ongetlayout callbacks of the documentView, using the current data and layout keys and criteria, (thus updating its current layout).

The effect argument specifies the transition effect to use, if you are using the default page manager. This argument is ignored for other page managers. This argument can be 'fade', 'fade-flakes', or 'fade-tiles'.

Using the Criteria Argument

This section shows examples that use the criteria argument. In the first example, the client method creates an object for use as the criteria argument:

    var reqId = {HistoryStart:this.historyStart,HistoryEnd:this.historyEnd};
    reqId.SessionID = data.SessionID;
    reqId.SessionMRN = data.SessionMRN;

    docView.setDocumentKey(key,reqId);
    docView.updateLayout();

The next example creates a criteria object that contains a search term entered by the user and a property used internally by the layout graph:

    docView.setDocumentKey(key,{term:this.searchTerm, initLoad:true});
    docView.setLayoutKey(key);
    docView.updateLayout('fade');

The criteria argument is available within the %OnGetJSONContent() method as pCriteria. In the following example, the %OnGetJSONContent() method first checks to make sure that pCriteria is an object, and then extracts a property from it, for use in retrieving data from the server:

    if $IsObject(pCriteria) {
        set tDocId=pCriteria.docId }
    else {
        set tDocId=""
    }
   ///use tDocId to retrieve specific data, if applicable

Getting Keys of a documentView

Zen Mojo also provides methods that you can use to get the current data and layout keys for any given documentView. These methods are methods of the documentView instance. The methods are as follows:

getDocumentKey()

ClientMethod getDocumentKey() [ Language = javascript ]

Returns the data key for this documentView (for the current level of the document stack).

getLayoutKey()

ClientMethod getLayoutKey() [ Language = javascript ]

Returns the layout key for this documentView (for the current level of the document stack).

Working with Document Stacks

To work with a document stack, you invoke methods of a documentView instance. To invoke one of these methods from a client method, use a couple of steps like the following:

var mainView = zen('mainView');
mainView.methodname();

In the first line, zen('mainView') is a reference to the documentView whose id is 'mainView'. The second line invokes a method associated with that documentView.

getLevel()

ClientMethod getLevel() [ Language = javascript ]

Returns the current document stack level. The initial stack level is 0. When you use pushDocument(), the level is incremented by 1. When you use popDocument(), the level is decremented by 1.

popAll()

ClientMethod popAll(render,clearDataCache) [ Language = javascript ]

Removes all document versions except for the original, updates the display, and sets the document stack level to 0. If render is true, the method re-renders the newly revealed previous document version. If clearDataCache is 1, the method clears the cache for the panel that is now displayed.

popDocument()

ClientMethod popDocument(render,clearDataCache) [ Language = javascript ]

Removes the most recent document version from the document stack, updates the display, and decrements the document stack level by 1. For information on render and clearDataCache, see popAll().

popDocuments()

ClientMethod popDocuments(number, render, clearDataCache) [ Language = javascript ]

Removes the given number (number) of most recent document version from the document stack, updates the display, and decrements the document stack level as needed. For information on render and clearDataCache, see popAll().

pushDocument()

ClientMethod pushDocument(layoutKey, layoutCriteria, dataKey, dataCriteria) [ Language = javascript ]

Adds a new document version onto the document stack and displays it (by default) in front of the previous versions. The new document version uses the given layout key and criteria and data key and criteria to fetch its layout and data. If dataKey is not provided, then the data from the current level is used.

This method also increments the document stack level by 1.