EWD Mobile
Tutorial: Part 1
M/Gateway Developments Ltd http://www.mgateway.com
M/Gateway Developments Ltd
Table of Contents
Introduction 1
Background 1
Pre-requisites 1
Lesson 1 3
Hello World 3
Lesson 2 7
Hello World Analysed 7
Lesson 3 10
Some Simple Changes to Hello World 10
Lesson 4 12
Buttons, Events, Hiding and Showing UI Elements 12
Lesson 5 16
How EWD Custom Tags relate to Sencha Touch Classes 16
Lesson 6 21
Accessing Data held in GT.M or Caché 21
Lesson 7 25
Menus and Lists 25
Adding a handler 27
Adding a Slide Animation 28
Using EWD to make the coding even simpler 29
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) i
Adding a Back Button 32
Automating the List’s Back Button 34
Lesson 8 36
Tab Panels 36
Using EWD Fragments with the Tab Panel 37
Lesson 9 39
Selecting Data from a List 39
Creating our List 39
Adding a NextPage 41
Adding a Back Button 42
Making the NextPage recognise the Item Selected from the List 42
Retrieving more Details for the Selected Item 44
Appendix 1: Installing EWD 46
Installing EWD 46
GT.M 46
Caché 46
Configuring EWD 46
Caché & CSP 47
1a) Simple Default Configuration 47
1b) Custom Configuration 47
2) Define CSP Application 47
Caché & WebLink 48
GT.M 49
Creating EWD Pages 49
Running EWD Applications 50
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) ii
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) iii
Introduction
Background
EWD Mobile is a rapid application framework for mobile web applications. It is an extension of
Enterprise Web Developer (EWD) that integrates the Sencha Touch Javascript framework (http://
www.sencha.com), exposing it as a set of Custom Tags.
EWD Mobile allows extremely rapid development of Caché- and GT.M-based Mobile Web
Applications that look and behave like Native Applications, running on a variety of mobile devices including the iPhone, iPad, Android phoneƒs and tablets and the Blackberry Playbook. EWD Mobile
applications will also run on desktop WebKit browsers such as Chrome and Safari.
Key benefits of using EWD Mobile are:
One application definition will run on all mobile devices that use WebKit browsers, instead of writing
separate versions of applications for the iPhone, iPad, Android devices, etc.
The development and maintenance effort is orders of magnitude less using EWD Mobile than writing
Native Applications for mobile devices
Distribution of applications and their updates is not dependent on their acceptance into an App Store.
This document provides a tutorial to help you learn how to build Mobile Apps using EWD Mobile.
Pre-requisitesBefore you begin this tutorial, you should install the latest build of EWD (build 857 or later). Details on
how to install and configure EWD are provided in Appendix I.
You will also need to install the latest version of the Sencha Touch Javascript framework. You can
obtain this from http://www.sencha.com.
This tutorial makes some assumptions about your configuration that are explained in detail in
Appendix I. The key assumptions are:
• Your EWD Application root path will be:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 1
• c:\ewdapps (Windows)
• /usr/ewdapps (Linux)
• If you are using Caché, you’ll be working in the USER namespace
• If you are using GT.M, the instance you’ll be using is in /usr/local/gtm/ewd
• Sencha Touch has been installed under your web server’s root directory in a subdirectory named /sencha-1.0
You’ll need to adjust the examples appropriately if your configuration is different.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 2
Note: if you’re using a Windows default Cache CSP configuration and using the built-in web server that uses port 57772:
• You should install the Sencha Touch files into the directory path c:/InterSystems/Cache/CSP/ewd/sencha
• Don’t add the version number (-1.0) to the path name as this appears to cause problems
• In the examples that follow in these tutorials, anywhere you see the URL root /sencha-1.0, substitute it with /csp/ewd/sencha
Lesson 1
Hello WorldIn time-honoured fashion, let’s start this tutorial by creating a simple “Hello World” application that will
run as a mobile application. We’ll analyse in detail how this application works and what all the XML means in the next section, but for now just try the following steps and see how little is involved in
developing mobile applications with EWD.
We’re going to name this demo application stdemo, so you’ll be creating and editing files in the
directory c:\ewdapps\stdemo (or /usr/ewdapps/stdemo)
You can use any text or HTML editor to create and edit your EWD source pages. In this tutorial we’ll
assume that you are using a simple text editor such as Notepad.
Create a text file named index.ewd (ie c:\ewdapps\stdemo\index.ewd) that contains the following:
Note 1: keep each tag on a single line – ie don’t include line breaks inside a tag
Note 2: if you are using CSP with the default built-in web server that runs on port 57772, see the notice on Page 2 above.
OK, let’s compile and run this application. Start up a GT.M session or a Caché Terminal session and change to the USER
namespace. Type the following (depending on whether you’re using GT.M, CSP or WebLink):
CSP: d compileAll^%zewdAPI(“stdemo”,,”csp”)
WebLink: d compileAll^%zewdAPI(“stdemo”,,”wl”)
GT.M: d compileAll^%zewdAPI(“stdemo”)
Note the two commas if you’re using Caché!
If you’ve properly installed and configured things, you should have seen something like the following:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 3
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content> <st:panel fullscreen="true" html="Hello World!" /> </st:content></st:container>
USER>d compileAll^%zewdAPI("stdemo",,"csp")c:\ewdapps\stdemo\ewdAjaxError.ewdc:\ewdapps\stdemo\ewdAjaxErrorRedirect.ewd
c:\ewdapps\stdemo\ewdErrorRedirect.ewdc:\ewdapps\stdemo\index.ewd
c:\InterSystems\Cache\CSP\ewd\stdemo\ewdLogout.csp Load of CSP page started on 03/06/2011 17:11:39
Loading file C:\InterSystems\Cache\CSP\ewd\stdemo\ewdAjaxError.csp as cspCompiling file /csp/ewd/stdemo/ewdAjaxError.csp
Loading file C:\InterSystems\Cache\CSP\ewd\stdemo\ewdAjaxErrorRedirect.csp as cspCompiling file /csp/ewd/stdemo/ewdAjaxErrorRedirect.cspLoading file C:\InterSystems\Cache\CSP\ewd\stdemo\ewdErrorRedirect.csp as csp
Compiling file /csp/ewd/stdemo/ewdErrorRedirect.cspLoading file C:\InterSystems\Cache\CSP\ewd\stdemo\ewdLogout.csp as csp
Compiling file /csp/ewd/stdemo/ewdLogout.cspLoading file C:\InterSystems\Cache\CSP\ewd\stdemo\index.csp as cspCompiling file /csp/ewd/stdemo/index.csp
Compiling class csp.stdemo.ewdajaxerrorCompiling class csp.stdemo.ewdajaxerrorredirect
Compiling class csp.stdemo.ewderrorredirectCompiling class csp.stdemo.ewdlogoutCompiling class csp.stdemo.index
Compiling routine csp.stdemo.ewdajaxerror.1Compiling routine csp.stdemo.ewdajaxerrorredirect.1
Compiling routine csp.stdemo.ewderrorredirect.1Compiling routine csp.stdemo.ewdlogout.1Compiling routine csp.stdemo.index.1
Load finished successfully.
USER>
You can now run the application. Start the browser on your mobile device and enter the URL:
GT.M: http://192.168.1.100/ewd/stdemo/index.ewd
CSP: http://192.168.1.100/csp/ewd/stdemo/index.csp
WebLink: http://192.168.1.100/scripts/mgwms32.dll?MGWLPN=LOCAL&MGWAPP=ewdwl&app=stdemo&page=index
You’ll need to change the IP address to that of your web server. If you are using a default CSP configuration using the built-in web server that uses port 57772, the URL you should use is:
CSP: http://192.168.1.100:57772/csp/ewd/stdemo/index.csp
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 4
What you should see, after a short pause while it loads everything up,
is this.
If you’re running in an iPhone, iPod Touch or iPad, you’ll notice that
the application is running full screen without Safari’s URL Location
window being visible. However, Safari’s toolbar is still visible at the
bottom, and if you wanted to restart the application, you’d need to
relaunch Safari and tediously re-enter that lengthy URL.
However, there’s a further trick you can do on an iPhone or iPad
(Android devices have an equivalent procedure). Click that
rectangular symbol in the middle of the bottom toolbar and up will
pop the following:
Click the “Add to Home Screen” button
and you’ll see:
Click the blue Add button in the top right corner, and the Touch-
Icon that we’d specified in the index.ewd page’s
<st:image type=’icon’> tag will be added to your iPhone’s
Home Screen:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 5
Now you can start our Demo application by simply touching the icon, just
as if it was a Native iPhone/iPad
App. What’s more, when you start
it up this way, you’ll see the startup splash screen, and when
the application is fully loaded and ready for use, you’ll no longer see any trace of Safari’s chrome:
Now it just looks like a Native App!
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 6
Lesson 2
Hello World AnalysedHopefully you’ll agree that there wasn’t much involved in getting an albeit very simple EWD Mobile
application up and running. Now let’s take a more detailed look at what we did and why we did it.
Every EWD Application requires what is known as the Container Page or First Page. This is basically
an initial HTML page that acts as a container for the initial content and all subsequent content that will
be sent to the mobile browser by EWD. EWD applications use Ajax techniques for injecting chunks of
markup into the container page. As far as your browser is concerned, an EWD application is actually
a single page of HTML that never leaves the browser. EWD will handle all that Ajax stuff for you
automatically.
The Container Page can be named anything you like (avoid punctuation marks in names). However,
by convention, we usually name this page index.ewd. EWD pages must have a file extension
of .ewd.
So, our EWD Container page is the file we created named index.ewd. The reason we created it in the
path c:\ewdapps is because, in Appendix 1, that path was configured as what’s known as the
Application Root Path. The Application Root Path is the directory under which EWD’s compiler will search for EWD applications. The name of each application is the same as the name you assign to
each subdirectory under the Application Root Path. We named our application stdemo, so that’s
why we created the files in the directory c:\ewdapps\stdemo.
Now let’s take a close look at the contents of index.ewd. You’ll notice that the EWD files we created
just consist of XML (or XML-like) tags. In fact, as we’ll see later, an EWD file can also contain HTML
tags and Javascript. Those of you who are familiar with technologies such as PHP or Java Server
Pages will therefore realize that EWD is essentially what’s generally known as a “server pages”
technology. However, since most of the EWD pages are just fragments of markup that are injected
into the Container Page, we refer to EWD as a “server fragments” technology. EWD differs
significantly from other server pages technologies in many ways. In particular, the level of abstraction, ie the degree to which EWD describes what your application should do rather that how it should do it,
is very much higher than anything else in the web application development framework marketplace.
That means that you type less and your EWD files are a very succinct description of what each
fragment is going to be doing.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 7
Here’s index.ewd again:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content> <st:panel fullscreen="true" html="Hello World!" /> </st:content></st:container>
The tags in this file are known as Custom Tags.
The first one (<ewd:config>) is a generic EWD one with which all EWD pages must start. The
attribute isFirstPage=”true” tells EWD that this is the first page and can therefore be invoked using a
simple “static” URL. The attribute cachePage=”false” tells EWD to add a variety of HTTP response headers that will prevent your browser from caching the page, so you get a fresh copy loaded every
time you invoke it.
The second Custom Tag (<st:container>) and its child tags will generate all the HTML for the
Container Page. You simply need to specify a few attributes for your specific application:
• rootPath: the name of the subdirectory under the web server’s root directory where you installed
the Sencha Touch files. This is used by EWD to generate the URLs that will fetch the Sencha Touch
Javascript and CSS files.
• title: the HTML title applied to the container page. It’s also used as the default text for the touch
(startup) icon.
Inside the <st:container> tags are a set of <st:image> tags that define the URLs for the startup images and icon. The type attribute defines their purpose:
• icon: the path of the icon image file that a user can add to their iPhone’s Home Screen. This image
file should be 72 X 72 pixels in size and without rounded corners or gloss (EWD can add these
automatically). You’ll find that the example file we’re referencing is included in the Sencha Touch
“Kitchen Sink” example source directory.
• phoneStartupScreen: the path of the startup splash screen that will appear in a phone while the
first page is loading. This image file should be 320 X 460 pixels in size. You’ll find that the example
file we’re referencing is included in the Sencha Touch “Kitchen Sink” example source directory.
• tabletStartupScreen: the path of the startup splash screen that will appear in a tablet or desktop
browser while the first page is loading. This image file should be 768 X 1004 pixels in size. You’ll
find that the example file we’re referencing is included in the Sencha Touch “Kitchen Sink” example
source directory.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 8
Finally inside the <st:container> tags is the <st:content> tag inside which you define your initial
content. What we’ve specified is a simple <st:panel> tag.
Panels are the primary components that you use to define the UI of a Sencha Touch application. As
you’ll discover, there are many pre-defined types of panel, and panels can be nested inside each
other to pretty much any depth. In our simple Hello World application, we are using the simplest
panel possible. We’ve told it to occupy the full screen, which is what your main outer panel should
always do, and we’re just defining its content using a simple html attribute.
The result, as you saw, was a pretty unimpressive looking Hello World message! However, we can
now begin to extend this application to make it look more like a proper mobile application.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 9
Lesson 3
Some Simple Changes to Hello WorldIn this lesson we’re going to make some simple modifications to our Hello World application.
Let’s first add a toolbar.
We can add a toolbar by using the <st:toolbar> tag which can be added inside any <st:panel> tag.
Toolbars can be docked to a variety of places in its parent panel, but the top and bottom are the usual
places. We’ll dock ours to the top of the main panel.
Let’s try it. Edit index.ewd so it now looks like:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content>
<st:panel fullscreen="true" html="Hello World!"> <st:toolbar dock="top" title="EWD Mobile" /> </st:panel> </st:content>
Re-compile this fragment file using:
GT.M: d compilePage^%zewdAPI(“stdemo”,”helloWorld”)
CSP: d compilePage^%zewdAPI(“stdemo”,”helloWorld”,,”csp”)
WebLink: d compilePage^%zewdAPI(“stdemo”,”helloWorld”,,”wl”)
Note those two commas again if you’re using CSP or WebLink! The compilePage() command just
recompiled the index.ewd page, leaving everything else unchanged.
Now try re-running the application by clicking on the EWD touch icon again. This time you should see
a toolbar at the top of the screen:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 10
Already that looks better!
Next we’ll add another toolbar, but this time we’ll dock it the bottom of the main panel, and we’ll also make the main content panel scrollable:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content>
<st:panel fullscreen="true" html="Hello World!" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile" />
<st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
Recompile and re-run by clicking the EWD icon and you
should see there’s now a bottom toolbar also:
Try swiping inside the main panel – you should find the text
will scroll up and down and bounce back into position.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 11
Lesson 4
Buttons, Events, Hiding and Showing UI ElementsWe’re now going to take a look at how you can add buttons into our example page’s top toolbar and
how they can be used to control the UI.
Edit index.ewd so it now looks like this:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content> <st:panel fullscreen="true" html="Hello World!" scroll="vertical">
<st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel>
So we’ve added a toolbar button tag inside the top toolbar. Notice that we’ve also added an id
attribute to the bottom toolbar: you’ll see why later.
Recompile this page and try running the application again.
You should now see a button with the word “Hide” in it. Clicking or tapping it won’t do anything
however: that’s because we haven’t defined a handler for it. So let’s add that now. Initially we’ll just
show an alert message when the button is tapped:
<ewd:config isFirstPage="true" cachePage="false">
<st:js at="top"> EWD.sencha.onHideBtnTapped = function() { Ext.Msg.alert('Attention!', 'You clicked the Hide button!', Ext.emptyFn); };</st:js>
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <st:content> <st:panel fullscreen="true" html="Hello World!" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile">
<st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 12
OK so what does this extra stuff do? We added a handler attribute to the “Hide” toolbar button and
named it EWD.sencha.onHideBtnTapped. We then defined this as a function in the <st:js> tag. The <st:js> tag allows us to add Javascript to the fragment’s payload. The at=”top” attribute ensures that
it is sent before any of the Sencha Touch Javascript that is generated from the <st:panel> etc tags.
This is important in this instance because the handler function must be defined and exist before it is
attempted to be bound as a handler to the button.
This also raises an important point about the Sencha Touch tags. Unlike many of the more
conventional EWD Custom Tags that generate other HTML tags, the Sencha Touch tags generate
Javascript. Therefore if you also add your own Javascript into a fragment, you need to determine
whether it should be generated before or after the Sencha Touch code. Use the at attribute in the
<st:js> tag to control this:
<st:js at=”top”> generates your Javascript before the Sencha Touch code
<st:js at=”end”> generates your Javascript after the Sencha Touch code
So, compile and run this new version. Now when you click the
“Hide” button you’ll see a Sencha Touch alert:
In fact there is no reason why the handler function needs to be
in the dynamically-generated EWD fragment. It would be better if it was defined in a static Javascript file for a variety of reasons,
not least because the browser can cache it, but also because it
will be easier to maintain and debug. So let’s do that.
Create a file named stdemo.js in your web server’s root directory (eg c:\inetpub\wwwroot
or /var/www), containing the handler function:
EWD.sencha.onHideBtnTapped = function() { Ext.Msg.alert('Attention!', 'You clicked the Hide button!', Ext.emptyFn); };
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 13
Remove the original version that we put in index.ewd. We’ll now have to tell EWD to load the
stdemo.js file. We do this in the index.ewd page by adding a <script> tag inside the <st:container>
tag:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images>
<script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true" html="Hello World!" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
Note: if you are using a default CSP configuration with the built-in web server running on port 57772, save stdemo.js into the directory c:\InterSystems\Cache\CSP\ewd and change the tag in index.ewd to <script src="/csp/ewd/stdemo.js" />
Recompile and re-run the application. It should run identically to before.
We now know that our handler function is being correctly triggered when the “Hide” button is clicked,
but now let’s make it actually hide something, specifically the bottom toolbar.
Now if you remember, we added an id attribute to the bottom toolbar, and now you’ll discover why we
did that. It provides Sencha Touch with a handle that we can use to invoke its various methods. In
this example we’ll invoke its hide() method. The key to this is the Sencha Touch function
Ext.getCmp(id) which returns the widget object with the specified id. So, change the
onHideBtnTapped function in stdemo.js as follows:
EWD.sencha.onHideBtnTapped = function() { Ext.getCmp("bottomToolbar").hide(); };
Because we simply changed the static Javascript file, there’s no need to recompile any EWD pages
this time. Just restart the application in the mobile browser. This time, when you click the button, the
bottom toolbar disappears.
So how can we get it to reappear? What would be nice would be to change the “Hide” button to say
“Show”, and make the toolbar reappear when it’s clicked, meanwhile changing the button to say
“Hide” again.
It’s possible to change the button text and handler dynamically, but actually it’s a lot simpler to have
two buttons: “Hide” and “Show”, each with their own handler, and make the buttons hide and appear
at the right times. Try the following:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 14
First amend index.ewd as follows, adding the new “Show” toolbar button. Note how we initially make
it hidden:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true" html="Hello World!" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" />
<st:toolBarButton text="Show" id="showBtn" handler="EWD.sencha.onShowBtnTapped" hidden="true" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
Next amend stdemo.js as follows:
EWD.sencha.onHideBtnTapped = function() { Ext.getCmp("bottomToolbar").hide(); Ext.getCmp("hideBtn").hide(); Ext.getCmp("showBtn").show(); };
EWD.sencha.onShowBtnTapped = function() { Ext.getCmp("bottomToolbar").show(); ; Ext.getCmp("hideBtn").show(); Ext.getCmp("showBtn").hide(); };
By making sure that the buttons also had id attributes, we can alternately turn them on and off while making the toolbar disappear and reappear.
Let’s try one last trick before we finish this lesson. How can we move the buttons to the right hand
side of the toolbar? That’s easily done by using the <st:spacer> tag:
Simply edit index.ewd as follows:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true" html="Hello World!" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" />
<st:spacer /> <st:toolBarButton text="Show" id="showBtn" handler="EWD.sencha.onShowBtnTapped" hidden="true" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
Now recompile and re-run the demo: now you should have the Hide button appearing on the left side
of the toolbar, and the Show button will appear on the right.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 15
Lesson 5
How EWD Custom Tags relate to Sencha Touch ClassesIn general, every EWD Sencha Touch tag is an XML representation of a corresponding Sencha Touch
Class. You can find the full API documentation for Sencha Touch classes at http://dev.sencha.com/deploy/touch/docs/
So, for example, the <st:panel> represents the Ext.Panel class. As such, the <st:panel> can have, as
an attribute, any of the simple name/value pair Config Options defined in the Sencha Touch API
documentation. However, the EWD Custom Tags can often have additional EWD-specific attributes
that are short-cut ways of describing commonly used behaviours, so you’ll probably find yourself
using very few of the available Config Options in your EWD pages.
You can supply the Config Options as attribute names. The names are not case sensitive as far as you are concerned, but EWD will ensure that they are converted into the correct valid case-sensitive
names in the final compiled code.
Some of the Config Options described in the Sencha Touch API documentation are supplied as
objects or arrays, eg items, listeners, etc. In general, such Config Options should not be used in the
corresponding EWD Custom Tags since there are alternative mechanisms within the EWD Sencha
Touch tags for representing them. For example, when you nest <st:panel> tags inside each other,
EWD converts the inner ones into members of the items array of the outer ones. If you need a more
complex listener that can’t be represented using the built-in shortcut techniques, you can use an
<st:listeners> tag and child <st:listener> tags to represent them. However this type of advanced use
of the EWD Sencha Touch tags is beyond the scope of this tutorial.
Although EWD can be used to generate Sencha Touch applications without the author really
understanding much about the Javascript that EWD generates, as with any tool, the more you can
learn about the Sencha Touch framework itself, the better you’ll understand what’s going on under the
hood and the easier you’ll find debugging when things inevitably go wrong.
One of the best tools you’ll find for understanding and seeing what EWD is doing is the Developer
Tools panel that you’ll find in the desktop versions of the Chrome and Safari browsers. EWD Sencha
Touch applications will run perfectly in these browsers, and you’ll find that they become the preferred
development platforms for your work.
To bring up the Developer Tools Panel in Chrome, click the spanner (or wrench) icon in the top left
corner of the browser, and select Tools/Developer Tools from the menu:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 16
Initially you’ll find the Developer Tools panel appears at the bottom half of the browser window. You’ll
find it’s a lot easier to use if you undock it by clicking its bottom left icon:
You’ll also find it best to open up the Console sub-panel by clicking the icon next to the undock icon. If any Javascript errors occur you’ll see lots of useful detail in this Console panel – this is invaluable
when trying to debug problems:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 17
If you click on the Network tab you can see the source code that was sent to the browser for each
page or file that was fetched. If you’re using WebLink, the EWD pages are all named mgwms32.dll in
the list. If you use CSP or GT.M, you’ll see the
pages named
index.ewd or index.csp
etc.
Click on the first one
and you’ll see the
contents of the
Container page
(index.ewd) that was
actually sent to the browser:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 18
Click this icon to open the Console
You can cut and paste the
content into a text editor if you want to view it in
detail.
Now scroll down through
the content of index.ewd
until you find the line
highlighted here:
You’ll see a long line of Javascript that has been generated from the tags we placed inside the
<st:content> tag. It’s pretty difficult to read and understand, so here’s a tip. Copy the Javascript line
shown in the example above, bring up the excellent online Javascript beautifier page (http://
jsbeautifier.org/), paste the generated code into the window and click the Beautify button. You should
now see the generated Javascript nicely laid out:
Now you can see that what was actually sent to the browser was an Ext.Panel constructor that
defined our simple Hello World panel, toolbars and buttons.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 19
If you study the code that EWD generated, you’ll begin to understand how the EWD Sencha Touch
tags relate to the Sencha Touch classes and their Config Options.
In the subsequent examples of this tutorial, you should use these tools to examine more closely
what’s happening.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 20
Lesson 6
Accessing Data held in GT.M or CachéSo far our demo application hasn’t really done anything that couldn’t have been done with static files.
The whole point of EWD is to allow a seamless integration with the GT.M and Caché database environments. With EWD you can integrate with either M or Caché ObjectScript code and can
access data held in either Global storage or in Caché Objects. If you are using Caché you can also
use Caché SQL to query your databases. Additionally EWD will interoperate perfectly with Ensemble.
In Part 2 of this tutorial you’ll start to see how powerful and slick this integration really is, but let’s finish
off this Part 1 of the tutorial with some simple examples of how we can access and use the GT.M or
Caché database.
Let’s start by replacing that Hello World message with some information from the GT.M or Caché
database. What we’ll use is an EWD function that returns the current version of EWD. We can invoke
this function from within the GT.M or Caché environment:
write $$version^%zewdAPI()
Edit the index.ewd page as follows:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getVersion^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content>
<st:panel fullscreen="true" html="#version" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" /> <st:spacer /> <st:toolBarButton text="Show" id="showBtn" handler="EWD.sencha.onShowBtnTapped" hidden="true" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" /> </st:panel> </st:content></st:container>
What we’ve done is added what is known as a Pre-Page Script to the fragment. This is a GT.M or
Caché function that will be invoked before the fragment is rendered and sent to the browser. In EWD
Mobile applications, Pre-Page scripts are the only touch-point you have with GT.M and Caché. They are what you use to fetch and marshall data from your database, and what you also use to validate
posted data and save it back to your database. Although you’ll be frequently using Pre-page scripts
in your applications, you’ll find that EWD does so much for you already that the amount of actual M or
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 21
Caché ObjectScript coding you’ll have to do will be pretty small, which is good news for development
speed and simplicity of downstream maintenance.
If you are using Caché, Pre-page scripts can either be M-style extrinsic functions or Caché Class
Methods. The example above is using the M-style extrinsic function style which is compatible with
both GT.M and Caché. If you wanted to use a Caché-style Class Method, you’d express it as
something like:
<ewd:config isFirstPage="false" pageType="ajax" prePageScript="##class(demo.st).getversion">
Note that if you use Caché Class Methods, your EWD applications will only be able to be run on Caché systems. If you use extrinsic functions and stick to standard M coding and Globals, you can freely migrate your EWD applications between GT.M and Caché.
You’ll also see that we’ve replaced the literal text Hello World in the <st:panel> tag’s html attribute with
a reference to what is known as an EWD Session Variable: #version. We’ll examine the EWD Session
in greater detail in Part 3 of the Tutorial. For now just follow the example and see how it works.
So now we need to create that actual Pre-page Script in GT.M or Caché. Using an appropriate editor
in GT.M or Caché Studio, create the routine stdemo (eg stdemo.m in GT.M) containing the following:
stdemo ; ;getVersion(sessid) ; n version ; s version=$$version^%zewdAPI() d setSessionValue^%zewdAPI("version",version,sessid) QUIT "" ;
If you want to use a Caché Class Method, it would look like the following:
ClassMethod getVersion(sessid As %String) As %String{ s version=$$version^%zewdAPI() d setSessionValue^%zewdAPI("version",version,sessid) QUIT "" }
Notice that in both examples the calling signature is basically the same: the pre-page script function
must have a single parameter: sessid. This is the unique EWD Session Id that EWD’s run-time
engine will automatically pass to your function. That Session Id is what provides access to the user’s
specific persistent Session information. EWD provides a whole range of APIs that allow you to access
and manipulate the user’s persistent Session data, and you see the simplest one being used here:
setSessionValue().
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 22
Notice also that a Pre-Page script must always Quit with a return value. By convention, a return
value of null (ie an empty string) means that the Pre-page script completed without any error
occurring.
So what this example pre-page script is doing is getting the EWD version string and putting it into an
EWD Session value named version.
In the EWD page we can then access that Session variable by using the reference to it: #version.
When you want to use an EWD Session Variable as the value of an attribute in an EWD Custom Tag,
just use the Session Variable name prefixed with #, eg as in our example:
<st:panel fullscreen="true" html="#version" scroll="vertical">
So, save and compile your GT.M/Caché function and then re-compile the index.ewd page. Now run it
again and you should see:
There we go: our application is now displaying data that has originated in the GT.M or Caché
database!
Let’s just make one final change to demonstrate a different way of using EWD Session Values, this
time within some standard HTML markup in our panel. We can do that by removing the html attribute
and simply nesting some HTML markup inside the panel, eg:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 23
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getVersion^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content>
<st:panel fullscreen="true" scroll="vertical"> <st:toolbar dock="top" title="EWD Mobile"> <st:toolBarButton text="Hide" id="hideBtn" handler="EWD.sencha.onHideBtnTapped" /> <st:spacer /> <st:toolBarButton text="Show" id="showBtn" handler="EWD.sencha.onShowBtnTapped" hidden="true" /> </st:toolbar> <st:toolbar dock="bottom" id="bottomToolbar" />
<div> <div> Your version of EWD is: </div> <div> <?= #version ?> </div> </div> </st:panel> </st:content></st:container>
Note that the block of markup must be encased in a single HTML tag: in this example we’re using a
<div> tag. Inside that tag you can have any HTML markup you want.
This time, we’re going to display the contents of the EWD Session variable named version as some
text inside a <div> tag. So this time we use the special syntax:
<?= #version ?>
Those of you who are familiar with PHP will recognize this syntax. Note that the Session Variable
name must still be prefixed with a # to denote that this is a Session variable.
So, finally, compile and run the modified version of index.ewd above and you should see:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 24
Lesson 7
Menus and ListsOne of the primary UI components that is used in most mobile web applications is the menu or List.
The List is a particularly effective way of navigating and selecting from quite large amounts of data in mobile devices because you can use a swipe gesture to quickly scroll through the list. The scrolling
list will have momentum and will continue to scroll by after a fast swipe gesture.
So let’s change our simple Hello World application and make it start with a simple list of 3 options, the
first of which will take us to our Hello World page.
What we use to create menus in EWD is the Sencha Touch <st:list> tag. The options or data in the
list are defined dynamically within Caché or GT.M. So edit the index.ewd file in your stdemo directory
as follows:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true">
<st:toolbar dock="top" title="EWD Mobile" />
<st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list>
</st:panel> </st:content></st:container>
Now add the Pre-Page script function getMainMenu() to your stdemo routine, eg:
getMainMenu(sessid) ; n list ; s list(1,"optionText")="Hello World" s list(2,"optionText")="Example 2" s list(3,"optionText")="Example 3" ; d saveListToSession^%zewdSTAPI(.list,"mainMenuOptions",sessid) ; QUIT ""
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 25
Once you’ve created and saved these files, recompile the stdemo application.
If you’re using GT.M, you’ll also have to ensure that the routine file stdemo.m that contains the new
pre-page script has been re-compiled, by running, in the Linux shell:
mumps stdemo.m
Additionally if you’re using GT.M, it’s also a good idea to signal to the EWD back-end processes that
they should be relinked. Do this from the GT.M shell by doing the following (make sure you’re in the
correct file-path first, eg /usr/local/gtm/ewd):
$ mumps -direct
GTM> d relink^%zewdGTM
If you’ve done everything correctly, when you re-run the stdemo application you should see:
Let’s take a look at what we did to create this. Specifically look at index.ewd and its pre-page
script (getMainMenu):
• First we used the <st:list> tag which creates an instance of the Ext.List class
• We added this as a sub-component of the main panel which is occupying the full screen of our
mobile device, so it sat inside the main panel and below the top toolbar
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 26
• The pre-page script (getMainMenu()) creates a simple array of options. The first subscript (1..n)
denotes the position of the option in the list, and the second subscript (“optionText”) defines a property that we want to use and/or display in the list.
• The <st:list> tag has a child tag <st:layout> which allows us to define how we want each row in the
list to be presented. In this example we just want to display the optionText property, so we use the
<st:field> tag to denote that.
• The option array that is created in the pre-page script is saved to the EWD Session as a JSON
datastore named mainMenuOptions using the special EWD/Sencha Touch API: saveListToSession()
• By defining the sessionName attribute of the <st:list> tag to be mainMenuOptions, the list of options we saved into the EWD Session using that name will be used to dynamically populate the List.
Note that we could have used any property name instead of optionText, but whatever name you use
in the options array must be referenced as an <st:field> name within the <st:layout> tag.
Adding a handlerOK, so we’ve now displayed our list of options as a menu. However, it’s not doing much yet: tapping
any of the options will have no effect at present.
That’s because we haven’t defined any handler for the menu options yet. So let’s change that. As you’re going to discover, we have numerous options available to us now, but let’s start with something
simple and we’ll progressively make it slicker and powerful.
First edit the index.ewd page as follows:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true"> <st:toolbar dock="top" title="EWD Mobile" />
<st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" onTap="EWD.sencha.helloWorld"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list>
<st:panel id="helloworld" html="Hello World!" hidden="true" />
</st:panel> </st:content></st:container>
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 27
What we’ve done is add an onTap attribute to the <st:list> tag and we’ve added our Hello World
panel as an initially hidden sub-panel.
Now let’s define that onTap handler function in the stdemo.js file:
EWD.sencha.helloWorld = function(index,record) { Ext.getCmp("mainMenu").hide(); Ext.getCmp("helloworld").show();};
The onTap handler function takes two parameters: index (the option number that you tapped: 0..n), and record (the data record held in the tapped row)
In this first example, we’ll simply hide the main menu and make the Hello World panel appear in its
place. Remember that the id attribute of our Sencha Touch tags allows us to point directly to them
using Sencha Touch’s Ext.getCmp() method.
If you save the edited stdemo.js file, recompile the modified mainMenu.ewd page and re-run the
application, you should now find that tapping any of the menu options will make the menu disappear
and the Hello World! Message will appear.
OK so that’s a step forwards, but how can we make the Hello World message appear only if we click
the first menu option? That’s where the index parameter can be useful. Try editing the
EWD.sencha.helloWorld() function as follows:
EWD.sencha.helloWorld = function(index,record) { Ext.getCmp("mainMenu").hide(); if (index === 0) Ext.getCmp("helloworld").show();};
When you save stdemo.js and re-run the application, you should now find Hello World! only appears
when you click the first menu option.
Adding a Slide AnimationThat’s getting better, but one of the cool features you’ll frequently see in mobile applications is the
animations such as sliding panels when you tap menu options, so let’s now add that to our menu.
The first thing to understand is how animated sliding panels work conceptually in Sencha Touch.
What you require is a special type of containing panel. In Sencha Touch, panels can have a property
known as a layout, and there are a variety of layout types available. The one we require for sliding
animations is called a card layout, and in EWD you can specify this using the <st:cardPanel> tag. We
need to make both the List and our Hello World panel to be members of this Card Panel in order for
them to be animated. So change index.ewd as follows:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 28
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true"> <st:toolbar dock="top" title="EWD Mobile" />
<st:cardPanel id="mainCardPanel"> <st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" onTap="EWD.sencha.helloWorld"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list>
<st:panel id="helloworld" html="Hello World!" /> </st:cardPanel> </st:panel> </st:content></st:container>
What we’ve done is to wrap the <st:list> tag inside a <st:cardPanel> tag, and we’ve also
moved the Hello World panel inside the <st:cardPanel>. Only one panel at a time is displayed
in a Card Panel, and the first one is used as the one to initially be displayed. As a result we
can safely remove the hidden=”true” attribute from the helloworld panel.
Now modify the EWD.sencha.helloWorld() function:
EWD.sencha.helloWorld = function(index,record) { if (index === 0) Ext.getCmp("mainCardPanel").setActiveItem(Ext.getCmp("helloworld"),"slide");};
The Sencha Touch setActiveItem() function selects which panel is to be made visible (or active) inside the Card Panel. Here we’ll make the panel with an id of helloworld the active one, and we specify a
slide transition to provide the desired animation.
Save these files, recompile the application and now when you click the first menu option, the Hello
World panel should slide into view. Now it’s starting to look cool!
Using EWD to make the coding even simplerAlthough we haven’t had to write much code to make this happen, EWD can make specifying menus
even quicker and simpler, with less reliance on explicitly using the underlying Sencha Touch Javascript
functions.
The first thing we can do is to programmatically specify the page associated with a particular option
within our pre-page script. We do that by adding an additional property to the array that defines the
page: we’ll use a property named page for this, but you can choose any name you like:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 29
getMainMenu(sessid) ; n list ; s list(1,"optionText")="Hello World" s list(1,"page")="helloworld" s list(2,"optionText")="Example 2" s list(2,"page")="example2" s list(3,"optionText")="Example 3" s list(3,"page")="example3" ; d saveListToSession^%zewdSTAPI(.list,"mainMenuOptions",sessid) ; QUIT ""
Now add this new field to the layout, but make sure it’s not actually displayed by setting displayInList=”false”:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true"> <st:toolbar dock="top" title="EWD Mobile" /> <st:cardPanel id="mainCardPanel"> <st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" onTap="EWD.sencha.helloWorld"> <st:layout>
<st:field name="page" displayInList="false"/> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> <st:panel id="helloworld" html="Hello World!" /> </st:cardPanel> </st:panel> </st:content></st:container>
Now we can replace that onTap attribute with a special EWD attribute named nextPageField, and take
out the Hello World panel:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true"> <st:toolbar dock="top" title="EWD Mobile" /> <st:cardPanel id="mainCardPanel"> <st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" nextPageField="page"> <st:layout> <st:field name="page" displayInList="false"/> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> <st:panel id="helloworld" html="Hello World!" /> <- remove this line </st:cardPanel> </st:panel> </st:content></st:container>
Now we’re going to create a new EWD page, actually a partial page known as a fragment that will
contain just the Hello World panel. So create a new text file named helloworld.ewd in your stdemo application directory (eg c:\ewdapps\stdemo or /usr/ewdapps/stdemo). It should contain the
following:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 30
<ewd:config isFirstPage="false" pageType="ajax">
<st:panel id="helloworld" html="Hello World!" />
We’ve not seen an EWD fragment before so let’s take a closer look at this one:
The first thing to notice is the <ewd:config> tag. Unlike the Container page (index.ewd), the attribute
isFirstPage=”false” specifies that this is not a first page, so can only be accessed via a URL that EWD
automatically tokenizes with randomly-generated name/value pairs. What this means is that even if a
user was aware that your application included a fragment named helloWorld.ewd, they would be unable to access that fragment arbitrarily via its associated URL – it can only be accessed if the URL
includes the name/value pairs that EWD is expecting to also be attached to the URL. EWD
applications are highly secure as a result of this feature.
Notice also the pageType=”ajax” attribute. helloWorld.ewd is known as a fragment because it does
not contain a complete page of HTML: it is simply a fragment of content that will be injected, using
Ajax techniques, into the main container page. In the case of helloWorld.ewd, what will be injected
into the Container page is actually the Javascript that defines the Hello World panel. You don’t need
to worry about how the Ajax stuff happens: EWD will look after it for you. All other EWD fragments
that you create should use the same <ewd:config> tag as we’ve used for helloWorld.ewd.
Back to what this fragment is going to do: the idea is that when we click one of the menu options, the
corresponding fragment will slide into view. In fact, we don’t have to specify a transition since slide is used by default. Just to make sure that our new mechanism will be used instead of our original
Javscript function, delete or comment out the EWD.sencha.helloworld() function from stdemo.js.
Now save the files and recompile the stdemo application (using compileAll^%zewdAPI) and try re-
running it.
You should find this behaves just like our first “long-hand” approach, but now we’re defining the menu
text and the associated page dynamically in index.ewd’s pre-page script instead of using Javascript.
There’s another key difference in this approach: the helloworld panel is being injected into the
browser’s page using Ajax techniques rather than pre-existing in the page and being made visible.
This has its downsides: a round-trip to the server is required to fetch the fragment. However it also
has many benefits, not least the fact that it allows us to break up the UI into small, manageable chunks that can, if required, be developed and maintained independently by different people.
Now try trying some different transitions. Possible options are:
• flip
• pop
• cube
• fade
• slide
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 31
For example:
<st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" nextPageField="page" transition="fade" >
As a final exercise in this part of the lesson, now try adding panels for the Example 2 and Example 3
options by creating separate EWD fragment files for them, ie example2.ewd and example3.ewd. They
should look similar to the helloworld.ewd fragment we created above.
You should now have a fully functioning menu, with each of the three options bringing their respective
panel into view.
Adding a Back ButtonOf course, by now it will be obvious to you that there’s still a deficiency in our menu: it’s impossible to
go back to the main menu and choose a different option. The only way to see the main menu again is
to restart the application!
So let’s fix that by adding a Back Button when we click a menu option and slide a fragment into view.
Once again there is the “long-hand” manual Sencha Touch mechanism and a simple automated
shortcut EWD mechanism. Let’s use the Sencha Touch mechanism first, then we’ll see how EWD can simplify the process.
The first step is to add a back button into the toolbar in mainMenu.ewd:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true">
<st:toolbar dock="top" title="EWD Mobile"> <st:toolbarButton ui="back" id="backBtn" text="Back" hidden="true" handler="EWD.sencha.onBackBtnTapped" />
</st:toolbar> <st:cardPanel id="mainCardPanel"> <st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" nextPageField="page"> <st:layout> <st:field name="page" displayInList="false"/> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> </st:cardPanel> </st:panel> </st:content></st:container>
The ui=”back” attribute specifies that we want a properly styled Back-button, and we want it initially hidden. We’ve also specified a handler, so let’s define that next. What we need is a function that will
return the user to the main menu, reversing the slide transition. So let’s add that to the stdemo.js file:
EWD.sencha.onBackBtnTapped = function() { Ext.getCmp("mainCardPanel").setActiveItem(0, {type:"slide", direction: 'right'}); Ext.getCmp("backBtn").hide(); Ext.getCmp("helloworld").destroy(); };
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 32
The setActiveItem() function is used again to return the List into view: notice that we use a 0 (zero) as
its first parameter to specify the first item in the Card Panel which was the List (ie the main menu). The second parameter is an object that invokes a reverse slide transition.
When we return to the List, we want to hide the button again which is the purpose of the second
command. But what about that third command that uses the destroy() function: what’s it there for?
The reason is because we’re using Ajax techniques to inject the helloworld panel (or one of the
others), and when we go back to the menu there’s a good chance that we’ll choose the same option
and inject another instance of the helloworld panel into the page. Because the helloworld panel is
actually represented as a complex set of Javascript objects within Sencha Touch, it’s going to get
horribly confused if we try to inject multiple instances of this same object into the page. We can avoid
that by getting Sencha Touch to destroy it and clear away all vestiges of it when we go back to the
List.
There’s one last thing we need to do: make the button appear when the helloworld panel slides into
view. We’re using EWD’s automated nextPageField mechanism, so we don’t have an explicit handler
function that we have access to in order to show() the back button. However, we can add the
necessary Javascript into the helloworld.ewd page:
<ewd:config isFirstPage="false" pageType="ajax">
<st:js at="end"> Ext.getCmp("backBtn").show();</st:js>
<st:panel id="helloworld" html="Hello World!" />
This inline Javascript command will make the back button appear when the fragment is injected into
the page.
Try it all out: save the new versions of the files, recompile them and run the application again. You
should now be able to navigate to and fro between the Main Menu and the HelloWorld panels, with
the back button appearing and disappearing at the correct times:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 33
We still have a couple of problems:
• we need to add copies of the Javascript logic that shows the back button to the other two fragments that slide into view when you click the other two main menu options
• that destroy() method is only being applied to the helloworld panel. What if the user chooses one of
the other options? Things will clearly go wrong.
You can easily fix the first issue. To fix the second, we need to change the Back Button handler to
identify and destroy whatever panel is the current one. That’s actually quite simple to do: here’s the
modified version of the handler function:
EWD.sencha.onBackBtnTapped = function() { var cardPanel = Ext.getCmp("mainCardPanel"); var currentPanel = cardPanel.getActiveItem(); cardPanel.setActiveItem(0, {type:"slide", direction: 'right'}); Ext.getCmp("backBtn").hide(); currentPanel.destroy(); };
Note the way I’ve set up variables named cardPanel and currentPanel that are pointers to the
mainCardPanel and the currently active card panel objects: that’s because I’m making more than one
reference to each the objects in the logic, so it’s more efficient when done this way. As a side benefit I
think it’s also easier to read and maintain when written this way.
The key function here is the Sencha Touch getActiveItem() function which returns the currently active
item in the Card Panel.
Now we have a totally general purpose Back Button handler. Try it for yourself.
Automating the List’s Back ButtonSo that’s how to use the Sencha Touch functions to implement the back button with the required
behaviour. However, EWD can automate almost everything we’ve done manually.
Simply remove the ui and handler attributes from the back button tag in mainMenu.ewd and replace
them with type=”autoback” and cardPanel=”mainCardPanel”, ie:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 34
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getMainMenu^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true"> <st:toolbar dock="top" title="EWD Mobile">
<st:toolbarButton type="autoback" id="backBtn" text="Back" hidden="true" cardPanel="mainCardPanel" /> </st:toolbar> <st:cardPanel id="mainCardPanel"> <st:list id="mainMenu" sessionName="mainMenuOptions" scroll="true" nextPageField="page"> <st:layout> <st:field name="page" displayInList="false"/> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> </st:cardPanel> </st:panel> </st:content></st:container>
For good measure you can delete or comment out the button handler that we previously added to
stdemo.js. Also remove the inline code that we previously added to the three fragments that brought
the back button into view. So, for example, the helloworld.ewd fragment should look like this again:
<ewd:config isFirstPage="false" pageType="ajax">
<st:panel id="helloworld" html="Hello World!" />
Save the files, recompile the application and run it again: it should behave just as before, but this time
the back button’s appearance and disappearance now happens entirely automatically!
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 35
Lesson 8
Tab PanelsIn Lesson 7 we saw how to create a simple menu and Card Panel that we could use for navigation.
In Sencha Touch there is an alternative UI technique which is the TabPanel. Instead of a list of options in a menu, we can present the options as a set of tabs in a toolbar.
The advantage of this approach is its simplicity: the TabPanel looks after all the animation and to-ing
and fro-ing between options for us. If you’ve only got a small number of menu/navigation options,
they’re probably the better technique to use.
So let’s rewrite our application to use a TabPanel instead.
Edit index.ewd to look like the following:
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true">
<st:toolbar dock="top" title="EWD Mobile" />
<st:tabPanel id="mainTabPanel"> <st:panel id="helloworld" title="Hello" html="Hello World!" /> <st:panel id="example2" title="Example 2" html="Example 2" /> <st:panel id="example3" title="Example 3" html="Example 3" /> </st:tabPanel>
</st:panel> </st:content></st:container>
Recompile the stdemo application and try running it again. This time you should see:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 36
Try clicking the tabs and you’ll see the three sub-panels alternately slide in and out of view. This is
clearly a much simpler method to specify in order to allow navigation around your applications.
You can see, however, the key limitation: if you’re running the application on an iPhone or Android
phone: you don’t have much room for meaningful tab names. If you are running on a desktop or
tablet you have much more room, in which case tabs become a much more useful UI device.
Using EWD Fragments with the Tab Panel
You can also see that in order to use the TabPanel widget, you apparently need to specify all the sub-
panels and their contents in the same page. This can be advantageous, because no additional
round-trips to the server are required.
However, your application may be sufficiently large that you want to break it up into EWD fragments.
This is, in fact, possible to do, but one warning: sometimes, because of the way in which Sencha
Touch handles the height of its panels, the rendering of injected panels from fragments fails. However, if we keep the fragments and injected panels simple, we can demonstrate the technique.
Instead of having to explicitly use Sencha Touch’s event handlers and functions, EWD Mobile makes it
very simple by allowing you to add an attribute named page to each of the panels for the
corresponding tabs, eg:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 37
<ewd:config isFirstPage="true" cachePage="false">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true">
<st:toolbar dock="top" title="EWD Mobile" /> <st:tabPanel id="mainTabPanel"> <st:panel id="helloworld" title="Hello" page="helloworld" /> <st:panel id="example2" title="Example 2" page="example2" /> <st:panel id="example3" title="Example 3" page="example3" /> </st:tabPanel>
</st:panel> </st:content></st:container>
Now edit or create the three content fragment files as follows:
helloworld.ewd:<ewd:config isFirstPage="false" pageType="ajax">
<st:panel html="Hello World!" addTo="helloworld" />
example2.ewd:<ewd:config isFirstPage="false" pageType="ajax">
<st:panel html="This is example 2" addTo="example2" />
example3.ewd:<ewd:config isFirstPage="false" pageType="ajax">
<st:panel html="This is example 3" addTo="example3" />
Recompile the stdemo application and now try running it. Each panel fragment should slide into view when you click its corresponding tab. If you look in detail at what happens when you run it using
Chrome’s Developer Tools, you’ll see three parallel asynchronous requests are made for the content
fragments immediately after index.ewd is rendered.
The cool thing is that these requests are only made once when the Tab Panel is initially rendered, and
thereafter when you switch between tabs, you’re working entirely locally in the browser.
You’ll find that this demonstration works well. However, to reiterate the earlier warning: sometimes
you’ll find that whilst the fragment has been successfully injected into the container page and added
to its parent panel without any Javascript errors being reported, nothing will be visible. This is due to
the way in which Sencha Touch sizes and renders its panels and their contents.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 38
Lesson 9
Selecting Data from a ListWe’re going to re-visit the <st:list> tag, but this time we’ll examine it’s role in displaying a set of data.
We’ll also look at how you can do something when the user selects an item from the list.
The differences to our previous example where we used a List as a UI navigation device are:
• The list will contain the results of a database search rather than some predetermined options
• We will probably want to perform the same action irrespective of the row in the List that is selected
by the user.
Creating our ListFor this example we’ll use one of the Globals that EWD will have created on your system, specifically
the one that holds the documentation for its DOM APIs. This will give us a nice long list of options to
display in our application.
We’ll use the Tab Panel that we created in the previous lesson, and we’ll replace the middle panel
(example2) with a panel that will display the list of the APIs. You’ll find that we can’t add the List to
the TabPanel by using a separate fragment - it simply won’t render. So edit index.ewd as follows:
<ewd:config isFirstPage="true" cachePage="false" prePageScript="getAPIList^stdemo">
<st:container rootPath="/sencha-1.0/" title="Hello World"> <st:images> <st:image type="tabletStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" src="/sencha-1.0/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.0/examples/kitchensink/resources/img/icon.png" addGloss="true" /> </st:images> <script src="/stdemo.js" /> <st:content> <st:panel fullscreen="true">
<st:toolbar dock="top" title="EWD Mobile" /> <st:tabPanel id="mainTabPanel"> <st:panel id="helloworld" title="Hello" page="helloworld" />
<st:panel id="example2" title="List" layout="card"> <st:list scroll="vertical" id="apiList" sessionName="listOfAPIs"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> </st:panel>
<st:panel id="example3" title="Example 3" page="example3" /> </st:tabPanel>
</st:panel> </st:content></st:container>
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 39
When you are creating a List such as this inside a Tab Panel, it’s very important to follow a pattern
such as the one shown above otherwise Sencha Touch won’t display anything. In particular, make sure you have the attributes exactly as shown in red.
The <st:list> tag is defined similarly to our previous example, and this time the list of options is being
held in an EWD Session variable named listOfAPIs. That is being created by the pre-page script:
getAPIList^stdemo. Here’s what that function looks like:
getAPIList(sessid) ; n list,name,no ; s name="",no=0 f s name=$o(^%zewd("documentation","DOM","method",name)) q:name="" d . s no=no+1 . s list(no,"optionText")=name ; d saveListToSession^%zewdSTAPI(.list,"listOfAPIs",sessid) ; QUIT ""
The global ^%zewd(“documentation”) is one that EWD will have created on your system when you
installed it. It contains quite a few records so it’s a good example to use in this demo application.
Save these files, routine, etc, recompile and run the application again and you should see the
following:
As you can see, clicking on the List tab brings up the list of APIs. You can try swiping through the
menu to see how quickly you can search and navigate through it.
So that’s our menu displaying. Now how can we use it?
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 40
Adding a NextPageTypically you’ll want the user to be able to tap a menu option and have a new panel slide into view
that presents some more specific information about the option they selected, either to simply view it
or manipulate it in some way. Let’s see how to do that.
The first thing is to add two EWD-specific attributes to the <st:list> tag in the index.ewd page (only
that part of index.ewd is shown below):
<st:panel id="example2" title="List" layout="card"> <st:list scroll="vertical" id="apiList" sessionName="listOfAPIs" nextPage="apiDetails" cardpanel="example2"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list></st:panel>
The nextPage attribute tells EWD the name of the fragment to fetch when any item in the list is
tapped. The cardpanel attribute tells EWD the id of the Card Panel that you want to use so that the
nextPage fragment can be both added to it and animated as it comes into view. A slide transition is
used by default. Notice in index.ewd that we specified the example2 panel to have a layout=”card”
for this purpose (as highlighted in red above).
We haven’t created the fragment named apiDetails.ewd that is referenced by the nextPage attribute, yet, so let’s do that now: create the file in your stdemo directory. Initially we’ll keep its contents simple
just to check this step works correctly:
<ewd:config isFirstPage="false" pageType="ajax">
<st:panel id="apiDetails" html="List item was selected!" />
Save, compile and re-run the application as usual. This time when you tap any of the API names in
the list, our new apiDetails panel should now slide into view:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 41
Adding a Back ButtonOf course we now need a Back button in the toolbar to allow us to return to the list of APIs, so let’s
add that. We use the same autoback mechanism that was described earlier:
<st:panel fullscreen="true">
<st:toolbar id="topToolbar" dock="top" title="EWD Demo"> <st:toolbarButton type="autoback" cardpanel="example2" id="listBackBtn" text="Back" hidden="true" /> </st:toolbar> <st:tabPanel id="mainTabPanel"> <st:panel id="helloworld" title="Hello" page="helloworld" />
<st:panel id="example2" title="List" layout="card"> <st:list scroll="vertical" id="apiList" sessionName="listOfAPIs" nextPage="apiDetails" cardpanel="example2"> <st:layout> <st:field name="optionText" displayInList="true"/> </st:layout> </st:list> </st:panel>
<st:panel id="example3" title="Example 3" page="example3" /> </st:tabPanel>
</st:panel>
What we’ve done is to add a back button to the toolbar and automated it to work with the Card Panel
whose id is example2. We initially make it hidden so that it only appears when the nextPage fragment
(apiDetails.ewd) slides into view. The attributes in red show how everything hinges around the
example2 id. Recompile and try running the application to see the back button working.
Making the NextPage recognise the Item Selected from the ListIt should be clear by now that there is one remaining step that we need to understand in this exercise
to make it a really useful List example: how can we make the apiDetails.ewd fragment recognise which API we tapped in the List so that it can provide the user with information specific to that
particular one?
Actually it’s very simple. By using the nextPage attribute in the <st:list> tag, EWD is already
automatically sending the number of the item you tapped as a name/value pair that is added to the
HTTP request for apiDetails.ewd. This number equates to the number in the option array that you
originally created in the pre-page script. So if the user taps the first item, EWD sends a value of 1.
For example, if you were using WebLink, the request for the apiDetails fragment would look
something like this:
http://192.168.1.110/scripts/mgwms32.dll?MGWCHD=0&MGWAPP=ewdwl&app=stdemo&page=apiDetails&ewd_token=MWCFjJQIi9sShTZlEN1iXkYI2d3K55&n=v8eU35uZWEIWPVZKZMQ3eKJpgvHp30&listItemNo=1&ewdrn=612485987
Highlighted in red is the name/value pair (listItemNo) that EWD added when the first API in the List
was tapped.
The trick is to process and make use of this request name/value pair in a pre-page script that we’ll
now add to apiDetails.ewd:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 42
<ewd:config isFirstPage="false" pageType="ajax" prepagescript="getAPIDetails^stdemo">
<st:panel id="apiDetails" html="List item was selected!" />
In this pre-page script, we can pick up the value of that name/value pair using the EWD API getRequestValue():
getAPIDetails(sessid) ; n list,no,name ; s no=$$getRequestValue^%zewdAPI("listItemNo",sessid) d mergeArrayFromSession^%zewdAPI(.list,"listofAPIs",sessid) s name=$g(list(no,"optionText")) d setSessionValue^%zewdAPI("apiName",name,sessid) ; QUIT ""
Lets examine what this function will do:
• It gets the value of the listItemNo name/value pair using EWD’s getRequestValue() API. This identifies the option selected by the user
• It then retrieves the original list of options from the EWD Session, by using the
mergeArrayFromSession() method (this basically reverses the action of the saveListToSession()
method that was used in the pre-page script - getAPIList() for index.ewd)
• Now it can retrieve the name for the selected API from the options array by using the list number
that was sent by EWD
• We can then save that name as an EWD Session value named apiName. We can then refer to that name in the fragment’s markup.
One last step: we want to display the value of the Session variable (apiName) that was created in the
pre-page script function.. Edit apiDetails.ewd:
<ewd:config isFirstPage="false" pageType="ajax" prepagescript="getAPIDetails^stdemo">
<st:panel id="apiDetails"> <div> You selected the API named <?= #apiName ?> </div></st:panel>
Save all the files, recompile the stdemo application and run it again. Now when you tap an API in the
List, the apiDetails panel that slides into view should confirm the one you tapped, eg:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 43
We now have a simple, but fully-functional menu that is driven by data held in GT.M or Caché.
Retrieving more Details for the Selected ItemLet’s just add one final enhancement: we’ll retrieve the purpose of the selected API from the ^%zewd
Global and display it in the apiDetails panel. Simply edit the getAPIDetails() function in the ^stdemo
routine:
getAPIDetails(sessid) ; n desc,list,no,name ; s no=$$getRequestValue^%zewdAPI("listItemNo",sessid) d mergeArrayFromSession^%zewdAPI(.list,"list",sessid) s name=$g(list(no,"optionText")) d setSessionValue^%zewdAPI("apiName",name,sessid) s desc=$g(^%zewd("documentation","DOM","method",name,"purpose")) d setSessionValue^%zewdAPI("apiPurpose",desc,sessid) ; QUIT ""
Now edit the apiDetails.ewd page:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 44
<ewd:config isFirstPage="false" pageType="ajax" prepagescript="getAPIDetails^stdemo">
<st:panel id="apiDetails">
<div> <div> API: <?= #apiName ?> </div> <br /> <div> Purpose: <?= #apiPurpose ?> </div> </div>
</st:panel>
Save, recompile and re-run the application. Finally we have a proper and useful application that
retrieves real details from your GT.M or Caché database in response to the user selecting from a
menu:
You now have enough knowledge to begin building mobile applications that can allow a user to
navigate through lists of data and then retrieve and display related information. Try modifying the
examples to use and display some of your own data.
That completes Part 1 of our EWD Mobile Tutorial. In Part 2 we’ll introduce more widgets including
forms and we’ll take a closer look at the mechanics of the EWD Session.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 45
Appendix 1: Instal l ing EWD
Installing EWD
GT.MYou should either use the M/DB installer (http://gradvs1.mgateway.com/main/index.html?path=mdb/
mdbDownload) which will build you a system with the very latest build of EWD automatically, or get
the latest EWD routine files from https://github.com/robtweed/EWD. See our website (http://
www.mgateway.com) for details on installing EWD on GT.M systems.
Caché
You should download a copy of the latest version of EWD from our web site (http://
www.mgateway.com):
• Click the Enterprise Web Developer tab
• Click the tabs Download EWD followed by EWD for Caché.
• Complete the registration form and you’ll be able to download the latest copy of EWD for free. The
Sencha Touch custom tags are included in EWD.
The zip file that you'll download contains one critical file:
• zewd.xml - the object code file that you install into your %SYS namespace using
$system.OBJ.Load(). Let this overwrite any existing copy of ^%zewd* routines if you already have
EWD on your Caché system
Configuring EWD
EWD can generate CSP, WebLink and GT.M versions of Mobile web applications from the same EWD
application source code. If you're already using EWD, then you can immediately start developing EWD applications.
If you're new to EWD, then you'll need to configure EWD for either WebLink, CSP or GT.M, depending
on which technology you use. There are configuration instructions on our web site, but here's a quick
way of configuring them, based on certain assumptions - just change the references according to
your exact GT.M or Caché/WebLink/CSP configuration.
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 46
Caché & CSP
1a) Simple Default Configuration
If you are using a default Caché installation and want to initially use the built-in Apache web server
that is configured to use port 57772, you can just run (in a Caché Terminal session):
do configureDefault^%zewdCSP
This sets up the configuration global ^zewd for you.
1b) Custom Configuration
However, if you have configured IIS or some other web server for use with CSP, you’ll need to
manually configure EWD as appropriate to your specific configuration. This is done via the global
^zewd. Here’s an example of how to do this:
Assumptions:
• you'll be running your EWD-generated CSP applications in your USER namespace
• you're using IIS as your web server and its root path is c:\inetpub\wwwroot
• your source EWD applications will reside under the path c:\ewdapps
• the CSP application directories and files generated by EWD will be saved under c:\InterSystems\Caché\CSP\ewd
Create a global named ^zewd as follows (adjust as necessary):
^zewd("config","RootURL","csp")="/csp/ewd" ^zewd("config","applicationRootPath")="c:\ewdapps" ^zewd("config","outputRootPath","csp")="c:\InterSystems\Cache\CSP\ewd" ^zewd("config","jsScriptPath","csp","mode")="fixed" ^zewd("config","jsScriptPath","csp","path")="/" ^zewd("config","jsScriptPath","csp","outputPath")="c:\Inetpub\wwwroot"
2) Define CSP Application
Next, you must create a CSP Application named "/csp/ewd" that points to the outputRootPath above
and directs you to the required namespace (USER). To so this, use the Caché System Management
Portal, select Security Management/ CSP Applications, then click the Create New CSP Application
link.
Fill out the form as shown below to get you started:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 47
The settings shown above are for a simple default CSP system using the built-in web server. If you
have a customized CSP configuration, you may need to make some adjustments, in particular to the
CSP Files Physical Path.
EWD should now be ready to use with CSP.
Caché & WebLink
Assumptions:
• you'll be running your EWD applications in your USER namespace
• you're using IIS as your web server and its root path is c:\inetpub\wwwroot
• your source EWD applications will reside under the path c:\ewdapps
• you'll be using the WebLink Server (MGWLPN) LOCAL which, by default, connects incoming
requests to the USER namespace
Create a global named ^zewd in the USER namespace as follows (adjust as necessary):
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 48
^zewd("config","RootURL","wl")="/scripts/mgwms32.dll" ^zewd("config","applicationRootPath")="/usr/ewdApps" ^zewd("config","jsScriptPath","wl")="fixed" ^zewd("config","jsScriptPath","wl","mode")="fixed" ^zewd("config","jsScriptPath","wl","outputPath")="c:\Inetpub\wwwroot" ^zewd("config","jsScriptPath","wl","path")="/"
You also must create the global (again in USER):
^MGWAPP("ewdwl")="runPage^%zewdWLD"
This latter global creates the WebLink dispatcher to EWD's WebLink run-time engine.
GT.M
Assumptions:
• you'll be running your EWD applications in an instance of GT.M running in /usr/local/gtm/ewd
• you're using Apache as your web server and its root path is /var/www
• your source EWD applications will reside under the path /usr/ewdapps
• m_apache has been installed and configured to dispatch to EWD’s runtime code when URLs are
encountered containing /ewd
• Javascript and CSS files that are generated by EWD will be saved under the webserver
path /resources
Create a global named ^zewd as follows (adjust as necessary):
^zewd("config","RootURL","gtm")="/ewd/"^zewd("config","applicationRootPath")="/usr/ewdapps"^zewd("config","jsScriptPath","gtm","mode")="fixed"^zewd("config","jsScriptPath","gtm","outputPath")="/var/www/resources"^zewd("config","jsScriptPath","gtm","path")="/resources/"^zewd("config","routinePath","gtm")="/usr/local/gtm/ewd/"
Creating EWD Pages
This tutorial will guide you through the process, but here’s a quick summary of the process involved,
based on the configuration settings shown above.
Having configured your EWD environment, you should now be ready to start developing. Create your
new EWD application source pages in subdirectories of the Application Root Path, eg if your
Application Root Path is c:\ewdapps and your application is named myApp::
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 49
c:\ewdapps\myApp\index.ewd
c:\ewdapps\myApp\login.ewd
You can use any text editor to create and edit these files.
To create an executable web application from these pages, you must compile them. This is most
easily done using the command-line APIs that you invoke from within Caché Terminal or, if you are using GT.M, from within a Linux terminal session running the GT.M shell.
To compile an entire application (eg one named myApp):
CSP: USER> d compileAll^%zewdAPI("myApp",,"csp")
WebLink: USER> d compileAll^%zewdAPI("myApp",,"wl")
GT.M: USER> d compileAll^%zewdAPI("myApp")
To compile one page (eg myPage.ewd) in an application (eg myApp):
CSP: USER> d compilePage^%zewdAPI("myApp","myPage",,"csp")
WebLink: USER> d compilePage^%zewdAPI("myApp","myPage",,"wl")
GT.M: USER> d compilePage^%zewdAPI("myApp","myPage")
Running EWD Applications
You’ll now have a runnable iPhone Web Application. You start it using the web server in your mobile
device (eg Safari on the iPhone). The structure of the URL you’ll use depends on whether you’re
using GT.M, WebLink or CSP:
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 50
CSP
For CSP EWD applications, the structure of the URL you’ll use is:
http://127.0.0.1/csp/ewd/[applicationName]/[pageName].csp
where: applicationName is the name of your EWD application
pageName is the name of the first page of your EWD application
for example:
http://127.0.0.1/csp/ewd/myApp/index.csp
WebLink
For WebLink EWD applications, the structure of the URL you’ll use is:
http://127.0.0.1/scripts/mgwms32.dll?MGWLPN=LOCAL&MGWAPP=ewdwl&app=[applicationName]&page=
[pageName]
where applicationName is the name of your EWD application
pageName is the name of the first page of your EWD application
for example:
http://127.0.0.1/scripts/mgwms32.dll?MGWLPN=LOCAL&MGWAPP=ewdwl&app=myApp&page=index
If you’re using Apache, you’ll typically replace /scripts/mgwms32.dll with cgi-bin/nph-mgwcgi
Of course if you’re using a WebLink Server other than LOCAL, you’ll also need to change the value of
the MGWLPN name/value pair.
GT.M
For GT.M EWD applications, the structure of the URL you’ll use is:
http://127.0.0.1/ewd/[applicationName]/[pageName].ewd
where applicationName is the name of your EWD application
pageName is the name of the first page of your EWD application
for example:
http://127.0.0.1/ewd/myApp/index.ewd
Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved
EWD Mobile Tutorial Part 1 (Build 857) 51
Top Related