extc web developer api manual - m/gatewaygradvs1.mgateway.com/download/apiguide3.0.618.pdf · extc...

eXtc Web Developer

Rapid Web Application Development and Ajax Framework for Caché

Session API and Design Page Tag GuideVersion 3.0.618

Background

eXtc Web Developer is a rapid application development environment for building andmaintaining Caché-linked web applications, running under a number of environmentsincluding Caché Server Pages (CSP), PHP and Java Server Pages (JSP).

The PHP implementation relies on, and makes use of the m_php gateway that allows thePHP run-time environment to communicate with Caché. The JSP implementation relieson, and makes use of the m_jsp gateway that allows the JSP run-time environment tocommunicate with Caché.

This document is a reference guide covering the two main aspects of eXtc WebDeveloper:

• The special tags and attributes that you can use within your design pages thatcontrol eXtc Web Developer’s behaviour.

• The Caché API methods for accessing and manipulating the session object in yourpre-page and action scripts;

Your eXtc Web Developer pages may include CSP scripts or PHP or JSP coding.However, by doing so, you make your web applications specific to that environment. It isstrongly recommended that you use eXtc Web Developer’s custom tags and API methodsinstead: by doing so you will be able to cross-compile your applications to any of thesupported run-time environments.

eXtc Web Developer provides its own range of built-in custom tags that implement manyprogrammatic behaviours and functions in a platform-independent way. If you find thatyou need your own extensions to eXtc Web Developer’s behaviour, you can define yourown custom tags and define their run-time behaviour on any of the supported run-timeenvironments. M/Gateway Developments wishes to encourage the development of thirdparty catalogues of custom tags and re-usable components for eXtc Web Developer, andthe export and import of custom tag definitions is fully supported within the product.

Pre-requisites

This guide assumes that you have read the eXtc Web Developer Overview, theInstallation Guide and Tutorial documents.

eXtc Web Developer : Session API and Design Page Tag Guide. Version 3.0.618: 9 October 2007. 2004-2007, M/Gateway Developments Ltd. All Rights Reserved

1

Command-line compilation eXtc Web Developer Pages

You will normally compile your eXtc Web Developer pages using the web-basedmanagement application. For information on installing, configuring and running thisapplication, see the Installation documentation.

eXtc Web Developer also provides command line interfaces for compiling entireapplications and/or individual pages. These are described below.


2

compileAll^%zewdAPIDescription Compiles all the eXtc Web Developer Design Pages in an

application

Example d compileAll^%zewdAPI(“myApp”,,”csp”)

Compile all the pages in the “myApp” application, and create a CSPversion of the application.

By not specifying the output mode, the default configured mode will beapplied – eg collapsed. If in doubt, explicitly define the output mode.

Parameters DescriptionapplicationName Name of the eXtc Web Developer application

outputMode “pretty” : creates an indented, formatted version of thePHP, JSP or CSP page

“collapse” : collapses all the HTML in the page into acontinuous stream with no white space between tags

If omitted, the default setting for your eXtc Web Developerconfiguration will be used.

To determine your default setting, run the following in aterminal session in any namespace:

w $$getDefaultFormat^%zewdAPI()

If no default has been configured, “pretty” is used as thedefault.

technology “csp” : creates a CSP application from the Design Pages

“php” : creates a PHP application from the Design Pages

“jsp” : creates a JSP application from the Design Pages

“wl” : creates a set of WebLink routines from the DesignPages

If not specified, “php” is used as the default.


3

outputPath This is not normally used. By default, the page will becompiled into the path specified by your outputRootPathsetting. You can inspect this setting using:

w $$getOutputRootPath^%zewdAPI("php")

d:\inetpub\wwwroot\php

w $$getOutputRootPath^%zewdAPI("csp")

d:\cache42\csp

w $$getOutputRootPath^%zewdAPI("jsp")

c:\Program Files\Apache Software Foundation\Tomcat5.5\webapps\jsp-examples\ewd

You can over-ride the default path by using this optionalparameter.

multiLingual Optional parameter that will enable and control the multi-lingual processing of your eXtc Web Developerapplication.

Values are:

0 : No multi-lingual processing1: Multi-lingual processing, linguistic review mode2: Multi-lingual processing, final run mode

If omitted, the default multi-lingual setting is used. Thiscan be inspected using:

w $$getDefaultMultiLingual^%zewdAPI()

returnValue n/a


4

compilePage^%zewdAPIDescription Compiles a specified eXtc Web Developer Design Page in

an application

Example d compilePage^%zewdAPI(“myApp”,”myPage”,,”csp”)

Compile the page named “myPage.ewd” in the “myApp” application,and create a CSP version of the page.

By not specifying the output mode, the default configured mode will beapplied – eg collapsed. If in doubt, explicitly define the output mode.

Parameters DescriptionapplicationName Name of the eXtc Web Developer application

pageName Name of the page to be compiled. You must omit the fileextension (ie .ewd).

Note: If your application is stratified into sub-directoriesunder the main application path, then you can compile apage in one of the subdirectories by specifying itssubdirectory.

For example, if your eXtc Web Developer application rootpath was:

c:\myEWDApps

Your application named “myApp” would reside in:

c:\myEWDApps\myApp

Normally all your .ewd Design Pages would reside in thispath. However, you could have sub-directories of this pathwhich contain pages, eg:

c:\myEWDApps\myApp\admin\myAdminPage.ewd

To compile this page, set the pageName parameter to:

admin\myAdminPage

The compiled page will be automatically created in theadmin subdirectory of the Output Root Path. If this pathdoes not physically exist, it will be created automatically.


5

outputMode “pretty” : creates an indented, formatted version of thePHP, JSP or CSP page

“collapse” : collapses all the HTML in the page into acontinuous stream with no white space between tags

If omitted, the default setting for your eXtc Web Developerconfiguration will be used.

To determine your default setting, run the following in aterminal session in any namespace:

w $$getDefaultFormat^%zewdAPI()

If no default has been configured, “pretty” is used as thedefault.

technology “csp” : creates a CSP page from the Design Page

“php” : creates a PHP page from the Design Page

“jsp” : creates a JSP page from the Design Page

“wl” : creates a WebLink routine from the Design Page

If not specified, “php” is used as the default.

outputPath This is not normally used. By default, the page will becompiled into the path specified by your outputRootPathsetting. You can inspect this setting using:

w $$getOutputRootPath^%zewdAPI("php")

d:\inetpub\wwwroot\php

w $$getOutputRootPath^%zewdAPI("csp")

d:\cache42\csp

w $$getOutputRootPath^%zewdAPI("jsp")

c:\Program Files\Apache Software Foundation\Tomcat5.5\webapps\jsp-examples\ewd

You can over-ride the default path by using this optionalparameter.


6

multiLingual Optional parameter that will enable and control the multi-lingual processing of your eXtc Web Developerapplication.

Values are:

0 : No multi-lingual processing1: Multi-lingual processing, linguistic review mode2: Multi-lingual processing, final run mode

If omitted, the default multi-lingual setting is used. Thiscan be inspected using:

w $$getDefaultMultiLingual^%zewdAPI()

returnValue n/a


7

The eXtc Web Developer Tags and Attributes

Your eXtc Web Developer design pages can use a variety of special tags and attributes todescribe, at a high level, what your pages are doing. This section describes each of thetags and/or attributes.

Note that tag names should be in lower-case. Attribute names are not case sensitive, butattribute values are case sensitive.

Local Variables

Your pages can include technology-specific references to variables if you wish : thesewill be left untouched by eXtc Web Developer’s compiler, eg:

CSP: <p>The value is #(myVar)#</p>PHP: <p>The value is <?= $myVar ?></p>JSP: <p>The value is <%= myVar %></p>

However, eXtc Web Developer provides an alternative, technology-independentmechanism. It is strongly recommended that you adopt this convention, because thisallows you to automatically cross-compile your application to either CSP, JSP or PHP.There are no benefits to be obtained by using CSP, PHP or JSP-specific in-page syntax.

In fact, eXtc Web Developer adopts the PHP convention as the standard means ofrepresenting a variable. A local, in-page variable is always denoted by a leading $ and isdelimited with <?= and ?>, ie:

EWD: <p>The value is <?= $myVar ?></p>

This is left untouched if you compile to PHP, but if you compile to CSP or JSP, then itwill automatically convert it to:

CSP: <p>The value is #(myVar)#</p>JSP: <p>The value is <% out.print(myVar) %></p>

This EWD variable syntax can be used anywhere in a Design Page, even within a tagattribute.

Note that the scope of such local, in-page variables is dictated by the technology you areusing.

Session Variables

Your pages can access and make use of values held in the session object. Thetechnology-independent syntax is very similar: simply substitute the leading $ with a #.eg:

EWD: <p>The message is <?= #myVar ?></p>


8

The value of the session variable myVar is substituted at run-time. If the session variablehas not been instantiated, or if it cannot be resolved as a scalar variable, then a null valueis returned.

So, for example, if your pre-page script had included:

d setSessionValue^%zewdAPI(“myVar”,”eXtc Web Developer rules!”,sessid)

Then, at run-time, your page will display:

The message is eXtc Web Developer rules!

By adopting this syntax, and by using eXtc Web Developer’s session API methods, yourapplications will be able to compile to run in either CSP, JSP or PHP.

Session Objects

EWD also allows the use of session objects. Simply substitute an object reference anduse the same API methods, eg:

d setSessionValue^%zewdAPI(“person.address.postCode”,”EC1 4EA”,sessid)s postCode=$$getSessionValue^%zewdAPI(“person.address.postCode”,sessid)

In your pages you can refer to:

Post code : <?= #person.address.postCode ?>

Temporary session values

It is quite common to gather and marshall a lot of data in a pre-page script and generate alarge set of session values that are to be used on the current page only – once displayed onthe page, the session values are no longer needed. To avoid the need for laborioussession management logic, EWD allows you to use temporary session variable. These areavailable for the page whose pre-page script creates them, but they are not persisted.

Temporary session variables are simply denoted by prefixing with tmp. For example:

d setSessionValue^%zewdAPI(“tmp.postcode”,”EC4A 2TR”,sessid)

Temporary session arrays are defined by prefixing tmp_ For example:

d mergeArrayToSession^%zewdAPI(.myArray,”tmp_details”,sessid)


9

In your pages you can refer to:

Post code : <?= #tmp.postcode ?>

or

<ewd:forEach sessionName=”tmp_details” index=”$ix”>

Special Notes for Java Server Pages

Java is a strictly typed language, so all variables that are used in Java Server Pages mustbe declared and typed correctly. As far as possible, EWD will do this for youautomatically. However, in some circumstances, particularly when using the <ewd:set>and related tags to create new variables, you may need to specifically declare the type ofvariable that you require. You do this by adding the “type=” attribute and using theappropriate Java type name, eg:

<ewd:set return=”$myVar” value=”#ewd_sessid” type=”int”>

EWD attempts to be as intelligent as possible, however, and will examine the operandsand/or attribute values to determine the type of the variable(s) used in the tag. Forexample, EWD will automatically determine that the return variable in the followingexamples is of type “int”:

<ewd:set return="$limit" firstValue="#ewd_sessid" secondValue=30 operand="+"><ewd:set return=$i value=”20”>

If in doubt, specify the type explicitly.

Java Server Pages are also rigorous about case sensitivity of page names in URLs. Makesure that page references in your EWD pages use the same case as the names used whenthe pages were compiled into JSP and saved.

If you use the EWD Event Broker/HyperEvent mechanism in JSP, you'll also find that theapplication name (which is used to automatically create the URL path) must match thecase of the physical path in which the pages are saved. If you consistently use the samecase structure for page names and application names throughout EWD, you'll find thatyou do not have any problems with JSP.


10

extc Web Developer Custom Tags

The set of Custom Tags that are included in EWD are described below.


11

<ewd:ajaxOnload>Description For use within Ajax Page Fragments, this tag is used to specify a block of Javascript

that will be invoked after the page fragment replaces its target ID's innerHTML.

This tag can be placed anywhere within the page fragment, but by convention, it isnormally placed immediately after the <ewd:config> tag.

Any sequence of Javascript commands and function calls can contained within the<ewd:ajaxOnload> tag, and may also include:

– EWD session variables ;– one or more calls to the ewd.ajaxRequest pseudo-function.

eg

<ewd:ajaxOnload> alert(“Page fragment has been loaded”) ;</ewd:ajaxOnload>

Note: if you need to comment a line of Javascript within the <ewd:ajaxOnload> tag,you must use the /* .... */ convention. Use of the // convention will cause theJavascript to fail.

AttributesName Value(s) Notes Default

n/a n/a


12

<ewd:apply>Description This tag can be used to conditionally segment sections of HTML and EWD custom

tags that apply to a specified run-time technology, eg CSP-specific, JSP-specific orPHP-specific code. The HTML and other tags between a <ewd:apply> and itsterminating </ewd:apply> tags will only be compiled for the specified technology.

Normally used if you are designing pages that will be capable of running in PHP, JSPand CSP environments, but where some in-page logic cannot be specified in atechnology-neutral way using EWD’s built-in custom tags. Using the <ewd:apply>tag, you can specify and keep separate the CSP-specific logic, the JSP-specific logicand the PHP-specific logic that defines a piece of in-page functionality. At compiletime, the appropriate logic is compiled into the run-time page. This ensures that youwon’t get CSP logic getting into a PHP page or vice versa.

If your pages will only be used in a specific technology – eg if your pages will onlyever be used in a PHP environment – there is no need to use the <ewd:apply> tag.

It is recommended that you should always try to use the technology-independentEWD custom tags and avoid the use of the <ewd:apply> mechanism if possible.


technology “csp”, “jsp” or “php” n/a


13

<ewd:config>Description This tag can appear once in each page, by convention and for clarity as the first tag at

the top of the page (although it can actually appear anywhere in the page). It is usedto define one or more configuration settings for the page. Note that you can include a<ewd:config> tag in your template document (ewdTemplate.ewd), in which case allpages in the application inherit the <ewd:config> attributes specified in the templatepage, in addition to any specified in the <ewd:config> tag in the design page.


prePageScript functionCall

where functionCall can be a call to aCaché extrinsic function, a Cachémethod or a PHP function.

eg:

prePageScript=”myFunc^myRoutine”

prePageScript= ”##class(myPckge.myClass).myMethod”

prePageScript=”$myPHPFunc”

If not specified, nopre-page script willbe invoked for thepage.

If you call a PHPfunction, it mustreside in the currentpage. The PHPfunction can, if youwish, invoke m_phpfunctions to accessyour Caché database.

Calls to JSP methodsare not currentlysupported.

n/a

templatePrePageScript functionCall

where functionCall can be a call to aCaché extrinsic function

eg:

templatePrePageScript= ”myFunc^myRoutine”

This optionalattribute can only bespecified in the<ewd:config> tag ofthe ewdTemplate.ewdpage.

If specified, thefunction will beinvoked for everypage that uses thetemplate. Thefunction is invokedbefore any page-specific pre-pagescript.

n/a

pageType If the page is an Ajax Page Fragment,then you must specify

pageType=”ajax”

Otherwise for standard HTTP pages,omit this attribute

For use with AjaxPage Fragments only

N/a


14

isFirstPage

or

publicPage

trueOrFalse

eg isFirstPage=”false”

publicPage=”true”

If the application iscompiled to PHP orJSP, this specifieswhether or not thethis page can beaccessed with asimple URL thatspecifies the PHP orJSP page. If set tofalse, then the pagecan only be accessedfrom within an activesession

If the application iscompiled to CSP,then a value of trueequates to a “Public”page, whilst a valueof false equates to a“Private” page.

The two attributenames aresynonymous. Theyshould not both beused in the same<ewd:config> tag, butif they are,isFirstPage takesprecedence.

true

defaultTimeout noOfSeconds

eg defaultTimeout=3600

Sets the default session timeout to1hour. After 1 hour’s inactivity, thesession will be marked for deletion.

Sets the defaultsession timeout for allsubsequent pages,unless over-ridden ona page-by-page basiswith the pageTimeoutattribute.

1200

pageTimeout noOfSeconds

eg pageTimeout=60

Sets the page timeout to 1minute. After1 minute’s inactivity, the session willbe marked for deletion.

Sets the sessiontimeout for thecurrent page

DefaultTimeout valueas definedabove

homePage URL

eg homePage=”/index.htm”

Sets the URL towhich the user shouldbe redirected whenthey explicitly log outof the applicationusing theewdLogout.ewd page.

As defined inthe EWDconfigurationsettings fortheapplication


15

redirection “client” or “server”

eg redirection=”client”

CSP-specific optionalsetting. By default,EWD uses server-side redirection toimplement thenextPage mechanismwhen you submit aform. This is veryefficient, but cancause problems ifusers instruct theirbrowser to refresh thepage. Theseproblems can beavoided by usingclient-sideredirection, but thisrequires an extraHTTP round-trip tothe browser so is lessefficient.

JSP and PHPapplications willalways use client-sideredirection.

server

persistentRequest trueOrFalse

eg persistentRequest=”false”

Specifies whether ornot the HTTP requestname/value pairs areto be automaticallytransferred to thepersistent sessionobject within Caché.

Currently onlyimplemented in thePHP version. Notethat the use of thissetting will preventmost of theautomatedmechanisms in eXtcWeb Developer fromworking,

true

errorClass If you are using the automaticmechanism for highlighting form fieldsin error, specifiy the CSS style class tobe applied for all fields in error (seealso the setFieldError() API method)

eg errorClass=”myErrors”

Value must be adefined CSS styleclass.

N/a


16

pageTitle Text

eg pageTitle=”My First Page”

Specifies the title ofthe page. This setsthe special eXtc WebDeveloper sessionvariable$ewd_pageTitlewhich you can thenuse throughout yourpage, eg for the<title> tag and in thepage header caption.If these are defined inthe template page,then all you need tospecify in each pageis its pageTitleattribute in the<ewd:config> tag.

null

applyTemplate trueOrFalse

eg applyTemplate=”false”

Specifies whether ornot the templatefeatures (as specifiedin the ewdTemplate.ewd page) are to beapplied to this page.

true

overrideTemplate trueOrFalse

eg overrideTemplate=”true”

Specifies whether ornot the attributesspecified in thedesign page’s<ewd:config> tagshould be replacedby, or should overrideany that also appearin the template page’s<ewd:config> tag

false

ie <ewd:config>attributesspecified inthe templatedocument takeprecedence.

confirmText confirmMessageText Sets the defaultconfirm message textif you have used aconfirm attribute for asubmit button. Maybe overridden by aconfirmText attributein a submit buttonitself

“Click OK ifyou’re sureyou want todelete thisrecord”


17

secureRequest trueOrFalse

eg secureRequest=”false”

If set to true, onlyname/value pairs thatare explicitly definedin URLs and forms inthe design page arecopied automaticallyto the session object.

If set to false, allHTTP requestname/value pairs arecopied to the sessionobject

Only implemented inthe PHP version

true

errorPage pageName

eg errorPage=”myErrorPage”

PHP or JSPapplications: definesthe page that willhandle any run-timeerrors. If not defined,control will be passedto the default page(ewdError.php orewdError.jsp) whichis automaticallycreated by thecompiler.

This parameter doesnot apply to CSPapplications. Errortrapping andredirection to an errorpage in CSP must beconfigured using theCaché/CSPconfiguration tool.

ewdError


18

mgwsiServer

(Note : this supercedesthe mphpServerattribute which is nowdeprecated).

Name of the MGWSI gateway serverthat will access Caché.

eg mgwsiServer=”main”

This parameter onlyapplies to PHP or JSPapplications:

– defines the mgwsigateway servername that will beused whenaccessing Caché

It will be ignoredwhen compiling toCSP. For a CSPapplication, the CSPserver and namespaceis defined in theCaché ConfigurationManager

LOCAL

escapeText true or false

eg escapeText=”true”

Determines whetheror not toautomatically HTML-escape the values ofsession variables thatare used to display intext, hidden orpassword fields. Ifset to true, relevantHTML entities areused instead ofcharacters such asdouble and singlequotes, angle bracketsetc.

false

onErrorScript Function or method reference

eg onErrorScript=”myError^myRoutine”

Optionally defines afunction or methodthat will be invokedwhenever an erroroccurs in an actionscript. Thismechanism is notnormally used, butcan be used inspecific situationswhere, when an erroroccurs, you needmanipulate sessionvalues for example.

No onErrorScriptdefined.


19

arraySize Integer > 0

eg 256

Optionally defines thesize of the sessionarray in JSPapplications.

Not relevant for CSPor PHP applications

If you require verylarge amounts ofsession data storage,you may need toincrease this value.

To apply globally foran application, setthis parameter in the<ewd:config> tag ofthe application'stemplate(s),

128cachePage true or false

eg cachePage=”false”

Optionally causesHTTP headers to beadded to the page toprevent it beingcached.

true


20

<ewd:comment>Description This tag allows you to add comments to your design pages that will be removed at

compile time from the PHP, JSP or CSP page. Any text or child tags within a<ewd:comment> and </ewd:comment> tag pair will be removed from the compiledpage.


n/a n/a


21

<ewd:else>Description This tag may be used in conjunction with any of EWD's “if” tags, ie any tag whose

name starts with ewd:if

For example:

<ewd:if firstValue=”$xx” operation=”=” secondValue=”2”> <p>This is one line of text</p><ewd:else> <p>An alternative line of text</p></ewd:else>


n/a n/a


22

<ewd:elseif>Description This tag is used to specify an “elseif” conditional block of HTML, JavaScript or

other code within a design page. This tag may be used in conjunction with any ofEWD's “if” tags, ie any tag whose name starts with ewd:if, and also in conjunctionwith the <ewd:else> tag.

The <ewd:elseif> tag emulates a standard elseif condition, ie:

elseif firstValue {operation} secondValue

Eg, elseif $index > 10

firstValue = “$index”operation = “>”secondValue=”10”

eg

<ewd:if firstValue=”$index” operation=”=” secondValue=”1”> <p>Write out some HTML</p><ewd:elseif firstValue=”$index” operation=”=” secondValue=”2”><p>Write out some other HTML</p><ewd:else> <p>Write some different HTML</p></ewd:if>


firstValue The first value or variable preceeding theoperation. If this is a variable, it must bepreceeded by a “$” character.

Eg firstValue=”$index”

Usually a variable n/a

secondValue The second value or variable followingthe operation. If this is a variable, it mustbe preceeded by a “$” character.

Eg secondValue=”10”

Literal value orvariable

n/a

operation Defines the conditional operator

Eg operation=”=”

Usually a literal value

Specify “not equals”using the syntax “!=”

n/a


23

<ewd:execute>Description Invoke a Caché function or procedure within the page.

Note that although this incurs little penalty in CSP, there is a distinct overhead ininvoking a call to Caché from within a PHP or JSP page. You should do as muchprocessing as possible in your pre-page and/or action scripts, and only resort to<ewd:execute> when absolutely necessary.

Parameters can be literals, in-page variables and/or session variables, eg

<ewd:execute method="xyz^myRoutine" param1="abc" param2="$x"param3="#y">


method The method to be invoked

Eg method=”myProc^myRoutine”

Usually a litreral n/a

type procedure or function

If you specify a procedure, this equatesto a call of the form:

Do myProc^myRoutine

If you specify a function, this equates toa call of the form:

S returnValue=$$myFunc^myRoutine()

Usually a literal function

return If type=function, then the returnValue ispassed to the variable specified in thisattribute, eg

return=”$myReturnValue”

If type=procedure, this attribute isignored.

Usually a variable, inwhich case the firstcharacter should be a“$”

n/a


24

param1param2…paramn

Optional parameters, to be passed to theprocedure or function.

Eg param1=”jobDetails” param2=”$columnNo” param3=”#mySessionVar”

May be any of:

- literal value- page/local variable- session variable

Page/local variablesare specified byadding a leading “$”

Session variables arespecified by adding aleading “#”

n/a


25

<ewd:expandPage>Description This tag allows you to create and in-page variable that holds an expanded, tokenised

URL, representing a specified EWD page. Normally used for internal purposes, thistag may nevertheless be useful in situations where you wish to define a link to anEWD page. Most relevant situations are normally catered for by EWD's standardcustom tags, so this tag is unlikely to be used.

eg

<ewd:expandPage page=”myPage.ewd” return=”$url”>


page Name of the required EWD page,including its file extension.

n/a

return Local variable that will hold theexpanded, tokenised URL (specific to thetechnology of compilation)

Variable should beprefixed with “$” todenote a local pagevariable.

n/a


26

<ewd:for>Description This tag may be used to specify a “for” loop


from Initial start value for the loop.

If the value is held in a “local” variable,the attribute value should commence witha “$”

If the value is held in a session variable,the attribute value should commence witha “#”

Eg from=”1”

Starts the loop with a value of 1

from=”$start”

Starts the loop with the value held inthe PHP variable “$start” or the CSP/JSPvariable “start”

from=”#start”

Starts the loop with the value held inthe session variable named “start”

n/a


27

to Terminating value for the loop.



Eg to=”10”

Terminates the loop when a value of10 is reached

to=”$end”

Ends the loop with the value held in thePHP variable “$end” or the CSP/JSPvariable “end”

to=”#end”

Ends the loop with the value held in thesession variable named “end”

n/a

increment Increment value for the loop.



Eg increment=”1”

Increments the loop counter by 1

incrment=”$inc”

Increments the loop counter by the valueheld in the PHP variable “$inc” or theCSP variable “inc”

increment=”#inc”

Increments the loop counter by the valueheld in the session variable named “inc”

n/a


28

counter Specifies the local in-page variablename that will be used to hold the valueof the loop counter. The attribute valueshould always be specified as a variable,so its first character should be a “$”

Eg counter=”$counter”

The variable $counter may then be usedby any other relevant <ewd:*> tag insidethe <ewd:for> </ewd:for> block.

n/a


29

<ewd:forEach>Description This tag may be used to iterate through a session array structure.

Typically the array structure will have been instantiated into a session array within apre-page script, using the mergeArrayToSession() method. For example:

s table(1)=”abc” s table(2)=”def” s table(3)=”hij” d mergeArrayToSession^%zewdAPI(.table,"mySortableTable",sessid)

The <ewd:forEach> tag allows you to iterate through each index value – in thisexample these values will be 1,2 and 3 – and also each associated data value – in thisexample the values “abc”, “def” and “hij” respectively.

It is also possible to iterate through a local array structure using this tag. If you areusing CSP, a reserved local array (%ewdVar) is used. If you are using PHP, you mayuse any associative array (eg $myLocalArray). If you are using JSP, you may useany EWD-defined “local array”, created using the m_jsp.ma_local_set() method.


sessionName The name of the session array

In the example above, the sessionNamewould be “mySortableTable”

n/a

localName The name of the local array See notes aboveabout the use of localarrays in CSP, PHPand JSP.

Note: you must useeither sessionNameor localName, but notboth.

The localNameshould be specifiedwithout any leading“$”, even if usingPHP.

n/a

index Defines the CSP/PHP/JSP variable thatwill hold the value of the array index ateach iteration.

Eg index=”$rowId”

The attribute valuemust begin with a “$”to denote a variable.

n/a


30

return Defines the CSP/PHP/JSP variable thatwill hold the value of the array data ateach iteration

Eg return=”$data”


n/a

startValue Optional parameter that allows an initialvalue of the index to be specified. If thisvalue does not exist in the array, the nextvalue in collating sequence will beretrieved on the first iteration.

May be a literal or avariable


n/a

endValue Optional parameter that allows a lastvalue of the index to be specified.Iterations will cease when this value (or alater value in collation order) is found inthe array.

May be a literal or avariable


n/a

subscriptList

Note: this has beensuperceded by theparamn mechanismdescribed below.

Optional parameter that allows the use ofadditional array subscript values, in orderto iterate through lower levels of a multi-dimensional session array.

For example, if the array was creates inthe pre-page Script as follows:

s table(“row”,1)=”abc” s table(“row”,2)=”def” s table(“row”,3)=”hij” s table(“col”,1)=”Col 1” s table(“col”,2)=”Col 2” d mergeArrayToSession ^%zewdAPI(.table,"myTable", sessid)

The “row” level of this session arraycould be traversed using:

<ewd:forEach sessionName=”myTable”subscriptList=”row” index=”$rowNo”return=”$rowData”>

</ewd:forEach>


n/a


31


Note: thismechanism ispreferred to thesubscriptListattribute for definingintermediate arraysubscript values.

Optional parameter that allows the use ofadditional array subscript values, in orderto iterate through lower levels of a multi-dimensional session array.

For example, if the array was creates inthe pre-page Script as follows:

s table(“row”,1)=”abc” s table(“row”,2)=”def” s table(“row”,3)=”hij” s table(“col”,1)=”Col 1” s table(“col”,2)=”Col 2” d mergeArrayToSession ^%zewdAPI(.table,"myTable", sessid)

The “row” level of this session arraycould be traversed using:

<ewd:forEach sessionName=”myTable”param1=”row” index=”$rowNo”return=”$rowData”>

</ewd:forEach>

In general, if the session array is multi-dimensional, ie of the format:

Array(sessionName,param1,param2,…, Paramn)

..then define the additional parameters,specifying the array node required


May be any of:




A value of space (“ “)must be specifiedusing the specialpseudo-variable$space

A value of null (““)must be specifiedusing the specialpseudo-variable $nul

n/a


32

<ewd:getArrayValue>Description This tag is used to obtain the value of a local (in-page) CSP, JSP or PHP array. This

tag is currently limited to single-dimensioned arrays, ie of the form:

arrayName(index)=return

eg in CSP:

rowData(1)=”xyz”rowData(2)=”abc”

or, in PHP:

$rowData[1] == “xyz”$rowData[2] == “abc”

In JSP, arrays are mapped into the special m_jsp array structure.

Note: this should not be confused with a session array, for which other tags should beused.


arrayName The name of the local array n/a

index Defines the value of the array index.

This may be a literal value or a variable.If a variable is specified, it must bedenoted by a preceeding $ character.

n/a

return Defines the CSP/PHP/JSP variable thatwill hold the value of the array data forthe specified index


Must be a variable.


n/a


33

<ewd:getPiece>Description This tag is typically used within a <ewd:forEach> or similar tag, where the return

variable contains a list of values separated by an ASCII character (eg ASCII 1)

This tag can be used to extract one of the data values.


data The variable containing the multiplesubstrings of sub-data.

This must be a variable, and thereforemust have a preceeding “$” character.

Eg data=”$rowData”

Must be a variable n/a

asciiDelimiter Defines the ASCII value of the delimiterthat separates the sub-data strings withinthe data.

Eg asciiDelimiter=”1”

Normally a literalvalue

n/a

pieceNumber Defines the substring number (startingfrom 1) that should be extracted from thedata string.

Eg pieceNumber=”2”

Can be a literal valueor a variable

n/a

return Defines the CSP/PHP/JSP variable thatwill hold the value of the specifiedsubstring

Eg return=”$Col1”



34

<ewd:getSessionArrayValue>Description This tag is used to obtain the value from a session array for a specified index, or for a

specified node in a multi-dimensional array.

The session array will normally have been created within a pre-page script using amethod such as mergeArrayToSession().

For example, if the following array was created in your page’s pre-page script:

d deleteFromSession^%zewdAPI("testing",sessid) s myArray("column",99,123)="Hello world"d mergeArrayToSession^%zewdAPI(.myArray,"testing",sessid)

You now have a session array that is subscripted by the sessionName (“testing”) andthree further parameters (“column”,99,123)

If you further specify a session variable “mySessionVar” with a value of 123 d setSessionValue^%zewdAPI("mySessionVar",123,sessid)

In your page, you could test obtain the value of this array reference by using, for example:

<ewd :set return=”$colNo” value=99><ewd:getSessionArrayValue sessionName=”testing” param1=”column” param2=”$colNo” param3=”#mySessionVar” return=$arrayValue >

<p>The value is <?= $arrayValue ?></p>


sessionName The name of the session array n/a

index If this is a simple array of the format:

Array(sessionName,index)=value

..then index defines the value of thesession array index.

This may be a literal value or a variable.If a variable is specified, it must bedenoted by a preceeding $ character.

n/a


35


An alternative to using index. If thesession array is multi-dimensional, ie ofthe format:




May be any of:




A value of space (“ “)must be specifiedusing the specialpseudo-variable$space

A value of null (““)must be specifiedusing the specialpseudo-variable $nul

n/a

return Defines the CSP/PHP/JSP variable thatwill hold the value of the array data forthe specified index



n/a


36

<ewd:getSessionValue>Description This tag is used to obtain the value of a scalar session value.

The session array will normally have been created within a pre-page script using amethod such as mergeArrayToSession().


sessionName The name of the session variable n/a

return Defines the CSP/PHP/JSP variable thatwill hold the value of the specifiedsession variable



n/a


37

<ewd:if>Description This tag is used to specify a conditional block of HTML, JavaScript or other code

within a design page. It may be used in conjunction with an <ewd:else> tag

The <ewd:if> tag emulates a standard if condition, ie:

If firstValue {operation} secondValue

Eg, if $index > 10

firstValue = “$index”operation = “>”secondValue=”10”

eg

<ewd:if firstValue=”$index” operation=”=” secondValue=”1”> <p>Write out some HTML</p><ewd:else> <p>Write some different HTML</p></ewd:if>


firstVallue The first value or variable preceeding theoperation. If this is a variable, it must bepreceeded by a “$” character.

Eg firstValue=”$index”


secondVallue The second value or variable followingthe operation. If this is a variable, it mustbe preceeded by a “$” character.



n/a

operation Defines the conditional operator

Eg operation=”=”


Specify “not equals”using the syntax “!=”

n/a


38

<ewd:ifArrayExists>Description This tag is used to create a conditional block of markup that will execute if a

specified local (in-page) CSP, JSP or PHP array is instantiated. This tag is currentlylimited t

Note: this should not be confused with the <ewd:ifSessionArrayExists> tag which isused to detect the existence of a session array

eg

<ewd:ifArrayExists arrayName="ewdTabMenu">

<ewd:ifArrayExists arrayName="ewdTabMenu" param1=”1” param2=”$myVar”>


arrayName The name of the local array The name should notbe prefixed with a“$”, even if this isbeing compiled toPHP

n/a


If the session array is multi-dimensional,ie of the format:




May be any of:




n/a


39

<ewd:ifContains>Description This tag is used to specify a conditional block of HTML, JavaScript or other code


HTML within an <ewd:ifContains> …</ewd:ifContains> block will only berendered if the specified input variable contains the specified substring. The tagemulates the conditional statement :

If input contains subString

Eg, if $myVariable contains “hello”

input = “$myVariable”subString=”hello”

eg

<ewd:if Contains input=”$myVariable” substring=”hello”> <p>Write out some HTML</p><ewd:else> <p>Write some different HTML</p></ewd:ifContains>


input The literal value or, more likely, avariable that is to be tested. If this is avariable, it must be preceeded by a “$”character.

Eg input=”$myVariable”


subString The literal value of, or variablecontaining, the sub-string which is to betested for being contained in the input.

If this is a variable, it must be preceededby a “$” character.

Eg subString=”hello”

substring=$mySubString


n/a


40

<ewd:ifSessionArrayExists>Description This tag is used to specify a conditional block of HTML, JavaScript or other code


HTML within an <ewd:ifSessionArrayExists> …</ewd:ifSessionArrayExists>block will only be rendered if the specified session array node has been instantiated.

eg

<ewd:ifSessionArrayExists sessionName=”jobDetails” param1=”column” param2=”$colNo” param3=”#myVar” > <p>Write out some HTML</p><ewd:else> <p>Write some different HTML</p></ewd:ifSessionArrayExists>

For example, if the following array was created in your page’s pre-page script:

d deleteFromSession^%zewdAPI("testing",sessid) s myArray("column",99,123)="Hello world"d mergeArrayToSession^%zewdAPI(.myArray,"testing",sessid)

You now have a session array that is subscripted by the sessionName (“testing”) andthree further parameters (“column”,99,123)

If you further specify a session variable “mySessionVar” with a value of 123 d setSessionValue^%zewdAPI("mySessionVar",123,sessid)

In your page, you could test for the existence of this array reference by using, forexample:

<ewd :set return=”$colNo” value=99><ewd:ifSessionArrayExists sessionName=”testing” param1=”column” param2=”$colNo” param3=”#mySessionVar” >


sessionName The session variable or array that is to betested for its instantiation

Eg sessionName=”jobDetails”

Literal value n/a


41


Additional parameters, specifying thearray node required


May be any of:




n/a


42

<ewd:ifSessionNameExists>Description This tag is used to specify a conditional block of HTML, JavaScript or other code


HTML within an <ewd:ifSessionNameExists> …</ewd:ifSessionNameExists>block will only be rendered if the specified session variable or array has beeninstantiated.

eg

<ewd:if SessionNameExists sessionName=”jobDetails”> <p>Write out some HTML</p><ewd:else> <p>Write some different HTML</p></ewd:ifSessionNameExists>


sessionName The session variable or array that is to betested for its instantiation

Eg sessionName=”jobDetails”

Literal value n/a


43

<ewd:image><ewd:imageMap>

Description These tags are used in combination to provide a useful shorthand for assigning animage file to a specific value of a local or session variable.

eg

<ewd:image height=”100” width=”200”> <ewd:imageMap variableName=”#myVar” value=”1” src=”/images/one.jpg”> <ewd:imageMap variableName=”#myVar” value=”2” src=”/images/two.jpg”></ewd:image>

In this example, if the value of the session variable #myVar is “1”, then the image file/images/one.jpg will be displayed. If the value of #myVar is “2”, then the imagefile /images/two.jpg will be displayed. Each image will be displayed with a height of100 and a width of 200.

e

Attributes for <ewd:image>Name Value(s) Notes Default

height The height of the image to be displayed. Literal values, localvariables or sessionvariables may be usedto specify the value ofthis attribute.

n/a

width The width of the image to be displayed. Literal values, localvariables or sessionvariables may be usedto specify the value ofthis attribute.

n/a

Attributes for <ewd:imageMap>Name Value(s) Notes Default

variableName The variable whose value is to bemapped to an image file

A local variable orsession variable maybe used to specify thevalue of this attribute.

n/a

value The value to be mapped to an image file Literal value n/a

src The URL path for the mapped image file Literal value n/a


44

<ewd:include>Description Use this tag to include a defined block of tags into the current page at the location

defined by the <ewd:include> tag.

The tags to be included will be contained in the specified text file. The tags to beincluded can be anything that could normally be contained in an EWD page,including EWD custom tags and user-defined custom tags.

eg <ewd:include file=”myFile.inc”>


file Filename containing the block of tags tobe included. The file must exist in thefilepath containing the application'sEWD source pages.

The file extension may be anything youlike, but “ewd” is not recommended.

Eg file=”myTags.inc”

Literal value n/a


45

<ewd:incrementCounter>Description This tag may be used to increment an in-page variable, typically inside an

<ewd:forEach> loop

eg <ewd:incrementCounter return=”$count”>


return Use this attribute to specify the variablethat is to be incremented.

Note that if the return variable/counterdoes not exist, it is instantiatedautomatically on the first invocation ofthis tag

eg return=”$myCounter”

In-page variable :denoted by preceding$

n/a


46

<ewd:initialiseArray>Description This tag is used to delete and initialize a local array within either the CSP, PHP or

JSP environment for the current page. If the array already exists, its contents aredeleted.


arrayName The array that is to be initialized.

Eg arrayName=”myArray”

Literal value n/a


47

<ewd:instantiate>Description This tag is restricted for use in EWD pages that will be compiled to JSP or VB.Net,

allowing a local variable or array to be declared with a valid type.

Examples:

<ewd:instantiate name="myArray" type="array" size="64"><ewd:instantiate name="myString" type="String"><ewd:instantiate name="myInt" type="int"><ewd:instantiate name="myInt" type="int" initialvalue="1">

Note, in most circumstances, this tag is for internal use only and is automaticallyadded during compilation where appropriate, based on the use of other EWD customtags.

For all other technologies, this tag will be ignored and removed at compilation time.


name The variable or array to be declared Literal value n/a

type The type to be assigned to the variable orarray

Literal value.Possible values are:

– String– int– array

Note these are casesensitive

n/a

size If an array is declared, use this attributeto declare its size

Literal value(numeric)

n/a

initialValue You may optionally assign an initialvalue to a variable using this attribute.

Literal value

Applies to String orint types only

n/a


48

<ewd:javaScript>Description This tag is used to wrapper the contents of a JavaScript file which is retrieved into a

container page using <script language=javascript src=myJSPage.ewd></script>

This allows you to have a JavaScript file that contains session variables, andoptionally create them in a pre-page script.

The page should start with an <ewd:config> tag, eg:

<ewd:config firstpage=false applyTemplate="false">

followed by the <ewd:javaScript> tag, inside which is the entire JavaScript content.EWD will automatically add the correct Content-type HTTP header to the page.

For example:

<ewd:config firstpage=”false” applyTemplate="false"prepageScript="jsTest^rtTest"><ewd:javascript>myVar = '<?= #myVar ?>' ;function displayVar() { alert("myVar=" + myVar) ;}</ewd:javascript>

The pre-page script jsTest^rtTest contains the following:

jsTest(sessid) d setSessionValue^%zewdAPI("myVar","hello Rob",sessid) QUIT ""

If this page was saved as jstest2.ewd, then another page in the same application canuse it as follows:

<script language=javascript src=jstest2.ewd></script><body onload="displayVar()">

and the value of the variable myVar, generated in Caché, will be displayed as aJavaScript alert.


n/a n/a n/a n/a


49

<ewd:mergeToJSObject>Description This tag allows you to merge an entire EWD session object, or just a sub-tree of an

EWD session object to a corresponding Javascript Object hierarchy

eg:

<ewd:mergeToJSObject sessionName=”info.accounts.details”jsName=”ACCOUNT.properties” />

This will merge all property name/value pairs under the EWD session object“info.accounts.details” into the javascript object ACCOUNT.properties, where theywill appear as corresponding property name/value pairs. Note that the Javascriptobject parent level must already be instantiated within your page.

Eg

In EWD Session:

info.accounts.details.name = “Rob Tweed”info.accounts.details.city = “London”info.accounts.details.country = “UK”

The example tag above would create the javascript object properties:

ACCOUNT.properties.name = “Rob Tweed”ACCOUNT.properties.city = “London”ACCOUNT.properties.country = “UK”

ACCOUNT.properties would have to be already instantiated within the page for thisto work, eg:

<script language=”javascript”> ACCOUNT = {} ; ACCOUNT.properties = {} ;</script>

<ewd:mergeToJSObject sessionName=”info.accounts.details”jsName=”ACCOUNT.properties” />

Note that the same effect can be achieved using:

<script language=”javascript”> ACCOUNT = {} ; ACCOUNT.properties = {} ; EWD.utils.mergeObjectFromSession(“info.accounts.details”, “ACCOUNT.properties” ) ;</script>

However, if you compile to CSP or WebLink, the <ewd:mergeToJSObject> tag willbe more efficient, because the merging is done at page rendering time. With othercompilation targets (eg PHP, JSP), there is no performance difference, and bothtechniques require an Event Broker call-back to Cache.


50


sessionName The name of the EWD session objectparent node whose child properties are tobe copied

Literal n/a

jsName The name of the Javascript object parentnode to which the properties will copied

Literal n/a


51

<ewd:modulo>Description This tag is used to return the modulo of two numbers. This is often useful inside an

<ewd:forEach> loop to determine odd or even iterations (eg to set different styles)

eg:

<ewd:modulo return="$mod" data="$lineNo" modulus=”2”>


return The variable that will contain the resultof the modulo function

eg return=”$myMod”

Variable name,preceeded by $

n/a

data The variable whose modulo is to bedetermined

eg data=”$loopNo”

Variable name,preceeded by $

n/a

modulus The modulus to be applied

eg modulus=”2”

Literal or variablename

n/a


52

<ewd:moveTag>Description This tag is used toinstruct the EWD compiler to move a specified tag to the location

denoted by the <ewd:moveTag> tag.

This tag is normally used as part of a custom tag definition, and allows a custom tagto pull in page-specific tags, making a very powerful construct that would otherwiserequire complex DOM programming to achieve the same effect.

For a full description, see the documentation on custom tags.

eg:

<ewd:moveTag name="rt:tabs" deleteOuterTag="true" />

The <ewd:moveTag> will be replaced with the specified tag and its child nodes. ThedeleteOuterTag attribute allows you to also remove the moved tag, leaving just itschildren.


name Tag name that is to be moved to theplace denoted by the <ewd:moveTag>tag.

It is recommended that the specified tagis unique. It is normally an arbitrarilydefined custom tag, eg:

“rt:myDummyTag”

Literal value n/a

deleteOuterTag “true” or “false”

If set to true, not only is the<ewd:moveTag> removed from theEWD page DOM, but also the tag thatwas specified for moving. All that willbe left will the nodes that were childrenof the tag specified in the name attribute


FALSE


53

<ewd:refresh>Description This tag is used as a shorthand way of generating a <meta> tag that redirects to a

specified EWD page after a specified number of seconds. The <ewd:refresh> tagmay be placed anywhere in your Design Page. The compiler will remove this tag andcorrectly place the substituted <meta> tag in the page’s <head> section.

<ewd:refresh time=”900” url=”myNextPage.ewd”>

is the equivalent of specifying:

<meta http-equiv="refresh" content="900;url=myNextPage.ewd">


time Number of seconds of inactivity beforethe page automatically redirects to thespecified page

Usually a literal value n/a

url The EWD page name to which the pagewill redirect. The compiler will expandthe name and encode it and/or tokenise itappropriately



54

<ewd:replace>Description This tag is used to replace all occurrences of a substring within a string literal or

variable.


input The source string literal or variable

A variable is specified by putting a “$” infront of the name

Eg input=”$myString”


fromString The substring that is to be replaced if it isfound in the input


Eg fromString=”hello”


toString The substring that is to substitute eachoccurrence of the fromString


Eg toString=”there”


return The resulting string variable containingthe substituted substrings


Eg return=”$myNewString”



55

<ewd:responseHeader>Description This tag is used to set an HTTP Response Header

eg:<ewd:responseHeader name=”Content-type” value=”image/svg+xml”><ewd:responseHeader name=”Expires” suppress=”true”>


name HTTP Response Header name

Eg name=”Content-type”


value HTTP Response Header value

Eg value=”image/svg+xml”


suppress true or false

eg suppress=”true”

CSP-specific optionto suppress thecreation of HTTPheaders that areotherwise created bydefault.

The Expires header isone of the mainexamples. This iscreated by default byCSP, but you oftenneed to suppress it if,for example whensending an SVGgraphic stream.

false


56

<ewd:schemaForm>Description This tag is used to render an instance of a schema-linked form.

EWD's schema-linked forms mechanism allows you to define an XML schema whichis automatically mapped to a corresponding HTML form. Once you've defined theschema, all you need to do is place the <ewd:schemaForm> tag into a page, and theform will be automatically rendered according to the schema definition. By adding asubmit buttons with the built-in schemaForm action, the generated form willautomatically save its data into an XML instance document which corresponds to thelinked XML schema.

Example:

<ewd:schemaForm schemaName="#schemaName"instanceName="#instanceName"> <input type="submit" name="submit1" value="Submit" action="saveToDOM^%zewdSchemaForm" nextpage="myNextPage"> </ewd:schemaForm>


schemaName The name of the schema DOM (this willhave been created using EWD's schema-linked forms functionality)

Literal value orsession variable

n/a

instanceName Name of the instance XML documentthat currently holds existing data, and/orwill hold the new/edited data after formsubmission


n/a

suppressForm true or false

eg suppressForm=”true”

By default, the automatic form renderinglogic will generate the form fields insidea <form>....</form> tag pair. Thisdefault mode can be used for standaloneforms.

If you want to embed the generated formfields inside an existing form, you canuse this attribute to suppress theautomatica generation of the <form> and</form> tags.

false


57

<ewd:schemaViewInstance>Description This tag is used to display an instance of a schema-linked DOM, in displayable view

mode.

EWD's schema-linked forms mechanism allows you to define an XML schema whichis automatically mapped to a corresponding HTML form. Once you've defined theschema and saved an instance document from the auto-generated form, all you needto do is place the <ewd:schemaViewInstance> tag into a page, and the data in theinstance document will be automatically rendered according to the schema definition.

Example:

<ewd:schemaViewInstance instanceName="#instanceName"suppressNull="#suppressNull" suppressInvisible="#suppressInvisible"styleSheet="/myStyle.css" />


instanceName Name of the instance XML documentthat currently holds existing data, and/orwill hold the new/edited data after formsubmission

EWD can automatically determine theassociated schema from the referenceheld at the top of the instance document.


n/a

suppressNull true or false

eg suppressNull=”true”

By default, the automatic renderingengine will display fields that have datavalues of null. Use this attribute todisplay only non-null values


false

suppressInvisible true or false

eg suppressInvisible=”true”

When defining a schema-linked form,you can specify certin tags as beinginvisible (eg if they are simply used forgrouping sub-elements and don't containany useful data as such)

By default, the automatic renderingengine will display fields that have datavalues of null. Use this attribute todisplay only non-null values


false


58

styleSheet URL of stylesheet to be applied todisplay.

By default, the stylesheet that wasdefined in the associated schema isapplied to the rendered display. Thisattribute allows you to override thisstylesheet with any other. If used, it isthe responsibility of the author to ensurethat the class names match to the schema.


The stylesheetdefined in theassociatedschema isapplied.


59

<ewd:set>Description This tag is used set a local variable in the CSP, PHP or JSP page. It has two formats:

<ewd:set return=”$myVar” value=”123”>

This is the equivalent of {set} $myVar = 123

Or:

<ewd:set return=”$myVar” firstValue=”$x” operand=”+” secondValue=”3”>

This is the equivalent of {set} $myVar = $x + 3


return The variable to be created


Eg return=”$myNewString”


value The value to which the return variable isto be set.


Eg value=”hello”

Usually a literal n/a

firstValue A literal or variable value


Eg firstValue=”$x”

n/a

secondValue A literal or variable value



n/a


60

operand The operand to apply between thefirstValue and secondValue

eg operand=”+”

Note : to concatenate two substrings, usethe operand “_” (ie underscore). Thiswill be converted to “.” or “+” if youcompile to PHP or JSP respectively.

n/a


61

<ewd:setArrayValue>Description This tag is used set a local array value in the CSP, PHP or JSP page


arrayName The name of the array

Eg arrayName=”myArray”

Must be a literalvalue

n/a

index The array index whose value is to be set.


Eg index=”3”


value The value to which the array element isto be set.


Eg value=”hello”



62

<ewd:spinner>Description Creates a spinner control within your web page/form. This is a composite device

consisting of a text field and, to the right of it, two stacked buttons which incrementor decrement the integer value in the text field.

The default styles that are applied to the spinner components are defined in the fileewd.css that is generated by EWD's compiler. You may over-ride these styles ifrequired.

<ewd:spinner name="mySpinner" value="*" min="<?= #min ?>" max="<?= #max ?>" imagePath="/" increment="100" onUp="alert('up clicked!')" onDown="alert('down clicked!')" />


name Name and id that will be applied to thespinner's <input type=”text”> field.


value Default value that will be initiallydisplayed in the text field when the pageis first rendered.

Usually “*” whichapplied the value ofthe correspondinglynamed sessionvariable

n/a

size Optional attribute that allows you todefine the size attribute of the spinner's<input type=”text”> component

Usually a literal

2min Optional attribute that allows you to

define the minimum integer value for thespinner

Usually a literal

0max Optional attribute that allows you to

define the maximum integer value for thespinner

Usually a literal

999999999increment Optional attribute that allows you to

specify the speed with which the spinnerincrements/decrements

Number ofmilliseconds

100imagePath Optional attribute that allows you to

define the path holding the spinner'sbutton image file.

If you compile to CSP, PHP, JSP orASP.Net, the default images are“spinnerUp.gif” and “spinnerDown.gif”which reside in the same path as thecompiled pages.

If you compile to WebLink, you shoulduse this attribute to define the location ofthese files

Usually a literal


63

onUp Event handler to be applied as anonClick event to the increment/Up button


onDown Event handler to be applied as anonClick event to the decrement/Downbutton


onUporDown Event handler to be applied as anonClick event to both buttons


All otherattributes

eg onChange,class etc

Any other event handler orattribute may be defined, and willbe applied to the text fieldcomponent of the spinner.



64

<ewd:svg>Description This tag is a shorthand for the <object> tag that is used to create a placeholder for an

SVG page.

eg

<ewd:svg width=400 height=300 page="teamGraph">

This is synonymous with:

<object width=400 height=300 data=teamGraph.ewdtype="image/svg+xml"></object>


height Height of the SVG image Usually a litreral n/a

width Width of the SVG image Usually a litreral n/a

page The eXtc Web Developer page that willgenerate the SVG stream. The fileextension (.ewd) is optional.



65

<ewd:svgPage>Description This tag is used to create an HTTP response that contains an SVG stream.

If used, the page must contain just this tag and a <ewd:config> tag. If yourapplication uses a template, make sure you specify applyTemplate=false in the<ewd:config> tag.

The <ewd:svg> tag allows you to specify the method that is to be invoked on theCaché server to generate the SVG stream

The <ewd:svgPage> tag will automatically create an HTTP response that includes thecorrect Content-type header etc.

eg

<ewd:svgPage method="drawTeamGraph^ybcResults" param1="#ewd_sessid">


method The method to be invoked that willgenerate the SVG stream

Eg method=”myProc^myRoutine”



Optional parameters, to be passed to theprocedure or function.


May be any of:




n/a

Note for JSP Tomcat configuration:

By default, the Tomcat JSP compiler will add white space as a result of line-feeds between the various JSPdirective tags. Whist this rarely causes problems for HTML pages, it will prevent dynamically-generatedSVG content from working within your browser. Provided you are using Tomcat 5, you can fix this bychanging the configuration definition in your default web.xml file (normally found in the “\ProgramFiles\Apache Software Foundation\Tomcat 5.5\conf” path if you are using Windows).

Using a text editor, find the servlet definition for JSPs which will look something like this:

<servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>eXtc Web Developer : Session API and Design Page Tag Guide. Version 3.0.618: 9 October 2007. 2004-2007, M/Gateway Developments Ltd. All Rights Reserved

66

<init-param> <param-name>fork</param-name> <param-value>false</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet>

Add the following before the <load-on-startup> tag:

<init-param> <param-name>trimSpaces</param-name> <param-value>true</param-value> </init-param>

Save the web.xml file and then stop and restart Tomcat. Recompile your EWD page(s) and next time yourun the generated JSP pages, the leading white space should now be suppressed.


67

<ewd:trace>Description This tag may be used for debugging purposes. It set a value into the global ^%

zewdTrace. This global is automatically incremented.


text The text or value to be set into the traceglobal

Eg text=”running the xyz() method”

A variable may specified by putting a “$”in front of the name



68

<ewd:url>Description This tag is an alternative to the <ewd:expandPage> tag. It allows you to create an in-

page variable that holds an expanded, tokenised URL, representing a specified EWDpage. Normally used for internal purposes, this tag may nevertheless be useful insituations where you wish to define a link to an EWD page. Most relevant situationsare normally catered for by EWD's standard custom tags, so this tag is unlikely to beused.

eg

<ewd:url return="$fullUrl" url="$xpage" />


url Name of the required EWD page,excluding its file extension.

Literal value, localvariable or sessionvariable

n/a

return Local variable that will hold theexpanded, tokenised URL (specific to thetechnology of compilation)

Variable should beprefixed with “$” todenote a local pagevariable.

n/a


69

<form>Description eXtc Web Developer can be instructed to automate your forms


action ewd

eg: action=”ewd”

Only forms thatspecify the action as“ewd” will beprocessed by eXtcWeb Developer.This allows you toprovide your ownspecific formprocessing if youwish.

n/a

method “uploadFile”

eg: method=”uploadFile”

ie instead of the more usual “post” or“get”

Optional shortcutmechanism forspecifying a form thatwill allow file uploadvia HTTP. Ie, thisattribute creates aform tag as follows:

<form method="post"enctype="multipart/form-data">

See also <inputtype=”file”>

n/a


70

<input type=”text”><input type=”password”>

<input type=”hidden”>Description eXtc Web Developer can provide several shorthand mechanisms


focus trueOrFalse

eg focus=”true”

If set to true, eXtcWeb Developer willadd the necessaryJavaScript to forcefocus onto this fieldwhen the form isloaded into the user’sbrowser.

Does not apply totype=”hidden”

Focus=”true” shouldbe specified for onlyone field in the page.If more than one isspecified, the resultmay be unpredictable,but normally the lastfield specified willobtain focus.

false

value “*”

eg : value=”*”

If a value exists in thesession array/objectfor this field (iematched by fieldname), then its valueis automatically usedas a default.

This is synonymouswith using

value= ”<?= #fname ?>”

for a field namedfname

value=””

ie no value isdisplayed,even if itexists in thesession object


71

<input type=”radio”>Description eXtc Web Developer automates the checking of radio buttons

In most cases, simply specify the name for the radio button and populate sessionobject for the same name with the appropriate value, eg:

The radio button with the matching value will be automatically checked

Invoice: <input type=”radio” name=”payment” value=”i”>Cash: <input type=”radio” name=”payment” value=”c”>Credit Card: <input type=”radio” name=”payment” value=”cr”>

If the value of the session name “payment” is set to “c”, then the cash option will beautomatically checked.


autocheck yesOrNo

Eg autocheck=”no”

Allows you to disablethe automaticchecking mechanism

yes

checkUsing Optional Parameter, over-riding thedefault eXtc Web Developer radio buttonauto-checking mechanism.

Variable name (denoted by an initial $)that should be used to determine whetheror not the radio button should bechecked.

Eg checkUsing=”$activated”

Allows you to over-ride the automaticchecking mechanism

This is a usefulmechanism if you areusing a radio buttonwithin a<ewd:forEach> loop

The normalauto-checkingmechanism isapplied if thisattribute is notspecified.


72

<input type=”checkbox”>Description eXtc Web Developer automates the checking of checkboxes

In most cases, simply specify the name for the checkbox and populate the Selectedarray in the session object for the same name with the appropriate value, eg:

The checkbox button with the matching value will be automatically checked

Red: <input type=”checkbox” name=”colour” value=”r”>Blue: <input type=”checkbox” name=”colour” value=”b”>Green: <input type=”checkbox” name=”colour” value=”g”>

Any matching value that is set in the Selected array for this field name within theSession object will result in the associated checkbox being checked.

When submitted, the Selected array will be repopulated automatically from thevalues that were checked by the user.


autocheck yesOrNo

Eg autocheck=”no”

Allows you to disablethe automaticchecking mechanism

yes

checkUsing Optional Parameter, over-riding thedefault eXtc Web Developer checkboxauto-checking mechanism.

Variable name (denoted by an initial $)that should be used to determine whetheror not the checkbox should be checked.



This is a usefulmechanism if you areusing a checkboxwithin a<ewd:forEach> loop



73

<input type=”file”>Description eXtc Web Developer provides a technology-independent mechanism for file

uploading.

The appropriate logic will be added to your page to ensure that the uploaded file issaved with the filename and in the file path you require for your application.

Note: This is available for CSP and PHP only. JSP does not provide a standardmechanism for HTTP-based file uploading, but a number of servlets are freelyavailable to facilitate this. These all work differently, so for the current EWDrelease, we have not provided a wrappered technique for JSP.


filePath Session variable or literal value thatdefines the path and filename to whichthe uploaded file should be saved.

Eg filePath=”#myFile”

filePath=”d:\myPath\myFile.txt”

If you use a sessionvariable, the namemust start with a “#”

Set the sessionvariable value in theactions script that isinvoked when the fileupload form issubmitted.

n/a


74

<select>Description eXtc Web Developer automates the creation of the drop-down list options for a

<select> tag

In most cases, simply specify the name for the <select> tag and populate the Listarray in the session object, eg:

<select name=”country></select>

Note that you must explicitly specify the closing tag. Using the empty tag syntax (ie<select name=”country />) will not work.

The recommended mechanism for defining <option> tags in EWD is to use the$$appendToList or $$addToList API methods within your pre-page scripts.


useList ListName

Eg useList=”country”

Allows you to use theList array for anotherfield name. This is auseful performanceoptimization if youhave several drop-down lists in a pagethat use the same setof options.

If notspecified, it isassumed thatthe optionswill bedefined in theList array forthe matchingsession objectname.

checkUsing Optional Parameter, over-riding thedefault eXtc Web Developer select auto-checking mechanism.

Variable name (denoted by an initial $)that should be used to determine whichoption should be checked.





75

<textarea>Description eXtc Web Developer automates the creation of the text content for a <select> tag

Simply specify the name for the <textarea> tag and populate the text array in thesession object, eg:

<textarea name=”comments”>*</textarea>

Note that you must explicitly specify the closing tag. Using the empty tag syntax (ie<textarea name=”comments />) will not work.

Note also that you must specify an asterisk (*) between the opening and closing<textarea> tags.


n/a


76

<input type=”button”>Description eXtc Web Developer can be instructed to automate a clickable button in terms of the

back-end action that it invokes and the next page to which the user is taken.

The scenario that eXtc Web Developer usefully automates is where a loopingconstruct creates a repeating group of buttons (eg one per row in a table). You willwant the button in each row to run the same action and go to the same next page, butyou’ll want to pass in one or more name/value pairs that relate to the specificiteration of the loop.


action methodCall

where methodCall can be a call to a Cachéextrinsic function, a Caché method or aPHP function.

eg:

action=”myFunc^myRoutine”

action= ”##class(myPckge.myClass).myMethod”

action=”$myPHPFunc”

eg: action=”ewd”

Caché methods thatare used as Actionscripts must returneither a null value(indicating success)or a string value(indicating anerror). The stringvalue returned inthe event of anerror should be theerror messageassociated with theerror that occurred.

If no actionattribute isspecified, thenno actionmethod isinvoked. Inthis situation,if a nextpageattribute isspecifed, thenthe user willbe takenuncondition-ally to thespecifiedpage.


77

nextpage pageName

eg nextpage=”myNextPage”

Note that the page name should not includea file extension (neither .php nor .ewd).The nextpage can be defined via a PHP,CSP or JSP variable, in which case thevariable name is preceded by a “$”,eg:

nextPage=”$myPHPVar”nextPage=”$myCSPVar”

The key difference with the use of thenextpage with this tag is that you canspecify additional name/value pairs to bepassed to the Caché back end. The syntaxis as follows:

nextPage=”pageName?name1=value1 &name2=value2….etc”

To pass in the value of a PHP, CSP or JSP“local” variable, substitute the value withthe name of the variable, prefixed with a“$”, eg:

nextPage=”myPage?recordNo=$recNo”

To pass in the value of a PHP, CSP or JSPsession variable, substitute the value withthe name of the session variable, prefixedwith a “#”, eg:

nextPage=”myPage?recordNo=#recNo”

You can also pass in values from the page’sobject model, by passing in JavaScriptvalues. You can only pass in JavaScriptvalues from the document object, sotypically you’ll need to use form fields,either visible or hidden, depending on whatyou’re doing. For example:

nextPage=”myPage?recordNo=$recNo&format=document.compForm.xformat.Value”

This would feed in the value of the xformatfield. This may be a visible form field or ahidden one.To use a JavaScript variable in this syntax,it must start with the characters“document.” or, if not in the documentobject, prefix the JavaScript reference with“javascript.”. If you prefix with“javascript.”, it is simply used as a signal tothe EWD compiler, and is stripped from thebeginning of the JavaScript reference.

Specifies the nextpage to which theuser will be taken.If action is defined,the user will onlybe taken to thenextpage if no erroroccurred. If anerror occurred inan action script, theuser will bereturned to thecurrent page

If nextpage isnot specified,the user willbe returned tothe currentpage,


78

Note: if you speficy the special, reservedname/value pair name of“ewdAllFields=true”, then all form fieldsfor the form that contains the button will besubmitted when the button is clicked Thisprovides a useful shortcut instead ofspecifying each of the form fieldsindividually.

Note that all name/value pairs that arespecified after the nextPage will beautomatcally instatiated in the sessionarray/object. This also applies if theewdAllFields mechanism is used.

confirm trueOrFalse

eg confirm=”true”

If confirm=”true”,the user will bepresented with aJavaScript confirmwindow, asking theuser to confirm theaction. This ismost usuallyassociated with asubmit button thatwill deletesomething. Thisallows the user toprotect againstaccidental pressingof such a submitbutton.

eXtc WebDeveloper willprovide a defaultquestion/messagein the confirmwindow, but youcan override thiswith theconfirmTextattribute.

false

confirmText confirmMessageText

eg: confirmText=”Click OK if you want todelete this attachment”

Specifies the textmessage/questionto appear in theJavaScript confirmwindow if you havespecifiedconfirm=”true”

"Click OK ifyou're sureyou want todelete thisrecord"

Note: If you define an action script and/or nextpage for a button, then it is important tounderstand that the linkage to the button is via the name attribute of the button. Every


79

button and/or submit button in a page must therefore be uniquely named, even if thebuttons are conditionalised inside <ewd:if> or equivalent tags.


80

<input type=”submit”><input type=”image”>

Description eXtc Web Developer can be instructed to automate many of the operations relating tothe submission of a form


action methodCall

where methodCall can be a call to aCaché extrinsic function, a Caché methodor a PHP function.

eg:




Caché methods thatare used as Actionscripts must returneither a null value(indicating success)or a string value(indicating an error).The string valuereturned in the eventof an error should bethe error messageassociated with theerror that occurred.


nextpage pageName


Note that the page name should notinclude a file extension (neither .phpnor .ewd)

Specifies the nextpage to which theuser will be taken. Ifaction is defined, theuser will only betaken to the nextpageif no error occurred.If an error occurred inan action script, theuser will be returnedto the current page.

If the next page towhich the user shouldbe redirected isconditional on therun-time data, thenyou should use thesetRedirect() APImethod in your actionscript to specify thepage, and specify anominal, default pagein the nextpageattribute.

If nextpage isnot specified,the user willbe returned tothe currentpage


81

confirm trueOrFalse

eg confirm=”true”

If confirm=”true”, theuser will be presentedwith a JavaScriptconfirm window,asking the user toconfirm the action.This is most usuallyassociated with asubmit button thatwill delete something.This allows the userto protect againstaccidental pressing ofsuch a submit button.

eXtc Web Developerwill provide a defaultquestion/message inthe confirm window,but you can overridethis with theconfirmText attribute.

false

confirmText confirmMessageText

eg: confirmText=”Click OK if you wantto delete this attachment”

Specifies the textmessage/question toappear in theJavaScript confirmwindow if you havespecifiedconfirm=”true”

"Click OK ifyou're sureyou want todelete thisrecord"

target Target name

Allows you to speficy a target (eg aframe or window) to which the nextpagewill be directed.

Eg:

target=”rightFrame”

Literal value

If the target does notexist, a new windowwill be opened by thebrowserautomatically, butyou will not havecontrol over itsdimensions orposition

Currentwindow/frame

Note: You can add your own onClick event handler to a submit button. eXtc WebDeveloper will append your event handler logic at the end of its own generated logic.

Your onClick event handler may be designed to conditionally suppress or allow thesubmit button to work, eg:

<script language=”javascript”>function myFunc() { return false ;}</script>


82

<input type=”submit” name=”submit” value=”submit” nextpage=”myNextPage”action=”myFunc^myRoutine” onclick=”return myFunc()”>

If the JavaScript function returns false, the submit button will be correctly suppressed.

If you want to include a Confirm message, then reword your onClick event handler toread:

onClick=”if (!myFunc()) return false”

This will allow the Confirm message to correctly display if the submit is not suppressed.

Note (2) : If you define an action script and/or nextpage for a submit button, then it isimportant to understand that the linkage to the button is via the name attribute of thebutton. Every button and/or submit button in a page must therefore be uniquely named,even if the buttons are conditionalised inside <ewd:if> or equivalent tags.


83

All <input> tags, except <input type=submit>Description You can make any input tag invoke a submit. You specify the Event Handler that

you wish to invoke the submission, and specify the action, nextpage and thename/value pairs that should be passed to the Caché back-end. These name/valuepairs can include:

• Literal values• Local (ie in-page) variables• Session variables• JavaScript object references and variables

All declared name/value pairs are automatically instantiated as session variables, socan be accessed subsequently using, eg the $$getSessionValue() method.


event eventHandler

eg event=”onClick”

The event thatwill trigger thesubmission.

n/a

action methodCall

where methodCall can be a call to a Cachéextrinsic function, a Caché method or a PHPfunction.

eg:




Caché methodsthat are used asAction scriptsmust returneither a nullvalue (indicatingsuccess) or astring value(indicating anerror). Thestring valuereturned in theevent of an errorshould be theerror messageassociated withthe error thatoccurred.



84

nextpage pageName


Note that the page name should not include afile extension (neither .php nor .ewd)

The nextpage can be defined via a PHP, JSPor CSP variable, in which case the variablename is preceded by a “$”,eg:

nextPage=”$myPHPVar”nextPage=”$myCSPVar”

The key difference with the use of thenextpage with this tag is that you can specifyadditional name/value pairs to be passed to theCaché back end. The syntax is as follows:

nextPage=”pageName?name1=value1 &name2=value2….etc”

To pass in the value of a PHP, JSP or CSP“local” variable, substitute the value with thename of the variable, prefixed with a “$”, eg:

nextPage=”myPage?recordNo=$recNo”

To pass in the value of a PHP, JSP or CSPsession variable, substitute the value with thename of the session variable, prefixed with a“#”, eg:

nextPage=”myPage?recordNo=#recNo”

You can also pass in values from the page’sobject model, by passing in JavaScript values.You can only pass in JavaScript values fromthe document object, so typically you’ll needto use form fields, either visible or hidden,depending on what you’re doing. Forexample:

nextPage=”myPage?recordNo=$recNo&format=document.compForm.xformat.value”

This would feed in the value of the xformatfield. This may be a visible form field or ahidden one. To use a JavaScript variable inthis syntax, it must start with the characters“document.” or, if not in the document object,prefix the JavaScript reference with“javascript.”. If you prefix with “javascript.”,it is simply used as a signal to the EWDcompiler, and is stripped from the beginning ofthe JavaScript reference.

Specifies thenext page towhich the userwill be taken. Ifaction isdefined, the userwill only betaken to thenextpage if noerror occurred.If an erroroccurred in anaction script, theuser will bereturned to thecurrent page

If nextpage isnot specified,the user willbe returned tothe currentpage,


85

Any tags with a href, src, data or url attributeDescription You can specify a reference to a design page (ie a .ewd page) by using the .ewd file

extension in any of these tags.

Tags to which this applies includes:

• <a>• <img>• <object>• <frame>• <meta>


href

src

data

url

pageName.ewd

eg <a href=”myNextPage.ewd”> Go to my next page</a>

If you are running inPHP or JSP, thecompiled PHP or JSPpage will beautomaticallyprotected by a sessiontoken and a pagetoken.

n/a


86

Any tags that accept an event handlerDescription eXtc Web Developer automates the generation of pop-up windows.

The automation is triggered by the popup attribute with a non-null value, eg:

<form><input type=”button” name=”help1” value="Help" popup="eHelpWindow" page="sysConfigHelp" event="OnClick" x=50 y=50 height=400 width=600></form>


popup windowName

eg popup=”eHelpWindow”

The name is arbitrary and is used as theJavaScript window name.

Specifies that a pop-up window should betriggered and openedwhen the specifiedevent occurs

No pop-upwill becreated

event eventHandler

eg event=”onClick”

The event that willtrigger the pop-up.

Must be used togetherwith the eventattribute

onClick

onClickPre JavaScript to be applied before the pop-up is generated

eg:

onclickPre="personID = selectPerson() ;if(personID != '') {"

N/a

onClickPost JavaScript to be applied after the pop-upis generated

eg:

onclickPost="}"

Note the way that the above pre- andpost- code allows the pop-up to occurconditionally.

N/a


87

page pageName

eg page=”sysConfigHelp”

The file extension (.php or .ewd) shouldnot be specified unless you are specifyingadditional name/value pairs. You canspecify additional name/value pairs to bepassed to the Caché back end. Thesyntax is as follows:

page=”pageName.ewd?name1=value1 &name2=value2….etc”

To pass in the value of a PHP, JSP orCSP “local” variable, substitute the valuewith the name of the variable, prefixedwith a “$”, eg:

page=”myPage.ewd?recordNo=$recNo”

To pass in the value of a PHP, JSP orCSP session variable, substitute the valuewith the name of the session variable,prefixed with a “#”, eg:

page=”myPage?recordNo=#recNo”

You can also pass in values from thepage’s object model, by passing inJavaScript values, eg from hidden orvisible form fields. For example:

page=”myPage?recordNo=$recNo&format=document.compForm.xformat.value”

This would feed in the value of thexformat field. This may be a visibleform field or a hidden one.

To use a JavaScript variable in thissyntax, it must start with the characters“document.” or, if not in the documentobject, prefix the JavaScript referencewith “javascript.”. If you prefix with“javascript.”, it is simply used as a signalto the EWD compiler, and is strippedfrom the beginning of the JavaScriptreference.

Specifies theapplication pagename that willpopulate the pop-upwindow when it iscreated.

No page willbe used topopulate thepop-upwindow

x windowXCoord

eg x=”50”

Specifies the x-coordinate of thepop-up window’s topleft corner (in pixels)

0


88

y windowYCoord

eg y=”50”

Specifies the y-coordinate of thepop-up window’s topleft corner (in pixels)

0

width windowWidth

eg width=”300”

Specifies the width ofthe pop-up window(in pixels)

100

height windowHeight

eg height=”400”

Specifies the heightof the pop-up window(in pixels)

100

toolbar yesOrNo

eg toolbar=”yes”

Specifies whether ornot to add thebrowser toolbar to thepop-up window

no

location yesOrNo

eg location=”yes”

Specifies whether ornot to add thebrowser locationwindow to the pop-upwindow

no

directories yesOrNo

eg directories=”yes”

Specifies whether ornot to add thedirectory selectiondevice to the pop-upwindow

no

status yesOrNo

eg status=”yes”

Specifies whether ornot to add the statusline to the bottom ofthe pop-up window

no

menubar yesOrNo

eg menubar=”yes”

Specifies whether ornot to add thebrowser menu bar tothe pop-up window

no

scrollbars yesOrNo

eg scrollbars=”no”

Specifies whether ornot to add a scrollbar(if needed) to thepop-up window

yes

resizable yesOrNo

eg resizable=”no”

Specifies whether ornot the pop-upwindow should beresizable by the user

yes


89

Any tags that accept an event handlerDescription eXtc Web Developer can allow a browser event to be handled by the Caché back-end

system.

The values of JavaScript can be passed to the Caché method that is invoked. TheCaché method can either return a null value (no action on the browser) or a string ofJavaScript commands and/or methods that will be executed within the browser, eg tomodify the values of form fields.

Note that the same syntax can be used within a JavaScript function, eg:

<script language=”javaScript”> function myFunc() { a = document.myForm.myField.value ; ewd:myCacheFunction(a) ; }</script>


OnXxxx

ie any event handler

ewd:CacheMethodName(paramList)

eg onClick=”ewd:checkValue(this.value)”

Specifies a Cachémethod that will beinvoked when thespecified eventoccurs.

No eventhandler willbe invoked


90

Any JavaScript containing a document.location referenceDescription You can specify a design page (ie a .ewd page) by using the .ewd file extension.

For example:

<script language=”JavaScript”> function myFunc() { document.location = “myNextPage.ewd” ; } function myAlternativeFunc() { document.location.href = “myOtherPage.ewd” ; }</script>


n/a n/a


91

Tags used within Template Pages

This section details the special tags that may be specified in the template page(ewdTemplate.ewd).


92

<ewd:template>Description This tag is used as the document element (ie outer tag) of an ewdTemplate.ewd page.


n/a


93

<ewd:head>Description This tag is used as a wapper tag to define a chunk of HTML (including JavaScript

and Style Sheets) to be placed at the start of the <head> section of the application’spages.


n/a


94

<ewd:header>Description This tag is used as a wapper tag to define a chunk of HTML (including JavaScript) to

be placed at the start of the <body> section of the application’s pages.


n/a


95

<ewd:footer>Description This tag is used as an outside wapper tag to define a chunk of HTML (including

JavaScript) to be placed at the end of the <body> section of the application’s pages.


n/a


96

<ewd_body>Description This tag is used to define default <body> tag attributes that will be added to the

<body> tags of each application page..


Any <body> attribute If any event handlers(eg onLoad) aredefined in both the<ewd_body> tag andan application page,then the event handlerin the applicationpage is appendedafter the eventhandler defined in the<ewd_body> tag,

All other attributesthat are defined in anapplication page areoverridden if thesame attribute isdefined in the<ewd_body> tag.


97

<ewd:backdrop>Description This tag is used as an outside wapper tag to define a chunk of HTML (including

JavaScript) within which each application page will be inserted (see ewd:insertPage).


n/a


98

<ewd:block>Description This tag defines a block of markup within a target EWD page that will be inserted

into a corresponding <ewd:insertBlock> tag in the template page, matching by id.

Eg, if the template was as follows:

<ewd:template><ewd:backdrop>...some markup <ewd:insertBlock id=”block1” />....some more markup <ewd:insertBlock id=”block2” />...some more markup</ewd:backdrop></ewd:template>

then the page would be defined as follows:

<ewd:config ....>

<html><head>....</head><body>

<ewd:block id=”block1”> ....markup for block 1</ewd:block>

<ewd:block id=”block2”> ....markup for block 2</ewd:block>

</body></html>

Note that multiple template blocks can also be used with Ajax page fragments.


id The id of the target page block to beinserted into the corresponding template<ewd:insertBlock> tag

Literal value N/a


99

<ewd:content>Description This tag is used in include files (see <ewd:include>). The content of include files

must be wrappered in the <ewd:content> tag. Any HTML outside the <ewd:content>tag will be ignored.


n/a


100

<ewd:insertBlock>Description This tag allows multiple insertion points to be defined within a template document.

The target page is defined as a set of blocks using <ewd:block> tags, which are theninserted at compile time into the associated <ewd:insertBlock> tags within thetemplate backdrop.

Eg:

<ewd:template><ewd:backdrop>...some markup <ewd:insertBlock id=”block1” />....some more markup <ewd:insertBlock id=”block2” />...some more markup</ewd:backdrop></ewd:template>


id The id of the target page block to beinserted into the template backdrop

Literal value N/a


101

<ewd:insertPage>Description This tag is used inside an <ewd:backdrop> tag to define the point at which the

<body> section of each application page is inserted (excluding the application page’s<body> tag)


n/a


102

<ewd:include>Description This tag is used as an outside wapper tag to define a chunk of HTML (including

JavaScript) that will be used to replace a matching <ewd:include> tag withinapplication pages.


id idReference

eg: id=”myIncludeBlock”

A text string thatuniquely identifiesthe include block

n/a

file Filename of file containing include block

eg: file=”adverts.inc”

Filenames MUSThave an extension of .inc and their contentsmust start with a<ewd:content> tagand end with a</ewd:content> tag.The file must exist inthe same directorypath as the .ewd files.

Note that a templatepage may contain<ewd:include> tagswhose contents aredefined in a file.

n/a


103

The Session API Methods

The following section details the methods and functions that are available to you formanipulating the Session object.

All the methods and functions are contained in the routine ^%zewdAPI. The generalcalling interfaces are:

s value=$$function^%zewdAPI(param1,param2,sessid)

d procedure^%zewdAPI(param1,param2,sessid)

All methods require the session ID to be passed as a parameter. Your pre-page and actionscripts will be automatically passed this as their one and only parameter. By convention,your scripts should use the variable sessid for this purpose.

HTML Form Field Mapping in eXtc Web Developer

EWD automatically maps HTML form element values to corresponding Session Objectvalues.

EWD abstracts the physical session object creation and manipulation so that you use thesame API methods irrespective of the run-time technology that you choose to use. If youcompile to CSP, EWD makes use of EWD's own session object. EWD handles the verydifferent ways in which these three run-time environments behave : as far as you, thedeveloper, is concerned, EWD applications appear to behave identically regardless of therun-time technology you decide to use.

If you compile to PHP or JSP, EWD uses its own session persistence mechanism : ieEWD pages running in PHP and JSP do not use the session mechanisms that are built into those technologies. EWD automatically projects and synchronises the session arraydata structure between the PHP or JSP environment and the Caché environment. Henceif you create a session variable within a pre-page script within Caché , it will beautomatically available as the same named session variable within the PHP or JSP page.

When an HTML form is submitted, or a URL that includes name/value pairs is invoked,EWD automatically maps the values of the form fields or the name/value pairs tocorrespondingly named session values within Caché. For security reasons, only thoseform fields or name/value pairs that were detected by EWD during compilation of thepage will be automatically mapped in this way.

Three basic session data structures are used in the HTML field mapping:

• single value fields (eg text fields, radio buttons, single-value select tags);• multi-value fields (eg radio buttons, multiple-value select tags);• textArea fields.eXtc Web Developer : Session API and Design Page Tag Guide. Version 3.0.618: 9 October 2007. 2004-2007, M/Gateway Developments Ltd. All Rights Reserved

104

Note that in addition to these HTML form-specific session data structures, EWD providesother APIs for creating and manipulating your own custom session data structures (egmulti-dimensional arrays).

In your pages' pre-page scripts, you will typically fetch the appropriate data from yourclasses or globals for the page. You then invoke the EWD functions that correctly mapyour data values to the corresponding HTML form field types in your page. In order tomake the process as intuitive and as clearly understandable as possible, EWD providesspecific APIs for this mapping (these actually invoke the more primitive EWD sessionAPIs for the three data structures listed above). The ones that you will probably use mostfrequently are listed below (for full details of each API method, see the detaileddescriptions in the next chapter):

API Methods for mapping to HTML fieldssetTextValue() Maps a Caché value to an HTML text field. The value

will appear in the text field. eg:

<input type=”text” name=”username” value=”*”>

Synonymous with setSessionValue(), this methodcreates the named session variable and assigns a singlevalue to it.

setHiddenValue() Maps a Caché value to an HTML hidden field. Thevalue will be set into the hidden field in the web pagewhen it is rendered. eg:

<input type=”hidden” name=”username” value=”*”>


setRadioOn() Maps a Caché value to an HTML radio button, andcauses it to be checked, eg:

<input type=”radio” name=”colour” value=”r”>


Note that there is no setRadioOff() method. A radiobutton is turned off by setting another value on.


105

initialiseCheckbox() Clears down the session array used for the specifiedcheckbox field name, resulting in all checkboxes for thefield name to be unchecked.

Synonymous with clearSelected()setCheckboxOn() Maps a Caché value to an HTML checkbox, and causes

it to be checked, eg:

<input type=”checkbox” name=”states” value=”CA”>

Synonymous with addToSelected(), this method willallow one or more values to be assigned to a namedsession array.

setCheckboxOff() Maps a Caché value to an HTML checkbox, and causesit to be un-checked, eg:

<input type=”checkbox” name=”states” value=”CA”>

Synonymous with removeFromSelected(), this methodremoves one of the values assigned to a named sessionarray.

setSelectValue() Maps a Caché value to an HTML single-choice <select>tag, and causes the specified option to be highlighed andselected, eg:

<select name=”colour”> <option value=”r”>Red</option> <option value=”b”>Blue</option></select>


Note that there is no unsetSelectValue() method. Asingle-choice <select> option is un-highlighed anddeselected by setting another value.

initialiseMultipleSelect() Clears down the session array used for the specifiedmultiple-choice <select> tag, resulting in all optionsbeing un-highlighted and de-selected.

Synonymous with clearSelected()


106

setMultipleSelectOn() Maps a Caché value to an HTML multiple-choice<select> tag option, and causes it to be highlighted andpre-selected, eg:

<select name=”colour” multiple=”multiple”> <option value=”r”>Red</option> <option value=”b”>Blue</option></select>

Synonymous with addToSelected(), this method willallow one or more values to be assigned to a namedsession array.

setMultipleSelectOff() Maps a Caché value to an HTML multiple-choice<select> tag option, and causes it to be un-highlightedand de-selected, eg:

<select name=”colour” multiple=”multiple”> <option value=”r”>Red</option> <option value=”b”>Blue</option></select>

Synonymous with removeFromSelected(), this methodremoves one of the values assigned to a named sessionarray.

createTextArea() Maps a Caché local array of text to an HTML textareafield.

This method creates a session array that is specificallydesigned for manipulating textarea text.

By the time your pages' action scripts are invoked by EWD, the values of HTML formfields (or URL name/value pairs) will have been automatically mapped into thecorresponding session object by EWD. Typically your action script will validate and savethe data into your classes or globals. EWD provides you with a set of API methods foreasily and intuitively extracting the submitted form values from the session object.

The ones that you will probably use most frequently are listed below (for full details ofeach API method, see the detailed descriptions in the next chapter):


107

API Methods for mapping from HTML fieldsgetTextValue() Maps a submitted HTML text field to a Caché value .

<input type=”text” name=”username” value=”*”>

Synonymous with getSessionValue(), this methodretrieves the value from the named session variable.

getPasswordValue() Maps a submitted HTML password field to a Cachévalue .

<input type=”password” name=”myPassword”>


getHiddenValue() Maps a submitted HTML hidden field to a Caché value .

<input type=”hidden” name=”myPassword”>


getRadioValue() Maps the checked value of a submitted HTML radiobutton field to a Caché value .


isRadioOn() Determines whether or not the specified value for aradio button was checked when the form was submitted.

isCheckboxOn() Determines whether or not the specified value for acheckbox was checked when the form was submitted.

getSelectValue() Maps the highlighted, selected option of a submittedsingle-choice HTML <select> tag to a Caché value .


isSelectOn() Determines whether or not the specified option of asingle-choice <select> tag was highlighted and selectedwhen the form was submitted.

isMultipleSelectOn() Determines whether or not the specified option of amultiple-choice <select> tag was highlighted andselected when the form was submitted.

Synonymous with isSelected()


108

getTextArea() Maps the submitted text contained within the specifiedtextarea field into a Caché local array.

Synonymous with mergeFromTextArea()


109

Summary of EWD API methods

The full set of EWD API methods is summarised below:

Single Value Form FieldsRelevant Fields <input type=text>

<input type=password><input type=hidden><input type=radio><select>

Associated Methods addToSessiondeleteFromSessiongetSessionValuegetTextValuegetPasswordValuegetHiddenValuegetRadioValuegetSelectValueisRadioOnisSelectOngetSessionValuessetSessionValuesetTextValuesetHiddenValuesetRadioOnsetSelectValuesetSessionValuesclearSessionByPrefix


110

Multi-Value Form FieldsRelevant Fields <input type=checkbox>

<select multiple=multiple>

Associated Methods initialiseCheckboxsetCheckboxOnsetCheckboxOffsetCheckboxValuesinitialiseMultipleSelectsetMultipleSelectOnsetMultipleSelectOffsetMultipleSelectValuesisCheckboxOngetCheckboxValuesisMultipleSelectOngetMultipleSelectValuesaddToSelectedclearAllSelectedclearSelectedmergeFromSelectedmergeToSelectedisSelectedclearSessionByPrefixgetSessionValuessetSessionValues

TextArea FieldsRelevant Fields <textarea>

Associated Methods appendToTextAreaclearTextAreacreateTextAreagetTextAreamergeFromTextAreamergeTextAreaFromRequestmergeToTextAreaclearSessionByPrefix


111

<select> tag optionsRelevant Fields <select>

<select multiple>

Associated Methods addToListappendToListclearListcountListgetTextFromListisListDefinedmergeToListremoveFromListclearSessionByPrefix

File UploadingRelevant Fields <input type=”file”>

Associated Methods getUploadedFileNamegetUploadedFileSizegetUploadedFileType

Array handlingRelevant Fields These are for creating and manipulating

multi-dimensional session arrays for usewithin your web pages

Associated Methods addToSessionclearSessionArraydeleteFromSessionexistsInSessiongetDataTypeErrorsgetSessionArraymergeArrayFromSessionmergeArrayToSessionmergeGlobalFromSessionmergeGlobalToSessionmergeFromRequestmergeFromSessionmergeToSessionsetSessionArrayclearSessionByPrefix


112

Error and other programmatically generated messagesRelevant Fields These functions are not related to form

fields. They are used within action and pre-page scripts to create localized error andother messages.

Associated Methods errorMessagesystemMessage

CookiesAssociated Methods setCookie

getCookiedeleteCookieconvertDaysToSeconds

Request and Server Name/Value PairsRelevant Fields These functions are not related to form

fields. They are used to retrievename/value pairs from the requestobject/array or to retrieve CGI environmentvariables from the server object/array

Associated Methods addServerToSessiongetRequestValuegetServerValue

Access to EWD's HTML to XML ParserRelevant Fields These function are not related to form

fields. They allow EWD's HTML to XMLparser to be used with files, streams andURLs. The parsed page is saved as apersistent eXtc DOM and is then availablefor processing and analysis.

Associated Methods parseHTMLFileparseURLparseHTMLStream

Debugging / Error TracingRelevant Fields These functions are not related to form

fields. They are provided to facilitatedebugging of run-time errors

Associated Methods loadErrorSymbols


113

Detailed Descriptions of eXtc Web Developer API Methods

The following pages describe in detail the full set of EWD's API methods, which you mayuse in your Caché scripts.


114

addCSPServerScriptDescription Adds a CSP in-page script block into your EWD page

The specified script text is wrappered as follows andappended as a child of a specified parent node.

<script language=”cache” runat=”server”>...script text</script>

Associated Design PageTag(s)

n/a

Example do addCSPServerScript^%zewdAPI(parentOID,scriptText)

Parameters DescriptionparentOID Pointer (eXtc OID) to the parent node to which the CSP

script block should be appended as a child nodescriptText Variable containing the text of the CSP script. Lines

should be separated with CRLF characters (ie $c(13,10)).

A maximum of 32k of text may be defined.

returnValue n/a


115

addJavascriptFunctionDescription Adds a javascript function into your EWD page. If a

<script language=”javascript”> tag exists, EWD will use itas a container for the new function. Otherwise EWD willautomatically add a <script language=”javascript”> tag.

The contents of the javascript function must be defined in alocal array, subscripted by line number

This function is for use in your custom tag processors


n/a

Example Set scriptOID=$$addJavascriptFunction^%zewdAPI(docName,.jsTextArray)

Parameters DescriptiondocName The name of the current EWD page DOM. The variable

docName will be automatically available to you withinyour custom tag processor.

jsTextArray Local array containing the contents of the Javascriptfunction, of the format:

jsTextArray(1)=”function myFunc() {“jsTextArray(2)=” alert('test function') 'jsTextArray(3)=”}”

Passed by Reference

returnValue The OID of the <script> tag which contains the function.


116

addJavascriptObjectDescription Adds a javascript object declaration into your EWD page.

If a <script language=”javascript”> tag exists, EWD willuse it as a container for the new declaration. OtherwiseEWD will automatically add a <scriptlanguage=”javascript”> tag.

The contents of the javascript object must be declaredwithin a local array, subscripted by line number

This function is for use in your custom tag processors


n/a

Example Set scriptOID=$$addJavascriptObject^%zewdAPI(docName,.jsTextArray)

Parameters DescriptiondocName The name of the current EWD page DOM. The variable

docName will be automatically available to you withinyour custom tag processor.

jsTextArray Local array containing the contents of the Javascriptfunction, of the format:

jsTextArray(1)=”myObj.test = function() {“jsTextArray(2)=” alert('test function') 'jsTextArray(3)=”} ;”

Passed by Reference

returnValue The OID of the <script> tag to which the function has beenadded.


117

addServerToSessionDescription Merges the server array (containing CGI environment

variables) into the session array


n/a

Example do addServerToSession^%zewdAPI(sessid,.serverArray)

Parameters DescriptionSessid The session ID

serverArray Reference to the server array

Note: call by reference

returnValue n/a


118

addToListDescription Adds a drop-down option to the list array in the session

object at the specified position. The appendToList()method will be more commonly used, but the addToList()method is useful for example to insert an initial option atthe head of the list.


<select><select multiple>

Example set textValue=”United Kingdom”set codeValue=10do appendToList^%zewdAPI(“country”,textValue,codeValue,0,sessid)

Adds the United Kingdom to the list at position 0, ie the head of thelist. If selected, it will return a value of 10.

Parameters DescriptionfieldName Name of the <select> field name

textValue Option’s text value (ie the value that will appear in thedrop-down list)

codeValue Option’s code value (ie the value that is sent to the back-end when this option is chosen, and the value that, whenset into the session, will highlight this option)

listPosition The position in the drop-down list. The position in thedrop-down list is determined by strict ASCII collatingsequence of this parameter, so an initial position of 0 isacceptable if required. However, by convention, listposition usually starts from 1.

sessid The session ID

returnValue n/a


119

addToResultSetDescription Manually sets a property and its value into an EWD

Session ResultSet, as a new (last) index record.

This provides an alternative means of defining and/ormodifying an EWD Session ResultSet to usingcopyResultSetToSession or mergeRecordArrayToResultSet

Note: a new index record will be added to the ResultSeteach time this procedure is called. If you want to addseveral properties into a new (last) index simultaneously,use mergeRecordArrayToResultSet instead.


N/a

Example Do addToResultSet^%zewdAPI("searchResults",”zipCode”,”123456”,sessid)

Adds a new index to the EWD Session ResultSet named“searchResults” and creates the zipCode property in it with a value of“123456”

Parameters DescriptionresultSetName Name of the EWD Session ResultSet

propertyName Name of the property within the EWD ResultSetvalue Value of the propertysessid The session ID

returnValue N/a


120

addToSelectedDescription Adds a value to the Selected array in the session object for

a specified field name.

Usually used to specify checkbox values or multiple drop-down list values.


<input type=checkbox><select multiple>

Example do addToSelected^%zewdAPI(“colours”,”red”,sessid)do addToSelected^%zewdAPI(“colours”,”blue”,sessid)

Adds the values “red” and “blue” to the Selected array for colours

If the following checkboxes exist, they will be automatically checked:

<input type=checkbox name=”colours” value=”red”><input type=checkbox name=”colours” value=”blue”>

Parameters DescriptionfieldName Name of the field name

value Value to set in the Selected array.


returnValue n/a


121

addToSessionDescription Adds a variable or array to the session object, using the

same name.


<input type=text><input type=password><input type=hidden><input type=radio><select>

Also used to define an array of information for processingwithin the page

Example do addToSession^%zewdAPI(“colour”,sessid)

If a local variable called colour exists, a session object variable namedcolour will be created with the same value.

If colour is a local array, its contents are merged to an array of thesame name in the session object. The array can have any number ofdimensions.

Note that this method provides a shortcut alternative to thesetSessionValue() method, where the local variable and session nameare the same, eg

do setSessionValue^%zewdAPI(“colour”,colour,sessid)

Parameters DescriptionarrayName Name of the variable or array

Sessid The session ID

returnValue n/a


122

appendToListDescription Appends a drop-down option to the list array in the session

object. Adds to the end of the current list. If the list doesnot exists when this is called, a position of 1 is allocated.



Example set textValue=”United Kingdom”set codeValue=10do appendToList^%zewdAPI(“country”,textValue,codeValue,sessid)

When the page is rendered, this will create, within the <selectname=”country”> tag:

<option value=”10”>United Kingdom</option>

Parameters DescriptionfieldName Name of the <select> field name to which the generated

<option> tag is to be added

textValue Option’s text value (ie the value that will appear in thedrop-down list)

codeValue Option’s code value (ie the value that is sent to the back-end when this option is chosen, and the value that, whenset into the session, will highlight this option)


returnValue n/a


123

appendToTextAreaDescription Appends a line of text to the end of the session text array

for a specified fieldname


<textarea>

Example set text=”This is a line of text”do appendToTextArea^%zewdAPI(“comments”,text,sessid)

Parameters DescriptionFieldname Name of the textarea field name

Text A line of text


returnValue n/a


124

applicationRootPathDescription Returns the EWD application root path (ie the path under

which all your EWD application source directories reside)


N/a

Example USER> w $$applicationRootPath^%zewdAPI()d:\ewdApps

Parameters DescriptionreturnValue The EWD application root path


125

clearAllSelectedDescription Deletes everything in the session selected array, for all

names.



Example do clearAllSelected^%zewdAPI(sessid)

Parameters Descriptionsessid The session ID

returnValue n/a


126

clearListDescription Deletes everything in the session List array, for the

specified fieldname..Deletes all options for the specified drop-down list



Example do clearList^%zewdAPI(“country”,sessid)

Parameters Descriptionfieldname The <select> tag’s field name


returnValue n/a


127

clearSchemaFormErrorsDescription Deletes information on all errors that were generated by the

schema-linked form mechanism .For use with EWD's schema-linked forms technology


N/a

Example do clearSchemaFormErrors^%zewdAPI(sessid)

Parameters DescriptionSessid The session ID

returnValue n/a


128

clearSelectedDescription Deletes the specified session selected array

Effectively un-checks or un-highlights the associatedcheckbox or drop-down



Example do clearSelected^%zewdAPI(“colours”,sessid)

Deletes any existing values in the Selected array for the colours field.

Parameters DescriptionfieldName The field name whose Selected Array values are to be

deleted.


returnValue n/a


129

clearSessionArrayDescription Deletes a named array from the session object


n/a

Clears an array that has been created for programmaticdisplay within a page, eg within a table

Example do clearSessionArray^%zewdAPI(arrayName,sessid)Parameters Description

arrayName Name of the array to be deleted from the session object.


returnValue n/a


130

clearSessionByPrefixDescription Clears all session objects whose names start with the

specified prefix string. Note that this removes all matchingsession variables, session arrays, Selected arrays, Listarrays and TextArea arrays from the session.

Provides a rapid and convenient way of removinginformation from the session object.


All tags

Example do clearSessionByPrefix^%zewdAPI(“myField”,sessid)

Clears all session objects starting with “myField”Parameters Description

prefix Prefix substring. All session objects starting with thisprefix substring will be cleared from the session.


returnValue n/a


131

clearTextAreaDescription Deletes the specified text array from the session object


<textarea>

Example do clearTextArea^%zewdAPI(“comments”,sessid)

Deletes any text for the comments field

Parameters DescriptionfieldName Name of the field name


returnValue n/a


132

convertDateToSecondsDescription Converts the specified date (in $h format) to the number of

seconds since January 1st 1841 ($h=0)


n/a

Example set secs=$$convertDateToSeconds^%zewdAPI($h)

Parameters Descriptiondate In $h format

returnValue Number of seconds since Jabuary 1st 1841


133

convertDaysToSecondsDescription Converts the specified number of days to seconds


n/a

Example set secs=$$convertDaysToSeconds^%zewdAPI(100)

Returns the number of seconds in 100 days

Parameters DescriptionnoOfDays Number of days

returnValue Number of seconds


134

convertSecondsToDateDescription Converts the number of seconds since January 1st 1841 to

the equivalent date in $h format


n/a

Example USER> w $$convertSecondsToDate^%zewdAPI(5243068622)60683,57422

Parameters Descriptionseconds No of seconds since January 1st 1841

returnValue Date in $h format


135

copyListDescription Copies the contents of a List (ie defining the <option> tags

for a <select> tag)


<select>

Example Do copyList^%zewdAPI(“oldListName”,”newListName”,sessid)Parameters Description

fromList Name of list to be copied

toList Name of new list to be created


returnValue N/a


136

copyObjectToSessionDescription Copies a Cache object to an EWD session object

Note that the current implementation will only copy simplename/value pair properties from the Cache Object and willignore any inheritence etc.


N/a

Example s oref=##class(Testing.Person).%OpenId(1)d copyObjectToSession^%zewdAPI(oref,"person",sessid)

This copies the Cache object Testing.Person to an EWD session objectnamed person.

Parameters Descriptionoref The oref of the Cache Object

sessionName Name of the EWD session object to which the Cacheobject will be copied


returnValue N/a


137

copyRequestValueToSessionDescription Copies a variable or array from the incoming HTTP

request array to the session object


May or may not be associated with form tags. Onlynecessary for programmatically created form fields.

Example do copyRequestValueToSession^%zewdAPI(“companyStaff”,sessid)

The variable or array named companyStaff is copied from the requestarray to the session object

Parameters DescriptionarrayName Name of the request array or variable to be copied


returnValue n/a


138

copyResultSetToSessionDescription Copies a Cache resultSet to an EWD session resultSet

Note that the current implementation will only copy simplename/value pair properties from the Cache resultSet


N/a

Example S rs = ##class(%Library.ResultSet).%New()d rs.Prepare("SELECT Name, DateOfBirth FROM Testing.Person")d rs.Execute()d copyResultSetToSession^%zewdAPI(rs,"myResultSet",sessid)d rs.Close()

This copies the Cache resultSet “rs” to an EWD session resultSetnamed “myResultSet”

Within your page, you could process this as follows:

<ewd:forEach sessionName="myResultSet" index="$recNo"> <tr> <td><?= #myResultSet[$recNo].Name ?></td> <td><?= #myResultSet[$recNo].DateOfBirth ?></td> </tr> </ewd:forEach>

Parameters Descriptionoref The oref of the Cache ResultSetsessionName Name the EWD session resultSet to which the Cache

resultSet will be copied


returnValue N/a


139

countListDescription Returns the number of members in a <select> tag’s list of

options


<select>

Example set noOfItems=$$countList^%zewdAPI(“colour”,sessid)

Gets the number of options that have been defined for the “colour”<select> tag

Parameters DescriptionlistName Name of the <select> list


returnValue The number of options defined in the list


140

createDirectoryDescription Creates a new directory in the host file system.

Associated Design PageTag(s)Example Set path=”d:\test\myDirectory”

Set ok=$$createDirectory^%zewdAPI(path)

Parameters Descriptionpath Full path of the directory to be created. If the directory

already exists, the command has no effectreturnValue Although a value is returned, it may be ignored under most

circumstances.


141

createJSPCommandDescription Creates a Java Server Pages script block for insertion into

your Design Page.


n/a

For use in your custom tag processing scripts.

Example s jspOID=$$createJSPCommand^%zewdAPI(text,docOID)s jspOID=$$appendChild^%eDOMAPI(jspOID,parentOID)

Creates a JSP script block and appends it as a child of the specifiedparent node.

Parameters DescriptionscriptText Variable containing the text of the JSP script. Lines



docOID The eXtc OID of the Design Page DOM. This is madeavailable to you by EWD through the Custom Pageprocessing script interface.

returnValue Pointer (eXtc OID) to the node that is created in the DesignPage DOM.


142

createPHPCommandDescription Creates a PHP script block for insertion into your Design

Page.


n/a

For use in your custom tag processing scripts.

Example s phpOID=$$createPHPCommand^%zewdAPI(text,docOID)s phpOID=$$appendChild^%eDOMAPI(phpOID,parentOID)

Creates a PHP script block and appends it as a child of the specifiedparent node.

Parameters DescriptionscriptText Variable containing the text of the PHP script. Lines



docOID The eXtc OID of the Design Page DOM. This is madeavailable to you by EWD through the Custom Pageprocessing script interface.

returnValue Pointer (eXtc OID) to the node that is created in the DesignPage DOM.


143

createTextAreaDescription Copies a local array of text to the specified text array in the

session object


<textarea>

Example do createTextArea^%zewdAPI(“comments”,.notes,sessid)

Copies the text held in the local array named notes into the sessionobject text array for the field named comments.

The notes array will be of the form:

notes(lineNo)=text

eg:

notes(1)=”This is the first line”notes(2)=”Second line of text”….etc

This will cause the following <textarea> tag to be automaticallypopulated:

<textarea name=”comments”>*</textarea>

Parameters DescriptionfieldName Name of the textarea field name

arrayName Name of the local area containing text

Local array format is:

Array(lineNumber)=text

Called by reference.


returnValue n/a


144

decDateDescription Decodes a date from $h format to dd mmm yyyy format


n/a

Example USER> w $$decDate^%zewdAPI($h)22 Feb 2007

Parameters Descriptiondateh Date in $h format

returnValue Date in dd mmm yyyy format


145

deleteAllErrorLogsDescription Clears down the log of errors for all sessions


n/a

Example D deleteAllErrorLogs^%zewdAPI

Parameters DescriptionreturnValue N/a


146

deleteCookieDescription Deletes a named cookie from the user’s browser


n/a

Used specifically in pre-page and action scripts for deletinga named cookie

Example do deleteCookie^%zewdAPI("username",sessid)

The cookie named username is deleted from the user’s browser

Parameters DescriptioncookieName Name of the cookie to be deleted


returnValue n/a


147

deleteErrorLogDescription Clears down the log of errors for a specified session


n/a

Example Do deleteErrorLog^%zewdAPI(sessid)

Parameters Descriptionsessid Session ID whose error log is to be clearedreturnValue N/a


148

deleteFileDescription Deletes a file from the host file system.

Associated Design PageTag(s)Example Set filepath=”d:\test\myDirectory\myFile.txt”

Set ok=$$deleteFile^%zewdAPI(filepath)

Parameters Descriptionfilepath Full path of the file to be deleted.

returnValue Although a value is returned, it may be ignored under mostcircumstances.


149

deleteFromSessionDescription Deletes a variable or local array from the session object


May or may not be associated with form fields. Ifassociated with a form field, then this method applies tothe following types:


Example do deleteFromSession^%zewdAPI("companyStaff",sessid)

The variable or array named companyStaff is deleted from the sessionobject

Parameters DescriptionarrayName Name of the session array or variable to be deleted


returnValue n/a


150

deleteFromSessionObjectDescription Deletes a specified property from an EWD session object




Example do deleteFromSessionObject^%zewdAPI("person",”name”,sessid)

The”name” property is deleted from the EWD session object named“person”

Parameters DescriptionobjectName Name of the session object

propertyName Name of the session object property to be deleted


returnValue n/a


151

deleteSessionDescription Deletes all information from the session object for the

specified session ID

This is usually done for you automatically, but for systemmanagement purposes, use this API to clear down aspecific session ID and remove all its records and indicesfrom the ^%zewdSession global.

Does not apply to CSP


n/a

Example do deleteSession^%zewdAPI(sessid)


returnValue n/a


152

deleteSessionObjectDescription Deletes a specified EWD session object




Example do deleteSessionObject^%zewdAPI("person",sessid)

The EWD session object named “person” is deleted, along with all itsproperties.

Parameters DescriptionobjectName Name of the session object to be deleted


returnValue n/a


153

deleteWarningDescription Deletes the user warning from the session object


n/a

Example do deleteWarning^%zewdAPI(sessid)


returnValue n/a


154

directoryExistsDescription Determines whether or not a specified directory path exists

in the host file system

Associated Design PageTag(s)Example Set path=”d:\test\myDirectory”

Set exists=$$directoryExists^%zewdAPI(path)

Parameters Descriptionpath Full path of the directory

returnValue 1 = directory exists0 = directory does not exist


155

doubleQuotesDescription Doubles up any quotes in a string

Used internally but available for general use.

Associated Design PageTag(s)Example USER> Set string=”abc””def””ghi”

USER> write stringabc”def”ghiUSER> write $$doubleQuotes^%zewdAPI(string)abc””def””ghi

Parameters DescriptioninputString Input string

returnValue String with any quotes doubled up


156

errorMessageDescription Defines a localized error message for use within Action

Scripts. Also escapes the message for correct display inthe JavaScript alert window.

The behaviour of this function depends on a number ofcircumstances:

1) If the application has not been compiled to usemulti-lingual localization, the specified errormessage is passed back unchanged

2) If the application is compiled using multi-linguallocalization and you are running in the defaultlanguage, the specified error message is passedback unchanged.

3) If the application is compiled using multi-linguallocalization and you are running in a language otherthan the default one but no translation is available,the specified error message is passed backunchanged. The first time this function runs for thespecified message, the error message isautomatically added to the phrase table and isallocated a text ID.

4) If the application is compiled using multi-linguallocalization and you are running in a language otherthan the default one and a translation is available,the function returns the translated phrase.


Not associated with specific tags.

Example if username=”” QUIT $$errorMessage^%zewdAPI(“You must enter ausername”,sessid)

Parameters DescriptionerrorMessage The error message (in the default language).


returnValue The original or translated version of the error message (seethe description above)


157

existsInSessionDescription Determines whether or not a variable or array name exists

in the session object


May or may not be associated with form fields. Ifassociated with a form field, then this method applies to alltypes

Example set exists=$$existsInSession^%zewdAPI(“colour”,sessid)

Parameters DescriptionvariableName Name of the session variable or array.

If this relates to a form field, the name of the variableshould be the same as that of the form field, and mustmatch in terms of upper/lower case.

Eg If the form field name is “Username”, then the sessionvariable name must also be “Username”, and not“username” or “USERNAME”.


returnValue 1 if the variable exists in the session object

0 if it doesn’t exist in the session object


158

existsInSessionArrayDescription Determines whether or not a specified session array value

exists in the Session.

This method can be used for session arrays with multipleparameters


N/a

Example S exists=$$existsInSessionArray^%zewdAPI(“myArray”, ”a”,”b”,”123”,sessid)

Determines whether or not the session array elementmyArray(“a”,”b”,123) exists in the session.

Parameters DescriptionsessionName The name of the session array

subscripts 1..n The value of the required subscriptssessid The EWD Session IDreturnValue 1 = the session array node exists

0 = the session array node is not defined


159

fileExistsDescription Determines whether or not a specified file exists in the host

file system

Associated Design PageTag(s)Example Set filepath=”d:\test\myDirectory\myFile.txt”

Set exists=$$fileExists^%zewdAPI(filepath)

Parameters Descriptionpath Full path of the file

returnValue 1 = file exists0 = file does not exist


160

fileInfoDescription Returns the size and last modification date for a specified

file.

Associated Design PageTag(s)Example EXTC>k

EXTC>d fileInfo^%zewdAPI("d:\myFiles\myFOPFile3.txt",.props)EXTC>w props("date")="2007-02-19 14:11:44"props("size")=1602


infoArray Called by reference

Returns the file size [infoArray(“size”)] and date of lastmodification [infoArray(“date”)]

returnValue n/a


161

fileSizeDescription Returns the size of a specified file.

Associated Design PageTag(s)Example USER> w $$fileSize^%zewdAPI("d:\myFiles\myFOPFile3.txt")

1602


returnValue The size of the file in bytes


162

getApplicationRootPathDescription Returns the EWD application root path (ie the path under



N/a

Example USER> w $$getApplicationRootPath^%zewdAPI()d:\ewdApps

Parameters DescriptionreturnValue The EWD application root path


163

getCheckboxValuesDescription Creates a local array of HTML checkbox field values that

were checked by the user when the form was submitted


<input type=checkbox>

Example do getCheckboxValues^%zewdAPI("colours",.values,sessid)

A local array named “values” is created which contains the checkedvalues, eg:

values(“r”)=”r”values(“b”)=”b”

would be returned if the following checkboxes were checked:

<input type=”checkbox” name=”colours” value=”r”><input type=”checkbox” name=”colours” value=”b”>

Parameters DescriptionfieldName The checkbox field name

localArrayName The name of the local array into which the checked valueswill be copied

Called by reference


returnValue n/a


164

getCookieValueDescription Gets the value of a cookie from the incoming request array


n/a

Example set value=$$getCookieValue^%zewdAPI(“username”,sessid)

Gets the value of the cookie named username

Parameters DescriptioncookieName Name of the cookie


returnValue Value of the cookie

Null if the cookie does not exist.


165

getDataTypeErrorsDescription If the form that you are validating in your action script uses

custom-defined data types, then you can obtain an array oferrors (if any occurred) that were detected by the data typeencoding function(s).

This function returns a local array of the format:

errorArray(fieldname)=errorMessage

where :

- fieldname is the name of the form field to whichdata type encode processing was applied

- errorMessage is the error message returned by theencode processing function

By calling this function, your action script has all theinformation relating to errors that may have occurred in theautomatic encoding of any form fields that use yourcustom-defined data types.

For more information on defining and using data types, seethe separate EWD document.


Any form field to which a custom data type has beenapplied

Example do getDataTypeErrors^%zewdAPI(.errorArray,sessid)

Merges any data type errors into a local array named errorArray

Parameters DescriptionerrorArray Name of the local array into which the data type errors are

to be merged

Called by reference


returnValue n/a

Null if the cookie does not exist.


166

getDefaultFormatDescription Returns the default format in which EWD's compiler will

lay out a page's HTML (indented or collapsed)

If not defined (using setDefaultFormat), this functionreturns “pretty”, ie indented format.


N/a

Example USER> w $$getDefaultFormat^%zewdAPI()pretty

Parameters DescriptionreturnValue The default compilation layout format.


167

getDefaultMultiLingualDescription Returns the default multilingual mode for EWD's compiler.

If not defined (using setDefaultMultiLingual), this functionreturns 0 (ie pages will not be compiled in multilingualmode)


N/a

Example USER> w $$getDefaultMultiLingual^%zewdAPI()0

Parameters DescriptionreturnValue The default multi-lingual mode


168

getDefaultTechnologyDescription Returns the default technology for EWD's compilations.

If not defined (using setDefaultTechnology), this functionreturns “csp” (ie EWD pages will be compiled into CSPpages unless specifically overridden)


N/a

Example USER> w $$getDefaultTechnology^%zewdAPI()php

Parameters DescriptionreturnValue The default compilarion technology


169

getHiddenValueDescription Obtain the value of a submitted HTML text field.


<input type=hidden>

Example set username=$$getHiddenValue^%zewdAPI(“username”,sessid)

Parameters DescriptionfieldName Name of the HTML hidden field.

The name must be the same as that of the form field, andmust match in terms of upper/lower case.

Eg If the hidden field name is “Username”, then thefieldName must also be “Username”, and not “username”or “USERNAME”.


returnValue The value of the hidden field.

Null if the variable does not exist in the session object


170

getJavascriptFunctionBodyDescription This function is for use in custom tag processors, and allows you to

extract the contents of a named Javascript function from the EWD pageDOM.

Note that the body of the specified Javascript function is returned as asingle string, with line breaks denoted by CRLF [$c(13,10)] characters,and also note that the body does not include the “function myFunction{“ declaration line or the closing brace [ } ] This method will search for the specified javascript function in all<script> tags within the EWD page DOM


For use in custom tag processing functions.

Example In a page that contains the following Javascript function

function release(objid) { obj=document.getElementById(objid) ; obj.className = "popupOn" ; grabbed = false ; }

s text=$$getJavascriptFunctionBody^%zewdAPI("release",docName) text would contain the following string:

obj=document.getElementById(objid) ; obj.className = "popupOn" ; grabbed = false ;

Parameters DescriptionfunctionName Name of the required Javascript functiondocName The EWD page DOM name. The variable docName is

automatically available for you within your custom tagprocessor method.

returnValue A text string that contains the body of the specifiedJavascript function.


171

getJavascriptObjectBodyDescription This function is for use in custom tag processors, and allows you to

extract the contents of a named Javascript object method definitionfrom the EWD page DOM.

Note that the body of the specified Javascript object definition isreturned as a single string, with line breaks denoted by CRLF [$c(13,10)] characters, and also note that the body does not include the“myObj.myFunction = function() {“ declaration line or the closingbrace [ } ] This method will search for the specified javascript object methoddeclaration in all <script> tags within the EWD page DOM



Example In a page that contains the following Javascript function

myObj.myFunc = function(objid) { obj=document.getElementById(objid) ; obj.className = "popupOn" ; grabbed = false ; }

set text=$$getJavascriptFunctionBody^%zewdAPI("myObj.myFunc",docName) text would contain the following string:

obj=document.getElementById(objid) ; obj.className = "popupOn" ; grabbed = false ;

Parameters DescriptionobjectMethodName Name of the required Javascript object methoddocName The EWD page DOM name. The variable docName is

automatically available for you within your custom tagprocessor method.

returnValue A text string that contains the body of the specifiedJavascript object method definition.


172

getJSScriptsPathDescription Returns the web server path in which an EWD application's Javascript

[.js] files will be found


Normally for internal use only

Example S path=$$getJSScriptsPath^%zewdAPI("ewdMgr","php")

Parameters DescriptionapplicationName Name of the EWD application

technology The compilation technology

returnValue The webserver path (or relative path) under which this application's .jsfiles will be found.


173

getJSScriptsPathModeDescription Returns the type of web server path in which an EWD application's

Javascript [.js] files will be found – ie fixed or relative.



Example S pathMode=$$getJSScriptsPathMode^%zewdAPI("php")

Parameters Descriptiontechnology The compilation technology

returnValue The type of webserver path under which this application's .js files willbe found.

Possible values are:

– fixed– relative

If the path mode is not defined, the function returns a null value.


174

getJSScriptsRootPathDescription Returns the root web server path in which an EWD application's

Javascript [.js] files will be found (if defined)



Example Set rootPath=$$getJSScriptsRootPath^%zewdAPI("php")


returnValue The web server root path for .js files


175

getMultipleSelectValuesDescription Creates a local array of options within an HTML multiple-

choice <select> tag that were highlighted by the user whenthe form was submitted


<select multiple=”multiple”>

Example do getMultipleSelectValues^%zewdAPI("colours",.values,sessid)

A local array named “values” is created which contains the highlightedoptions, eg:


would be returned if the following options were highlighted:

<select name=”colours” multiple=”multiple”><option value=”r”>Red</option><option value=”b”>Blue</option></select>

Parameters DescriptionfieldName The multiple-choice <select> tag name

localArrayName The name of the local array into which the highlighedoption values will be copied

Called by reference


returnValue n/a


176

getNextChildDescription Obtain the OID of the next child node in the eXtc DOM

This provides a handy shortcut to the use of thegetFirstChild() and getNextSibling() methods providedthrough the DOM API.

Normally for use in your custom tag processing methods.


Applies to all tags

Example set childOID=$$getNextChild^%zewdAPI(parentOID,childOID)

Parameters DescriptionparentOID Pointer (eXtc OID) to the parent node through whose child

nodes you wish to iterate

childOID Pointer (eXtc OID) to the current child node. Set this tonull (“”) to obtain the first child.

returnValue Pointer (eXtc OID) to the next child node

Returns null if no more child nodes.


177

getNormalisedAttributeValueDescription For use in custom tag processor functions.

This method will normalise the value of a custom tag attribute duringcompilation:

– special value “$nul” will be replaced with “” [null]– special value “$space” will be replaced with “ “ [space]– literal values will be returned quoted. Double quotes will be used,

except for PHP and JSP where single quotes are used– if compiling to CSP, JSP or VB.Net, the initial $ is stripped off

local variable names– session variables are returned as the correct data structure for the

corresponding compilation technology (eg %session.Data referenceif compiling to CSP)


For use in custom tag processors

Example S value=$$getNormalisedAttributeValue^%zewdAPI(“myAttr”,nodeOID,”php”)

Parameters DescriptionattributeName The name of the custom tag attribute

nodeOID Pointer (eXtc OID) to the current node. This variable is automaticallyavailable for you in your tag processing method.

technology The compilation technologyreturnValue The normalised value


178

getOutputRootPathDescription Returns the root file path into which EWD will compile pages for the

specified technology



Example USER> W $$getOutputRootPath^%zewdAPI("php")d:\php\apps


returnValue The compilation output root path.


179

getPasswordValueDescription Obtain the value of a submitted HTML password field.


<input type=password>

Example set password=$$getPasswordValue^%zewdAPI(“myPassword”,sessid)

Parameters DescriptionfieldName Name of the HTML password field.

The name should be the same as that of the form field, andmust match in terms of upper/lower case.

Eg If the form field name is “myPassword”, then thefieldName must also be “myPassword”, and not“mypassword” or “MYPASSWORD”.


returnValue The value of the password field.

Null if the fieldName does not exist in the session object


180

getRadioValueDescription Obtain the value of a submitted HTML text field.


<input type=radio>

Example set colour=$$getRadioValue^%zewdAPI(“colour”,sessid)

Parameters DescriptionfieldName Name of the HTML radio button.


Eg If the radio button name is “Colour”, then thefieldName must also be “Colour”, and not “colour” or“COLOUR”.


returnValue The value of the radio button checked item.



181

getRequestValueDescription Gets the value of a name/value pair from the incoming

HTTP request array.

Normally this is unnecessary for explicitly definedname/value pairs. However, if you have programmaticallygenerated form fields (eg created in a loop), you will needto manually identify and extract the name/value pairs andplace them into the session object.


May or may not be associated with form fields. Ifassociated with a form field, then this method applies to alltypes.

Example set value=$$getRequestValue^%zewdAPI("companyStaff",sessid)

Obtains the value of the name/value pair named companyStaff

Parameters Descriptionname Name of the name/value pair in the request array


returnValue The value of the specified name/value pair

Null if the name does not exist in the request array


182

getResultSetValueDescription Gets the value of an EWD Session ResultSet property

The EWD Session ResultSet property will have beencreated either using the API procedurescopyResultSetToSession, addToResultSet ormergeRecordArrayToResultSet


N/a

Example set value=$$getResultSetValue^%zewdAPI("searchResults", 10,”zipCode”,sessid)

Obtains the value of the zipCode property in the 10th ResultSet record

Typically this will be used within a $order loop that iterates throughthe index values.


index Index/record number of the resultSetpropertyName Name of the property within the EWD ResultSetsessid The session ID

returnValue The value of the specified ResultSet property.

Null if it does not exist.


183

getRootURLDescription Returns the root URL that EWD will generate in all page URLs for a




Example s rootURL=$$getRootURL^%zewdAPI("csp")w rootURL/csp/ewd


returnValue The root URL to be used when EWD generates all its page URLs


184

getSelectValueDescription Obtain the value of a submitted HTML single-choice

<select> tag.


<select>

Example set state=$$getSelectValue^%zewdAPI(“state”,sessid)

Parameters DescriptionfieldName Name of the HTML <select> tag.


eg If the <select> tag field name is “State”, then thefieldName must also be “State”, and not “state” or“STATE”.


returnValue The value of the <select> option that was highlighted andselected.


Note : if an <option> tag is defined with a null value,getSelectValue() ensures that you'll be returned a nullvalue if that option was selected by the user. If you usegetSessionValue(), you will be returned a value of ASCII160 for an <option> with a null value. Therefore thegetSelectValue() method is recommended.


185

getServerValueDescription Gets the value of a CGI environment variable from the

incoming server array.


n/a

Example set value=$$getServerValue^%zewdAPI("REMOTE_ADDR",sessid)

Obtains the value of the REMOTE_ADDR environment variable

Parameters Descriptionname Name of the name/value pair in the server array


returnValue The value of the specified CGI environment variable

Null if the name does not exist in the request array


186

getSessionArrayDescription Copies (or more formally, merges) an array in the session

object to a local array


n/a

Usually used to handle and manage programmaticallycreated persistent arrays

Example do getSessionArray^%zewdAPI(“staff”,sessid,.myStaff,1)Parameters Description

arrayName Name of the array in the session object.


localArrayName Name of the local array to which the session array is to becopied.

Note: called by reference.

The array can have any number of dimensions.

clearArray Set to 1 if you want to initially delete the local array

Set to 0 if you want to leave the local array intact beforeyou merge the session array contents into it.

returnValue n/a


187

getSessionValueDescription Obtain the value of a simple scalar session variable or

EWD session object



Example For simple scalar session variables:

set username=$$getSessionValue^%zewdAPI(“username”,sessid)

For EWD session objects:

set name=$$getSessionValue^%zewdAPI(“person.name”,sessid)set postCode=$$getSessionValue^%zewdAPI(“person.addr.postCode”,sessid)

Parameters DescriptionvariableName Name of the session variable, or session object reference



Object references of any depth can be specified


returnValue The value of the session variable



188

getSessionValuesDescription Obtain the values of all session variables whose names

start with a specified prefix substring.

The values are returned in a local array whose structurematches that used in the setSessionValues() method.


<input type=text><input type=password><input type=hidden><input type=radio><input type=checkbox><select><select multiple>

Example do getSessionValues^%zewdAPI(“myField”,.valueArray,sessid)

The values of all session names starting with “myField” will bereturned into the local array named valueArray

Parameters Descriptionprefix Prefix substring. Values for all session names that start

with the specified prefix substring will be returned.


189

arrayName Local array into which the values will be placed. Called byreference.

The structure of this array is:

- for single value fields:

arrayName(fieldname)=value

- for multi-value fields (eg checkbox, multiple select) :

arrayName(fieldname,sequenceNo)=value

where sequenceNo is an integer, starting at 1. Thesequence number has no significance, other thanallowing multiple values to be assigned to a name.

for example:

s array("test1")=1 s array("test3")="field 3" s array("text4")="field 4" s array("test2",1)=2 s array("test2",2)=3 s array("test5")="B"


returnValue n/a


190

getSessionValuesByPrefixDescription Finds all session variables and arrays that match the

specified prefix, and instantiates local variables/arrays ofthe same name.

Associated Design PageTag(s)Example D getSessionValuesByPrefix^%zewdAPI(“myVar”,sessid)

If session names myVar1 and myVar2 existed in the session, youwould now have two local variables defined:

myVar1myVar2

Parameters Descriptionprefix Prefix on which session variables and arrays are to be

matched.


returnValue N/a


191

getTagByNameAndAttrDescription For use in custom tag processing functions.

Locates the first tag in the EWD page DOM that matchesthe specified tag name with the specified value for aspecified attribute.

Eg find the first “input” tag with a “type” attribute whosevalue is “submit”



Example S tagOID=$$getTagByNameAndAttr^%zewdAPI(“input”,”type”,”submit”,1,docName)

Parameters DescriptiontagName The tag name to be located

attrName The attribute name to be matchedattrValue The value of the specified attribute to be matchedmatchCase 1 = case-sensitive match on attribute value

0 = case-insensitive match on attribute valuedocName Name of the EWD page DOM. This variable is

automatically available to your custom tag processingfunctions.

returnValue OID pointer to the matched tag (if found).

Null if no match found.


192

getTagOIDDescription For use in custom tag processing functions.

Locates the first tag in the EWD page DOM that matchesthe specified tag name



Example S tagOID=$$getTagOID^%zewdAPI(“input”,docName)

Parameters DescriptiontagName The tag name to be located

docName Name of the EWD page DOM. This variable isautomatically available to your custom tag processingfunctions.

returnValue OID pointer to the matched tag (if found).

Null if no match found.


193

getTextAreaDescription Copies the text that was in the submitted textarea field into

a local array

Synonymous with mergeFromTextArea()


<textarea>

Example do getTextArea^%zewdAPI(“comments”,.notes,sessid)

Creates a local array named notes that contains the text held in thesubmitted “notes” textarea field.

The array will be keyed by line number, and the “0” indexed value willcontain the number of lines of text in the array, eg:

notes(0)=2notes(1)=”This is line 1”notes(2)=”This is line 2”


localArrayName Local array name to which the text will be copied

Called by reference


returnValue n/a


194

getTextFromListDescription Return the text value for a <select> tag’s code value



Example set textValue=$$getTextFromList^%zewdAPI(“country”,1,sessid)

Gets the text value for the country whose code value is 1

Parameters DescriptionfieldName The <select> tag’s field name

codeValue The code value of the option whose text we require


returnValue The text value for the specified code


195

getTextValueDescription Obtain the value of a submitted HTML text field.


<input type=text>

Example set username=$$getTextValue^%zewdAPI(“username”,sessid)

Parameters DescriptionfieldName Name of the HTML text field.


Eg If the text field name is “Username”, then thefieldName must also be “Username”, and not “username”or “USERNAME”.


returnValue The value of the text field.



196

getTraceModeDescription Determines whether you have EWD trace mode enabled or

disabled.

See traceModeOn and traceModeOff

Trace mode is useful during testing for debuggingproblems. A record of significant events is saved into the^%zewdTrace global.


N/a

Example set mode=$$getTraceMode^%zewdAPI()

Parameters DescriptionreturnValue Trace mode status.

1 = enabled0 = disabled


197

getUploadedFileNameDescription Return the name of the file that was uploaded from the

user’s browser.


<input type=”file” name=”theFile”>

Example set filename=$$getUploadedFileName^%zewdAPI(“theFile”,sessid)

Gets the name of the file that was uploaded via the tag<input type=”file” name=”theFile”>

Parameters DescriptionfieldName The value of the name attribute in the <input type=”file”>

tag


returnValue The name of the uploaded file


198

getUploadedFileSizeDescription Return the size, in bytes, of the file that was uploaded from

the user’s browser.



Example set size=$$getUploadedFileSize^%zewdAPI(“theFile”,sessid)

Gets the size, in bytes, of the file that was uploaded via thetag <input type=”file” name=”theFile”>


tag


returnValue The size, in bytes, of the uploaded file


199

getUploadedFileTypeDescription Return the mime type of the file that was uploaded from

the user’s browser.



Example set type=$$getUploadedFileType^%zewdAPI(“theFile”,sessid)

Gets the mime type of the file that was uploaded via the tag<input type=”file” name=”theFile”>


tag


returnValue The mime type of the uploaded file


200

importDescription Imports and installs a new build of EWD from the

distribution XML file.

Associated Design PageTag(s)Example d import^%zewdAPI()

d import^%zewdAPI(“d:\downloads\zewd.xml”)

Due to the ^%zewdAPI routine being overwritten duringthe execution of this method, you may see a run-time errorreported. This can be safely ignored.

Parameters DescriptionfilePath The path in which the EWD distribution XML file

(zewd.xml) has been placed.

If you run the import method from a Cache terminalsession in the %SYS namespace, then you can leave thisparameter blank, in which case the import method willexpect to find zewd.xml in your %SYS path (egc:\cachesys\mgr)

returnValue N/a


201

inetDateDescription Converts a $h formatted date into Internet Date/Time

format, eg

Fri, 23 Feb 2007 11:45:25

Associated Design PageTag(s)Example USER> s date= $$inetDate^%zewdAPI($h)

USER> w dateFri, 23 Feb 2007 11:45:25

Parameters DescriptionhDate Date in $h format

returnValue Date in Internet Date/Time format


202

inetTimeDescription Converts a $h formatted date into Internet Time format, eg

11:45:25

Associated Design PageTag(s)Example USER> s time= $$inetTime^%zewdAPI($h)

USER> w time11:45:25

Parameters DescriptionhDate Date in $h format

returnValue Date in Internet Time format


203

initialiseCheckboxDescription Unchecks all the values in the specified HTML checkbox

Usually invoked prior to setting the specific checkedvalues using setCheckboxOn()




Example do initialiseCheckbox^%zewdAPI(“colours”,sessid)

Unchecks all the values for the “colours” checkbox.

Parameters DescriptionfieldName The name of the checkbox field(s) to be cleared

eg :


To clear both fields, the fieldName would be “colours”


returnValue n/a


204

initialiseMultipleSelectDescription Un-highlights and de-selects all the options in the specified

HTML multiple-choice <select> tag

Usually invoked prior to setting the specific checkedvalues using setMultipleSelectOn()



<select multiple=multiple>

Example do initialiseMultipleSelect^%zewdAPI(“colours”,sessid)

De-selects all the options in the “colours” <select> tag.

Parameters DescriptionfieldName The name of the multiple-choice <select> tag being

initialised.

eg :

<select multiple=”multiple”><option value=”r”>Red</option><option value=”b”>Blue</option></select>

To clear both options, the fieldName would be “colours”


returnValue n/a


205

instantiateJSPVarDescription Adds the necessary type declaration into the JSP page


n/a

Used in your custom tag processing scripts, when creatingJSP pages

Example Do instantiateJSPVar^%zewdAPI(name,”String”,docOID )

Defines a JSP variable as type String : EWD will add the appropriatetype declaration into the compiled JSP page

Note that this only needs to be used within your own custom tagprocessing scripts. Any variables used within the page by EWD, orused by EWD's custom tags, are automatically declared for you.

Parameters DescriptionvarName The name of the variable to be declared

type The Java type of the variable being declared, eg String.Note that this is case sensitive

docOID The eXtc OID of the Design Page DOM. This is madeavailable to you through the custom tag processing scriptinterface.

arraySize If you are declaring an array, specify its maximum sizehere.

initialValue Optionally you may define an initial value for the variablebeing declared.

returnValue n/a


206

isCheckboxOnDescription Determines whether or not the particular value for an

HTML checkbox was checked by the user when the formwas submitted.



<input type=”checkbox”>

Example if $$isCheckboxOn^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName The field name of the checkbox

fieldValue The checkbox value being tested


returnValue 1 = The specified checkbox value was checked by the user.

0 = The specified value was not checked


207

isListDefinedDescription Determines whether or not a List array has been defined for

a specified field name



Example set exists=$$isListDefined^%zewdAPI(“colour”,sessid)



returnValue 1 = List array exists

0 = List array does not exist


208

isMultipleSelectOnDescription Determines whether or not the specified option of a

multiple-choice HTML <select> tag was selected by theuser when the form was submitted.




Example if $$isMultipleSelectOn^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName The field name of the multiple-choice <select> tag

fieldValue The value of the option being tested


returnValue 1 = The option with the specified value was selected by theuser.

0 = The option was not selected


209

isRadioOnDescription Determines whether or not the specified radio button value

was checked when the form was submitted


<input type=”radio”>

Example set optionSelected=$$isRadioOn^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName The field name being tested

fieldValue The value of the field being tested


returnValue 1 = The field value was checked when the radio button wassubmitted

0 = The field value was not checked


210

isSelectedDescription Determines whether a name/value pair exists in the

Selected session array – in other words, whether or not theparticular value for a multi-valued field was checked orselected by the user.


<input type=”checkbox”><select multiple>

Example if $$isSelected^%zewdAPI(“colour”,”red”,sessid)




returnValue 1 = The field value was selected and exists in the Selectedarray

0 = The field value was not selected


211

isSelectOnDescription Determines whether or not the specified option value for a

single-choice <select> tag was highlighted when the formwas submitted


<select>

Example set optionSelected=$$isSelectOn^%zewdAPI(“colour”,”red”,sessid)




returnValue 1 = The option with the specified value was highlighedwhen the <select> tag was submitted

0 = The option was not highlighted


212

javascriptFunctionExistsDescription For use in custom tag processing functions.

Determines whether or not the specified Javascript function exists inthe EWD page DOM



Example Set funcExists=$$javascriptFunctionExists^%zewdAPI(“replace”,docName)

Parameters DescriptionfunctionName The name of the Javascript function. Eg if you have a function

declared as:

function myFunc() {....}

then the function name would be “myFunc”

docName The EWD page DOM name. This variable is automatically availablefor your page processing functions.

returnValue 1 = The Javascript function exists in the EWD page DOM

0 = No Javascript function of the specified name could be found


213

javascriptObjectExistsDescription For use in custom tag processing functions.

Determines whether or not the definition of the specified Javascriptobject exists in the EWD page DOM



Example Set objExists=$$javascriptObjectExists^%zewdAPI(“myObj.myProperty”,docName)

Parameters DescriptionobjectRef The name of the Javascript object. Eg if you have an object declared

as:

myObj.myFunc = function(objid) { obj=document.getElementById(objid) ; obj.className = "popupOn" ; grabbed = false ; }

then you would be able to determine that it exists if you specify theobjectRef as “myObj.myFunc”

docName The EWD page DOM name. This variable is automatically availablefor your page processing functions.

returnValue 1 = The Javascript object definition exists in the EWD page DOM

0 = No Javascript object definition for the specified name could befound


214

listDOMsByPrefixDescription For use in Cache terminal sessions

Lists EWD DOMs whose names start with the specified prefix

Associated Design PageTag(s)Example USER> d listDOMsByPrefix^%zewdAPI("health")

healthwarehealthware_v_2healthware_v_3

Parameters Descriptionprefix DOM name prefix

returnValue N/a


215

loadErrorSymbolsDescription Command-line API for use in Cache terminal session,

which loads the symbol table and session contents from theerror trap global (^%zewdError) into your terminalsession's symbol table.

This allows you to inspect the run-time environment at thetime the error occurred


n/a

Example d loadErrorSymbols^%zewdAPI(136)

Loads the symbol table and session contents from the error trapinformation for session number 136. The symbols and their values cannow be inspected

Parameters Descriptionsessid The session ID for which an error has been logged in the

^%zewdError global

returnValue n/a


216

lowerCaseDescription Converts a string to lower case

Associated Design PageTag(s)Example S lcString=$$lowerCase^%zewdAPI(“My String”)

w lcStringmy string

Parameters DescriptioninputString Input text string

returnValue String converted to lower case


217

makeStringDescription Create a string variable that consists of a specified character repeated a

specified number of times.

Associated Design PageTag(s)Example S string=$$makeString^%zewdAPI(“x”,10)

w stringxxxxxxxxxx

Parameters Descriptioncharacter Character from which to construct the string

length Number of times the specified character is to be repeated

returnValue Generated string


218

mergeArrayFromSessionDescription Creates a local array from a session object array


n/a

Used for handling and managing programmatically createdpersistent arrays

Example do mergeArrayFromSession^%zewdAPI(.staff,"companyStaff",sessid)

A local array named staff is created from an array named companyStaffin the session object. The array can have any number of dimensions.

Parameters DescriptionarrayName Name of the local array to be created from the session

Note: called by reference

sessionArrayName Name of the session array from which the local array is tobe created


returnValue n/a


219

mergeArrayToSessionDescription Merges the contents of a local array to a simple multi-

dimensional, sparse session array


n/a


Example do mergeArrayToSession^%zewdAPI(.staff,"companyStaff",sessid)

The contents of the local array named staff are merged to an arraynamed companyStaff in the session object. The array can have anynumber of dimensions.

Parameters DescriptionarrayName Name of the local array to be merged to the session


sessionArrayName Name of the session array to which the local array is to bemerged


returnValue n/a


220

mergeArrayToSessionObjectDescription Merges the contents of a local array to an EWD Session Object

Note that this differs significantly from mergeArrayFromSession and isprimarily used for instantiating Session Objects that can be mapped toJavascript Objects using JSON.


n/a

Used for instantiating EWD Session Objects that can be mapped toJavascript Objects using JSON.

Example If you create the following local array in your pre-page script:

s person("Name")="Rob"s person("DateOfBirth")="13/06/1955"s person("Address","PostCode")="RH2 0QA"s person("Address","Line1")="35 Durfold Drive"s person("Address","2","hello")="world"

do mergeArrayToSessionObject^%zewdAPI(.person,"person",sessid)

will create an EWD Session Array named person, with properties:

person.Nameperson.DateOfBirthperson.Address.PostCodeperson,Address.Line1person.Address.2.hello

This can be mapped to a corresponding Javascript Object by using theEWD.utils.getObjectFromSession() method within your EWD page,eg:

<input type="button" id="xxx" value="Fetch person object from EWDSession" onClick="EWD.utils.getObjectFromSession('person')">

The Javascript object will have the same properties, with oneexception: person.Address.2.hello will be mapped to person.Address[2].hello

Parameters DescriptionarrayName Name of the local array to be merged to the Session Object


sessionObjectName Name of the EWD Session Object to which the local array is to bemerged


returnValue n/a


221

mergeFromRequestDescription Copies an array of a values from the incoming HTTP

request array.

Normally this is unnecessary for explicitly definedname/value pairs. However, if you have programmaticallygenerated form fields (eg created in a loop), you will needto manually identify and extract the name/value pairs andplace them into the session object.


n/a


Example do mergeFromRequest^%zewdAPI(.company,"companyStaff",sessid)

Copies the array of values from the name/value pair namedcompanyStaff in the incoming requestArray, creating a local arraynamed company.

Parameters DescriptionlocalArrayName Name of the local array to be created

Note: call by reference

name Name of the name/value pair in the request array

returnValue n/a


222

mergeFromSelectedDescription Creates a local array from the Selected array in the session

object for the specified field name



Example do mergeFromSelected^%zewdAPI("colours",.selected,sessid)

A local array named selected is created from the Selected array for the“colours” field name in the session object.

Parameters DescriptionfieldName The <select> or checkbox field name

localArrayName The name of the local array into which the Selected arraywill be copied

Called by reference


returnValue n/a


223

mergeFromSessionDescription Creates a local array from a session object array of the

same name


n/a


Example do mergeFromSession^%zewdAPI("companyStaff",sessid)

A local array named companyStaff is created from an array namedcompanyStaff in the session object. The array can have any number ofdimensions.

Parameters DescriptionarrayName Name of the session array to be copied. The local array

will have the same name.


returnValue n/a


224

mergeFromTextAreaDescription Copies the text from the text array in the session object for

a specified fieldname, into a local array


<textarea>

Example do mergeFromTextArea^%zewdAPI(“comments”,.notes,sessid)

Creates a local array named notes from the comments textarea array inthe session object.


localArrayName Local array name to which the text will be copied

Called by reference


returnValue n/a


225

mergeGlobalFromSessionDescription Creates a global from a session object array

Associated DesignPage Tag(s)

n/a


Example do mergeGlobalFromSession^%zewdAPI(“^%work ($j)”,"companyStaff",sessid)

The global ^%work($j) is created from an array named companyStaff in thesession object. The array can have any number of dimensions.

Parameters DescriptionglobalName Name of the global to be created from the session

Note : you can specify as many literal parameters within theglobal as you like ; eg “^%work($j,”systemSettings”

The session array contents are merged into the specified globalnode.

sessionArrayName Name of the session array from which the global is to be created


returnValue n/a


226

mergeGlobalToSessionDescription Merges the contents of a global to a session object array


n/a


Example do mergeGlobalToSession^%zewdAPI(“^%work($j)”,"companyStaff",sessid)

The contents of the global ^%work($j) are merged to an array namedcompanyStaff in the session object. The array can have any number ofdimensions.

Parameters DescriptionglobalName Global reference to be merged to the session

sessionArrayName Name of the session array to which the global is to bemerged


returnValue n/a


227

mergeRecordArrayToResultSetDescription Merges a local array of name/value pairs into a new (last)

record in an EWD session ResultSet


N/a

Example Set propsArray(“name”)=”Rob”Set propsArray(“city”)=”London”Set propsArray(“country”)=”UK”do mergeRecordArrayToResultSet^%zewdAPI(“searchResults”, .propsArray,sessid)

Merges the property name/value pairs that are held in the local arraypropsArray into a new, last index record in the EWD Session ResultSetnamed searchResults

Within your page, you could process this ResultSet as follows:

<ewd:forEach sessionName="searchResults" index="$recNo"> <tr> <td><?= #searchResults[$recNo].name ?></td> <td><?= #searchResults[$recNo].city ?></td> <td><?= #searchResults[$recNo].country ?></td> </tr> </ewd:forEach>


propertyArray Reference to the local array containing propertyname/value pairs



returnValue n/a


228

mergeTextAreaFromRequestDescription Merges text from the incoming request array to the text

array for the matching name in the session object


<textarea>

Example do mergeTextAreaFromRequest^%zewdAPI(“colours”, .requestArray,sessid)

Copies the text held in the incoming request object for the field named“colours” into the session array under the same name.


requestArray Reference to the request array



returnValue n/a


229

mergeToListDescription Merges a local array into the session List array for a

specified field.

Used to rapidly and simply populate the options list of a<select> tag

The local array must be in the format:

Array(listPosition)=textValue~codeValue



Example set country(1)=”UK~1”set country(2)=”USA~2”set country(3)=”Europe~3”do mergeToList^%zewdAPI(“country”,.country,sessid)


localArrayName The name of the local array that contains the options

Call by reference


returnValue n/a


230

mergeToSelectedDescription Copies a local array to the Selected array in the session

object for the specified field name



Example do mergeToSelected^%zewdAPI("colours",.selected,sessid)

A local array named selected is copied to the Selected array for the“colours” field name in the session object.

Parameters DescriptionfieldName The <select> or checkbox field name

localArrayName The name of the local array that will be copied to theSelected array

Called by reference


returnValue n/a


231

mergeToSessionDescription Adds a variable or array to the session object, using the

same name.

This method is synonymous with the addToSession()method


May be used for any of the single-value form fields, or forarrays

Example do mergeToSession^%zewdAPI(“colour”,sessid)

The contents of the local array named colour are merged to an array ofthe same name in the session object. The array can have any numberof dimensions.

Parameters DescriptionarrayName Name of the variable or array


returnValue n/a


232

mergeToTextAreaDescription Copies the text from a local array to the text array in the

session object for a specified fieldname


<textarea>

Example do mergeToTextArea^%zewdAPI(“comments”,.notes,sessid)

Copies a local array named notes to the comments textarea array in thesession object.

The local array should be of the format:

notes(lineNo)=lineOfText

eg:

notes(1)=”This is the first line”notes(2)=”This is the second line”


localArrayName Local array name from which the text will be copied

Called by reference


returnValue n/a


233

namespaceDescription Returns the current Cache namespaceAssociated Design PageTag(s)Example S namespace=$$namespace^%zewdAPI()

Parameters DescriptionreturnValu Current namespace


234

parseHTMLFileDescription Converts an HTML text file into an XHTML DOM


n/a

Example Set filePath=”/myApp/myHTMLFile.htm”set docName=”myHTMLFile”Set error=$$parseHTMLFile^%zewdAPI(filePath,docName)

Parses the specified file and converts it to properly structured XMLand creates an eXtc DOM named myHTMLFile

Parameters DescriptionfilePath The filepath of the HTML file

docName The name of the eXtc XML DOM to be created. If a DOMof this name already exists it is deleted and overwritten

returnValue Null if no error occurs during parsing. Otherwise it returnsthe error string.


235

parseHTMLStreamDescription Converts a Stream object that contains HTML into an

XHTML DOM


n/a

Exampleset docName=”myHTMLFile”Set error=$$parseHTMLStream^%zewdAPI(streamName,docName)

Parses the specified Stream and converts it to properly structured XMLand creates an eXtc DOM named myHTMLFile

Parameters DescriptionstreamName The name of the Stream object that contains HTML

docName The name of the eXtc XML DOM to be created. If a DOMof this name already exists it is deleted and overwritten



236

parseStreamDescription Converts a Stream object that contains HTML or XML

into an EWD DOM


n/a

Exampleset docName=”myXMLFile”d parseStream^%zewdAPI(streamName,docName,.error,0)

Parses the specified Stream of XML and converts it to an EWD DOMnamed myXMLFile

Parameters DescriptionstreamName The name of the Stream object that contains HTML or

XML

docName The name of the EWD DOM to be created. If a DOM ofthis name already exists it is deleted and overwritten

error Details of any errors that occurred during parsing. Null ifstream was successfully parsed

Passed by referenceisHTML 1 = treat Stream contents as HTML and convert to

XHTML format

0 = treat Stream contents as XML and do not process ormodify the tag names or attribute names and values

returnValue N/a


237

parseURLDescription Fetches an HTML page as specified by a URL and

converts it into an XHTML DOM


n/a

ExampleSet server=”www.mgateway.com”set url=”/php/mgw/home.php”set docName=”myHTMLFile”Set error=$$parseURL^%zewdAPI(server,url,docName)

Fetches the page at the specified URL and converts it to properlystructured XML and creates an eXtc DOM named myHTMLFile

Parameters Descriptionserver Domain name or IP address of the server on which the

page residesurl The URL path for the required pagedocName The name of the eXtc XML DOM to be created. If a DOM

of this name already exists it is deleted and overwritten



238

parseXMLFileDescription Converts an XML text file into an EWD DOM


n/a

Example Set filePath=”/myApp/myXMLFile.txt”set docName=”myXMLFile”Set error=$$parseXMLFile^%zewdAPI(filePath,docName)

Parses the specified file of XML and creates an EWD DOM namedmyXMLFile

Parameters DescriptionfilePath The filepath of the XML file

docName The name of the EWD DOM to be created. If a DOM ofthis name already exists it is deleted and overwritten



239

randCharDescription Returns a single alphanumerc character at random


n/a

Example Set char=$$randChar^%zewdAPI()

Parameters DescriptionreturnValue A single randomly generated alphanumeric character.


240

removeDOMsByPrefixDescription For use in Cache terminal sessions

Permanently deletes EWD DOMs whose names start with the specifiedprefix

Associated Design PageTag(s)Example USER> d removeDOMsByPrefix^%zewdAPI("health")

healthwarehealthware_v_2healthware_v_3

Parameters Descriptionprefix DOM name prefix

returnValue N/a


241

removeFromListDescription Remove an option from a <select> tag’s drop-down list

array



Example do removeFromList^%zewdAPI(“country”,1,sessid)

Removes the country who’s code value is 1 from the option list for<select name=”country”>


codeValue The code value of the option to be deleted


returnValue n/a


242

removeFromSelectedDescription Removes a specified value from the Selected array in the

session object for a specified field name.

Usually used to un-check checkbox values or un-highlightmultiple drop-down list values.

Design Page Tag(s) <input type=checkbox><select multiple=multiple>

Example do removeFromSelected^%zewdAPI(“colours”,”red”,sessid)do removeFromSelected^%zewdAPI(“colours”,”blue”,sessid)

As a result of removing these values from the “colours” Selected array,if the following checkboxes exist, they will be automatically un-checked:


Parameters DescriptionfieldName Selected Array field name

value Value to be removed from the Selected array


returnValue n/a


243

removeInstanceDocumentDescription Permanently deletes a specified schema-linked instance

document (created using EWD's schema-linked formtechnology)

Design Page Tag(s)Example Set ok=$$removeInstanceDocument^%zewdAPI(“myInstanceDoc”)

Parameters DescriptioninstanceDocName Name of the instance document to be deleted

returnValue A value of null will be returned.


244

removeQuotesDescription Removes any quotes (single or double) from the start and

end of a text string

Design Page Tag(s)Example Set unquotedString=$$removeQuotes^%zewdAPI(quotedString)

Parameters DescriptioninputString String whose start and end quotes (if present) are to be removed

returnValue Unquoted version of the input string.


245

renameFileDescription Renames a host file system file.

Design Page Tag(s)Example Set ok=$$renameFile^%zewdAPI(oldName,newName)

Parameters DescriptionoldFilePath Current filepath of file to be renamed

newFilePath New filepathreturnValue Always returns a value of 1


246

replaceDescription Replaces the first instance of a substring in a text string

with another substring

Design Page Tag(s)Example Set oldString=”abcdefghi”

Set newString=$$replace^%zewdAPI(oldString,”def”,”12345”)write newStringabc12345ghi

Parameters DescriptionoldString The string to be converted

fromString The character substring to be replaced

toString The replacement character substring

returnValue The converted string


247

replaceAllDescription Replaces all instances of a substring in a text string with

another substring

Design Page Tag(s)Example Set oldString=”abcdefgdefhi”

Set newString=$$replaceAll^%zewdAPI(oldString,”def”,”12345”)write newStringabc12345g12345hi

Parameters DescriptionoldString The string to be converted

fromString The character substring to be replaced

toString The replacement character substring



248

replaceJavascriptFunctionBodyDescription Finds a specified Javascript function in the EWD page DOM and

replaces its contents

The new function body content is held in a single text variable withline breaks denoted by CRLF [$c(13,10)] characters

Note that this function performs a body replacement – the originalcontents of the JavaScript function will be discarded

Design Page Tag(s) For use in custom tag processing functions

Example Set newBody=” alert('testing') ;”set newBody=newBody_$c(13,10)_” var x = 123 ;”

Set ok=$$replaceJavascriptFunctionBody^%zewdAPI(“myFunc”,newBody,docName)

This would result in:

function myFunc(a,b) { alert('testing') ; var x = 123 ;}

Note that the function declaration and any inputs are left unchanged.

Parameters DescriptionfunctionName The JavaScript function whose contents are to be replaced

newBody Text string containing the new function body contendocName The EWD DOM name. This variable is automatically

available to your custom tag processing functions.

returnValue A value of 1


249

replaceJavascriptObjectBodyDescription Finds a specified Javascript object definition in the EWD page DOM

and replaces its contents

The new object definition body content should be held in a single textvariable with line breaks denoted by CRLF [$c(13,10)] characters

Note that this function performs a complete body replacement – theoriginal contents of the JavaScript function will be discarded

Design Page Tag(s) For use in custom tag processing functions

Example Set newBody=” alert('testing') ;”set newBody=newBody_$c(13,10)_” var x = 123 ;”

Set ok=$$replaceJavascriptObjectBody^%zewdAPI(“myObj.myFunc”,newBody,docName)

This would result in:

myObj.myFunc = function(objid) { alert('testing') ; var x = 123 ; }

Note that the object declaration and any inputs are left unchanged.

Parameters DescriptionobjectName The JavaScript object definition whose contents are to be

replaced

newBody Text string containing the new object definition bodycontent

docName The EWD DOM name. This variable is automaticallyavailable to your custom tag processing functions.

returnValue A value of 1


250

replaceOptionsByFieldNameDescription This function can be used in conjunction with an Event

Broker/HyperEvent call to replace the <option> tags of a specified<select> tag.

The function returns the appropriate stream of Javascript that willreplace all the options.

Design Page Tag(s) <select>, via an Event Broker/ HyperEvent call to Cache.

Example In the Cache function that your Event Broker call invokes you firstreplace the contents of the session List for the <select> tag, eg using:

d clearList^%zewdAPI(“mySelect”,sessid) d appendToList^%zewdAPI(“mySelect”,”New Value 1”,1,sessid) d appendToList^%zewdAPI(“mySelect”,”New Value 2”,2,sessid)...etc

Then Quit from the Cache function using:

QUIT $$replaceOptionsByFieldName^%zewdAPI(formName,”mySelect”,”mySelect”,sessid)

Note that in order to use this method, you need to pass the current formname through the Event Broker interface, eg in your EWD page:

<form name=”myForm”>...<input type=”text” name=”myTextField” value=”*”onChange=”ewd:swapList^myRou(this.form.name)”><select name=”mySelect”></select>...</form>

The Cache function label would be defined as follows:

swapList(formName)

Parameters DescriptionformName The value of the name= attribute of the <form> tag in which the

<select> tag resides.

fieldName The value of the name= attribute of the <select> tag that is beingupdated

listName The name or the EWD Session List that contains the <option> tagdefinitions. In most cases this is the same as the fieldName.

sessid The EWD Session IDreturnValue The stream of javascript that will replace the <select> tag options in

the web page.


251

replaceOptionsByIDDescription This function can be used in conjunction with an Event

Broker/HyperEvent call to replace the <option> tags of a specified<select> tag.

The function returns the appropriate stream of Javascript that willreplace all the options.

Design Page Tag(s) <select>, via an Event Broker/ HyperEvent call to Cache.

Example In the Cache function that your Event Broker call invokes you firstreplace the contents of the session List for the <select> tag, eg using:

d clearList^%zewdAPI(“mySelect”,sessid) d appendToList^%zewdAPI(“mySelect”,”New Value 1”,1,sessid) d appendToList^%zewdAPI(“mySelect”,”New Value 2”,2,sessid)...etc

Then Quit from the Cache function using:

QUIT $$replaceOptionsByID^%zewdAPI(”mySelect”,”mySelect”,sessid)

For example, in your EWD page:

<input type=”text” name=”myTextField” value=”*”onChange=”ewd:swapList^myRou()”><select name=”mySelect”></select>

The Cache function would be defined as follows:

swapList(formName)

Parameters DescriptionselectID The value of the name= attribute (or id= attribute) of the <select> tag

that is being updated. Note that it is unecessary to explicitly define anid= attribute in the <select> tag, since EWD's compiler willautomatically add one with the same value as the name= attribute.

listName The name or the EWD Session List that contains the <option> tagdefinitions. In most cases this is the same as the fieldName.

sessid The EWD Session IDreturnValue The stream of javascript that will replace the <select> tag options in

the web page.


252

sessionArrayValueExistsDescription Determines whether or not a specified session array value

exists in the Session.

Note that this method is limited to session arrays with asingle subscript. If the array has more than one subscript,use the existsInSessionArray method


N/a

Example S exists=$$sessionArrayValueExists^%zewdAPI(“myArray”,”123”,sessid)

Determines whether or not the session array elementmyArray(123) exists in the session.

Parameters DescriptionsessionName The name of the session array

subscript The value of the required subscriptreturnValue 1 = the session array node exists

0 = the session array node is not defined


253

sessionNameExistsDescription Determines whether or not a specified session variable or

array exists in the Session.

Note that this method is limited to session variables andarrays only. If you want to test for the existence of asession object, use sessionObjectPropertyExists


N/a

Example S exists=$$sessionNameExists^%zewdAPI(“colour”,sessid)

Determines whether or not the session variable colourexists in the session.

Parameters DescriptionsessionName The name of the session variable or array

sessid The EWD Session IDreturnValue 1 = the session name exists

0 = the session name is not defined


254

sessionObjectPropertyExistsDescription Determines whether or not a specified session object exists

in the Session.


N/a

Example S exists=$$sessionObjectPropertyExists^%zewdAPI(“person.addr”,”postCode”,sessid)

Determines whether or not the session objectperson.addr.postCode exists in the EWD session.

Parameters DescriptionobjectName The name of the session object

propertyName The name of the propertysessid The EWD Session IDreturnValue 1 = the session name exists

0 = the session name is not defined


255

setApplicationRootPathDescription Sets the EWD application root path (ie the path under



N/a

Example USER> d setApplicationRootPath^%zewdAPI(“d:\ewdApps”)

Parameters DescriptionappRootPath The EWD application root path

returnValue N/a


256

setCheckboxOffDescription Un-checks the specified value in the named HTML

checkbox

Synonymous with removeFromSelected()

Design Page Tag(s) <input type=checkbox>

Example do setCheckboxOff^%zewdAPI(“colours”,”red”,sessid)do setCheckboxOff^%zewdAPI(“colours”,”blue”,sessid)

If the following checkboxes exist, they will be automatically un-checked:


This method is not required if the initialiseCheckbox() method is used.

Parameters DescriptionfieldName Name of the HTML checkbox field(s)

value Checkbox value to be un-checked


returnValue n/a


257

setCheckboxOnDescription Checks the specified value in the named HTML checkbox

Synonymous with addToSelected()

Design Page Tag(s) <input type=checkbox>

Example do setCheckboxOn^%zewdAPI(“colours”,”red”,sessid)do setCheckboxOn^%zewdAPI(“colours”,”blue”,sessid)

If the following checkboxes exist, they will be automatically checked:


Parameters DescriptionfieldName Name of the HTML checkbox field(s)

value Checkbox value to be checked


returnValue n/a


258

setCheckboxValuesDescription Checks the values of an HTML checkbox, as specified via

a local array.

Synonymous with mergeToSelected()



Example do setCheckboxValues^%zewdAPI("colours",.values,sessid)

If the local array “values” contains:


Then the following checkbox values will be checked when the page isrendered:


Parameters DescriptionfieldName The checkbox field name

localArrayName The name of the local array that contains the values to bechecked

Called by reference


returnValue n/a


259

setCookieValueDescription Sets the value of a cookie on the user’s browser


n/a

Example do setCookieValue^%zewdAPI(“username”,”rob”,8640000,sessid)

Sets the value of the cookie named username to the literal value “rob”.The cookie will expire after 100 days.

Parameters DescriptioncookieName Name of the cookie

value Value of the cookie

expiryDuration The number of seconds until the cookie should expire

If not set, this defaults to zero. The cookie will thereforeexpire when the user closes the browser.

Also see the convertDaysToSeconds function.


returnValue n/a


260

setFieldErrorDescription This function forms part of EWD's automated mechanism

for highlighting errors when a form is submitted.

To use this mechanism, a CSS class must be defined todetermine how a field should be rendered if an error isflagged, eg:

<style type="text/css">.myErrorClass {background-color : #ffec9e ;border-color : #ff0000 ;}</style>

Then in each page, declare the error class in the<ewd:config> using the errorClass attribute:

<ewd:config ... errorClass=”myErrorClass” ...>

In your action script, you add the setFieldError function toyour field error checking logic. For example, if you werechecking to ensure that the field “title” could not have anull value:

i title="" d setFieldError^%zewdAPI("title",sessid) QUIT"You must enter a password"

In this case just the "title" field will be highlighted byapplying the error class, but you can reference as manyfields as you wish by making multiple calls to this APImethod before quitting from the action script.


Any form fields

Example do setFieldError^%zewdAPI(“myField”,sessid)

Flags the form field named “myField” to be highlighted using thenominated error stylesheet class.

Parameters DescriptionfieldName Name/ID of the field to be highlighted as in error


returnValue n/a


261

setHiddenValueDescription Sets the value of an HTML hidden field. The value will be

set into the HTML form when the page is rendered.

Synonymous with setSessionValue()


<input type=hidden>

Example do setHiddenValue^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName Name of the hidden field.

The fieldName should be the same as that of the formfield, and must match in terms of upper/lower case.

Eg If the hidden field name is “Username”, then thefieldName must also be “Username”, and not “username”or “USERNAME”.

value The value to be set into the HTML hidden field


returnValue n/a


262

setJSScriptsPathModeDescription Set the type of web server path in which an EWD application's

Javascript [.js] files will be found – ie fixed or relative.



Example D setJSScriptsPathMode^%zewdAPI("php",”fixed”)


pathMode The type of webserver path under which this application's .js files willbe found.

Possible values are:

– fixed– relative

If the path mode is not defined, the function returns a null value.

returnValue N/a


263

setJSScriptsRootPathDescription Set the root web server path in which an EWD application's Javascript

[.js] files will be found (if defined)



Example S rootPath=”c:\myJSPath”D setJSScriptsRootPath^%zewdAPI("php",rootPath)


rootPath The web server root path for .js files

ReturnValue N/a


264

setJumpDescription Used in a pre-page script to reset the page to which the

user will be directed.

This method is identical to the setRedirect() method (seelater)


n/a

Example do setJump^%zewdAPI(“mynextpage”,sessid)

Parameters DescriptionpageName Name of the page to which the user will be redirected.

The page name should not include the file extension (ie .php or .ewd), and should be in lower case.


returnValue n/a


265

setMultipleSelectOffDescription De-selects the specified option in the named HTML

multiple-choice <select> tag

Synonymous with removeFromSelected()

Design Page Tag(s) <select multiple=”multiple”>

Example do setMultipleSelectOff^%zewdAPI(“colours”,”red”,sessid)do setMultipleSelectOff^%zewdAPI(“colours”,”blue”,sessid)

If the following options exist, they will be automatically de-selected:

<select name=”colours” multiple=”multiple”><option value=”red”>Red</option><option value=”blue”>Blue</option></select>

This method is not required if the initialiseCheckbox() method is used.

Parameters DescriptionfieldName Name of the HTML multiple-choice <select> tag

value Option value to be de-selected


returnValue n/a


266

setMultipleSelectOnDescription Selects/highlights the specified option in the named HTML

multiple-choice <select> tag

Synonymous with addToSelected()

Design Page Tag(s) <select multiple=”multiple”>Example do setMultipleSelectOn^%zewdAPI(“colours”,”red”,sessid)

do setMultipleSelectOn^%zewdAPI(“colours”,”blue”,sessid)

If the following options exist, they will be automatically highlightedand selected:

<select name=”colours” multiple=”multiple”><option value=”red”>Red</option><option value=”blue”>Blue</option></select>


value Option value to be highlighed


returnValue n/a


267

setMultipleSelectValuesDescription Selects/highlights the specified options in the named

HTML multiple-choice <select> tag, via a local array ofvalues.

Synonymous with mergeToSelected()



Example do setMultipleSelectValues^%zewdAPI("colours",.values,sessid)

If the local array “values” contains:


Then the following options will be checked when the page is rendered:

<select name=”colours” multiple=”multiple”><option value=”r”>Red</option><option value=”b”>Blue</option></select>


localArrayName The name of the local array that contains the values to beselected

Called by reference


returnValue n/a


268

setNamespaceDescription Change Cache namespaceAssociated Design PageTag(s)

N/a

Example D setNamespace^%zewdAPI("user”)

Parameters Descriptionnamespace The Cache namespace to which you want to change

ReturnValue N/a


269

setOutputRootPathDescription Set the root file path into which EWD will compile pages for the




Example D setOutputRootPath^%zewdAPI("php",”d:\php\apps”)


rootPath The compilation output root path.

returnValue N/a


270

setRadioOnDescription Checks the HTML radio button field with the

corresponding value.



<input type=radio>

Example do setRadioValue^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName Name of the radio button field.

The fieldName should be the same as that of the radio button field, andmust match in terms of upper/lower case.

Eg If the radio button field name is “Username”, then the fieldNamemust also be “Username”, and not “username” or “USERNAME”.

value The value of the radio button to be checked


returnValue n/a


271

setRedirectDescription Used in a pre-page script to reset the page to which the

user will be directed.

This method is identical to the setJump() method (seeabove)


n/a

Example do setRedirect^%zewdAPI(“mynextpage”,sessid)

Parameters DescriptionpageName Name of the page to which the user will be redirected.

The page name should not include the file extension (ie .php or .ewd), and should be in lower case.


returnValue n/a


272

setResponseHeaderDescription Set an HTTP response header


Used in your scripts to define an HTTP response header which will besent along with the rendered page.

Example D setResponseHeader^%zewdAPI("content-type",”text/xml”,sessid)

Parameters DescriptionheaderName HTTP Request Header name (must be a standard HTTP request header

name)

headerValue HTTP Request Header value

sessid The current Session IDreturnValue N/a


273

setRootURLDescription Set the root URL that EWD will generate in all page URLs for a




Example D setRootURL^%zewdAPI("csp",”/csp/ewd”)


rootURL The root URL to be used when EWD generates all its page URLs

returnValue N/a


274

setSelectValueDescription Highlights the option with the corresponding value in an HTML single-

choice <select> tag.



<select>

Example do setSelectValue^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName Name of the select tag.

The fieldName should be the same as the name attribute value of the<select> tag, and must match in terms of upper/lower case.

Eg If the <select> tag's name is “Username”, then the fieldName mustalso be “Username”, and not “username” or “USERNAME”.

value The value of the option to be highlighed. Eg if the <select> tagincluded:

<option value=”r”>Red</option>

Then if the value was “r”, the “Red” option would be highlighed in theweb page when it was rendered.


returnValue n/a


275

setSessionArrayDescription Sets an item into an array within the session object


n/a

Example do setSessionArray^%zewdAPI(“staff”,”director”,”rob”,sessid)Parameters Description

arrayName Name of the array in the session object.

itemName Name of the item to be set into the array

itemValue Value of the item to be set into the array


returnValue n/a


276

setSessionValueDescription Sets the value of a simple session variable or a session

object



Example do setSessionValue^%zewdAPI(“colour”,”red”,sessid)

Sets the value of the session variable “colour” to “red”

Example of session object:

do setSessionValue^%zewdAPI(“person.addr.zipCode”,”123456”, sessid)

Sets the value of the session object person.addr.zipCode to “123456”

Parameters DescriptionvariableName Name of the session variable or object reference.



value The value to be assigned to the session variable or object


returnValue n/a


277

setSessionValuesDescription Sets the values of session variables that have been defined

in a local array. Allows “bulk” setting of session valueswith a single function call.


<input type=text><input type=password><input type=hidden><input type=radio><input type=checkbox><select><select multiple>

Example do setSessionValues^%zewdAPI(.valueArray,sessid)

Parameters DescriptionarrayName Name of the local array that holds names and values to be

set into the session. Must be called by reference.

The structure of this array is:

- for single value fields:

arrayName(fieldname)=value

- for multi-value fields (eg checkbox, multiple select) :

arrayName(fieldname,sequenceNo)=value

where sequenceNo is an integer, starting at 1. Thesequence number has no significance, other thanallowing multiple values to be assigned to a name.

for example:

s array("test1")=1 s array("test3")="field 3" s array("text4")="field 4" s array("test2",1)=2 s array("test2",2)=3 s array("test5")="B"


returnValue n/a


278

setTextValueDescription Sets the value of an HTML text field. The value will

appear in the HTML form when the page is rendered.



<input type=text>

Example do setTextValue^%zewdAPI(“colour”,”red”,sessid)

Parameters DescriptionfieldName Name of the text field.

The fieldName should be the same as that of the formfield, and must match in terms of upper/lower case.

Eg If the text field name is “Username”, then thefieldName must also be “Username”, and not “username”or “USERNAME”.

value The value to be set into the HTML text field


returnValue n/a


279

setWarningDescription Creates a user warning and sets it into the session object

Optionally used in action scripts.

The warning will be presented to the user in the form of aJavaScript alert.


<input type=submit>

Example do setWarning^%zewdAPI(“The attachment has been deleted”,sessid)

Parameters DescriptionwarningMessage Defines the text of the warning message


returnValue n/a


280

stripLeadingSpacesDescription Removes all leading spaces from a text string


N/a

Example W $$stripLeadingSpaces(“ hello Rob”)hello Rob

Parameters Descriptionstring Text string

returnValue The text string with all leading spaces removed


281

stripSpacesDescription Removes all leading and trailing spaces from a text string


N/a

Example W $$stripLeadingSpaces(“ hello Rob ”)_”x”hello Robx


returnValue The text string with all leading and trailing spaces removed


282

stripTrailingSpacesDescription Removes all trailing spaces from a text string


N/a

Example W $$stripLeadingSpaces(“hello Rob ”)_”x”hello Robx


returnValue The text string with all trailing spaces removed


283

suppressResponseHeaderDescription Suppress an HTTP response header from being generated by CSP


Used in CSP compilations only, to suppress HTTP Response Headersthat CSP will otherwise generate by default.

Example D suppressResponseHeader^%zewdAPI("expires",sessid)

Parameters DescriptionheaderName HTTP Request Header name to be suppressed (must be a standard

HTTP request header name)

sessid The current Session IDreturnValue N/a


284

systemMessageDescription Defines a localized message for use within Action and/or

pre-page Scripts. Also appropriately escapes the text.

The behaviour of this function depends on a number ofcircumstances:

5) If the application has not been compiled to use multi-lingual localization, the specified error message ispassed back unchanged

6) If the application is compiled using multi-linguallocalization and you are running in the defaultlanguage, the specified error message is passed backunchanged.

7) If the application is compiled using multi-linguallocalization and you are running in a language otherthan the default one but no translation is available,the specified error message is passed backunchanged. The first time this function runs for thespecified message, the error message is automaticallyadded to the phrase table and is allocated a text ID.

8) If the application is compiled using multi-linguallocalization and you are running in a language otherthan the default one and a translation is available, thefunction returns the translated phrase.


Not associated with specific tags.

Example set warning=$$systemMessage^%zewdAPI(“Details have beenupdated”,”advisory”,sessid)

Parameters DescriptionerrorMessage The error message (in the default language).


285

messageType User-defined type/category for the message. This parameteris used to categorise the message within the phraselocalization tables, to provide a means of identifying itssource when reviewing the translations of phrases.

Note that the errorMessage() function is actuallysynonymous with:

errorMessage=$$systemMessage^%zewdAPI(errorMessage,“error”,sessid)

ie it adds error messages to the localization table with amessageType of “error”. If you wish error messages to beidentified with another messageType, use thesystemMessage() function.


returnValue The original or translated version of the error message (seethe description above)


286

traceDescription Saves a text string as the last current record in the ^%zewdTrace global


Used for debugging purposes in your scripts

Note: the ^%zewdTrace global is not used for any other purpose andcan be safely killed, in whole or in part, at any time.

Example D trace^%zewdAPI(“myVar = “_myVar)

Parameters Descriptionstring Text string to be added as the last record in the ^%zewdTrace globalreturnValue N/a


287

traceModeOnDescription Switches trace mode on

A number of important and critical events are logged to the global ^%zewdTrace when this mode is activated, eg:

– the contents of each raw request– the current session contents– details of prepage and action scripts that are invoked


N/a

Example D traceModeOn^%zewdAPIParameters Description

returnValue N/a


288

traceModeOffDescription Switches trace mode off

Note: The contents of ^%zewdTrace are not deleted


N/a

Example D traceModeOff^%zewdAPIParameters Description

returnValue N/a


289

versionDescription Returns the current version and build number of eXtc Web Developer.


N/a

Example W $$version^%zewdAPI()eXtc Web Developer version 2.1.486

Parameters DescriptionreturnValue The current version and build number of eXtc Web Developer


290

zcvtDescription Provides an implementation-independent means of invoking Cache's

$zconvert (zcvt) function, eg for converting strings to upper and lowercase.

If you are developing applications for use on GT.M as well as, orinstead of Cache, then use this function instead of $zcvt.


N/a

Example S convertedString=$$zcvt^%zewdAPI(inString,”l”)

Converts inString to lower case.

Parameters DescriptioninputString The String to be convertedconversion Flag denoting the conversion required, eg:

– l : convert to lower case– u : convert to upper case



291

Logging out of a session

A user is explicitly logged out of a session by switching to the special pageewdLogout.ewd, either via a URL (eg within a <a> tag) or via the nextpage attribute of,for example, a submit button.


292

eXtc Web Developer Javascript Functions

EWD provides a range of Javascript functions that are available for you to use withinyour pages. EWD makes use of Javascript Objects, and all the internal functions existwithin the EWD object.

The following pages describe in detail the EWD Javascript functions.


293

EWD.ajax.allowSubmitDescription Property which will allow or prevent an Ajax Form submission from

taking place.

Example Typical use involves adding an onClick Event Hander to the <inputtype=submit ajax=”true”> tag within a form in an Ajax Page Fragment.If the Javascript function called by the Event Handler setsEWD.ajax.allowSubmit = false, then the form submission will not takeplace

eg

EWD.ajax.allowSubmit = false ;

The property is re-initialised automatically after use.


294

EWD.utils.findPosXDescription Returns the x-coordinate of the current page object.

Example var left = EWD.utils.findPosX(thisObj)

Typically thisObj would be passed via a tag's Event Handler as this

Alternatively:

var left = EWD.utils.findPosX(document.getElementById('myTag'))

Parameters Descriptionobj Pointer to a Javascript object such as an input tag.returnValue x-coordinate


295

EWD.utils.findPosYDescription Returns the y-coordinate of the current page object.

Example var top = EWD.utils.findPosY(thisObj)

Typically thisObj would be passed via a tag's Event Handler as this

Alternatively:

var top = EWD.utils.findPosY(document.getElementById('myTag'))

Parameters Descriptionobj Pointer to a Javascript object such as an input tag.returnValue y-coordinate


296

EWD.utils.getObjectFromSessionDescription Fetches a specified EWD session object via an Event Broker request

and instantiates it as a corresponding Javascript object of the samename

Example EWD.utils.getObjectFromSession (“myObject”)

The properties of the EWD session object named myObject will beinstantiated as Javascript object of the same name.

Use this in conjunction with the API methodmergeArrayFromSessionObject.

Parameters DescriptionobjName The name of the EWD session object to be copiedreturnValue n/a


297

EWD.utils.getPieceDescription Emulates the MUMPS $piece function, whereby a substring can be

extracted within a specified delimiter substring.

For example if a Javascript string variable contained the following:

abc#1234#def6#9877

then the substring “def6” could be extracted as piece number 3 using adelimiter of “#”

Example var refStr = “abc#1234#def6#9877” ;var subStr = EWD.utils.getPiece(refStr,”#”,3)) ;

subStr would contain the value “def6”

Parameters DescriptionrefString The reference string to be analyseddelimiter The substring to be used as a delimiterpieceNo The number of the piece to be extractedreturnValue The specified substring


298

EWD.utils.isIntegerDescription Determines whether or not a Javascript variable is an integer

Example var myVar = 1234 ;if (EWD.utils.isInteger(myVar)) alert(“Yes myVar is an integer!”) ;

Parameters DescriptionrefVar The reference variable to be testedreturnValue true if the reference string is an integer

false if the reference string is not an integer


299

EWD.utils.mergeObjectFromSessionDescription Fetches the properties of a specified EWD session object (or sub-

object) via an Event Broker request and merges them into acorresponding Javascript object

Example EWD.utils.mergeObjectFromSession (“person.address”, ”ACME.person”) ;

The properties of the EWD session object person.address will bemerged into the Javascript object ACME.person, eg

person.address.town >> ACME.person.townperson.address.zip >> ACME.person.zip

Parameters DescriptionsessionName The name of the EWD session object to be copiedjsOBJName The name of the Javascript object into which the properties will be

mergedreturnValue n/a


300

EWD.utils.putObjectToSessionDescription Sends a specified Javascript to Cache or GT.M via an Event Broker

request and instantiates it as a corresponding EWD session object

Note that only simple name/value pair properties within the Javascriptobject will be transferred. Functions, arrays or more complex, nested,properties will be ignored.

Example EWD.utils.putObjectToSession(“myObject”)

The properties of the Javascript object named myObject will beinstantiated as an EWD session object.

Parameters DescriptionobjName The name of the Javascript object to be copied to an EWD session

objectreturnValue n/a


301

Index

1) EWD Custom Tags

Tag Name Page<ewd:ajaxOnload> 12<ewd:apply> 13<ewd:backdrop> 98<ewd:block> 99<ewd_body> 97<ewd:config> 14<ewd:content> 100<ewd:comment> 21<ewd:else> 22<ewd:elseIf> 23<ewd:execute> 24<ewd:expandPage> (see also <ewd:url>) 26<ewd:footer> 96<ewd:for> 27<ewd:forEach> 30<ewd:getArrayValue> 33<ewd:getPiece> 34<ewd:getSessionArrayValue> 35<ewd:getSessionValue> 37<ewd:head> 94<ewd:header> 95<ewd:if> 38<ewd:ifArrayExists> 39<ewd:ifContains> 40<ewd:ifSessionArrayExists> 41<ewd:ifSessionNameExists> 43<ewd:image> 44<ewd:imageMap> 44


302

Tag Name Page<ewd:include> 45, 103<ewd:incrementCounter> 46<ewd:initialiseArray> 47<ewd:insertBlock> 101<ewd:insertPage> 102<ewd:instantiate> 48<ewd:javascript> 49<ewd:mergeToJSObject> 50<ewd:modulo> 52<ewd:moveTag> 53<ewd:refresh> 54<ewd:replace> 55<ewd:responseHeader> 56<ewd:schemaForm> 57<ewd:schemaViewInstance> 58<ewd:set> 60<ewd:setArrayValue> 62<ewd:spinner> 63<ewd:svg> 65<ewd:svgPage> 66<ewd:template> 93<ewd:trace> 68<ewd:url> 69

2) Special EWD features of standard HTML tags

HTML Tag Page<form> 70<input type=”button”> 77,84<input type=”checkbox”> 73,84<input type=”file”> 74,84<input type=”hidden”> 71,84


303

HTML Tag Page<input type=”image”> 71,71<input type=”password”> 71,84<input type=”radio”> 72,84<input type=”submit”> 81<input type=”text”> 71,84<select> 75<textarea> 76

3) Special EWD features of attributes of standard HTML tags

(ie applying to any HTML tags with the following attributes:)

Attribute Name Pagedata= 86href= 86onxxxx= (ie any event handler) 87src= 86url= 86

4) EWD shortcuts and special functionality

Functionality PageConditionalised form submission with confirmation message 81document.location, specifying an EWD page name 91Event Broker, HyperEvents, Event-driven server-side access 90Form submission 70, 81Name/Value pairs, in attributes that specify an EWD page/URL 85Pop-up windows 87


304

5) EWD API Methods for use in Scripts (in ^%zewdAPI)

Method Name PageaddCSPServerScript 115addJavascriptFunction 116addJavascriptObject 117addServerToSession 118addToList 119addToResultSet 120addToSelected 121addToSession 122appendToList 123appendToTextArea 124applicationRootPath 125clearAllSelected 126clearList 127clearSchemaFormErrors 128clearSelected 129clearSessionArray 130clearSessionByPrefix 131clearTextArea 132compileAll 3compilePage 5convertDateToSeconds 133convertDaysToSeconds 134convertSecondsToDate 135copyList 136copyObjectToSession 137copyRequestValueToSession 138copyResultSetToSession 139countList 140createDirectory 141createJSPCommand 142


305

Method Name PagecreatePHPCommand 143createTextArea 144decDate 145deleteAllErrorLogs 146deleteCookie 147deleteErrorLog 148deleteFile 149deleteFromSession 150deleteFromSessionObject 151deleteSession 152deleteSessionObject 153deleteWarning 154directoryExists 155doubleQuotes 156errorMessage 157existsInSession 158existsInSessionArray 159fileExists 160fileInfo 161fileSize 162getApplicationRootPath 163getCheckboxValues 164getCookieValue 165getDataTypeErrors 166getDefaultFormat 167getDefaultMultiLingual 168getDefaultTechnology 169getHiddenValue 170getJavascriptFunctionBody 171getJavascriptObjectBody 172getJSScriptsPath 173getJSScriptsPathMode 174


306

Method Name PagegetJSScriptsRootPath 175getMultipleSelectValues 176getNextChild 177getNormalisedAttributeValue 178getOutputRootPath 179getPasswordValue 180getRadioValue 181getRequestValue 182GetResultSetValue 183getRootURL 184getSelectValue 185getServerValue 186getSessionArray 187getSessionValue 188getSessionValues 189getSessionValuesByPrefix 191getTagByNameAndAttr 192getTagOID 193getTextArea 194getTextFromList 195getTextValue 196getTraceMode 197getUploadedFileName 198getUploadedFileSize 199getUploadedFileType 200import 201inetDate 202inetTime 203initialiseCheckbox 204initialiseMultipleSelect 205instantiateJSPVar 206isCheckboxOn 207


307

Method Name PageisListDefined 208isMultipleSelectOn 209isRadioOn 210isSelected 211isSelectOn 212javascriptFunctionExists 213javascriptObjectExists 214listDOMsByPrefix 215loadErrorSymbols 216lowerCase 217makeString 218mergeArrayFromSession 219mergeArrayToSession 220mergeArrayToSessionObject 221mergeFromRequest 222mergeFromSelected 223mergeFromSession 224mergeFromTextArea 225mergeGlobalFromSession 226mergeGlobalToSession 227mergeRcordArrayToResultSet 228mergeTextAreaFromRequest 229mergeToList 230mergeToSelected 231mergeToSession 232mergeToTextArea 233namespace 234parseHTMLFile 235parseHTMLStream 236parseStream 237parseURL 238parseXMLFile 239


308

Method Name PagerandChar 240removeDOMsByPrefix 241removeFromList 242removeFromSelected 243removeInstanceDocument 244removeQuotes 245renameFile 246replace 247replaceAll 248replaceJavascriptFunctionBody 249replaceJavascriptObjectBody 250replaceOptionsByFieldName 251replaceOptionsByID 252sessionArrayValueExists 253sessionNameExists 254sessionObjectPropertyExists 255setApplicationRootPath 256setCheckboxOff 257setCheckboxOn 258setCheckboxValues 259setCookieValue 260setFieldError 261setHiddenValue 262setJSScriptsPathMode 263setJSScriptsRootPath 264setJump 265setMultipleSelectOff 266setMultipleSelectOn 267setMultipleSelectValues 268setNamespace 269setOutputRootPath 270setRadioOn 271


309

Method Name PagesetRedirect 272setResponseHeader 273setRootURL 274setSelectValue 275setSessionArray 276setSessionValue 277setSessionValues 278setTextValue 279setWarning 280stripLeadingSpaces 281stripSpaces 282stripTrailingSpaces 283suppressResponseHeader 284systemMessage 285trace 287traceModeOn 288traceModeO 289version 290zcvt 291

6) EWD Javascript Functions & Properties

Function Name PageEWD.ajax.allowSubmit 294EWD.utils.findPosX 295EWD.utils.findPosY 296EWD.utils.getObjectFromSession 297EWD.utils.getPiece 298EWD.utils.isInteger 299EWD.utils.mergeObjectFromSession 300EWD.utils.putObjectToSession 301


310

extc web developer api manual - m/gatewaygradvs1.mgateway.com/download/apiguide3.0.618.pdf · extc...

Documents