Using Zen Mojo
Using Keys
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
  1. It obtains the current data key, layout key, or both from documentView A.
  2. 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.
  3. 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:
  1. It obtains the current data key, layout key, or both.
  2. 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:
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:
  1. Use the syntax zen('docViewId') to refer to the documentView that has the given id.
  2. Call the setDocumentKey() method, the setLayoutKey() method, or both of that documentView.
  3. 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:
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.