ewd mobile tutorial part 2 (build...

EWD Mobile

Tutorial: Part 2

M/Gateway Developments Ltd http://www.mgateway.com

M/Gateway Developments Ltd

http://www.mgateway.com

http://www.mgateway.com

Table of Contents

Introduction 1

Background 1

Lesson 10 2

Styling inside Panels 2

Lesson 11 6

Modal Panels 6

Lesson 12 11

Introduction to Forms 11

Lesson 13 17

The EWD Session 17

User Sessions and EWD Session Storage 19

Designer versus Programmer 20

Accessing the Session from within an EWD 4

Creating and Manipulating EWD Session Data 25

Processing Submitted Forms 27

The Request versus the EWD Session 28

Lesson 14 29

The Container Page Revisited 29

Controlling the EWD Session Timeout 29

Controlling the Browser’s Session Timeout Action 31

Copyright ©2011, M/Gateway Developments Ltd. All Rights Reserved

EWD Mobile Tutorial Part 2 (Build 857) i

Fetching data from GT.M or Caché as JSON 33

Lesson 15 35

Using EWD Mobile’s Form Field Types & Widgets 35

Text Fields 35

Submitting forms and viewing the EWD Session 39

HTML5 Number field 42

Disabled Fields 44

HTML5 Email Field 45

HTML5 URL Field 46

Checkboxes 47

Spinner Field 48

Select Field 49

Toggle Field 51

Radio Field 52

Date Field 53

Slider Field 56

Hidden Field 59

Textarea Field 59

Combo Field 60

Conclusion 63


EWD Mobile Tutorial Part 2 (Build 857) ii

Introduction

Background

This is the second part of our tutorial on mobile web application development using EWD Mobile.

It is recommended that you complete (or at least read) Part 1 before embarking on the exercises in

this second part of the tutorial.

In Part 1, we covered the basics of creating mobile web applications using EWD Mobile, touched on

how EWD Mobile integrates seamlessly with the Caché and GT.M databases and looked at the List and TabPanel widgets.

In Part 2 we’ll look at styling text, modal/pop-up panels and forms. We’ll also examine in more detail

the underlying architecture of EWD Mobile and in particular what’s behind EWD’s persistent Sessions.


EWD Mobile Tutorial Part 1 (Build 857) 1

Lesson 10

Styling inside Panels

By the end of Lesson 9 in Part 1, we were able to display a List of EWD’s DOM APIs, and when one was tapped, a new panel – apiDetails.ewd – would slide into view, providing further information about

the API.

The styling of the text that was displayed in the apiDetails panel was very basic, and in this lesson

we’ll look at a few EWD-specific styling tags that have been provided to give a nice look at feel to the

presentation of such text.

The main styling tag is the <st:pageItem> tag. This will create a rectangular area with rounded

corners in which your markup can be displayed. Let’s modify apiDetails.ewd to use it.

To begin with, simply place our text markup inside an instance of an <st:pageItem> tag, and add a

title attribute to it, for example:

<ewd:config isFirstPage="false" pageType="ajax" prepagescript="getAPIDetails^stdemo">

<st:panel id="apiDetails">

<st:pageItem title="API Details"> <div> <div> API: <?= #apiName ?> </div> <br /> <div> Purpose: <?= #apiPurpose ?> </div> </div>

</st:pageItem></st:panel>

Save this file, recompile and rerun the application. Select an API and you should now see our textual

information nicely displayed as follows:



You can turn off the default panel shadowing by simply adding the attribute shadow=”false”:

<st:pageItem title="API Details" shadow="false"> <div> <div> API: <?= #apiName ?> </div> <br /> <div> Purpose: <?= #apiPurpose ?> </div> </div> </st:pageItem>

And you can add a header to the panel:

<st:pageItem title="EWD DOM" header="API Details"> <div> <div> API: <?= #apiName ?> </div> <br /> <div> Purpose: <?= #apiPurpose ?> </div> </div> </st:pageItem>

resulting in the following:



We can further enhance the display by using <st:pageItemField> tags for the API and Purpose values

instead of the raw <div> tags that we originally used:

<st:pageItem title="EWD DOM" header="API Details">

<st:pageItemField label="API: " value="#apiName" /> <st:pageItemField label="Purpose: " value="#apiPurpose" /> </st:pageItem>

Now the apiDetails panel will look like this:



We can make one final enhancement, and allocate a width for the label:

<st:pageItem title="EWD DOM" header="API Details" labelWidth="75" > <st:pageItemField label="API: " value="#apiName" /> <st:pageItemField label="Purpose: " value="#apiPurpose" /> </st:pageItem>

The apiDetails panel now looks as follows:

You can have as many <st:pageItemField> tags as you like inside a single <st:pageItem> tag, and an

<st:panel> tag can contain as many <st:pageItem> tags as you want. You can even nest

<st:pageItem> tags inside each other: try it and see what happens.



Lesson 11

Modal PanelsAnother way of presenting information to the user is to use modal pop-up panels. EWD Mobile

makes this really easy to do and the appearance, provided by Sencha Touch, is very slick.

A very common use of pop-up panels in mobile applications is in association with toolbar buttons.

Clicking a button can trigger the appearance of a modal panel, and you can even get the panel to line

itself up visually with the button that opened it. You’ll see this visual effect used a lot in iPad

applications. You can now do the same thing using EWD Mobile.

So let’s try it out. What we’re going to do is to first add an About button that will be always visible on

the right hand side of the top toolbar. To do this, edit the index.ewd page (only the <st:content> part

is shown; the rest of the page remains the same as before):

<st:content> <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:spacer /> <st:toolbarButton id="aboutBtn" text="About" /> </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>

Note the <st:spacer> tag which forces the About button over to the right-hand side of the toolbar.

Save, recompile and re-run and the application will look like this when it starts:



Now we’ll add the modal panel to the tabPanel.ewd page, and also a handler for the About button:

<st:content> <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:spacer />

<st:toolbarButton id="aboutBtn" text="About" handler="EWD.sencha.onAboutBtnTapped"/> </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>

<st:panel id="aboutPanel" floating="true" width="250" height="200" modal="true" hidden="true"> <div> About EWD! </div> </st:panel>

</st:content>

Notice that we’ve put the modal panel outside the main panel. This is important to ensure that it

behaves correctly.

The key attributes that turns a panel into a modal pop-up one are:

• floating =” true”

• modal = “true”



We’re also specifying the size of the panel using the width and height attributes, and initially the panel

should be hidden. Initially we’re just putting a simple bit of text inside the panel. Once we have it working we’ll make it more interesting.

Now we need to define that handler for the About button, so add the following to your stdemo.js file:

EWD.sencha.onAboutBtnTapped = function(btn) { Ext.getCmp("aboutPanel").showBy(btn);};

The idea, of course, is to make the modal panel appear when the user taps the About button. Notice

that we’re using a different method this time: showBy() rather than show(). This is a really cool

method that positions the modal panel relative to another component. Note that we’re passing in a

parameter – btn. That is a pointer to our About button and by using it in the showBy() method, the

modal panel should line itself up relative to the button.

So, save your modified index.ewd page and stdemo.js file and recompile the stdemo application.

Now when you run it and you click the About button, you should see the following:

Tap anywhere outside the modal panel and it it will close automatically and you’ll get access to the main panels again.

The really nice thing about modal panels is that they can hold pretty much anything that a normal

docked panel can hold, eg scrolling text , forms and lists. So, for example, let’s put some more

meaningful text in the modal panel and we’ll use the <st:pageItem> tag (described in Lesson 10) to

format it:



<st:panel id="aboutPanel" floating="true" width="250" height="200" modal="true" hidden="true" scroll="vertical"> <st:pageItem title="About" shadow="false"> <div>

This is an EWD-based mobile application that demonstrates the Sencha Touch custom tags. This particular modal pop-up panel was described in Part 2 of the tutorial. </div>

</st:pageItem></st:panel>

We’ve put quite a bit of text in it, and we could have made the panel taller by increasing the height.

However, just to demonstrate the capabilities, we’ve told the modal panel to be scrollable in a vertical

direction. Save the modified index.ewd file, recompile it and re-run the application. This time you should see:

Try scrolling the text in the panel by touching and swiping it.

You’ll soon find that when you use modal panels, it will be difficult to find a particular height and width

that will work satisfactorily on both a tablet (eg an iPad) and a phone. Ideally you’ll want to use a

larger panel on a tablet since you have the available space, but restrict the size on the phone. Indeed

you may even decide not to use modal panels if the user is using a phone.

One of the nice things about Sencha Touch is that it is very easy to determine the type of device the

application is running on by using the property:

Ext.is.Phone

This will return true if the user is using an iPhone or Android phone, but false if the user is using

anything else (including a compatible desktop browser such as Chrome).

So, we could adjust the size of the modal panel dynamically in the About button handler as follows:



EWD.sencha.onAboutBtnTapped = function(btn) { var aboutPanel = Ext.getCmp("aboutPanel"); if (Ext.is.Phone) { aboutPanel.setHeight(200); aboutPanel.setWidth(250); } else { aboutPanel.setHeight(500); aboutPanel.setWidth(400); } Ext.getCmp("aboutPanel").showBy(btn);};

Try it out and see what happens.



Lesson 12

Introduction to Forms

So far we’ve just looked at UI functionality that allows the retrieval and display of data from your

database. Of course you’ll often want to build mobile applications that allow the user to save and

update information in your database.

In order to do that, you’ll need to be able to create and use forms within your mobile application.

First, however, a word of caution: mobile applications are all about slick, fast user interfaces. As soon

as you present a user with a form field where they need to type something in, you’re stopping them in

their tracks. Although some text entry is inevitable and unavoidable in most business applications, the trick is to keep this to an absolute minimum. There are often ways of getting the user to enter

meaningful and useful data without requiring them to type text, for example by using menus, radio

buttons, checkboxes, sliders, etc.

With that in mind, let’s look at how to present a form to a user.

We’ll start with a simple but useful form – a user login form. This will allow you to ensure that only

authorized users can access the application. Usually the login form will be the first thing that comes

up when the application is started, and that’s what we’ll now do with our demo application.

First, save a copy of your current index.ewd file to another temporary text file: we’ll want most of its

current content later. Next, edit the <st:content> part of index.ewd to look like the following:

<st:content> <st:panel id="mainPanel" fullscreen="true" layout="card">

<st:toolbar id="topToolbar" dock="top" title="EWD Demo" />

<st:form id="loginForm" submitOnAction="false"> <st:fieldset title="Please log in"> <st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" labelWidth="33%" /> <st:field type="submit" text="Login" style="drastic_round" /> </st:fieldset> </st:form>

</st:panel>

</st:content>

Also you can remove the pre-page script attribute from the <ewd:config> tag at the top of the page.



Save this new version of index.ewd and recompile the stdemo application. When you restart it, you

should see:

You’ll find that this form won’t do anything yet. Let’s first analyse what we specified to make this form

appear:

• We added a form panel, denoted by the <st:form> tag

• Inside the <st:form> we specified an <st:fieldset> tag which creates the styled grouped set of form

fields together with its title (“Please log in”)

• We then added three <st:field> tags for the username field, password field and Login button. Note

the id attributes that have been specified for the username and password fields: these are

important, as you’ll see later. The shape of the submit button is determined by the style attribute.

drastic-round is one of the standard Sencha Touch button styles and a good one for forms. Try

running the Sencha Touch Kitchen Sink demo application to see many of the others that are

available.

So that’s our basic form displaying itself properly. Next we’ll animate it so that when the Login button

is clicked, the tab panel that we’d previously designed slides into view. Initially we’ll not worry about

validating the username and password.

There are several things we need to do in order to animate the form. Remember from the earlier

exercises that animating a set of panels requires a card panel as a container, so we’ll add that first,

with the form initially the only card inside it:





<st:cardpanel id="mainCardPanel">

<st:form id="loginForm" submitOnAction="false"> <st:fieldset title="Please log in"> <st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" labelWidth="33%" /> <st:field type="submit" text="Login" style="drastic_round" /> </st:fieldset> </st:form>

</st:cardpanel>

</st:panel>

</st:content>

Next we add a couple of attributes to the submit button field to tell it

• the name of the fragment we want to fetch when it is clicked, and

• the id of the cardpanel to use as the container for the animation which is slide by default:




<st:form id="loginForm" submitOnAction="false"> <st:fieldset title="Please log in"> <st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" labelWidth="33%" />

<st:field type="submit" text="Login" style="drastic_round" nextpage="tabPanel" cardpanel="mainCardPanel" /> </st:fieldset> </st:form>

</st:cardpanel>

</st:panel>

</st:content>

Now we need to create a fragment file named tabPanel.ewd. This is going to contain the tab panel

content that we’d originally defined (in earlier lessons) in index.ewd: hopefully you saved that original

version as suggested earlier. If not, cut and paste the code below:

<ewd:config isFirstPage="false" pageType="ajax" prePageScript="getAPIList^stdemo">

<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>

Now try saving the edited files, recompile and re-run the application. You should find that

when you click the login form’s submit button, it will slide the tab panel into view, and

everything should then work as before – it’s really starting to look like a proper application

now!



However, you’ll notice that we’ve lost the List’s Back button (so you can’t return to the List

from the API Details panel), the About button and its associated modal panel. So let’s get

them reinstated. Edit index.ewd as follows:


<st:toolbar id="topToolbar" dock="top" title="EWD Demo"> <st:toolbarButton type="autoback" cardpanel="example2" id="listBackBtn" text="Back" hidden="true" /> <st:spacer /> <st:toolbarButton id="aboutBtn" text="About" handler="EWD.sencha.onAboutBtnTapped" /> </st:toolbar>


<st:form id="loginForm" submitOnAction="false"> <st:fieldset title="Please log in"> <st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" labelWidth="33%" /> <st:field type="submit" text="Login" style="drastic_round" nextpage="tabPanel" cardpanel="mainCardPanel" /> </st:fieldset> </st:form> </st:cardpanel>

</st:panel>

<st:panel id="aboutPanel" floating="true" width="250" height="200" modal="true" hidden="true" scroll="vertical"> <st:pageItem title="About" shadow="false"> <div> This is an EWD-based mobile application that demonstrates the Sencha Touch custom tags. This particular modal pop-up panel was described in Part 2 of the tutorial. </div> </st:pageItem></st:panel>

</st:content>

Save this version of index.ewd, recompile it and try running the application. Now everything should

be back as it was, except the user has to complete a login form first.

Notice that after the submit button is pressed, there is no way to bring back the form which is

precisely the behaviour we want.

Now let’s look at how we validate the username and password. Everything we need to do will take place in the pre-page script of tapPanel.ewd since this is the “nextPage” that we’re requesting when

the submit button is clicked. We already have a pre-page script for that page: it is currently just

fetching the list of DOM APIs for the List widget. Look in the routine file (stdemo.m or open

stdemo.mac using Caché Studio) and you’ll see that it currently contains:

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 deleteFromSession^%zewdAPI("list",sessid) d mergeArrayToSession^%zewdAPI(.list,"list",sessid) d saveListToSession^%zewdSTAPI(.list,"listOfAPIs",sessid) ; QUIT ""

Add the lines indicated below:



getAPIList(sessid) ;

n list,name,no,password ; s name=$$getSessionValue^%zewdAPI("username",sessid) s password=$$getSessionValue^%zewdAPI("password",sessid) i name'="rob" QUIT "Invalid name" i password'=1234 QUIT "Invalid password" ; 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 deleteFromSession^%zewdAPI("list",sessid) d mergeArrayToSession^%zewdAPI(.list,"list",sessid) d saveListToSession^%zewdSTAPI(.list,"listOfAPIs",sessid) ; QUIT ""

Save and recompile the stdemo routine. On GT.M it’s also a good idea to run the following in the

GT.M shell:

do relink^%zewdGTM

This ensures that the back-end m_apache processes relink their copy of the stdemo routine so

they’re using the latest version.

Now try running the application and try just clicking the submit button without entering any name or

password. This time you won’t be let in and an alert will up:

In fact you won’t be able to get any further unless you enter a username of rob and a password of

1234, which are the validation rules we’ve hard-coded into the pre-page script. Enter the correct

username and password, however, and the tab panel slides into view.



Note how simple EWD makes form field validation:

• We pick up the submitted values using EWD’s $$getSessionValue() method. The field name you use is the same as the id

attribute you specified in the form, ie:

<st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" labelWidth="33%" />

s name=$$getRequestValue^%zewdAPI("username",sessid) s password=$$getRequestValue^%zewdAPI("password",sessid)

• We’ve just used some simple hard-coding to validate the username and password, but you can use whatever user

authentication functionality you already have in place on your GT.M or Caché system, or write your own for your new

application.

• In order to signal a validation failure to EWD, simply QUIT with a non-empty string return value. Whatever string you

specify will automatically be used as the text in a Sencha Touch alert panel that will pop up.

• Otherwise your pre-page script should continue on its way and ultimately QUIT will an empty string as its return value.

This signals to EWD that the pre-page script ran without any validation errors, so it can now safely render the contents of

the nextpage fragment.

You now have a working username/password form. Try playing about with the validation logic in the

pre-page script, add new valid usernames, hook it up to an authentication global etc.



Lesson 13

The EWD Session

In the previous lesson, you’ll have noticed that in the pre-page script we used to validate the form, we

retrieved the username and password values by using EWD’s getSessionValue API method. In this

lesson we’ll learn all about the EWD Session, which is a key and extremely important part of EWD.

The EWD Session is a persistent data store that is automatically associated with each individual user.

The EWD Session storage exists as long as the user is deemed by EWD to be an active user: we’ll

see later how this is determined. Once a user is no longer an active user, EWD automatically deletes

his/her EWD Session storage.

The are two basic types of EWD Session storage:

• simple name/value pairs

• multi-dimensional arrays

Data is saved into the EWD Session in two main ways:

• explicitly using EWD’s Session API methods, eg setSessionValue, mergeArrayToSession

• implicitly when a form is submitted

Once a value has been saved into the EWD Session, the user can have access to it at any later stage

in any fragment for as long as the user is active.

We can demonstrate this very simply in the tabPanel.ewd page that we created in the previous

lesson. Let’s change the toolbar title to give a personalised greeting using the value of the username

entered by the user:




<st:js at="end"> Ext.getCmp("topToolbar").setTitle('Welcome <?= #username ?>');</st:js>



</st:tabPanel>

The Sencha Touch function setTitle() will dynamically modify the toolbar’s title. Notice how we’re

referencing the EWD Session Name within the Javascript: <?= #username ?>

Save this edited version of the tabPanel.ewd file and recompile it. Now when you log in, you’ll see the

following:

The Session is one of the key parts of EWD, and understanding how it works is important if you’re

going to get the full benefit of EWD. So now we’ll delve deep into what’s going on behind the scenes

in EWD.



User Sessions and EWD Session Storage

Let’s start right back the URL that you use to start an EWD application. Take the case of our stdemo

application: in order to start it up you’ll have used a URL similar to one of the following (your IP

address or domain name will be different of course):

• 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

In all three cases, what we’re doing is requesting the page named index.ewd from the EWD

application named stdemo. We are allowed to do this with a simple “static” URL because index.ewd

was configured to be a First Page by virtue of its <ewd:config> tag:

<ewd:config isFirstPage="true">

When you invoke a FirstPage with an untokenised URL, EWD creates a new, unique Session ID.

This is simply an integer value but it is unique to you, the user. Each time you subsequently click a

link or button in an EWD page within the application you’ve started, you send a URL back to the

Caché or GT.M server that identifies your Session ID via a set of randomly-generated name/value

pairs (or tokens) that will have been automatically added to the URL by EWD.

Actually those tokens do two things:

• They identify you as a bona fide user who is allowed to request a non-first-page fragment from the Caché/GT.M back end

system. If the token is missing or not recognized, EWD will return an error fragment or alert back to the browser and

refuse to retrieve the fragment

• They securely identify your unique session Id. This is achieved via a lookup table (mapping tokens to session Ids) that is

automatically maintained by EWD within the GT.M or Caché back-end system. EWD never directly exposes the user’s

session Id within the HTML or Javascript that runs in the browser. Instead it uses the random tokens on the URLs as a

highly secure proxy. If the user had to log in to access an EWD application, you (the owner of the application) can then be

highly confident that once the user has logged in, subsequent requests for fragments that make up that application can

only have come from that user and not from someone simply pretending to be that person. It is this high degree of

security that has made EWD a popular framework for applications that involve access to sensitive healthcare and financial

data.

If the EWD page that has been requested has an associated pre-page script it is invoked before

anything else happens. the user’s unique session Id (sessid) is passed into the method by EWD.

That’s why your pre-page script functions must always require sessid as their one and only input parameter.



http://192.168.1.100/ewd/stdemo/index.ewd

http://192.168.1.100/ewd/stdemo/index.ewd

http://192.168.1.100/csp/ewd/stdemo/index.csp

http://192.168.1.100/csp/ewd/stdemo/index.csp

http://192.168.1.100/scripts/mgwms32.dll?MGWLPN=LOCAL&MGWAPP=ewdwl&app=stdemo&page=index

http://192.168.1.100/scripts/mgwms32.dll?MGWLPN=LOCAL&MGWAPP=ewdwl&app=stdemo&page=index

Because the pre-page script knows the user’s unique session Id, calls can be made to the EWD Session API methods (eg getSessionValue, setSessionValue etc) to access and manipulate the user’s

specific Session storage. These APIs are described in detail later.

EWD’s Session Storage (known simply as the EWD Session) provides a means by which you, the

developer, can retain user-specific data for the lifetime of the user’s session. A user’s session starts

when they invoke the initial untokenised URL to an EWD application’s FirstPage, and finishes when

one of two things happens:

• Most commonly, after the user is inactive for a predetermined duration (20 minutes by default), at which point their

browser either:

• automatically refreshes, forcing a reload of the index (or whatever their first page was), which starts a new session

(this is the default EWD Mobile action); or

• redirects them to a static URL or the first page of a different EWD application (something that you, the developer can

decide to do)

• Less frequently, the user invokes an action (that you, the developer, has specified) that explicitly terminates their session

and redirects them to a static URL

Once an EWD session times out, it is no longer accessible, even with a previously validly tokenized

URL. Any requests will result in an error message being sent as a response. Any persistent EWD

Session Data that is associated with a user session that has timed out is automatically cleared down

by EWD’s garbage collector (though this may not occur immediately).

The EWD Session is a key part of the EWD architecture and determines how your EWD pages are

designed and how information is conveyed between the browser and back-end database. So let’s

examine it in some more detail.

Designer versus Programmer

You’ve seen in this tutorial that an EWD application consists of two distinct parts:

• EWD pages or fragments

• Back-end methods: ie Pre-page Script functions that execute within GT.M or Caché.

These are often referred to as the “front end” and “back end” respectively.

One of the key concepts of EWD is that these two parts of an application can be developed by two different people:

• Front-end design can be carried out by a web application designer

• Back-end method development can be carried out by a programmer who is familiar with GT.M or Caché, the data models

that define the organisation’s database, and business logic (ie functions, procedures and APIs) that already exist within the

organisation



The two halves of an EWD application require different disciplines and knowledge, and EWD allows each half to be developed by the correct person with the correct skills. Indeed the designer of the

front-end does not have to know anything about the back-end in order to create his/her part of the

application. Similarly, the programmer can develop all the scripts needed by an EWD application

without really having to know anything about how or why they are being used.

In practice, of course, many EWD applications will be developed by one or more people who

simultaneously adopt both roles of designer and programmer, but nevertheless, EWD provides a very

important separation between design and programming.

Unlike probably most other web application development environments, in EWD there is no use of

“data binding”. In other words, the front-end page page/fragment definitions have no direct access to

back-end data. This is deliberate and, contrary to most industry preconceptions, turns out to be highly advantageous.

In fact there’s a critical problem with data binding: it irrevocably interlinks the front end design with the

back-end data model. Whilst fine for rapid development of quick demonstration applications, for real-

world applications, data binding is distinctly bad news for downstream maintenance and change.

Let’s face it: all real-world applications, no matter how simple and trivial, change over time. With data

binding, if the front-end design needs changing, it will almost certainly have an impact on the back-

end database. Similarly, changes to the back-end database schema will almost certainly impact on

the front-end design logic. The result is a time-consuming, complex and unnecessary mess that

consumes hours of development time, and/or hinders or, in the worst cases, completely prevents

enhancements to the application.

EWD takes a totally different approach and deliberately separates and de-couples the front-end from

the back-end. In doing so, it provides an intermediate boundary layer between the front-end and

back-end: the EWD Session, to which each has access. The diagram below summarises the

architecture:



Thus, the front-end designer has access to and can reference and use EWD Session Variables and

Arrays in his/her pages. The designer does not need to know where they came from originally: he/she simply needs to know that they must exist in the EWD Session and knows their name and

structure (eg a simple name/value pair or a multi-dimensional array with a particular structure).

In EWD Mobile applications, the designer has no direct role in creating EWD Session data.

The task of creating and maintaining the data in the EWD Session is the sole responsibility of the

back-end programmer. Indeed the programmer’s role can be thought of as simply moving data

between the back-end database and the EWD Session:

• His/her Pre-Page Scripts will run queries against the database and transfer the results into EWD Session Variables and/or

Arrays (as summarised below);

• When a form has been submitted, EWD automatically copies the field values into corresponding EWD Session values,

using the field’s Id attribute value as the EWD Session variable name. It is then the programmer’s responsibility to validate

these values, and, if they are OK, save them back into the database and perhaps keep a copy in the EWD Session. This

“back-end” logic is performed in the pre-page script of the fragment specified as the nextpage in the form’s submit button.

These steps are summarised diagrammatically below:



The programmer can create all the scripts needed for an application without really having to have any

knowledge about the pages/fragments in which they will actually be used.

So, with EWD, the two participants, the designer and programmer, can work together, but separately.

The front-end design can be changed significantly without affecting the back-end database, and often

without even affecting the pre-page script functions. Conversely, the back-end database can be

altered without any impact on the front-end design: provided the new database schema can be

mapped in and out of the same EWD Session structures, the front-end will still operate identically because it won’t see any change in the EWD Session.

There’s another great benefit of this architecture. An EWD application can initially be fully developed

using mocked-up, hard-coded data in initial pre-page scripts. Once the front-end is agreed upon, the

pre-page script functions can be edited by a database programmer to maintain the original EWD

Session data structures but now using the real database and real business logic. The change from

design prototype to fully operational system requires no further work by the designer and retains

exactly the original design.

There’s a further benefit: it is quite possible to migrate an EWD application from one back-end

database technology to another. Provided the new pre-page scripts maintain the original EWD

Session data structures, the front-end design will neither know nor care that it’s being driven by an entirely different back-end database!



Accessing the Session from within an EWD Page

The designer accesses the EWD Session by using references to the data value(s) he/she wants to

display. There are three primary techniques:

• In an attribute of a Sencha Touch Custom tag. The name of the EWD Session variable should be prefixed with a #

character, eg

<st:panel title="#myTitle" />

• Anywhere else in the content of the page/fragment, including within Javascript, the <?= #sessionName ?> syntax is used,

eg:

Markup:

<div>The title <?= #myTitle ?> has come from the Session</div>

Javascript:

Ext.getCmp('topToolbar').setTitle('<?= #myTitle ?>');

• By specifying the sessionName attribute of a Sencha Touch Custom Tag. Usually in this context the sessionName refers

to an EWD Session Array through which the EWD Sencha Touch custom tag processor will iterate in order to display its

contents, eg:

<st:list sessionName="listOfAPIs" />

You’ve seen examples of all three techniques in the preceding examples of this tutorial. Now you

hopefully have a better idea what they mean!

EWD also provides more primitive custom tags for iterating through EWD Session Arrays, but in Sencha Touch applications these will be rarely used because most use of EWD Session Arrays is

embedded inside custom tags that process the array for you. Refer to the EWD API Guide (http://

gradvs1.mgateway.com/download/APIGuide3.0.618.pdf) for more details if you are interested.



http://gradvs1.mgateway.com/download/APIGuide3.0.618.pdf




Creating and Manipulating EWD Session Data

The programmer accesses the EWD Session through a range of APIs that are provided by EWD.

Although the EWD Session is physically implemented using Global storage in GT.M and Caché, the

programmer should never access the Global directly. This is because M/Gateway reserves the right

to change the Global structures in future releases of EWD if it becomes necessary. The APIs will

always retain their correct behaviour irrespective of such internal changes, whereas direct access to

the EWD Session Global by programmers almost certainly won’t!

Although EWD provides quite a large range of APIs for Session management, in practice there are

only a small number of APIs that the programmer will typically need to use.

All EWD Session APIs include as their last parameter the user’s session Id, denoted by the variable

sessid. The most common APIs are as follows:

• Creating a simple name/value pair

do setSessionValue^%zewdAPI(sessionName,value,sessid)

This creates a name/value pair named according to the sessionName parameter with a value provided by the value parameter.

• Getting the value of a simple name/value pair Session variable

set value=$$getSessionValue^%zewdAPI(sessionName,sessid)

This returns the value of a name/value pair named according to the sessionName parameter.

• Deleting a simple name/value pair Session variable

do deleteFromSession^%zewdAPI(sessionName,sessid)

This deletes a name/value pair named according to the sessionName parameter.



• Creating a Session array

First create a local array of any structure you like, eg

Then merge this to a corresponding EWD Session array using:

Note that array is called by reference, indicated by the period (.) that prefixes it

Because this API uses a non-destructive merge, it is usually good practice to first clear down

anything that might exist in the EWD Session array, ie:

• Getting back a Session array to access/manipulate its contents

First do the reverse of the previous example, ie recover the Session array as a local array using

(make sure the local array is initially cleared down):

Note that array is called by reference, indicated by the period (.) that prefixes it

If we applied this to the Session Array created in previous example above, the local array

would contain the following:



set array("a","b")=123 set array("a","b","c")="foo" set array("a","c")="xyz" set array("d","a")=999 set array("d","b")="bar"

do mergeArrayToSession^%zewdAPI(.array,sessionName,sessid)

do deleteFromSession^%zewdAPI(sessionName,sessid) do mergeArrayToSession^%zewdAPI(.array,sessionName,sessid)

do mergeArrayFromSession^%zewdAPI(.array,sessionName,sessid)

array("a","b")=123 array("a","b","c")="foo" array("a","c")="xyz" array("d","a")=999 array("d","b")="bar"

If you make any changes to the local array, use the mergeArrayToSession() API if you need to

save the changes back into the EWD Session.

• Deleting an EWD Session array

This deletes the entire contents of an EWD Session array named according to the

sessionName parameter

Processing Submitted Forms

When you submit a form, the value of each form field’s id attribute is used as the corresponding EWD

Session variable name.

So let’s look again at the pre-page script code we used for validating our example username/

password form:

n name,password ; s name=$$getSessionValue^%zewdAPI("username",sessid) s password=$$getSessionValue^%zewdAPI("password",sessid) i name'="rob" QUIT "Invalid name" i password'=1234 QUIT "Invalid password"

Here is the corresponding form:

<st:form id="loginForm" submitOnAction="false"> <st:fieldset title="Please log in"> <st:field type="text" id="username" label="Name" labelWidth="33%" /> <st:field type="password" id="password" label="Password" label-Width="33%" /> <st:field type="submit" text="Login" style="drastic_round" nextpage="ta-bPanel" cardpanel="mainCardPanel" /> </st:fieldset> </st:form>

So the value of the username field ended up in an EWD Session variable named “username”, as

highlighted in red. The value of the password field ended up in an EWD Session variable named “password”, as indicated in green.

In the pre-page script, we first get hold of the EWD Session variables using EWD’s getSessionValue()

API and then validate the values as required.

All subsequent fragments and their associated pre-page scripts have access to the username and

password values because they have been automatically saved in the user’s EWD Session storage.

Hence within the tabPanel.ewd page we were able to use the username EWD Session value to

modify the toolbar title:



do deleteFromSession^%zewdAPI(sessionName,sessid)


The Request versus the EWD Session

In addition to forms, it is possible to push values back to the back-end using arbitrary name/value pairs that you can add to requests for a fragment. For security reasons, these name/value pairs are

not automatically copied to the EWD Session. Instead they are transferred to ephemeral storage

known as the Request.

The Request is cleared down on every HTTP request, so if you need to process or access the

incoming values of any name/value pairs, you must do so immediately in the pre-page script of the

associated fragment. If you need any of the Request name/value pairs to persist longer, you must

transfer them to the EWD Session using the appropriate API as listed in the previous sub-section.

You use the EWD Javascript API EWD.ajax.getPage() to fetch a fragment asynchronously. To add

name/value pairs to this request, use the nvp property, eg:

var nvp = "questionText=" + text + "&insertBefore=" + insertBefore ; EWD.ajax.getPage({page:'addQuestion',nvp:nvp});

These values can be picked up in the pre-page script of the fragment that was specified in the page

property, ie addQuestion.ewd. For example:

getQuestionParams(sessid) n questionText,insertBefore s questionText=$$getRequestValue^%zewdAPI("questionText",sessid) s insertBefore=$$getRequestValue^%zewdAPI("insertBefore",sessid) ; ...etc



Lesson 14

The Container Page Revisited

In this lesson, we’re going to re-visit the EWD Mobile Container page and look at some more useful

features that it supports.

Controlling the EWD Session Timeout

The first thing we’ll look at is how to control the EWD Session timeout period and also how to control

what happens to your application when that timeout occurs.

When you use EWD Mobile, you get the benefit of a cool new built-in feature that was mentioned in

passing earlier in this Tutorial but which we’ll now examine in detail.

Specifically, EWD adds a Javascript countdown mechanism to the Sencha Touch Javascript code

that is sent to the browser in the container page. This mechanism is pre-set to the timeout duration of the EWD Session and counts down second by second. The countdown is reset whenever a

request is made to the Caché/GT.M back-end, for example to fetch a new fragment. The browser

countdown is actually set to reach zero about 20 seconds before the back-end times out. The

reason is to avoid the user seeing any errors reported by the EWD back-end which is what happens if

a user attempts to request a fragment after the EWD Session has timed out.

If the browser countdown reaches zero, it will do one of two things:

• by default it will reload the container page. This will cause a new EWD Session to be started and

the old one will time out soon after and will be automatically garbage-collected some time later.

• the developer can over-ride this default action by specifying a fragment that is to be loaded when the countdown reaches zero. What happens is now entirely in your control. By requesting your

timeout fragment, EWD will have, in fact, reset the session countdown clock at both the front and

back-ends, so you could allow the user to continue, or instead you could opt to do some tidying-up

work and then reload the container page, thereby starting a new session.



If you’ve tried leaving one of your demo tutorial apps running untouched for more than 20 minutes,

you’ll have seen the former action take place. Let’s make a quick change so that you can see that effect rather sooner than 20 minutes.

Edit the <ewd:config> tag of your index.ewd page as follows:

<ewd:config isFirstPage="true" cachePage="false" pageTimeout="120">

The pageTimeout attribute in the <ewd:config> tag sets the default EWD Session Timeout period in

seconds. What we’ve done is to tell EWD to terminate the session after 2 minutes of inactivity. Note

that this inactivity will be back-end inactivity – ie requests to access new fragments (even if those

fragments are nothing more that pre-page scripts). You need to be careful of this: the user could be

very active in the browser, doing all manner of local things, but if they never hit the back-end, the

EWD session will time out. Usually this won’t be a problem because, at the very least, you’ll probably

be fetching new data or content from the back-end as the user moves around the UI.

Try compiling your new version of index.ewd with the new pageTimeout parameter, restart the

application in the browser and leave it alone for 2 minutes. What you should see happen is that it reloads itself: this should be obvious because you’ll see the startup screen for a short time.

Clearly a two minute session timeout is somewhat impractical, so either remove the pageTimeout

attribute again (which resets it back to 20 minutes) or change it to a more sensible value.

There are times when it’s useful to dynamically modify the session timeout. This can be done in a

number of ways, but the easiest is to simply change the EWD Session value that retains the timeout

period: the EWD Session name for this is ewd_sessid_timeout. So in a fragment’s pre-page script

you could change this value using the command:

do setSessionValue^%zewdAPI("ewd_sessid_timeout",300,sessid)

If you do this at the back-end, then you MUST also inform the browser countdown clock of this new

timeout to ensure that it remains in sync. To do this, add the following to the Javascript that you send

back to the browser from the fragment that contains the pre-page script that changed the session

timeout:

EWD.sencha.sessionTimeout = 300;

For example if the pre-page script getAPIDetails^stdemo in the following fragment resets the

ewd_sessid_timeout Session value to 300 seconds, you should add the above code into an <st:js>

tag as follows (in this example we were already using at <st:js> tag):




<st:js at="end"> Ext.getCmp("topToolbar").setTitle('Welcome <?= #username ?>');

EWD.sencha.sessionTimeout = 300;

</st:js>



</st:tabPanel>

Remember: it is important to keep the browser’s count-down clock in sync with the back-end EWD Session if you modify the EWD Session timeout value!

Try some experiments of your own and see how you can control when and how the EWD

Session times out and how the browser times out accordingly.

Controlling the Browser’s Session Timeout Action

So far you’ll have been seeing the default timeout action by the browser, whereby EWD

makes it reload the container page when the countdown clock reaches zero. Now let’s see

how you can take control.

Edit the <st:container> tag of your index.ewd page as follows:

<st:container rootPath="/sencha-1.0/" title="EWD Demo" timeoutPage="finished">

This tells EWD that when the local countdown clock hits zero, it should send a request for a fragment

named finished.ewd.

Now create this new fragment, finished.ewd, and save it in your stdemo application directory (eg

c:\ewdapps\stdemo\finished.ewd). It should contain the following:



<ewd:config isFirstPage="false" pageType="ajax">

<script language="javascript">

Ext.Msg.alert('Attention!', 'Your EWD Session has now expired', Ext.emptyFn); setTimeout("window.location.reload();",4000);

</script>

Save this page, recompile the stdemo application and re-start it, and then leave it until the EWD

Session expires (to speed thing up a bit, you could reset the session timeout to 2 minutes again). You

should see the alert appearing telling you that the EWD Session has now expired, and 4 seconds later

it will reload the container page.

Your finished.ewd page is a standard EWD page and can have a pre-page script if required and any

content you want. Because the browser countdown clock reaches zero some seconds before the

back-end EWD Session times out, the finished.ewd fragment should have complete access to the

user’s EWD Session contents.

If you wanted, you could just do nothing – the very act of fetching your finished.ewd fragment will

have reset the session countdown counters at both the front-end and back-end. However, if you

decide that the user’s session really should be shut down, instead of reloading the container page

(which simply starts a brand new user session), you might want to redirect to a fixed or static HTML

page. Here’s an example:



<ewd:config isFirstPage="false" pageType="ajax">

<script language="javascript">

Ext.Msg.alert('Attention!', 'Your EWD Session has now expired', Ext.emptyFn); setTimeout("window.location = 'http://www.mgateway.com/ewd.html';",4000);

</script>

This timeout/redirect mechanism is very flexible and should provide you with all the control you need

when a user’s session times out.

Fetching data from GT.M or Caché as JSON

A common approach to Ajax applications these days is to describe all the UI logic in one page (or at

least a small number of pages), and only make round trips to the back-end to retrieve data as JSON

strings. This approach is fully supported by EWD. You’ve already seen how the <st:content> tag in

your index.ewd (ie the container) page allows you to define as much of the UI content as you require

in one page.

Writing EWD fragments that return JSON data is almost trivially simple. The first step is to create the

data you want to return in the form of a local array, eg:

s mydata(1,"firstname")="Rob"s mydata(1,"lastname")="Tweed"s mydata(2,"firstname")="Chris"s mydata(2,"lastname")="Munt"

Now save this array into an EWD Session Array in the usual way, eg:

do mergeArrayToSession^%zewdAPI(.myData,"names",sessid)

Now all you need to do in your page is to add the following tag as the fragment’s content:

<st:json sessionName="names" return="EWD.sencha.myJson" at="start" />

This tag will instruct EWD to convert the Session Array named “names” into a JSON string and to

stream it out as it is being converted. This streaming behaviour is important because it avoids any

maxstring errors that could otherwise occur if your array is converted into a very long JSON string.

In the example above, the JSON string is mapped to a Javascript object named

EWD.sencha.myJSON. In other words, for the example above, what will be received by the browser

will be:

EWD.sencha.myJson = [ {firstname:’Rob’,lastname:’Tweed’}, {firstname:’Chris’,lastname:’Munt’}];



http://www.mgateway.com/ewd.html'

http://www.mgateway.com/ewd.html'

The at attribute allows you to position the code above to occur before or after any generated Sencha

Touch code in your fragment, or in relation to other Javascript that you specify in the fragment. For example:

<ewd:config isFirstPage="false" pageType="ajax" prePageScript="getNames^stDemo">

<st:js at="end"> alert(JSON.stringify(EWD.sencha.myJson));</st:js>

<st:json sessionName="listOfAPIs" return="EWD.sencha.myJson" at="start" />

In the example above, an EWD Session Array named listOfAPIs is created in the pre-page script getNames^stDemo, sent to the browser as an object named EWD.sencha.myJson, and then its

contents are displayed in an alert immediately afterwards. See how the at attributes in the <st:js> and

<st:json> tags are used to control the order in which these two commands are executed.



Lesson 15

Using EWD Mobile’s Form Field Types & Widgets

In this lesson we shall be looking in more detail at the full range of form fields that are available to you

in EWD Mobile.

Text Fields

We’ve already seen the basic use of text fields in Lesson 12. We’ll now look at some cool additional

features of EWD Mobile’s text fields that you can use to make your forms look great and behave in a

sophisticated way.

We’re going to create a new form and add it to the stdemo application. Specifically, we’ll add it to one of the tabs that appear when you log in to the application, which means we’ll need to edit

tabPabel.ewd. Here’s what it currently should look like:



<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:tabPanel>

We’re going to change that third tab (currently labelled Example 3) and replace it with a form. You’ve

already seen how to handle the simple text and password form fields in a login form, but this new

form is going to demonstrate all the other form fields and widgets that are available to you in EWD

Mobile.

Edit tabPanel.ewd as follows:





<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="formPanel" layout="card" title="Form"> <st:form id="demoForm" submitOnAction="false" scroll="vertical"> <st:fieldset title="Form Fields Demo"> <st:field type="text" id="xname" label="Name" labelWidth="25%" required="true" ↵ placeHolder="Your name" useClearIcon="true" /> </st:fieldset> </st:form> </st:panel>

</st:tabPanel>

What we’ve added is a new Form Panel and FieldSet, and we’ve placed a text field inside the form.

We’ve seen a text field before, of course, but here we’re illustrating a number of the additional and

useful features you can specify (Note that the <st:field> tag should be typed as a single line and not

split over two or more lines):

• required = “true”: this doesn’t affect the functionality as such, but simply adds an asterisk to the

label to indicate that this is a required field. It will be up to you in your pre-page script to ensure that

a value is, indeed, added;

• placeholder = “Your name”: If the field value is empty, then this text will appear in a light grey font

to indicate to the user what type of value is expected

• useClearIcon = “true”: if set to true, and if the value of the field is not empty, this attribute will add

an icon to the right-hand side of the field which, when clicked, will clear the field.

Save your edited version of tabPanel.ewd, recompile the application and run it. When you log in and

click the new Form tab, you should see the following:



You can see the placeholder text in the field and the asterisk beside Name that denotes this is a required field. Type some characters into the field and the ClearIcon should automatically appear at

the right side of the field:

Now let’s look at how we can pre-populate this field from the Caché or GT.M database. If you’ve ever

used standard EWD, you’ll know how simply this is done. What you do is create an EWD Session

variable whose name is the same as that of the text field’s Id. You do this in the pre-page script of the

fragment containing the form. In this case, the field’s id is “xname”:



<st:field type="text" id="xname" label="Name" labelWidth="25%" required="true" ↵ placeHolder="Your name" useClearIcon="true" />

(note: the Id should be unique across all forms in your application - ie don’t use an Id that you’ve already used in another form, even if it is in a different fragment):

The pre-page script for the tabPanel.ewd page is getAPIList^stdemo:


So now let’s edit this function (eg using Studio), and add the following lines at the end:

getAPIList(sessid) ; n list,name,no,password ; s name=$$getRequestValue^%zewdAPI("name",sessid) s password=$$getRequestValue^%zewdAPI("password",sessid) i name'="rob" QUIT "Invalid name" i password'=1234 QUIT "Invalid password" d setSessionValue^%zewdAPI("username",name,sessid) ; 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 deleteFromSession^%zewdAPI("list",sessid) d mergeArrayToSession^%zewdAPI(.list,"list",sessid) d saveListToSession^%zewdSTAPI(.list,"listOfAPIs",sessid) ; ; Set demo form fields d setSessionValue^%zewdAPI("xname","Rob Tweed",sessid) ; QUIT ""

That’s all that’s required! Try re-running the application – you don’t need to recompile the EWD pages.

Note: if you’re using GT.M you’ll need to ensure that the new version of the stdemo routine has been recompiled and

relinked. Use the Linux shell command:

mumps *.m

and then, from the GT.M shell:

do relink^%zewdGTM

Now, when you click the Form tab, you should see the pre-populated field:



Submitting forms and viewing the EWD Session

What happens when the form is submitted? We’ve already seen how that works in the login form in Lesson 12, but let’s amend this new form and add a submit button. In order to see what’s happening, we’re going to make the submit button’s nextPage slide in a fragment that uses a cool EWD Mobile widget that will automatically display the contents of the EWD Session.

First edit the form in tabPanel.ewd (for clarity only the form is shown below):

<st:panel id="formPanel" layout="card" title="Form"> <st:form id="demoForm" submitOnAction="false" scroll="vertical"> <st:fieldset title="Form Fields Demo"> <st:field type="text" id="xname" label="Name" labelWidth="25%" required="true" ↵ placeHolder="Your name" useClearIcon="true" />

<st:field type="submit" text="Submit" style="drastic_round" nextpage="confirm" ↵ cardpanel="formPanel" /> </st:fieldset> </st:form></st:panel>

Also edit the index.ewd page to add an automated back button for the Card Panel named formPanel

(ie matching the panel id shown in red above). Again for clarity only the toolbar section of index.ewd is shown below:

<st:toolbar id="topToolbar" dock="top" title="EWD Demo"> <st:toolbarButton type="autoback" cardpanel="example2" id="listBackBtn" text="Back" hidden="true" />

<st:toolbarButton type="autoback" cardpanel="formPanel" id="formBackBtn" ↵ text="Back" hidden="true" /> <st:spacer /> <st:toolbarButton id="aboutBtn" text="About" handler="EWD.sencha.onAboutBtnTapped" /></st:toolbar>

Next, create the new confirm.ewd page that will slide into view when the form is submitted:



<ewd:config isFirstPage="false" pageType="ajax" ↵ prePageScript="validateFormData^stdemo">

<st:sessionList />

And finally, add its pre-page script (validateFormData) to the stdemo routine:

validateFormData(sessid) ; n name ; s name=$$getSessionValue^%zewdAPI("xname",sessid) i name="" QUIT "You must enter a name!" ; QUIT "" ;

Save these files and routine, recompile the application (and, if using GT.M, recompile and relink the

stdemo.m routine file), and re-start the application. Log in, navigate to the Form tab, change the

name field in the form and click the Submit button, for example:

What you’re seeing is a listing of the EWD Session, using a Sencha Touch extension widget known as a TouchGrid. You’ll see the the formatting isn’t really appropriate for the iPhone in portrait mode: if

you’re testing using an iPad or desktop browser it should look OK. On the iPhone, turn it to

landscape mode and it should be clearer. Click the column heading for Session Name twice and the

ordering of the rows will reverse, bringing the value of xname into view. It should show the value you

entered into the form field, eg:



Something you’ll have probably realized is that without having to do anything, EWD has automatically

moved the submitted value for the xname field from the Request to the EWD Session. It knew to do

this because it found and registered the name during compilation of the form, so it decided it was

safe for this Request value to be automatically persisted in the EWD Session.

This automated mechanism saves a lot of work by the developer, but remember that it is still vitally

important to validate the submitted value. We’re doing a simple validation test in this example:

validateFormData(sessid) ; n name ; s name=$$getSessionValue^%zewdAPI("xname",sessid) i name="" QUIT "You must enter a name!" ; QUIT "" ;

This is simply checking to see if no value at all was submitted. Test it out: click the Back button to

return to the form and then click the ClearIcon to the right of the Name field to clear it and then try clicking the Submit button. You should now see the validation error alert:



So now that we have this form in place and the TouchGrid conveniently displaying the contents of the

EWD Session after submitting the form, we’re all set to try out all the other Form types and widgets that are available in EWD Mobile.

HTML5 Number field

HTML5 has introduced a number of special new field types that have been implemented to some

degree by browser manufacturers. Several of them have been implemented in Sencha Touch

irrespective of their current support, so EWD Mobile exposes them also. As you’ll see, Mobile Safari

only partially supports these so far, but they are worth knowing about and even using already.

The first we’ll look at is the type=”number” field. This is designed to allow you to automatically limit

input to just numbers and restrict the range. Mobile Safari actually treats the field as a standard text

field but does do one trick: when you focus on the field, the virtual keyboard will bring up the numeric keys automatically, which is pretty useful. However you’ll be able to enter text characters if you want

(Note that by comparison, desktop Chrome automatically prevents you typing anything other than

numbers).

Specifying and interfacing a number field is pretty much identical to a text field. Let’s add one to our

form in tabPanel.ewd:

<st:panel id="formPanel" layout="card" title="Form"> <st:form id="demoForm" submitOnAction="false" scroll="vertical"> <st:fieldset title="Form Fields Demo"> <st:field type="text" id="xname" label="Name" labelWidth="25%" required="true" ↵ placeHolder="Your name" useClearIcon="true" />

<st:field type="number" id="houseNo" label="No" labelWidth="30%" ↵ required="true" placeHolder="Your House No" useClearIcon="true" /> <st:field type="submit" text="Submit" style="drastic_round" nextpage="confirm" ↵ cardpanel="formPanel" /> </st:fieldset> </st:form></st:panel>

We’ll pre-populate it with a value of 35 by using the following code in getAPIList^stdemo. Remember

that the thing that maps the field name to the EWD Session is its id:

getAPIList(sessid) ; n list,name,no,password ; ;...etc as before.... ; ; Set demo form fields d setSessionValue^%zewdAPI("xname","Rob Tweed",sessid) d setSessionValue^%zewdAPI("houseNo",35,sessid) ; QUIT ""

And we can validate it in saveFormData^stdemo. Even though we’ve specified a number field, we

must validate for numeric input because Mobile Safari hasn’t fully implemented the number type yet

and can allow text input:



saveFormData(sessid) ; n name,no ; s name=$$getSessionValue^%zewdAPI("xname",sessid) i name="" QUIT "You must enter a name!" s no=$$getSessionValue^%zewdAPI("houseNo",sessid) i no="" QUIT "You must enter a number!" i no'?1N.N QUIT "Number must be an integer between 1 and 1000" i no<1!(no>1000) QUIT "Number must be an integer between 1 and 1000" ; QUIT "" ;

Save these changes, recompile everything and re-run the application, login and tap the Form tab.

Tapping on the number field will bring up the numeric keypad in the iPhone:

Notice that currently there is a UI bug in the Sencha Touch Number field when viewed in an iPhone:

there is a grey bar to the right of the field that shouldn’t be there. Hopefully this will be fixed in a later

version of Sencha Touch.

You’ll also have noticed that the two form field tags are quite long with many attributes, some of which

appear in both tags. There’s a useful trick you can use to shorten the tags and reduce the risk of

duplication errors: simply take all the attributes that appear in every form field with the same name

and value and move them into a tag named <st:defaults> that is placed inside the <st:fieldset> tag.

For example, if all the fields are to have the same labelWidth, are all required and need a ClearIcon

displayed, you can do the following. Notice how much simpler and more succinct the individual

<st:field> tags become as a result:



<st:panel id="formPanel" layout="card" title="Form"> <st:form id="demoForm" submitOnAction="false" scroll="vertical"> <st:fieldset title="Form Fields Demo"> <st:defaults labelWidth="30%" useClearIcon="true" required="true" /> <st:field type="text" id="xname" label="Name" placeHolder="Your name" /> <st:field type="number" id="houseNo" label="No" placeHolder="Your House No" /> <st:field type="submit" text="Submit" style="drastic_round" nextpage="confirm" ↵ cardpanel="formPanel" /> </st:fieldset> </st:form></st:panel>

Now try modifying the number field in the form and click the Submit button. If you scroll down

through the Session List touchgrid, you should find that the Session Variable named houseNo now

contains your modified value.

Disabled Fields

Sometimes you’ll want fields that are displayed in a form but are disabled so that they cannot be

altered. This is simply done by adding the disabled attribute. For example, add the following field

inside the <st:fieldset> tag in tabPanel.ewd (put it after the Number field):

<st:field type="text" id="info" label="Disabled" disabled="true" ↵ required="false" useClearIcon="false" />

Notice how we can override the defaults for required and useClearIcon since they don’t make sense

for a disabled field.

Pre-populate the field in tabPanel.ewd’s pre-page script (ie in getAPIList^stdemo): add the following

line after the one that set a default for the Number field:

d setSessionValue^%zewdAPI("info","Info only",sessid)

Since this field cannot be altered in the form, there’s no need to add any validation code to

confirm.ewd’s pre-page script.

Recompile everything as before and re-run the application and you’ll now see that the disabled field

has been added to your form. Notice how it is automatically greyed-out and how you can’t get focus

on the field by tapping it:



HTML5 Email FieldAnother partially-supported HTML5 form field type is the email field. When used in an iPhone, you’ll

find that the virtual keyboard adapts itself by adding the @ character. Otherwise, like the Number

field, it doesn’t constrain the values you type and you’ll still need to add appropriate validation logic to

the pre-page script of the nextPage.

You can add an example to your demo form:

<st:field type="email" id="myEmail" label="Email" placeHolder="[email protected]" />

EWD Mobile treats it, for the purposes of interfacing, as a text field, so you can pre-populate it using:

d setSessionValue^%zewdAPI("myEmail","[email protected]",sessid)

Then add any validation logic to confirm.ewd’s pre-page script, eg:

s email=$$getSessionValue^%zewdAPI("myEmail",sessid) i email="" QUIT "You must enter an email address" i email'["@" QUIT "Invalid email address"

The field looks like the following when you tap on it: note the @ key in the virtual keyboard has been

added automatically:



mailto:[email protected]




HTML5 URL FieldAnother partially-supported HTML5 form field type is the url field. When used in an iPhone, you’ll find

that the virtual keyboard adapts itself by adding the .com option. Otherwise, like the Number field, it

doesn’t constrain the values you type and you’ll still need to add appropriate validation logic to the

pre-page script of the nextPage.

You can add an example to your demo form:

<st:field type="url" id="myUrl" label="URL" placeHolder="http://www.example.com" />

EWD Mobile treats it, for the purposes of interfacing, as a text field, so you can pre-populate it using:

d setSessionValue^%zewdAPI("myURL","http://mgateway.com",sessid)

Then add any validation logic to confirm.ewd’s pre-page script, eg:

s url=$$getSessionValue^%zewdAPI("myUrl",sessid) i url="" QUIT "You must enter a URL" i url'["." QUIT "Invalid URL"

The field looks like the following when you tap on it: note the .com and / keys in the virtual keyboard

has been added automatically:



http://www.example.com

http://www.example.com



Checkboxes

Those of you who are familiar with standard HTML checkboxes will find the EWD Mobile

implementation to be somewhat different. Rather than dealing with groups of checkboxes that share

a common name, Sencha Touch’s checkboxes are individual devices that relate to a single name per

checkbox. The Checkbox is used for a field where only one of two values is possible, typically values such as: on/off, true/false, 1/0 etc.

With the EWD Mobile checkbox field, you therefore define the value that will be represented by the

field being checked, for example, add the following field to your demo form:

<st:field type="checkbox" id="cool" label="Cool" value="true" />

Unlike standard HTML checkboxes, EWD Mobile treats the Sencha Touch checkbox, for the

purposes of interfacing, as a text field. You can pre-check the checkbox by setting the corresponding

value of the eponymous Session variable to the value specified in the tag, in this case “true”:

d setSessionValue^%zewdAPI("cool","true",sessid)

Setting the Session variable to any other value will leave it unchecked.

When the form is submitted, the checkbox field value is automatically saved as if it was a text field,

and will have one of two possible values:

• if checked, the value defined by the field’s value attribute (“true” in our example)

• if not checked, the string literal value “null”



Even though the form will only submit these two possible values, it is nevertheless good practice to

explicitly validate the field, to ensure that the form has not been spoofed or hijacked by someone who has bypassed the form and is attempting to force an invalid value into the form using a manually-

created HTTP request. So we’ll add the following code to confirm.ewd’s pre-page script:

s cool=$$getSessionValue^%zewdAPI("cool",sessid) i cool'="true",cool'="null" QUIT "Invalid Checkbox value"

Save and compile all these changes and run the application again. The checkbox will now appear in

the form:

Spinner Field

Spinner fields are a great idea if you need the user to enter a numeric value from a small possible

range of values. The user can simply touch a + or – button to increment or decrement the value by

one on each touch. You can set a maximum and minimum value for the spinner and the + and –

buttons will not change the value outside the specified range.

The user can still modify the value manually by typing into the field, so you’ll still need to apply validation to properly constrain the value entered.

So try adding a spinner field to your demo form in tabPanel.ewd:

<st:field type="spinner" id="counter" label="Spinner" minValue="5" maxValue="20" />

In this example we’re constraining the possible range between 5 and 20.



EWD treats a spinner field, for the purposes of interfacing, as a text field, so you can pre-populate it

using, eg:

d setSessionValue^%zewdAPI("counter",8,sessid)

You should also add appropriate validation logic to confirm.ewd’s pre-page script, eg:

s no=$$getSessionValue^%zewdAPI("counter",sessid) i no="" QUIT "You must enter a number!" i no'?1N.N QUIT "Number must be an integer between 5 and 20" i no<5!(no>20) QUIT "Number must be an integer between 5 and 20"

Save and compile these changes and when you re-run the application, the spinner field should

appear as shown below:

Select Field

The EWD Mobile Select field provides a spin-wheel widget from which the user can choose the

required value. As far as EWD is concerned, it behaves and is interfaced identically to a standard

HTML <select> field.

Add a Select field to your form by adding the following tag:

<st:field type="select" id="rank" label="Rank" useClearIcon="false"/>

It’s a good idea to avoid using a ClearIcon for this widget.



Interfacing a Select field to EWD is a little more complex than for other field types. The core name/

value pair is treated as a text value, but you must also specify the list of possible options. Those of you familiar with standard EWD coding will recognize the technique for pre-populating it:

d clearList^%zewdAPI("rank",sessid) d appendToList^%zewdAPI("rank","Guru","guru",sessid) d appendToList^%zewdAPI("rank","Master","master",sessid) d appendToList^%zewdAPI("rank","Student","student",sessid) d appendToList^%zewdAPI("rank","Instructor","teacher",sessid) d appendToList^%zewdAPI("rank","Assistant","aid",sessid) d appendToList^%zewdAPI("rank","Novice","novice",sessid) ; d setSessionValue^%zewdAPI("rank","student",sessid)

The appendToList() API is used to build the list of options that will appear in the spinwheel. The order in which the options appear is dictated by the order in which you append values, so in the example

above Guru will appear at the top of the list and Novice at the bottom. Note: it’s always a good idea

to first use clearList() to ensure that the list is cleared down before you add any new options to it.

The final setSessionValue() will pre-select the Student option.

As before, even with a device that only allows the user to pre-select a value from a list, it is

nevertheless a good idea to add validation code to prevent attempted malicious attacks. You can do

this very simply for Select items by using the getTextFromList() API: if this returns an empty string, the

submitted value must be erroneous, eg add the following to the pre-page script for confirm.ewd:

s value=$$getSessionValue^%zewdAPI("rank",sessid) s text=$$getTextFromList^%zewdAPI("rank",value,sessid) i text="" QUIT "Invalid rank value"

Save the changes and recompile everything and the Select field should now appear in your form, pre-

selected as Student:



Tapping on the field brings up the spinwheel. Note that Student is pre-selected on the wheel:

Click the Done button when you’ve selected a new value and the wheel will slide away from view and

the new value will be showing in the Select field.

Toggle Field

The EWD Mobile toggle field is an alternative to the Checkbox for allowing the user to select one of

two possible options for a value: in effect on/off, true/false or 1/0. Instead of turning a tick on or off,

the user slides a toggle switch to be either on or off.

Try adding a toggle field to the form in tabPanel.ewd as follows:

<st:field type="toggle" id="qualified" label="Qualified" />

EWD treats a toggle field, for the purposes of interfacing, as a text field with two possible values: 0

(zero) or 1, representing off and on respectively.

So to show the toggle switched on when the form is loaded:

d setSessionValue^%zewdAPI("qualified",1,sessid)

When submitted, the toggle field value will be saved to the EWD Session as a 1 (on) or 0 (off).

As before, to prevent malicious use of the form, you should also add appropriate validation logic to

confirm.ewd’s pre-page script, eg:



s no=$$getSessionValue^%zewdAPI("qualified",sessid) i no'=0,no'=1 QUIT "Invalid value for toggle!"

Save and compile these changes and when you re-run the application, the toggle field should appear

as shown below:

Radio Field

The EWD Mobile Radio Field behaves similarly to the standard HTML radio button field. It allows a set

of values to be listed in the form, and the user can select only one of the possible values by tapping a

tick against the value, causing the tick to be highlighted.

Add a group of radio fields to your form as follows. Note that each member of the group shares the

same name attribute value:

<st:field type="radio" name="colour" label="Red" value="red" required="false" /><st:field type="radio" name="colour" label="Blue" value="blue" required="false" /><st:field type="radio" name="colour" label="Green" value="green" required="false" /><st:field type="radio" name="colour" label="Yellow" value="yellow" required="false" />

EWD treats a group of radio fields, for the purposes of interfacing, as a text field with the possible

values defined in the individual fields: in the example above the possible values are red, blue, green or

yellow.

So to pre-check the blue option when the form is rendered:



d setSessionValue^%zewdAPI("colour","blue",sessid)

When submitted, the value of our example checked radio option will be saved into the EWD Session

variable named colour: ie the name attribute is used to map to the EWD Session name.

As before, to prevent malicious use of the form, you should also add appropriate validation logic to

confirm.ewd’s pre-page script, eg:

s value=$$getSessionValue^%zewdAPI("colour",sessid) i value'="red",value'="blue",value'="green",value'="yellow" QUIT "Invalid colour"

Save and compile these changes and when you re-run the application, the radio field group should

appear as shown below:

Date Field

The EWD Mobile Date field allows you to select the date using a set of spin-wheels. You can

constrain the year to a range that you specify. By default, Sencha Touch uses the USA date format,

but you can over-ride this for UK date formats, for example.

Add a date field to your form in tabPanel.ewd as follows:

<st:field type="date" id="dob" label="DOB" yearFrom="1910" yearTo="2011" />



Note the way we can control the range of years that will be allowed to be chosen via the spin-wheels

using the yearFrom and yearTo attributes.

The EWD interfacing is a little different from the other fields. To pre-populate a date when the form is

rendered, you specify the day, month and year properties of the EWD Session Object named dob (or

whatever the value of your date field’s id attribute). So in the pre-page script for tabPanel.ewd, just

add, for example:

d setSessionValue^%zewdAPI("dob.day",18,sessid) d setSessionValue^%zewdAPI("dob.month",8,sessid) d setSessionValue^%zewdAPI("dob.year",1964,sessid)

This should pre-populate the date field as 18th August 1964.

When the form is submitted, EWD will automatically save these three properties back into the EWD

Session using the new values from the date field. You’ll also get back an EWD Session value named

dob containing the full UTC-format date. So, for example, if you enter the date as December 15th

1970, the following EWD Session values will be saved (you’ll see them in the Session List TouchGrid

in confirm.ewd):

• dob.day: 15

• dob.month: 12

• dob.year: 1970

• dob: “Tue Dec 15 1970 00:00:00 GMT 0000 (GMT)”

As before, you should add validation to prevent malicious attacks via this field, so add something like

the following logic to the pre-page script for confirm.ewd:

s dd=$$getSessionValue^%zewdAPI("dob.day",sessid) s mm=$$getSessionValue^%zewdAPI("dob.month",sessid) s yy=$$getSessionValue^%zewdAPI("dob.year",sessid) ; i dd'?1N.N QUIT "Invalid date" i mm'?1N.N QUIT "Invalid date" i yy'?1N.N QUIT "Invalid date" i dd<1!(dd>31) QUIT "Invalid date" i mm=2,dd>29 QUIT "Invalid date" i ((mm=4)!(mm=6)!(mm=9)),dd>30 QUIT "Invalid date" i yy<1910!(yy>2011) QUIT "Year must be between 1910 and 2011"

Save and compile these changes and when you re-run the application, the date field should appear

as shown below:



If you tap within the date field, the date selection spinwheels will slide into view:

The date will be initially set to the one that we used to pre-populated the field. You’ll find that the year

limits on the year wheel are those we specified in the date field tag.

If you want to change the date format to UK format, you have to make two changes. The first is to

the index.ewd page: add the tag <st:locale dateFormat="d/m/Y" /> inside the <st:container> tag, for

example as shown below:



<ewd:config isFirstPage="true" cachePage="false">

<st:container rootPath="/sencha-1.1/" title="EWD Demo" timeoutPage="finished" debug="true"> <script src="/stdemo.js" /> <st:images> <st:image type="tabletStartupScreen" ↵ src="/sencha-1.1/examples/kitchensink/resources/img/tablet_startup.png" /> <st:image type="phoneStartupScreen" ↵ src="/sencha-1.1/examples/kitchensink/resources/img/phone_startup.png" /> <st:image type="icon" src="/sencha-1.1/examples/kitchensink/resources/img/icon.png" ↵ addGloss="true" /> </st:images>

<st:locale dateFormat="d/m/Y" />

<st:content> ....etc

Then, in your <st:field type=”date”> tags, add the attribute slotOrder="dmy", eg:

<st:field type="date" id="dob" label="DOB" yearFrom="1910" yearTo="2011" slotOrder="dmy" />

Now the field will appear in dd/mm/yyyy format and the spin-wheels are also in that order:

Slider Field

The Slider field is a cool alternative to a Number or Spinner field where you want the user to enter an

integer value between two limits. Its one limitation is that there is no directly visible indication of the actual value that the user has selected, but we’ll see an example of how that can be visualized.

First, add a slider field to your form:



<st:field type="slider" id="volume" label="Volume" minValue="0" maxValue="11" increment="1" />

The increment attribute, if not specified, defaults to 1. You can specify fractional values: for example if you specified an increment of 0.1, then the slider can return 1.1, 1.2, 1.3 etc as you slide it.

EWD treats a slider field, for the purposes of interfacing, as a text field, so you can pre-populate it using:

d setSessionValue^%zewdAPI("volume",4,sessid)

When the form is submitted, the value represented by the slider is saved into the correspondingly

named EWD Session variable.

Nevertheless, as discussed before, you should also add appropriate validation logic to confirm.ewd’s

pre-page script, eg:

s no=$$getSessionValue^%zewdAPI("volume",sessid) i no="" QUIT "You must enter a number for the volume!" i no'?1N.N QUIT "Volume must be an integer between 1 and 11" i no<1!(no>11) QUIT "Volume must be an integer between 1 and 11"

Note that you’d need to change the pattern match logic if you were using an increment setting that allowed fractional values.

Save and compile these changes and when you re-run the application, the slider field should appear

as shown below:



Try sliding it and clicking the Submit button. You’ll be able to inspect the submitted value in the

Session List TouchGrid: look for the name volume.

Let’s take a look at a way in which you can visualize the value as you move the slider. The key is to

add the onDrag attribute to the slider tag, eg:

<st:field type="slider" id="height" label="Height" minValue="0" ↵ maxValue="100" required="true" onDrag="EWD.sencha.onSliderDrag" />

Now we need to define that event handler method. First, add the following to the stdemo.js file:

EWD.sencha.onSliderDrag = function(slider,thumb,value) { var toolbar = Ext.getCmp("topToolbar"); toolbar.setTitle("slider: " + value); setTimeout('Ext.getCmp("topToolbar").setTitle("' + EWD.sencha.toolbarTitle + '");',1000);};

What this is going to do is replace the title text in the main toolbar with the current value of the slider

as you drag it. 1 second after you stop dragging the slider, the idea is that the original toolbar title will reappear. However, we’re doing that by initially saving the title in the Javascript property:

EWD.sencha.toolbarTitle. We can’t set that in stdemo.js because the toolbar title won’t exist at the

time when stdemo.js is loaded. Instead, add it to the <st:js> tag that we’ve already got in tabPanel.ewd:

<st:js at="end"> Ext.getCmp("topToolbar").setTitle('Welcome <?= #username ?>'); EWD.sencha.toolbarTitle = Ext.getCmp("topToolbar").titleEl.dom.innerText;</st:js>

Save and recompile everything and now try running the application. When you move the slider, you

should now see the current value in the toolbar title, eg:



Hidden Field

Hidden fields can be very useful at times for storing data within the form that won’t be displayed to the user (though any HTML DOM inspection tool will reveal the value!) but will be sent to the back-end

when the submit button is pressed.

Add one to your form as follows:

<st:field type="hidden" id="secret" />

EWD treats a hidden field, for the purposes of interfacing, as a text field, so you can pre-populate it

using, eg:

d setSessionValue^%zewdAPI("secret","sshhhh!",sessid)

When the form is submitted, the value of this field will be sent to the back-end and saved as a session

variable named secret.

Textarea Field

EWD Mobile exposes the Sencha Touch textarea field as a custom tag, but, to be honest, this is

currently not a particularly well-implemented widget and is pretty unwieldy to use, requiring a 2 finger

swipe gesture to scroll through lines of text. It may, of course, improve in later versions of Sencha

Touch. It’s included here for completeness. Provided you don’t have a lot of text, it’s usable. Try it

and see what you think.

Add a textarea field as follows:

<st:field type="textarea" id="bio" label="Bio" height="110" />

EWD handles this field differently to the way it handles a standard HTML <textarea> tag. In the

Sencha Touch version it treats the field as a single long text string value, with line feed characters (\n) as delimiters between the lines displayed in the textarea field in the browser.

So to pre-populate the field, we could do the following in the pre-page script of tabPanel.ewd:

s text="" f no=1:1:8 s text=text_"Line "_no_" of my bio\n" d setSessionValue^%zewdAPI("bio",text,sessid)

Note the use of the \n character string to denote a line-feed.

When the form is submitted, the value of the EWD Session variable named bio will be replaced with

the new contents of the textarea field. Once again, line-feed characters ($char(10)) will be embedded

within the string.



Save and recompile everything and now try running the application. The textarea field will appear as

follows:

Combo Field

The combo field is an EWD-specific Sencha Touch extension widget that is ideally suited for tablet

and desktop usage, but will nevertheless still work quite effectively in a phone.

The combo field allows you, the developer, to hook in a function of your choice that will display

potential matching values in a pop-up panel, based on the characters that have been already been

typed into the field. The list will change as characters are added or removed, and at any time the user

can tap an option from the list of matches in the pop-up panel instead of continuing typing.

This field is therefore ideally suited for entering values from large databases of options, for example patient names, drug names, etc.

The developer has complete control over the method that retrieves the matches, and can control the

maximum number of matches that will be displayed in the pop-up list.

Let’s add a combo field to your form. Simply add the following tag:

<st:field type="combo" id="api" label="Name" method="comboDemoMethod^stdemo" />

The dimensions of the pop-up panel default to:

• tablet: height: 200, width: 400

• phone: height: 60, width: 240



You can modify these if you wish, eg:

<st:field type="combo" id="api" label="Name" method="comboDemoMethod^stdemo" ↵ panelWidth="500" panelHeight="300" phonePanelWidth="200" ↵ phonePanelHeight="50" />

EWD treats a combo field, for the purposes of interfacing, as a text field, so you can pre-populate it

using:

d setSessionValue^%zewdAPI("api","ge",sessid)

The key aspect of a combo field, however, is the method that specifies what matching options will

appear in a pop-up panel as the user types into the field. Let’s add a method that will list the EWD

DOM APIs:

comboDemoMethod(prefix,options) ; n maxNo,no,stop,value ; s value=$o(^%zewd("documentation","DOM","method",prefix),-1) s maxNo=50 s no=0,stop=0 f s value=$o(^%zewd("documentation","DOM","method",value)) d q:stop . i value="" s stop=1 q . i prefix'="",$e(value,1,$l(prefix))'=prefix s stop=1 q . s no=no+1 . s options(no)=value . i no=maxNo s stop=1 QUIT ;

Combo methods have two inputs:

• prefix: the character string typed so far into the combo text field

• options: an array of matching options that your method creates and returns to EWD

In this example, we’re returning all the EWD DOM API method names (they are held in the global

^%zewd(“documentation”)) that start with the prefix string typed so far by the user. We’ve put an

upper limit of 50 names on this example, but you can try adjusting this. You can, of course, substitute

your own method that traverses one of your own globals or Caché Objects.

This method will be automatically invoked on every keystroke or every time the delete key is

depressed.

Save and compile all these changes and try running the application. If you tap inside the Combo field

and type the letter t, you should see the following (for clarity we’re showing what it looks like on the

iPad instead of the iPhone):



What has happened is that a pop-up panel has appeared above the Name field, listing all the EWD DOM APIs that start with the characters “get”. You can now continue typing, in which case the list will change to show the new list of matching APIs, or scroll through the list of matches and tap one of them. For example, scroll through the list until you find getLastChild and tap it. The keyboard and panel will disappear and getlastChild will now populate the Name field:



When you submit the form, the Name field is treated as a standard text field, and will appear in the

Session List TouchGrid against the name “api”.

Conclusion

That completes the full range of Form fields that are provided by Sencha Touch and exposed through

EWD. This also completes Part 2 of the Tutorial.

In Part 3 we’ll look at a few of the remaining widgets that will allow you to produce slick, rich and

compelling mobile web applications.



ewd mobile tutorial part 2 (build...

Documents