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:
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.
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;Copy code to clipboard
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.clsCopy code to clipboard
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"] ;Copy code to clipboard
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"] ;Copy code to clipboard
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.
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
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.
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.Utils. 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.
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.
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.