Additional Steps for Mobile and Hybrid Applications

Zen Mojo is designed for client-server interaction, and you can use it to create applications whose web clients are on either mobile devices or on desktops. Most of this book discusses tools and techniques that apply to both scenarios. This chapter, however, discusses additional steps that apply when you create applications for mobile devices. This chapter discusses the following topics:

For an overview, see “Mobile Applications” and “Hybrid Applications” in the first chapter.

Note:

Experienced Zen developers please note that some common design features of desktop Zen and CSP applications should not be used in mobile and hybrid apps. For example, avoid using Zen special variable %session in hybrid apps. When a user stops using the app and comes back later, a new session may be started even though the mobile app is still in the state the user left it. If the server requires %session to be in a specific state, this could cause serious problems.

Specifying Meta Tags

When you create a page for use on mobile devices, be sure to implement the %OnDrawHTMLMeta() method in the page class so that the page contains the appropriate meta tags. This method has the following signature:

Method %OnDrawHTMLMeta() As %Status

This method is called at the start of the HTML HEAD section of the page (just after the title). Your implementation should write any needed meta tags. For example:

Method %OnDrawHTMLMeta() As %Status
{
 Write "<meta name=""viewport"" content=""width=device-width, initial-scale=1.0,maximum-scale=1, user-scalable=no""/>"
 Quit $$$OK
}

This example sets both the initial and maximum scale equal to 1 and disables user scaling.

Modifying the Page Class to Support Offline Use

For use in a mobile environment, a Zen Mojo page class must be able to accept requests from the offline version of the page. To modify the page class in this way:

Override the ALLOWMOBILE parameter of the class and specify its value as 1:
```
Parameter ALLOWMOBILE =1;
```
Override the remoteBrokerAddress property of the class and specify its InitialExpression keyword. For the value of this keyword, specify the URL of the %CSP.Broker.cls file used by the web application. The URL must have the following form:
```
http://<remote-server>:<port>/csp/user/%25CSP.Broker.cls 
```
where %25 is used to represent a % character. For example:
```
Property remoteBrokerAddress As %ZEN.Datatype.string 
[ InitialExpression="http://yourserver:55001/csp/yourapp/%25CSP.Broker.cls"] ;
```
If you authenticate with CacheUserName and CachePassword, the remoteBrokerAddress must also specify CacheNoRedirect=1 to avoid browser cross-domain policy issues. The following example changes http: to https:, adds authentication, and specifies CacheNoRedirect=1 (second line has been split for readability):
```
Property remoteBrokerAddress As %ZEN.Datatype.string 
[ InitialExpression="https://yourserver:55001/csp/yourapp/%25CSP.Broker.cls?CacheUserName=_SYSTEM
&CachePassword=SYS&CacheNoRedirect=1"] ;
```

Requirements of the Packaged Application

Make sure that the packaged application provides the following items, all in a single directory:

The generated offline page (an HTML file), as discussed in the next section.
The JavaScript file generated for the page class, packagename_classname.js (which you can find in the install-dir/csp/broker directory).
Files required by the core parts of Zen Mojo, specifically, the following files from the install-dir/csp/broker directory:
- Files with names of the form ZEN*.js
- Files with names of the form ZEN_Mojo*.js
- zenutils.js
- cspxmlhttp.js
- cspbroker.js
- zenutils.js
Any files (or subdirectories of files) needed by the plugin or plugins.
Any additional files (such as image files) needed by the application.

Generating Offline Pages

This section describes how to generate an offline version (pure HTML) of a Zen Mojo page, for use as part of a mobile application.

Note:

Make sure to first modify the page class so that it supports offline use, as described earlier in this chapter.

Generating Only the Offline Page

To generate an offline version (pure HTML) of a Zen Mojo page, use the CreateOfflinePage() method of the %ZEN.Mojo.UtilsOpens in a new tab. This method is as follows:

ClassMethod CreateOfflinePage(pClassName As %String, 
                              ByRef pFileName As %String = "", 
                              pVerbose As %Boolean = 1) As %Status

Where pClassName is the full package and class name of the Zen Mojo page class, pFileName is the name of the file generated by this method, and pVerbose is a Boolean value to specify whether the method should write output messages. Note that pFileName is passed by reference, so you should place a period before this argument, if you use it.

For example:

 set class="ZMdemo.chui.HomePage"
 do ##class(%ZEN.Mojo.Utils).CreateOfflinePage(class,.filename,0)
 write filename

This method writes an HTML file to the install-dir/CSP/namespace directory where install-dir is the directory where you installed Caché or Ensemble, and namespace is the namespace in which you ran this method.

Note that the generated HTML file requires a set of files that must be in the same directory; without those files, this page appears empty or mostly empty. When you package the application, you copy this HTML file and all of its dependencies into a single directory. See the next section.

Generating an Offline Bundle

Zen Mojo provides an additional utility method that executes CreateOfflinePage(), identifies the generated files that it needs, and copies all these files to a target directory. This method, CreateOfflineBundle(), is intended to simplify the process of adding the files to a PhoneGap project. This method is as follows:

ClassMethod CreateOfflineBundle(pClassName As %String, pTargetFolder As %String) As %Status

Where pClassName is the full package and class name of the Zen Mojo page class and pTargetFolder is the target directory. The method creates this directory if it does not exist.

Important:

This method identifies only the files generated by the Zen Mojo page class. It does not attempt to examine the CSSINCLUDES or JSINCLUDES parameters, because in some cases, it would also be necessary to resolve the dependencies implied by those parameters. Similarly, if the page uses external resources, such as image files, this method does not identify those.