Background Information and Tasks

As background for the following chapters, this section describes basic techniques that you can use when you define client methods in Zen Mojo. It also contains a section on naming conventions to consider before starting to create Zen Mojo applications. It discusses the following topics:

General-Purpose Client Variables and Functions

For reference, this section lists some key general-purpose variables and functions that you can use within a Zen Mojo client method:

this — This standard JavaScript variable represents the current instance of the template or page, depending on where you use the variable.
That is, if you use this within a template method, it returns the template instance. If you use this within a page method, it returns the page instance.
zenPage — This InterSystems variable represents the current page object.
zen(id) — This InterSystems function returns a reference to the documentView or other component that has the given id.
Note that this function cannot be used to access layout objects, which are not components. To access layout objects, you use methods of the documentView component; see “Interacting with Layout Objects,” later in this book.
zenGet(property_or_array_item, optional_default_value) — This InterSystems function examines the given object property or array item and returns its value, an optional default value, or an empty string, depending on the scenario.
Specifically, if the property or array item is defined, the function returns its value. If the item is not defined, and if the second argument is specified, this function returns the value specified by the second argument. If the item is not defined, and if the second argument is not specified, this function returns an empty string ('').
For example, consider the following code:
```
if (myobj.prop4 == undefined) {
    var returnval = 'No information available';
}
```
That code is equivalent to the following:
```
var returnval=zenGet(myobj.prop4,'No information available');
```
console.log(argument) — This standard JavaScript function generates an entry in the web console log.
alert(argument) — This standard JavaScript function generates a popup that displays the given message. InterSystems recommends that you use this function only for diagnostic purposes.
zenPage.showMessage(argument) — This InterSystems function generates a popup message that displays the given message. InterSystems recommends that you use this function for messages intended for the user.

For other variables and functions provided by InterSystems, see “Client Side Functions, Variables, and Objects” in Developing Zen Applications. For additional standard JavaScript options, see any suitable JavaScript documentation.

Stashing Values

In some cases, you may want to temporarily save client-side data so that you can use it within multiple layouts. For example, it may be necessary to collect data from the user via multiple layouts before submitting that to the server. Or you might want to display data from one layout within a different layout. Or you might need to keep track of an internal identifier. In such cases, you can stash values and then later use them. To stash a value, save it in a property of the page instance or the template instance, depending on your preference.

To save a value in a property of the page instance, set a property of the zenPage variable. The zenPage variable is available in client methods in both the page and template classes.
Start the property name with an underscore character (_), which ensures that this property is defined only on the client. To avoid collision with internally used property names, consider starting your property names with _myApp or a similar short string.
To save a value in a property of the template instance, set properties of the this variable in a client method in a template class.
Note that you can also use this in a page class. In that context, this refers to the page instance. To avoid confusion, it is best to choose a single context for the stashed values (page or template) and then use that context consistently.

When you no longer need the stashed value, use delete to remove it. For example:

delete this._MyNewValues;

Converting a JSON Object to a String

Zen Mojo packages all communication between the client and server as JSON objects, as follows:

To retrieve data from the server, you (indirectly) call the template method %OnGetJSONContent(), which returns a Zen proxy object as output. Zen Mojo uses that to create an equivalent JSON object and then sends the JSON object to the client.
To submit data to the server, you call the submitData() method of the page. As input, you must use a JSON object that contains the data.

When you stash values, however, it is important to remember that you can stash only single JavaScript values (not objects). If you need to stash an entire JSON object, first use the utility method JSON.stringify(), which takes one argument, the JSON object, and returns a string. Then stash the returned string.

The JSON.stringify() utility method is available in client methods.

Establishing Naming Conventions

It is worthwhile to establish naming conventions to avoid confusion. This section discusses the following topics:

Zen Mojo programs are case-sensitive. Remember that a is not the same as A.

Class Names

InterSystems strongly recommends that you do not create any classes in a package called ZEN.Component using any combination of uppercase and lowercase characters. If you create a package called ZEN.Component, that interferes with the way that Zen generates client-side code.

Also, note that because a Zen Mojo application can be easily extended to use multiple templates, you might want to place your template classes in a subpackage.

Important:

Because these classes are automatically projected to XML, there is an additional consideration. If multiple classes have the same short class name (that is, the class name without the package), be sure that the NAMESPACE parameter is unique for each such class.

This rule is a consequence of the fact that the short class name becomes the name of a global XML element, and those elements must be unique in an XML namespace. In Caché, each XML-enabled class must have a unique combination of the short class name and the NAMESPACE parameter.

Method Names

InterSystems classes use case to distinguish between client and server methods. You might find it helpful to follow these conventions as well.

Kind of Method	Convention for Method Name	Example
Client method (that is, a method written in JavaScript)	Start with a lowercase letter and use an initial capital letter for each successive word (in-word capitalization).	myMethodName()
Server method (that is, a method written in ObjectScript, Caché Basic, or Caché MVBasic)	Start with an uppercase letter and use in-word capitalization. (Or start with a % character, followed by an uppercase letter.)	MyMethodName or %MyMethodName

Content Objects and JSON Providers

Each documentView is specified by two content objects — a data object and a layout graph, as described in “The Template System,” earlier in this book. You must use the names of these objects consistently in several places in the code, so it is useful to have a convention for them. One approach is as follows:

Use the name document for the data object of your primary documentView
Use the name layout for the layout graph of your primary documentView
Use more specific names for the content objects of other documentView components

Another approach is as follows:

Use the name componentidData for the data object of the documentView whose id is componentid
Use the name componentidLayout for the layout graph of the documentView whose id is componentid

Note that (via the PROVIDERLLIST parameter) the page class includes a JSON provider for each data object. For this reason, the names of the data objects also become names of the JSON providers. The terms data object and JSON provider are sometimes used interchangeably, although this book simply uses data object.

Keys

You can associate keys with many of the layout objects, and your application can end up with a large number of keys. It is particularly useful to establish a naming convention for them. A simple system would be as follows:

Use names that make the code easier to read.
Use a verb for the name of a key in a control.
Use a noun for the name of a key in any other scenario.
Adopt a hierarchical (or semi-hierarchical) set of names for related keys. For example, you might use the key name accounts for a layout element that displays a table of accounts, and then use the key name account-detail for a layout element that displays details for one account.

Important:

The name of a key cannot include a colon (:) character.