Working with Multiple Templates (Dynamic 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 the previous chapter) and dynamic dispatch (discussed in this 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 Dynamic Dispatch

Compared to explicit dispatch, the dynamic dispatch mechanism uses a larger set of small templates. Each template is key-specific and provides only one part of the page logic. For example, one template might only return content objects for a specific key. Another template would only handle select events for the same key.

When the dynamic dispatch mechanism is enabled (via the templateDispatchMode property), Zen Mojo checks for a key-specific template at several specific points within the page logic, loads the template, and then uses it for the designated purpose. Specifically, if dynamic dispatch is enabled:

When the client invokes the getContent() method of the page, Zen Mojo loads the applicable template and calls the getContent() method of that template class.
The following subsection explains how Zen Mojo finds the applicable template in this scenario and in the following scenarios.
When a select event occurs on the page, Zen Mojo loads the applicable template and calls the onselect() method of that template class.
When a change event occurs on the page, Zen Mojo loads the applicable template and calls the onchange() method of that template class.
When an event of any other type occurs on the page, Zen Mojo loads the applicable template and calls the onevent() method of that template class.

How Zen Mojo Finds Templates, in Dynamic Dispatch

In dynamic dispatch, Zen Mojo finds the template to load as follows:

Zen Mojo looks for a template in the following XML namespace:
```
templateDispatchBaseNamespace/scenario
```
Where templateDispatchBaseNamespace is the value of the page property of that name and scenario indicates the scenario.
If a data object is requested, scenario is data. If a layout graph is requested, scenario is layout. If an event (of any kind) has occurred, scenario is events.
In this namespace, Zen Mojo loads the template whose short class name is key, where key is the current key.

Note that this discussion assumes that you are using data as the provider name when you are retrieving data objects and that you are using layout as the provider name when you are retrieving layout graphs.

Modifying the Page to Use Dynamic Dispatch

To modify the page class to use dynamic dispatch:

Override the templateDispatchMode property of the class and specify its InitialExpression keyword as 1:
```
Property templateDispatchMode As %ZEN.Datatype.boolean [ InitialExpression=1] ;
```
Override the templateDispatchBaseNamespace property of the class and specify its InitialExpression keyword. For the value of this keyword, specify the base part of the XML namespace used by the templates.
For example, the Zen Mojo plugin reference documentation application uses this value:
```
Property templateDispatchBaseNamespace As %ZEN.Datatype.string 
[ InitialExpression="http://www.intersystems.com/zen/mojo/documentation"] ;
```

Defining the Templates

To enable dynamic dispatch, define a set of templates in three groups.

One group returns data objects. These templates must be in the XML namespace templateDispatchBaseNamespace/data. (That is, the NAMESPACE parameter of each of these template must equal templateDispatchBaseNamespace/data where templateDispatchBaseNamespace is the value of the page class property of that name.)
If you use a different provider name (a name other than data) to retrieve data objects, replace data with your provider name.
These templates must implement onGetContent() and (if suitable) %OnGetJSONContent().
One group returns layout graphs. These templates must be in the XML namespace templateDispatchBaseNamespace/layout
If you use a different provider name (a name other than layout) to retrieve layout graphs, replace layout with your provider name.
These templates must implement onGetContent().
One group defines all event handling. These templates must be in the XML namespace templateDispatchBaseNamespace/events
These templates must implement onselect(), onchange(), or onevent(), as needed.

Tip:

For clarify and ease of maintenance, you could place these groups of template classes in subpackages named Data, Layout, and Events, respectively. For an example, see the %ZEN.Mojo.PluginDocumentation.Templates package, which is part of the plugin reference documentation application.