Working with Multiple Templates (Explicit Dispatch)

So far this book has discussed only single-template applications, but your Zen Mojo application can use multiple template classes, which enables you to divide your application code into more easily maintained units.

Zen Mojo provides two ways to work with multiple templates: explicit dispatch (discussed in this chapter) and dynamic dispatch (discussed in the next chapter). In either case, the methods in the templates can use all the tools described in the earlier chapters of this book.

This chapter discusses the following topics:

Introduction to Explicit Dispatch

With the explicit dispatch mechanism, each template corresponds to an application area. Areas serve as short logical names for the templates, which have longer and less convenient class names.

The user makes selections on the page, invoking the goToArea() method or other methods that set the current area and therefore determine which template to use. The page methods getContent() and submitData() always use the current template, whichever that is.

Creating a page like this is only slightly more complex than creating a simple page. When a page has been set up this way, it is easy to extend the page by adding more templates.

Associating Areas with Templates

To define areas (and associate a template with each), implement the %OnGetTemplateList() method in the Zen Mojo page class. This method is as follows:

method %OnGetTemplateList(Output pTemplates) as %Status

Where pTemplates is expected to be a multidimensional array with the following nodes:

Node	Contents
pTemplate	Count of subnodes
pTemplate(i) where i is an integer	A $LISTBUILD list that consists of the following items, in order: Logical name of the area Full package and class name of the corresponding template XML namespace of the template

The following shows an example implementation:

Method %OnGetTemplateList(Output pTemplates) As %Status
{
    Set tSC = $$$OK
    Try {
        Kill pTemplates

        set area="area-home"
        set template="MyApp.Templates.HomeTemplate"
        set ns="http://www.corporate.com/myapp/home"
        Set pTemplates($I(pTemplates))=$LB(area,template,ns)

        set area="area-second"
        set template="MyApp.Templates.SecondaryTemplate"
        set ns="http://www.corporate.com/myapp/secondary"
        Set pTemplates($I(pTemplates))=$LB(area,template,ns)
    }
    Catch(ex) {
        Set tSC = ex.AsStatus()
    }
    Quit tSC
}

Setting the Current Area and Key for the Page

To set the current area for the page, use the following methods of the page instance. To invoke one of these methods from a client method, use the syntax zenPage.methodname().

gotoArea()

ClientMethod gotoArea(area, key1, key2, nohistory) [ Language = javascript ]

Sets the current area, current key1, and current key2. If nohistory is true, then do not push this change onto the history stack.

gotoAreaKB()

ClientMethod gotoArea(evt,area, key1, key2, nohistory) [ Language = javascript ]

Given a keyboard event (evt), sets the current area, current key1, and current key2. If nohistory is true, then do not push this change onto the history stack.

If you call any of these method, you should define changeAreaHandler() to specify what should happen when the current area and keys change.

Implementing changeAreaHandler()

If you call gotoArea() or gotoAreaKB(), be sure to define changeAreaHandler() in the page class. This method is invoked automatically by those methods, and it should specify what happens when the keys change.

The changeAreaHandler() method has following signature:

ClientMethod changeAreaHandler() [ Language = javascript ]

Accessing the Current Template

To access the current template, you can use the following methods of the page instance. To invoke one of these methods from a client method, use the syntax zenPage.methodname()

getTemplate()

ClientMethod getTemplate() [ Language = javascript ]

Returns a reference to the current template. Use this method so that, for example, you can execute methods of the template.

getTemplateForArea()

ClientMethod getTemplateForArea(area) [ Language = javascript ]

Returns the name of the template class associated with a given area.