Using Zen Mojo
Summary of Callbacks and Event Handlers
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter summarizes all the event handlers and callbacks that apply to a Zen Mojo page. To define the behavior of the page, you must implement some or all of these items. This chapter discusses the following topics:

The ongetdata and ongetlayout Callback Attributes
The two most basic callback attributes of a documentView are ongetdata and ongetlayout, which were introduced in earlier parts of this book.
When These Callbacks Are Used
When a Zen Mojo page is displayed or when the method updateLayout() is executed, Zen Mojo examines both ongetdata and ongetlayout, and executes the code specified in these callbacks. ongetdata is executed first, followed by ongetlayout (but see the following notes).
Typically, these callbacks invoke the page method getContent().
Within both callbacks, the variables key and value are available. The variable key equals the key of the selected layout object, if any, and the variable value equals the value of the selected layout object, if any.
Furthermore, within ongetlayout, it is possible to access the data object returned by ongetdata (but see the following notes).
Notes:
Specifying ongetdata or ongetlayout
To define either of these callback attributes, use the following general procedure:
Details for getContent()
The ongetdata and ongetlayout callback attributes typically call the getContent() method of the page. This section provides detailed information on this method.
(Note that it can also be useful to call this method in other scenarios. For example, see the onselect() method in the sample ZMdemo.LoadAsync.baseTemplate.)
The getContent() method returns a content object (a data object or a layout graph). This method has the following arguments:
getContent(providerName, key, criteria, force, notify)
Where:
The getContent() method does the following:
  1. It invokes the onGetContent() method of the associated template class. If that method returns content, the system returns that content.
    To find the initial template class, Zen Mojo examines the TEMPLATECLASS parameter of the page class.
  2. If onGetContent() returns null, the system checks to see whether the page cache contains any content. If so, the system returns that content.
  3. If there is no cached content, the system invokes the %OnGetJSONContent() method of the associated template class, uses the result to create the content, and then returns that content.
For a diagram of this activity, see The Template System,” earlier in this book.
Defining onGetContent()
Each Zen Mojo template class should define the onGetContent() method. This method is a dispatcher that returns a content object. This method has the following signature:
ClientMethod onGetContent(providerName, key, criteria) [ Language = javascript ]
Where:
In this method, the standard technique is to use an outer branching construct that uses the providerName argument.
The following shows an example. In this scenario, mainViewLayout and leftViewLayout are the keys for layout graphs. Notice that the switch construct contains branches only for these layout graphs. The method thus returns null when it is invoked with the key for a data object.
ClientMethod onGetContent(providerName, key, criteria) [ Language = javascript ]
{
    var content = null;

    // dispatch to convenient methods
    // if content is null, then the %OnGetJSONContent method will be called

    switch(providerName) {
    case 'mainViewLayout':
        content = this.myGetMainViewLayout(key,criteria);
        break;
    case 'leftViewLayout':
        content = this.myGetLeftViewLayout(key,criteria);
        break;
    }
    return content;
}
Defining %OnGetJSONContent()
In most cases, each Zen Mojo template class should define the %OnGetJSONContent() method. This method should return the requested data object as an output parameter. This method has the following signature:
ClassMethod %OnGetJSONContent(pProviderName As %String, 
                              pKey As %String, 
                              ByRef pParms, 
                              Output pObject As %RegisteredObject, 
                              pCriteria As %RegisteredObject, 
                              pLoad As %Boolean = 0) As %Status
Where:
In this method, the standard technique is to use an outer branching construct that uses the pProviderName argument.
Then, within any given pProviderName branch, use an inner branching construct that examines the pKey argument and that creates a different version of pObject depending on that argument. The following shows an example where pProviderName has only one possible value, but pKey has multiple possible values:
ClassMethod %OnGetJSONContent(pProviderName As %String, pKey As %String, ByRef pParms, 
                              Output pObject As %RegisteredObject, pCriteria As %RegisteredObject, 
                              pLoad As %Boolean = 0) As %Status
{

    if (pProviderName = "mainViewData") {

        //nothing to return for MyButton1 so there is no branch for that
        if (pKey = "MyButton2") {
            //create proxy object that the Zen Mojo will convert to a JSON string
            //and send to the client
            set pObject = ##class(%ZEN.proxyObject).%New()
            set random=$R(100)+1
            set tPerson = ##class(Sample.Person).%OpenId(random)
            set pObject.personName=tPerson.Name
            set pObject.personDOB=$zdate(tPerson.DOB,3)
        }
        elseif (pKey = "MyButton3") {
            //create proxy object that the Zen Mojo will convert to a JSON string
            //and send to the client
            set pObject = ##class(%ZEN.proxyObject).%New()
            set tList = ##class(%Library.ListOfObjects).%New()
            set pObject.children = tList
            For i=1:1:5 {
                // we could retrieve the same company more than once this way
                // but this is a demo so that doesn't matter
                set tNumber=$RANDOM(20)+1
                set tCompany = ##class(Sample.Company).%OpenId(tNumber)
                set tCompanyData = ##class(%ZEN.proxyObject).%New()
                set tCompanyData.companyName = tCompany.Name
                set tCompanyData.companyMission = tCompany.Mission
                set tCompanyData.companyRevenue = tCompany.Revenue
                Do tList.Insert(tCompanyData)
            }
            set pObject.rowCount = tList.Count()
        }

    } ; additional pProviderName branches would go here
    quit $$$OK
}
Other Callback Attributes
Zen Mojo provides several additional callback attributes for a documentView:
To use these callback attributes, specify a value for the attribute for a documentView used on the page. In most cases, the value is an expression that invokes a method you have implemented in the template class. For example:
  onresolvemethod="return zenPage.getTemplate().resolve(context,which);"
where getTemplate() is a method of basePage that returns a reference to the instance of the current template associated with the page.
Alternately, you could invoke it indirectly by calling a simple wrapper method of the same name in the page class. If necessary, you can implement the callback method itself in the page class, but best practice is to put all application logic in the template class.
Event Handlers
When an event occurs on the page, Zen Mojo automatically invokes an event handler in the associated template class. The Zen Mojo event handlers are the onselect(), onchange(), and onevent() methods, which have no behavior by default. You define these methods in your template class, in order to make your page interactive.
Where Events Are Supported
In each plugin, events are supported (by default) in the layout objects that are typically used for user interaction. This means that layout objects that represent buttons, menus, sliders, and other controls support events; that is, the plugin inserts event handling for those objects. Layout objects that represent static elements do not support events.
You can suppress the insertion of event handling for a given layout object. To do so, specify one or more of the following attributes of that layout object, as needed:
Implementing Event Handlers
Define some or all of the following event handler methods in your template class. In a typical implementation, these methods cause changes to the page or documentView instance, depending on your needs.
onselect()
ClientMethod onselect(key, value, docViewId) [ Language = javascript ]
Defines how the page behaves when a user selects a layout object in a documentView. The arguments are as follows:
onchange()
ClientMethod onchange(key, value, final, docViewId) [ Language = javascript ]
Defines how the page behaves when a user changes the value of a layout object in a documentView. The arguments are as follows:
onevent()
ClientMethod onevent(eventType, key, value, docViewId) [ Language = javascript ]
Defines how the page behaves when another type of event occurs within a documentView (an event other than select or change). The arguments are as follows: