enterprise web developer using the extjs widgets

Enterprise Web Developer

Using the ExtJS Widgets

Version 4.0.684.1

Background

Enterprise Web Developer (EWD) now includes advanced functionality that allowsyou to make use of the powerful Javascript widget libraries from ExtJS(http://extjs.com). By incorporating these widgets into your applications, you'll be ableto quickly and easily create Rich Internet Applications. Unlike users of these widgetlibraries who are forced to hand-craft the required code, you'll be able to let EWD doall the hard work. With EWD you'll be creating in minutes what others will take daysor weeks to accomplish. Your web applications will never look the same again!

This document is a reference guide to using EWD's ExtJS custom tags.

Pre-requisites

This guide assumes that you installed EWD (build 684 or later) and have read theeXtc Web Developer Overview, the Installation Guide, Tutorial and Ajax documents.You should also have the main EWD API Guide at hand.

You'll also need to install the ExtJS Javascript library files. Full instructions areavailable at their web site:

• ExtJS: http://extjs.com

Please note the licensing requirements for ExtJS. It is your responsibility to comply with these.

Enterprise Web Developer : Using the ExtJS Widgets. Version 4.0.684.1: 14 April 2008. 2008, M/Gateway Developments Ltd. All Rights Reserved

1

EWD's ExtJS Custom Tags

EWD provides a set of custom tags that represent the various ExtJS widgets. TheExtJS custom tags have a prefix of ext: For example:

<ext:grid><ext:tree>

EWD's compiler will convert these into the corresponding Javascript and HTML tagsthat you would otherwise have to write by hand. This approach provides you with amuch simpler and intuitive way of using ExtJS widgets, some of which can be verycomplex and require a lot of advanced Javascript programming.

EWD also automatically handles all the many additional complexities that can occurwhen using ExtJS widgets within an Ajax application, where whole sections ofmarkup containing one set of widgets are replaced with new markup containing newsets of widgets. With EWD you can focus on what you're wanting to do with theExtJS widgets, not how they actually work.

The current version of EWD does not implement the full set of ExtJS widgets, but themain desktop, windowing and layout widgets are available. More widgets will beadded in future builds.

ExtJS widgets are highly configurable via what are known as config options. EWDallows you to apply these config options by mapping them to correspondingly namedattributes within each ExtJS custom tag. Usually EWD will automatically apply a setof sensible defaults for config options that you don't specify. Values for all configoptions can be either string literal values or session variables, for example:

<ext:gridColumn header="#col1Title" width="120" sortable="true" />

The header value will be determined by a session variable named colTitle, denoted by the #character, whilst the width and sortable values use fixed literal values.

This document will not list the various config options for each ExtJS custom tag. Ifyou wish to find out the config options that are available for each custom tag, then youshould refer to the ExtJS API documentation at http://extjs.com/deploy/dev/docs/ forthe ExtJS class created by the EWD custom tag (see Appendix I for mappings).

EWD Configuration

When you install the ExtJS libraries, you'll usually do so by creating a sub-directoryunder your web server's root path into which all the ExtJS resurce files are copied, eg:

C:\Program Files\Apache Group\Apache2\htdocs\ext-2.0.2

or

/var/www/html/ext-2.0.2


2

If so, the various ExtJS Javascript files will be referred to, within your web pages, viaa relative URL based on the sub-directory name you chose, eg:

/ext-2.0.2

EWD provides a simple shortcut for loading the ExtJS Javascript files into yourapplications' pages. After the initial <ewd:config> tag at the top of your EWD pages,simply add:

<ext:config path=”/ext2.0.2” />

Substitute the path as appropriate to your ExtJS installation.

If you are developing an EWD Ajax application, you'll need this ExtJS configurationtag in only your container page(s). It should not appear in your EWD page fragments.


3

ExtJS Layout Widgets: ViewPort

One of the standard layout features provided by ExtJS is the Viewport. This allowsthe browser page to be divided into 5 areas, known as north, south, east, west andcenter. The panels can be initially set to be collapsed and/or with moveable/draggableborders. The Viewport is a good way of making very efficient use of the space withinthe browser page.

The ViewPort creates the outer container within the browser, and Panels are then usedto define the working areas within it.

Let's create a simple example. First, create a new EWD application sub-directorynamed extjsDemo. Eg if your EWD Application Root Path is c:\ewdApps, create:

c:\ewdApps\extjsDemo

Copy the page definition below and save it in a file named viewportDemo1.ewd in the extjsDemo application directory.

Note: EWD does not currently allow tags to be split across more than one line. Theexample boxes in this document will show some lines wrapped across 2 or morelines. Make sure you reduce these to a single line per tag in your EWD sourcefiles.

You should then have a file:

c:\ewdApps\extjsDemo\viewportDemo1.ewd

<ewd:config isFirstPage="true" /><ext:config path="/ext-2.0.2" /><html> <head> <title>EWD/Ext-JS Viewport & Layout Demo</title> </head> <body> <ext:viewport layout="border"> <ext:panel region="north" autoHeight="true" border="false" margins="0 0 1 0"> <div id="myNorthRegion" style="text-align:center">This is the North Panel</div> </ext:panel> <ext:panel region="west" title="West Region" collapsed="true" collapsible="true" split="true"width="500" minWidth="200" /> <ext:panel region="east" title="East Region" collapsed="true" collapsible="true" split="true"width="450" minWidth="250" /> <ext:panel region="center" title="Center Region" /> <ext:panel region="south" title="South Region" collapsed="true" collapsible="true"split="true" height="250" minHeight="100" /> </ext:viewport> </body></html>

Compile this page to the technology of your choice, eg:

d compileAll^%zewdAPI(“extjsDemo”,,”php”)


4

The first time you compile this page you should compile the complete application toensure that EWD generates all the additional supporting pages. Thereafter you canjust recompile the page on its own using:

d compilePage^%zewdAPI(“extjsDemo”,”viewportDemo1”,,”php”)

If you've installed and configured everything properly, when you run this page in abrowser, you should see something like the following:

If you click on the arrowed tabs on the west, east and south panels, they should eachslide into view. You can then drag their borders around or collapse them again byclicking the arrowed tabs again.

Currently, of course, there's nothing in any of the panels, so let's rectify that!

Let's create a simple page fragment that we'll use as content for each of the panels.Copy and paste the following fragment definition into a file and save it in theextjsDemo directory as panelContent1.ewd.

<ewd:config isFirstPage="false" pageType="ajax" /><span style="background-color:#ffffff;">Hello world!</span>


5

Now add a src attribute referring to this fragment to the east, west, south and centerpanels:

<ewd:config isFirstPage="true" /><ext:config path="/ext-2.0.2" /><html> <head> <title>EWD/Ext-JS Viewport & Layout Demo</title> </head> <body> <ext:viewport layout="border"> <ext:panel region="north" autoHeight="true" border="false" margins="0 0 1 0"> <div id="myNorthRegion" style="text-align:center">This is the North Panel</div> </ext:panel> <ext:panel region="west" src="panelContent1.ewd" title="West Region" collapsed="true"collapsible="true" split="true" width="500" minWidth="200" /> <ext:panel region="east" src="panelContent1.ewd" title="East Region" collapsed="true"collapsible="true" split="true" width="450" minWidth="250" /> <ext:panel region="center" src="panelContent1.ewd" title="Center Region" /> <ext:panel region="south" src="panelContent1.ewd" title="South Region" collapsed="true"collapsible="true" split="true" height="250" minHeight="100" /> </ext:viewport> </body></html>

Recompile the entire application:


and reload viewportDemo1 in your browser. Each of the panels should now containthe text Hello world!

You're now ready to extend this into a fully-fledged Ajax application. First, simplycopy the panelContent1.ewd file to create separately named fragments, eg:

• panelContentEast.ewd• panelContentWest.ewd• panelContentCenter.ewd• panelContentSouth.ewd

Next add a unique id attribute to the <span> tag in each of these fragments, eg inpanelContentEast.ewd:

<ewd:config isFirstPage="false" pageType="ajax" /><span id="myEastPanel" style="background-color:#ffffff;"> Initial text in the East Panel</span>


6

Finally change the references in the src attributes to the respective fragments, eg:

<ext:viewport layout="border"> <ext:panel region="north" autoHeight="true" border="false" margins="0 0 1 0"> <div id="myNorthRegion" style="text-align:center">This is the North Panel</div> </ext:panel> <ext:panel region="west" src="panelContentWest.ewd" title="West Region" collapsed="true"collapsible="true" split="true" width="500" minWidth="200" /> <ext:panel region="east" src="panelContentEast.ewd" title="East Region" collapsed="true"collapsible="true" split="true" width="450" minWidth="250" /> <ext:panel region="center" src="panelContentCenter.ewd" title="Center Region" /> <ext:panel region="south" src="panelContentSouth.ewd" title="South Region"collapsed="true" collapsible="true" split="true" height="250" minHeight="100" /> </ext:viewport>

Recompile the extjsDemo application and refresh your browser. You should see thedifferent content in each of the panels. The cool thing is that you've now also loaded aunique target id into the top of each of the panels, so you can now start delivering newfragments into each specific panel in response to user-generated events. Because thisis actually just one physical browser page, an event in one panel can cause a fragmentto be targetted into the same or any other panel.

Let's try this out. Your main container page (viewportDemo1.ewd) should now belooking like this:

<ewd:config isFirstPage="true" /><ext:config path="/ext-2.0.2" /><html> <head> <title>EWD/Ext-JS Viewport & Layout Demo</title> </head> <body> <ext:viewport layout="border"> <ext:panel region="north" autoHeight="true" border="false" margins="0 0 1 0"> <div id="myNorthRegion" style="text-align:center">This is the North Panel</div> </ext:panel> <ext:panel region="west" src="panelContentWest.ewd" title="West Region" collapsed="true"collapsible="true" split="true" width="500" minWidth="200" /> <ext:panel region="east" src="panelContentEast.ewd" title="East Region" collapsed="true"collapsible="true" split="true" width="450" minWidth="250" /> <ext:panel region="center" src="panelContentCenter.ewd" title="Center Region" /> <ext:panel region="south" src="panelContentSouth.ewd" title="South Region"collapsed="true" collapsible="true" split="true" height="250" minHeight="100" /> </ext:viewport> </body></html>

and your fragment named panelContentEast.ewd should currently contain:


7

<ewd:config isFirstPage="false" pageType="ajax" /><span id="myEastPanel" style="background-color:#ffffff;"> Initial text in the East Panel</span>

Note the target id this will introduce into the container page: myEastPanel

Now change your fragment named panelContentCenter.ewd to contain:

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

<script language="javascript"> function changeLeftPanel() { ewd.ajaxRequest("panelContentEast2","myEastPanel") ; }</script>

<span id="myCenterPanel" style="background-color:#ffffff;"> <input type="button" value="Click me!" onclick="changeLeftPanel()" /></span>

Let's examine what this fragment will do: when the button in this fragment is clicked,it will trigger the javascript function changeLeftPanel(), causing a fragment namedpanelContentEast2.ewd to be fetched and targetted in the id that was originally sentinto the East panel by the fragment panelContentEast.ewd.

So let's now finally create the fragment panelContentEast2.ewd:

<ewd:config isFirstPage="false" pageType="ajax" /><span> Look! The content in the East Panel has been changed!</span>

Recompile the extjsDemo application and refresh the browser. If you slide the Eastpanel open, you should see the following:


8

Now click the button in the Center panel. The content in the East panel shouldchange:

Your ExtJS Viewport is now ready to provide a framework for a complete Ajaxapplication!


9

Extending the Viewport: Tabs

ExtJS allows you to add tabbed panels to your Viewport. Let's add some to the centerpanel.

First, edit the main viewportDemo1.ewd page, and change the center panel tag from:

<ext:panel region="center" src="panelContentCenter.ewd" title="Center Region" />

to:

<ext:tabPanel region="center" title="Center Region" > <ext:tab title="Panel 1" closable="false" src="panelContentCenter.ewd" active="true" /> <ext:tab title="Panel 2" closable="false" onSelect="loadPanel2" /> </ext:tabPanel>

You'll also need to add the following Javascript to the <head> section ofviewportDemo1.ewd:

<script language="javascript"> function loadPanel2(tabId) { ewd.ajaxRequest("panelContentCenter2",tabId) ; }</script>

Note that the loadPanel2() function requires a parameter with a reserved name oftabId, yet in the onSelect attribute of the second tab, we just specify the functionname: EWD adds the input parameter automatically for you at compile time.

What's going to happen is that the second tab won't load its content fragment until thetab is clicked. We'll need to create that fragment, as a file namedpanelContentCenter2.ewd:


<span id=”myTab2”> This is the second tabbed panel in the center region!</span>

Once again, we'll seed a targetId (in this case myTab2) into the second tab pane, so wecan use this for targetting later fragments into the panel.


10

Try recompiling the extjsDemo application and refresh the browser again. This timeyou should see the following:

The panel for Tab 1 is displayed (using the content from fragmentpanelContentCenter.ewd) because its active attribute was set to true:

<ext:tab title="Panel 1" closable="false" src="panelContentCenter.ewd" active="true" />

Click the tab named Panel 2 and you should see the second tab appear with itscontents fetched from the fragment panelContentCenter2.ewd.

You can now add as many tabs as you like to any of the panels in the viewport.

Extending the Viewport: Accordion Panes

Another great feature you can add to your viewport is accordion panes. These allowlots of information to be stacked up into a pile of panels, with only one visible at anyone time. You can slide each panel into view simply by clicking its title bar or button.

EWD makes it easy to add accordion panes. Let's add some to the West panel.


11

First, edit the main viewportDemo1.ewd page, and change the west panel tag from:

<ext:panel region="west" src="panelContent1.ewd" title="West Region" collapsed="true"collapsible="true" split="true" width="500" minWidth="200" />

to:

<ext:accordionPanel region="west" title="West Region" collapsed="true" collapsible="true"split="true" width="500" minWidth="200"> <ext:panel id="pane1" border="false" title="Accordion Panel 1"src="accordionContent1.ewd" /> <ext:panel id="pane3" border="false" title="Accordion Panel 2"src="accordionContent2.ewd" /> </ext:accordionPanel>

Now we'll create the two content fragments:

accordionContent1.ewd:


<span id="myAccordionPane1"> This is the first accordion panel</span>

accordionContent2.ewd:


<span id="myAccordionPane2"> This is the second accordion panel</span>

Try recompiling the extjsDemo application and refresh the browser again. If you slideopen the West panel, you should see the following:


12

Click on the button at the right-hand side of the Accordion Panel 2 title banner and itwill slide open, replacing the first one.

Because we added unique ids to each of the content fragments, we can now targetthese accordion panels with Ajax page fragments!


13

ExtJS Layout Widgets: Toolbar & Menus

Another set of layout widgets provided by ExtJS allows you to add a toolbar to the topof your page (or panel), to which you can add buttons and drop-down menus.

Once again, EWD makes it very quick and easy to use these widgets.

First, create a new EWD page named toolbarDemo.ewd in your extjsDemo directory,containing the following:

<ewd:config isFirstPage="true"><ext:config path="/ext-2.0.2" debug="true"/>

<html><head><title>Toolbar Demo</title></head><body> <ext:toolbar id="myToolbar" />

<div id="myContent">This is a demo of the ExtJS Toolbar and Menus</div>

</body></html>

Compile using, eg:


Load this page into a browser and you should see the text:

This is a demo of the ExtJS Toolbar and Menus

underneath a very thin blue line. This thin blue line is the taskbar which, because itdoesn't yet contain anything, is barely visible.

We'll now add a menu button to this. Replace the line:

<ext:toolbar id="myToolbar" />

with:

<ext:toolbar id="myToolbar" > <ext:menu text="Example Menu" /></ext:toolbar>


14

Recompile toolbarDemo.ewd using, eg:

d compilePage^%zewdAPI(“extjsDemo”,”toolbarDemo”,,”php”)

and refresh your browser. You should now see the toolbar properly, complete withthe menu option. When you roll your mouse over the menu option, it will appear as abutton:

Clicking the menu option won't have any effect right now. Now let's add a couple ofmenu options to it.

<ext:toolbar id="myToolbar"> <ext:menu text="Example Menu"> <ext:menuOption text="First Option" /> <ext:menuOption text="Second Option" /> </ext:menu></ext:toolbar>

Recompile the page and refresh your browser. Now when you click the menu button,a drop-down panel with the two menu options will appear.

Now let's add a handler to the options so that we can trigger events when they areclicked:


15

<ext:toolbar id="myToolbar"> <ext:menu text="Example Menu"> <ext:menuOption text="First Option" handler="myClickHandler"/> <ext:menuOption text="Second Option" handler="myClickHandler"/> </ext:menu></ext:toolbar>

You'll then need to add the following Javascript block to the <head> section of thepage:

<script language="javascript"> function myClickHandler(item, e) { Ext.Msg.alert('Menu action','You clicked on the menu item: ' + item.text); } </script>

Notice the calling interface of the click handler function, with two parameters, itemand e. In this simple example we're just generating an alert, displaying which menuoption was clicked. Notice that in this example we're making use of the ExtJS alertwhich allows you to specify a message heading and automatically greys thebackground. We could, of course, used a standard Javascript alert().

Recompile the page and refresh the browser. Now you should get an alert when youclick a menu option.


16

It's now a simple step to use this menu to drive some Ajax behaviour. For example,just change the Javascript function to the following:

<script language="javascript"> function myClickHandler(item, e) { if (item.text == "First Option") { ewd.ajaxRequest("toolbarContent1","myContent") ; } if (item.text == "Second Option") { ewd.ajaxRequest("toolbarContent2","myContent") ; } } </script>

And now create the two fragments:

toolbarContent1.ewd:


<span> Here is the first option content!</span>

toolbarContent2.ewd:


<span> Here is the second option content!</span>

Recompile the extjsDemo application and refresh the browser. Now when you click amenu option, the content below the toolbar is replaced with that of the correspondingfragment. Of course we could have targetted any id within the browser page.

Multi-level Menus

EWD makes it easy to have multi-level drop-down menus of any depth you like.Simply use nested <ext:menuOption> tags, using the nesting to reflect the menuhierarchy you require, eg:


17

<ext:toolbar id="myToolbar"> <ext:menu text="Example Menu"> <ext:menuOption text="First Option" handler="EWD.ext.clickHandler" /> <ext:menuOption text="Second Option" handler="EWD.ext.clickHandler" /> <ext:menuOption text="Third Option"> <ext:menuOption text="Option 3a" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3b"> <ext:menuOption text="Option 3b-1" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3b-2" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3b-3" handler="EWD.ext.clickHandler"/> </ext:menuOption> <ext:menuOption text="Option 3c" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3d"> <ext:menuOption text="Option 3d-1" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3d-2" handler="EWD.ext.clickHandler"/> <ext:menuOption text="Option 3d-3" handler="EWD.ext.clickHandler"/> </ext:menuOption> </ext:menuOption> <ext:menuOption text="Fourth Option" handler="EWD.ext.clickHandler" /> </ext:menu></ext:toolbar>

This will generate the following menu in the browser:

Checkbox Menu Options

ExtJS also allows you to have menu options that you can check, firing an event whenyou do so. Once again, EWD makes this easy to use. Just modify the<ext:menuOption> tag to include the checked attribute with a value of true.

You also need to specify a different handler: checkHandler

<ext:menuOption text="I like EWD" checked="true" checkHandler="myCheckHandler" />


18

The checkHandler function works identically to the clickHandler, eg:

<script language="javascript"> function myCheckHandler(item, e) { alert('Checked the menu item: ' + item.text + '; checked=' + item.checked); } </script>

Note that you can determine the checked status of the option using the checkedproperty and act accordingly.


19

Grids

One of the greatest and most powerful features in ExtJS is its grid widget. Grids canbe either read-only or editable, or a mixture of the two (ie with some columns beingeditable and some being display-only).

EWD makes it very quick and simple to use ExtJS grid widgets.

We'll start with a simple display-only grid. Like many ExtJS widget, the data in a gridis held in a datastore. This is a JSON-based data structure which is delivered to thebrowser from the back-end system. EWD looks after all the JSON-specific aspects ofthe datastore creation and transmission, leaving you just the simple task of specifyingthe array of data that will populate the datastore and hence the grid.

First, let's create a simple page that will display a grid. Copy the contents below into afile named gridDemo.ewd.

<ewd:config isFirstPage="true"><ext:config path="/ext-2.0.2" />

<html><head> <title>Ext JS Grid Example</title></head><body>

<span><ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true"> <ext:gridColumn header="Company" width="60" sortable="true" tooltip="The company inquestion"/> <ext:gridColumn header="Price" type="float" width="30" sortable="true" /> <ext:gridColumn header="Change" type="float" width="30" sortable="true" /> <ext:gridColumn header="In Stock" type="bool" renderAs="checkbox" width="30" /></ext:grid></span>

</body></html>

You define an ExtJS grid using two custom tags:

<ext:grid> This defines the grid container, its dimensions and styling

<ext:gridColumn> This defines each column in the grid, and characteristicssuch as its heading, data type and whether or not it can besorted by clicking the column heading


20

If you compile and run the gridDemo.ewd page, you'll find that you get an InvalidRequest error. This is because we haven't created the datastore named myData that isreferred to in the <ext:grid> tag.

Datastores are the responsibility of the programmer to create, and this is done in theprePageScript. Add a pre-page script to the <ewd:config> tag:

<ewd:config isFirstPage="true" prePageScript="##class(ewd.test).getDemoGridData">

In the example above, we're going to call a Caché class method namedgetDemoGridData in a class named ewd.test. You can change this to use a class ofyour own choice. Here's the source code for the class method:

ClassMethod getDemoGridData(sessid As %String) As %String{s data(1,1)="Apple"s data(1,2)=29.89s data(1,3)="0.24"s data(1,4)="true"s data(2,1)="Ext"s data(2,2)=83.81s data(2,3)="0.28"s data(2,4)="true"s data(3,1)="Google"s data(3,2)=71.72s data(3,3)="0.02"s data(3,4)="false"s data(4,1)="Microsoft"s data(4,2)=52.55s data(4,3)="0.01"s data(4,4)="true"d createGridDatastore^%zewdExtJS(.data,"myData",”r”,sessid)QUIT ""}

In this example we're simply hard-coding values, but in real-world examples thevalues would be fetched from your database. However, the pattern will be the same:

• create a 2-dimensional local array: array(rowNo, colNo) = value

• pass this array into the createGridDatastore function that EWD provides for you.Note the parameter “r”. This specifies that the EWD Session array named myDatais allowed to be read via JSON by the browser. This parameter can be left blank,as “r” is the default.


21

The programmer's task is therefore straightforward and intuitive. He/she needs toknow nothing about how the ExtJS grid datastore is structured in JSON terms, norhow it is conveyed to the browser.

Equally, the page designer's task is straightforward and intuitive. Specify the grid andits column structure, and specify the name of the datastore that will populate it.

If you save and compile the class method above (adjusting the reference to it in theprePageScript attribute appropriately), then recompile the gridDemo.ewd page, whenyou reload the browser you should now see the following:

Note the way you can click on the column headings, and how you can drag thecolumns around, and also turn columns on and off.

You can try modifying some of the grid column attributes, add further columns, etc.For details of the available config option attributes, go to the ExtJS API guide athttp://extjs.com/deploy/dev/docs/ and reference:

<ext:grid> Ext/grid/GridPanel<ext:gridColumn> Ext/grid/ColumnModel

Editable Grids

EWD and ExtJS also allow you to make a grid editable, so you can use it as a simplespreadsheet-like interface for editing data in your database. You can make any or allof the columns editable by adding the attribute editAs to the <ext:gridColumn> tags.The value of the editAs attribute specifies the datatype and hence the mechanismand/or widgets that ExtJS will bring into play to allow you to edit the data field.Supported values in EWD are:

• text simple text field allowing any alphanumeric character• number text field allowing only numeric values• checkbox on/off checkbox for boolean values• select drop-down list of possible valid options for the value• date pop-up calendar widget allows simple date entry


22

For example, the following demonstrates how to specify all these types:

<ext:gridColumn header="Namespace" width="120" editAs="select" name="namespace"sortable="true"/> <ext:gridColumn header="Timeout (sec)" type="float" editAs="number" width="90"sortable="true" /> <ext:gridColumn header="Run Mode" editAs="select" name="runMode" width="90"sortable="true" /> <ext:gridColumn header="First Page" editAs="text" width="90" sortable="true" /> <ext:gridColumn header="Fast Symbol Table" type="bool" editAs="checkbox" width="110" /> <ext:gridColumn header="Compiled Date" type="date" dateFormat="d M Y" editAs="date"width="120" />

See later for more details on how to handle each of these types.

For now, let's modify our simple gridDemo.ewd page to make the Price columneditable. Change its column definition to include editAs=”number” :

<ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true"> <ext:gridColumn header="Company" width="60" sortable="true" tooltip="The company inquestion"/> <ext:gridColumn header="Price" type="float" width="30" editAs="number" sortable="true" /> <ext:gridColumn header="Change" type="float" width="30" sortable="true" /> <ext:gridColumn header="In Stock" type="bool" renderAs="checkbox" width="30" /></ext:grid>

When you recompile the page and refresh the browser, you should find that when youclick on any Price cell, you can now edit the value. Note the way you can only enternumeric characters!

However, when you tab or otherwise move away from an edited Price value, theoriginal value re-appears. We now need to get the new, edited value to the back-endand into the hands of the programmer who can validate and process the new, editedvalue if required.

This is done by adding a validationScript attribute to the <ext:grid> tag.

<ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true" validationScript=”class(ewd.test).setDemoGridData”>

Note that you must not specify the method using ##class. Make sure you leave outthe two # characters.


23

You must also give the EWD Session datastore read/write permissions. You do thisby changing the “r” parameter to “rw” in the createGridDatastore() method that youused in the prePageScript, ie.

ClassMethod getDemoGridData(sessid As %String) As %String{s data(1,1)="Apple"s data(1,2)=29.89s data(1,3)="0.24"s data(1,4)="true"s data(2,1)="Ext"s data(2,2)=83.81s data(2,3)="0.28"s data(2,4)="true"s data(3,1)="Google"s data(3,2)=71.72s data(3,3)="0.02"s data(3,4)="false"s data(4,1)="Microsoft"s data(4,2)=52.55s data(4,3)="0.01"s data(4,4)="true"d createGridDatastore^%zewdExtJS(.data,"myData",”rw”,sessid)QUIT ""}

Now, every time an editable grid cell value is changed and you move away from thegrid cell, this method will fire, passing the row number, column number and newvalue to the programmer. Note that the row and column numbers will be the originalvalues for the cell, so it doesn't matter if the user re-sorts the contents or drags thecoumns around.

So let's take a look at a simple example of what the programmer might do in the back-end validationScript method:

ClassMethod setDemoGridData(sessid As %String) As %String{s row=$$getSessionValue^%zewdAPI("extGridRow",sessid)s column=$$getSessionValue^%zewdAPI("extGridColumn",sessid)s value=$$getSessionValue^%zewdAPI("extGridValue",sessid)i value>99 QUIT "Value is too big!"QUIT ""}


24

When you change a value, EWD instantiates three session variables:

extGridRowextGridColumnextGridValue

The programmer should pick up these values in his/her script and perform anyvalidation. In the example above we're simply ensuring that the value cannot begreater than 99. In the event of a validation error, the programmer simply QUITs,returning an error message string. EWD automatically uses this to bring up an ExtJSalert.

If the value validates OK, the programmer can optionally save the new value. It is theprogrammer's responsibility to ensure that the row and column numbers providehim/her with sufficient information to save the new value back into the correct placein the database.

The modified value does not need to be committed to the database immediately. Themodified values reside in an EWD Session Array, in this case named myData. Whenediting is completed, the programmer can commit all the changed data at once. Forexample, to access the modified EWD Session values for the grid:

d mergeArrayFromSession^%zewdAPI(.myData,"myData",sessid)

The local array myData is exactly the same format as originally created in thegetDemoGridData() prePageScript method, but now contains the validated editedvalues. Note that any new values that failed validation are not changed in the EWDSession array, eg:

myData(1,1)="Apple"myData(1,2)=29.89myData(1,3)="0.24"myData(1,4)="true"myData(2,1)="Ext"myData(2,2)=23myData(2,3)="0.28"myData(2,4)="true"myData(3,1)="Google"myData(3,2)=44myData(3,3)="0.02"myData(3,4)="false"myData(4,1)="Microsoft"myData(4,2)=76myData(4,3)="0.01"myData(4,4)="true"

You should now be able to modify your demonstration grid to allow any of thecolumns to be edited, eg:


25

<ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true"> <ext:gridColumn header="Company" width="60" sortable="true" tooltip="The company inquestion" editAs=”text” /> <ext:gridColumn header="Price" type="float" width="30" editAs="number" sortable="true" /> <ext:gridColumn header="Change" type="float" width="30" sortable="true" editAs=”number” /> <ext:gridColumn header="In Stock" type="bool" renderAs="checkbox" width="30"editAs=”checkbox” /></ext:grid>

Invoking an Event Handler that Fires when a Row is Selected

Provided your grid does not contain any editable cells, you can add an event handlerthat will fire when you select a row from the grid. You can fire your own method andEWD passes it all the information you need to handle the data relevant to the rowwithin Javascript or in the Caché back-end (via an Event Broker call).

Simply add the attribute onRowSelect to the <ext:grid> tag. The attribute's value willbe the name of your function, eg

<ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true" onRowSelect="myFunc">

Your event handler function must have two input parameters:

• currentRecord an Array containing the values for each column in the selected row

• currentRow the row number of the back-end data store that you selected

eg:

<script language="javascript"> function myFunc(currentRecord,currentRow) { alert(currentRecord + ": " + currentRow) ; }</script>

If you click the third row in our demo grid, currentRow would have a value of 3 andcurrentRecord would contain:


26

currentRecord[0] = 2currentRecord[1] = “Google”currentRecord[2] = 71.72currentRecord[3] = 0.02currentRecord[4] = false

Your function can therefore access and use the values for the current row withinJavascript. If you want to return more data from the Caché back-end from within yourfunction, you can make an Event Broker call, eg:

<script language="javascript"> function myFunc(currentRecord,currentRow) { ewd:##class(ewd.test).fetchGridRecord(currentRow) ; alert(myRecord) ; }</script>

This method might look as follows:

ClassMethod fetchGridRecord(currentRow As %Integer, sessid As %String) As %String{ // access data related to the record identified by the currentRow number, eg // here is the data returned to Javascript as a hard-coded array QUIT "myRecord = ['This record',12,34,99,true,'Test value'];"}

In a real example, you'd use the value of currentRow as an index to look up theappropriate information from the Caché database and return one or more values asJavascript statements, or, as above, as a Javascript array.

Alternatively, you might pass the currentRow for use by the prePageScript of an Ajaxfragment that you target somewhere into your page, eg:

<script language="javascript"> function myFunc(currentRecord,currentRow) { var nvp=”rowNo=” + currentRow; ewd.ajaxRequest(“myFragment”,”myTargetId”,nvp) ; }</script>

In this example, we're fetching an EWD fragment named myFragment.ewd that willreplace in the innerHTML of the tag whose id is myTargetId. The prePageScript of


27

myFragment.ewd will be able to access the number of the selected row by accessingthe Request value named rowNo, eg:

s selectedRowNo = $$getRequestValue^%zewdAPI(“rowNo”,sessid)

Note that you cannot fire the onRowSelect Event Handler if any of your grid's cellsare defined as editable.


28

Menu Trees

The ExtJS Tree is another very useful widget. It creates the kind of expandingvertical menu trees that are now a familiar part of graphical user interfaces, eg:

Once again, EWD makes it very quick and easy to create these trees, of any sizeand/or hierarchy depth.

First, create an EWD page named treeDemo.ewd that contains the following:

<ewd:config isFirstPage="true" prePageScript="##class(ewd.test).getDemoTreeData"><ext:config path="/ext-2.0.2" />

<html><head> <title>Ext JS Tree Example</title></head><body>

<ext:tree datastore="myTreeData" style="overflow:auto;height:300px;width:200px;" text="Cars" />

</body></html>

Like the grid widget, the contents of the tree widget are contained in a JSONdatastore. EWD automates everything for you, reducing the task of the designer todetermining the positioning and basic styling of the tree, as above. The task of theprogrammer is to populate the tree datastore within the prePageScript, in this caseusing a Caché class method named getDemoTreeData(). Create your own version ofthis method containing the following:


29

ClassMethod getDemoTreeData(sessid As %String) As %String{s tree(1)="Ford"s tree(2)="Volvo"s tree(3)="Nissan"s tree(4)="Toyota"s tree(5)="Mercedes"s tree(6)="BMW"d createTreeDatastore^%zewdExtJS(.tree,"myTreeData",sessid) QUIT ""}

As you can see, the programmer simply creates a local array containing the menu treeoptions in the order in which they should appear, and then passes this into thecreateTreeDatastore() method that is provided by EWD.

If you save and compile the treeDemo.ewd page and getDemoTreeData() method, andlaunch the compiled version of treeDemo in a browser, you should see the tree:

Now let's add a few more levels to the tree hierarchy. That's very simple to do. Justexpress these using the natural hierarchy provided by the local array structure:

ClassMethod getDemoTreeData(sessid As %String) As %String{s tree(1)="Ford"s tree(1,1)="Focus"s tree(1,1,1)="Petrol"s tree(1,1,2)="Diesel"s tree(1,2)="Mondeo"s tree(1,2,1)="Petrol"s tree(1,2,2)="Diesel"s tree(2)="Volvo"s tree(2,1)="S40"s tree(2,2)="V70"s tree(2,3)="XC90"s tree(3)="Nissan"s tree(3,1)="Micra"s tree(3,2)="Qashqai"s tree(4)="Toyota"s tree(4,1)="Corolla"s tree(4,2)="Prius"


30

s tree(4,3)="Yaris"s tree(4,3,1)="2 door"s tree(4,3,2)="4 door"s tree(5)="Mercedes"s tree(5,1)="SL-Class"s tree(5,1,1)="SLK Roadster"s tree(5,2)="A-Class"s tree(5,3)="E-Class"s tree(6)="BMW"s tree(6,1)="3 Series"s tree(6,1,1)="318"s tree(6,1,2)="320"s tree(6,1,3)="325i"s tree(6,2)="5 Series"d createTreeDatastore^%zewdExtJS(.tree,"myTreeData",sessid) QUIT ""}

Refresh the page in the browser and you'll now see the new version of the tree whichcan be expanded out to reveal all the levels you've defined above.

Now of course we usually want this kind of tree menu so that we can trigger a specificaction depending on the menu option we choose. In the EWD/ExtJS tree, you can addan action automatically to any leaf-node in the tree hierarchy.

Let's create a simple Ajax-style interaction. First, change the treeDemo.ewd page asfollows:

<ewd:config isFirstPage="true" prePageScript="##class(ewd.test).getDemoTreeData"><ext:config path="/ext-2.0.2" />

<html><head> <title>Ext JS Tree Example</title>

<script language="javascript"> function selectCar(id,value) { var nvp="id=" + id + "&leafValue=" + value ; ewd.ajaxRequest("showCarDetails","carContent",nvp) ; }</script>

</head><body>

<ext:tree datastore="myTreeData" style="overflow:auto;height:300px;width:200px;" text="Cars"onClick="selectCar" />

<hr /><div id="carContent">Details will be shown here</div></body></html>


31

What we've done here is to add an onClick handler to the tree's leaf nodes that willtrigger a Javascript function named selectCar. Notice the interface to this function:

function selectCar(id,value)

EWD ensures that the id and the text value of the leaf node you clicked is passedthrough to the function. The format of the id is the text string extTreeData followedby the hierarchy level, with each level separated with the character, eg:

extTreeData5x1x1

This repesents the leaf node for tree(5,1,1) which was defined as follows:

s tree(5)="Mercedes"s tree(5,1)="SL-Class"s tree(5,1,1)="SLK Roadster"

The id therefore provides sufficient information to determine exactly which node inthe tree was clicked.

Of course, if all the leaf nodes have unique text, the value can be sufficient. In theexample above, the variable value would have a value of “SLK Roadster”.

By passing you both values, you can determine which you need to determine thesubsequent action you want to invoke.

In the example above, we're going to replace the innerHTML of the tag <divid="carContent"> with a fragment named showCarDetails.ewd, to which we're goingto pass two name/value pairs constructed from the id and value.

Now we'll create that fragment. Copy the following into a file namedshowCarDetails.ewd in the extjsDemo directory.

<ewd:config isFirstPage="false" pageType="ajax" prePageScript="##class(ewd.test).getCarDetails"/><span> Car details selected: <?= #carDetails ?></span>

Now we'll create the prePageScript for this fragment:

ClassMethod getCarDetails(sessid As %String) As %String{s id=$$getRequestValue^%zewdAPI("id",sessid)s leafValue=$$getRequestValue^%zewdAPI("leafValue",sessid)d setSessionValue^%zewdAPI("carDetails",id_": "_leafValue,sessid)QUIT ""}

We need to do this because the name/value pairs (id and leafValue) are passed as thethird parameter of the ewd.ajaxRequest method, and because this is evaluated at run-


32

time, EWD cannot safely instantiate these extra name/value pairs directly into theEWD Session. So they have to be extracted from the EWD Request. We're thenconcatenating them together and creating a session variable named carDetails. Thiscan then be displayed in the fragment as <?= #carDetails ?>.

So now you have all the building blocks. Compile the new version of treeDemo.ewdand the fragment showCarDetails.ewd, and save and compile the class methodgetCarDetails(). Refresh the compiled version of the treeDemo page and you shouldsee:

Open up one of the menu levels and click a leaf node and you should now seesomething like:

The fragment has replaced the original text at the bottom of the page with the id andtext value of the selected tree leaf node. You're now ready to adapt this simpleexample into your own Ajax applications!


33

The EWD/ExtJS Desktop

The techniques and widgets described above allow you to use the ExtJS widgets inconventional web and Ajax applications. However, ExtJS can go one better, andprovide you with a new way of presenting applications, using the ExtJS web desktopwidgets. EWD makes it amazingly simple to make use of these widgets to create yourown, fully functioning web desktop applications.

In order to use the EWD/ExtJS desktop widgets, you'll need to download theadditional customised components from the M/Gateway web site. You'll find these athttp://gradvs2.mgateway.com/main/extjs_desktop.zip Copy the contents into your ExtJS Javascript directories, eg /var/www/html/ext-2.0.2,maintaining the path structure within the zip file. This will create two newsubdirectories named desktop and images, ie

/ext-2.0.2/desktop/ext-2.0.2/images

You can now begin developing a desktop. Let's start with a very simple example.

Create a new file named desktopDemo.ewd in your extjsDemo directory, containingthe following:

<ewd:config isFirstPage="true"><ext:config path="/ext-2.0.2" />

<html><head><title>EWD/Ext-JS Desktop</title></head><body>

<ext:desktop title="Rob Tweed" iconClass="user" backgroundImage="/ext-2.0.2/desktop/ewdExtDesktop.jpg"> <ext:window title="Grids" showOnDesktop="true" desktopIcon="/ext-2.0.2/images/grid48x48.png" iconClass="panel" width="430" height="300" src="gridDemo2.ewd"/> </ext:desktop>

</body></html>

Adjust the image paths according to your ExtJS installation. Compile and run thispage in a browser and you should see the following:


34

You have your first web desktop application up and running! Let's take a look at whatthe EWD page defined.

First, the <ext:desktop> tag creates the desktop container and defines the backdropimage to use for your desktop. If you click on the Start button, you'll also see theusername you specified appearing at the top of the start panel.


35

Everything else is defined in the <ext:window> tags. In this case we've only defined asingle main window for the desktop which is associated with the single desktop iconnamed Grids. The current version of the desktop also mirrors this in the Start panel.

Let's take a look at the <ext:window> tag we specified:

<ext:window title="Grids" showOnDesktop="true" desktopIcon="/ext-2.0.2/images/grid48x48.png"iconClass="panel" width="430" height="300" src="gridDemo2.ewd" />

The attributes are as follows:

• title Specifies the text to display on the icon• showOnDesktop Display the icon on the desktop if true• desktopIcon Specifies the image file to use as the desktop icon• iconClass Specifies the class that defines the window image icon in

the Start panel, the taskbar and the window title bar• width the width of the window that will pop up• height the height of the window that will pop up• src the name of the fragment that will populate the window

If you click the Grids icon, a window should pop up with the dimensions youspecified (430 X 300), but it will contain the text Please wait... and you should thensee an Invalid Request error. This is because we haven't yet created the fragment thatwill contain the content for the window. We specified this to be src="gridDemo2.ewd"

We've already created a grid demo page, but that was a complete web page rather thana fragment, but we can quickly adapt it into a fragment. First, copy gridDemo.ewd togridDemo2.ewd

Next, edit it to contain the following:

<ewd:config isFirstPage="false" pageType="ajax" prePageScript="##class(ewd.test).getDemoGridData">

<span><ext:grid datastore="myData" stripeRows="true" title="Example Ext/EWD Grid" width="400"frame="true" liveUpdate="true" validationScript="class(ewd.test).setDemoGridData"> <ext:gridColumn header="Company" width="60" sortable="true" tooltip="The company inquestion"/> <ext:gridColumn header="Price" type="float" width="30" editAs="number" sortable="true" /> <ext:gridColumn header="Change" type="float" width="30" sortable="true" /> <ext:gridColumn header="In Stock" type="bool" renderAs="checkbox" width="30" /></ext:grid></span>

So now it's just a fragment of markup, without a <head> and <body> section, and itis declared as pageType=”ajax” in the <ewd:config> tag.


36

Compile this new fragment and it should now work. Reload the main desktop pageand then click the Grids icon (sometimes it takes a few seconds to become activated,particularly in Firefox). You should now see the following:

Now all you need to do is adjust the window and/or grid dimensions and you'll have agreat-looking web desktop application, and all built in just a few minutes!

Try adding more desktop icons, and convert some of your other ExtJS examples intofragments to use as contents for your windows. To do this, just add more<ewd:window> tags inside your <ext:desktop> tag in the main container page.

Special Use of Trees in the ExtJS Desktop

Something that is very useful in the desktop environment is to bring up an initialwindow that contains a tree menu. When you click any of the leaf nodes, you want anew window to pop up, but the fragment that populates the window should bedependent on the leaf node you clicked. EWD makes this very simple. First, let's adda new icon to our desktop:


37

<ext:desktop title="Rob Tweed" iconClass="user" backgroundImage="/ext-2.0.2/desktop/ewdExtDesktop.jpg"> <ext:window title="Grids" showOnDesktop="true" desktopIcon="/ext-2.0.2/images/grid48x48.png" iconClass="panel" width="430" height="300" src="gridDemo2.ewd"/> <ext:window title="Tree Demo" showOnDesktop="true" desktopIcon="/ext-2.0.2/images/about48x48.png" iconClass="panel" width="200" height="200"src="treeDemo2.ewd" /> </ext:desktop>

Now create the treeDemo2.ewd fragment that will populate the pop-up windowcreated when we click the Tree Demo icon:

<ewd:config isFirstPage="true" pageType="ajax" prePageScript="##class(ewd.test).getDemoTreeData2">

<span><ext:tree datastore="myTreeData" style="overflow:auto;height:300px;width:200px;" text="Cars"autoWindow="true" windowWidth="400" windowHeight="300" /> /></span>

This will create a tree menu, but notice the autoWindow, windowWidth andwindowHeight attributes. These cause a new window to open whenever any leaf nodeis clicked. Now we need to define the tree via the prePageScript:

ClassMethod getDemoTreeData2(sessid As %String) As %String{s tree(1)="Ford"_$c(1)_"treeDemoFrag1"s tree(2)="Volvo"_$c(1)_"treeDemoFrag2"s tree(3)="Nissan"_$c(1)_"treeDemoFrag3"d createTreeDatastore^%zewdExtJS(.tree,"myTreeData",sessid) QUIT ""}

Notice how we can define a fragment name for each leaf node by setting the secondpiece in each tree node (where the delimiter is ASCII 1) to the name of the requiredfragment. So, in other words, when we click the Ford option, the window that popsup will be populated by a fragment named treeDemoFrag1.ewd.

Now all we need to do is create the three fragments referred to by the prePageScript.Initially let's just create some simple basic content to demonstrate how it will all work:

treeDemoFrag1.ewd:

<ewd:config isFirstPage="false" pageType="ajax" /><span> You selected a Ford!</span>


38

treeDemoFrag2.ewd:

<ewd:config isFirstPage="false" pageType="ajax" /><span> You selected a Volvo!</span>

treeDemoFrag3.ewd:

<ewd:config isFirstPage="false" pageType="ajax" /><span> You selected a Nissan!</span>

Compile all these pages and when you re-load the main container page in the browser,you should then see the following (the tree window has been dragged to the left forclarity):

Now you're all set. You can now modify the three simple fragments and startpopulating the windows with much more complex content.


39

Running Separate EWD Applications in Desktop Windows

A cool trick with the desktop is to use the pop-up windows to act as containers forcompletely self-contained EWD applications (or indeed any other web application).Just load the window with a fragment that contains an <iframe> tag. The <iframe>can then load anything it likes into itself. You now have a complete applicationrunning in a desktop window!

Here's a quick guide to this trick. First add a new icon to your desktop:

<ext:window title="ewdMgr" showOnDesktop="true" desktopIcon="/ext-2.0.2/images/ewdMgr48x48.png" iconClass="panel" width="800" height="600"src="loadEwdMgr.ewd" />

Now create the fragment named loadEwdMgr.ewd:

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

<span><iframe src="/php/ewdMgr/index.php" width="100%" height="100%"frameborder="0"></iframe></span>

You'll probably need to modify the src path for the ewdMgr application for yourenvironment (or use a path to some other existing application).

That's all there is to it! Compile the desktopDemo.ewd and loadEwdMgr.ewd pagesand it should now work:


40

There you go! A complete web desktop application, and all built in a matter of a fewminutes!


41

APPENDIX I

Mapping of EWD ExtJS tags to ExtJS API Documentation References

Tag Name ExtJS Class<ext:grid> Ext.grid.GridPanel<ext:gridColumn> Class Ext.grid.ColumnModel<ext:menu> Ext.menu.Menu<ext:menuItem> Class Ext.menu.Item<ext:panel> Class Ext.Panel<ext:tab> Class Ext.TabPanel<ext:toolbar> Class Ext.Toolbar<ext:viewport> Class Ext.Viewport<ext:window> Class Ext.Window


42

enterprise web developer using the extjs widgets

Documents