extc web developer api manual - m/gatewaygradvs1.mgateway.com/download/apiguide3.0.618.pdf · extc...
TRANSCRIPT
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.
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
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.
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
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
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
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.
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
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.
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
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
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
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>
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
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)
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
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.
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
10
extc Web Developer Custom Tags
The set of Custom Tags that are included in EWD are described below.
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
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
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
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.
AttributesName Value(s) Notes Default
technology “csp”, “jsp” or “php” n/a
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
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.
AttributesName Value(s) Notes Default
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
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
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
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
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
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
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”
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
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
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
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.
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
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
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
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.
AttributesName Value(s) Notes Default
n/a n/a
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
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>
AttributesName Value(s) Notes Default
n/a n/a
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
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>
AttributesName Value(s) Notes Default
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
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
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">
AttributesName Value(s) Notes Default
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
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
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
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
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”>
AttributesName Value(s) Notes Default
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
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
26
<ewd:for>Description This tag may be used to specify a “for” loop
AttributesName Value(s) Notes Default
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
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
27
to Terminating 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 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.
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 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
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
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
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
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.
AttributesName Value(s) Notes Default
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
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
30
return Defines the CSP/PHP/JSP variable thatwill hold the value of the array data ateach iteration
Eg return=”$data”
The attribute valuemust begin with a “$”to denote a variable.
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
The attribute valuemust begin with a “$”to denote a variable.
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
The attribute valuemust begin with a “$”to denote a variable.
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>
The attribute valuemust begin with a “$”to denote a variable.
n/a
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
31
param1param2…paramn
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
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 “#”
A value of space (“ “)must be specifiedusing the specialpseudo-variable$space
A value of null (““)must be specifiedusing the specialpseudo-variable $nul
n/a
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
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.
AttributesName Value(s) Notes Default
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
Eg return=”$data”
Must be a variable.
The attribute valuemust begin with a “$”to denote a variable.
n/a
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
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.
AttributesName Value(s) Notes Default
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”
Must be a variable n/a
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
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>
AttributesName Value(s) Notes Default
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
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
35
param1param2…paramn
An alternative to using index. If thesession array is multi-dimensional, ie ofthe format:
Array(sessionName,param1,param2,…, Paramn)
..then define the additional parameters,specifying the array node required
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 “#”
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
Eg return=”$data”
The attribute valuemust begin with a “$”to denote a variable.
n/a
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
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().
AttributesName Value(s) Notes Default
sessionName The name of the session variable n/a
return Defines the CSP/PHP/JSP variable thatwill hold the value of the specifiedsession variable
Eg return=”$data”
The attribute valuemust begin with a “$”to denote a variable.
n/a
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
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>
AttributesName Value(s) Notes Default
firstVallue 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
secondVallue 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
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
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”>
AttributesName Value(s) Notes Default
arrayName The name of the local array The name should notbe prefixed with a“$”, even if this isbeing compiled toPHP
n/a
param1param2…paramn
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
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
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
39
<ewd:ifContains>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
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>
AttributesName Value(s) Notes Default
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”
Usually a variable n/a
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
Literal value orvariable
n/a
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
40
<ewd:ifSessionArrayExists>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
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” >
AttributesName Value(s) Notes Default
sessionName The session variable or array that is to betested for its instantiation
Eg sessionName=”jobDetails”
Literal value n/a
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
41
param1param2…paramn
Additional parameters, specifying thearray node required
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
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
42
<ewd:ifSessionNameExists>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
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>
AttributesName Value(s) Notes Default
sessionName The session variable or array that is to betested for its instantiation
Eg sessionName=”jobDetails”
Literal value n/a
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
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
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
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”>
AttributesName Value(s) Notes Default
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
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
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”>
AttributesName Value(s) Notes Default
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
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
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.
AttributesName Value(s) Notes Default
arrayName The array that is to be initialized.
Eg arrayName=”myArray”
Literal value n/a
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
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.
AttributesName Value(s) Notes Default
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
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
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.
AttributesName Value(s) Notes Default
n/a n/a n/a n/a
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
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.
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
50
AttributesName Value(s) Notes Default
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
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
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”>
AttributesName Value(s) Notes Default
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
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
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.
AttributesName Value(s) Notes Default
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
Usually a literal value
FALSE
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
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">
AttributesName Value(s) Notes Default
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
Usually a literal value n/a
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
54
<ewd:replace>Description This tag is used to replace all occurrences of a substring within a string literal or
variable.
AttributesName Value(s) Notes Default
input The source string literal or variable
A variable is specified by putting a “$” infront of the name
Eg input=”$myString”
Usually a variable n/a
fromString The substring that is to be replaced if it isfound in the input
A variable is specified by putting a “$” infront of the name
Eg fromString=”hello”
Usually a literal value n/a
toString The substring that is to substitute eachoccurrence of the fromString
A variable is specified by putting a “$” infront of the name
Eg toString=”there”
Usually a literal value n/a
return The resulting string variable containingthe substituted substrings
A variable is specified by putting a “$” infront of the name
Eg return=”$myNewString”
Must be a variable n/a
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
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”>
AttributesName Value(s) Notes Default
name HTTP Response Header name
Eg name=”Content-type”
Usually a literal value n/a
value HTTP Response Header value
Eg value=”image/svg+xml”
Usually a literal value n/a
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
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
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>
AttributesName Value(s) Notes Default
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
Literal value orsession variable
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
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
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" />
AttributesName Value(s) Notes Default
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.
Literal value orsession variable
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
Literal value orsession variable
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
Literal value orsession variable
false
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
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.
Literal value orsession variable
The stylesheetdefined in theassociatedschema isapplied.
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
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
AttributesName Value(s) Notes Default
return The variable to be created
A variable is specified by putting a “$” infront of the name
Eg return=”$myNewString”
Must be a variable n/a
value The value to which the return variable isto be set.
A variable is specified by putting a “$” infront of the name
Eg value=”hello”
Usually a literal n/a
firstValue A literal or variable value
A variable is specified by putting a “$” infront of the name
Eg firstValue=”$x”
n/a
secondValue A literal or variable value
A variable is specified by putting a “$” infront of the name
Eg secondValue=”123”
n/a
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
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
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
61
<ewd:setArrayValue>Description This tag is used set a local array value in the CSP, PHP or JSP page
AttributesName Value(s) Notes Default
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.
A variable is specified by putting a “$” infront of the name
Eg index=”3”
Usually a literal n/a
value The value to which the array element isto be set.
A variable is specified by putting a “$” infront of the name
Eg value=”hello”
Usually a literal n/a
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
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!')" />
AttributesName Value(s) Notes Default
name Name and id that will be applied to thespinner's <input type=”text”> field.
Usually a litreral n/a
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
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
63
onUp Event handler to be applied as anonClick event to the increment/Up button
Usually a literal n/a
onDown Event handler to be applied as anonClick event to the decrement/Downbutton
Usually a literal n/a
onUporDown Event handler to be applied as anonClick event to both buttons
Usually a literal n/a
All otherattributes
eg onChange,class etc
Any other event handler orattribute may be defined, and willbe applied to the text fieldcomponent of the spinner.
Usually a literal n/a
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
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>
AttributesName Value(s) Notes Default
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.
Usually a literal n/a
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
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">
AttributesName Value(s) Notes Default
method The method to be invoked that willgenerate the SVG stream
Eg method=”myProc^myRoutine”
Usually a litreral n/a
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
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.
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
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.
AttributesName Value(s) Notes Default
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
Usually a literal value n/a
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
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" />
AttributesName Value(s) Notes Default
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
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
69
<form>Description eXtc Web Developer can be instructed to automate your forms
AttributesName Value(s) Notes Default
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
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
70
<input type=”text”><input type=”password”>
<input type=”hidden”>Description eXtc Web Developer can provide several shorthand mechanisms
AttributesName Value(s) Notes Default
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
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
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.
AttributesName Value(s) Notes Default
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.
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
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.
AttributesName Value(s) Notes Default
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.
Eg checkUsing=”$activated”
Allows you to over-ride the automaticchecking mechanism
This is a usefulmechanism if you areusing a checkboxwithin a<ewd:forEach> loop
The normalauto-checkingmechanism isapplied if thisattribute is notspecified.
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
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.
AttributesName Value(s) Notes Default
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
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
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.
AttributesName Value(s) Notes Default
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.
Eg checkUsing=”$activated”
Allows you to over-ride the automaticchecking mechanism
The normalauto-checkingmechanism isapplied if thisattribute is notspecified.
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
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.
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
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.
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
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,
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
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
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
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.
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
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
AttributesName Value(s) Notes Default
action methodCall
where methodCall can be a call to aCaché extrinsic function, a Caché methodor a PHP function.
eg:
action=”myFunc^myRoutine”
action= ”##class(myPckge.myClass).myMethod”
action=”$myPHPFunc”
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.
If no actionattribute isspecified, thenno actionmethod isinvoked. Inthis situation,if a nextpageattribute isspecifed, thenthe user willbe takenuncondition-ally to thespecifiedpage.
nextpage pageName
eg nextpage=”myNextPage”
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
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
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>
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
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.
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
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.
AttributesName Value(s) Notes Default
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:
action=”myFunc^myRoutine”
action= ”##class(myPckge.myClass).myMethod”
action=”$myPHPFunc”
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.
If no actionattribute isspecified, thenno actionmethod isinvoked. Inthis situation,if a nextpageattribute isspecifed, thenthe user willbe takenuncondition-ally to thespecifiedpage.
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
84
nextpage pageName
eg nextpage=”myNextPage”
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,
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
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>
AttributesName Value(s) Notes Default
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
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
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>
AttributesName Value(s) Notes Default
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
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
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
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
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
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
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>
AttributesName Value(s) Notes Default
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
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
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>
AttributesName Value(s) Notes Default
n/a n/a
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
91
Tags used within Template Pages
This section details the special tags that may be specified in the template page(ewdTemplate.ewd).
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
92
<ewd:template>Description This tag is used as the document element (ie outer tag) of an ewdTemplate.ewd page.
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
n/a
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
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..
AttributesName Value(s) Notes Default
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.
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
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).
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
id The id of the target page block to beinserted into the corresponding template<ewd:insertBlock> tag
Literal value N/a
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
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.
AttributesName Value(s) Notes Default
n/a
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
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>
AttributesName Value(s) Notes Default
id The id of the target page block to beinserted into the template backdrop
Literal value N/a
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
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)
AttributesName Value(s) Notes Default
n/a
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
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.
AttributesName Value(s) Notes Default
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
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
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=”*”>
Synonymous with setSessionValue(), this methodcreates the named session variable and assigns a singlevalue to it.
setRadioOn() Maps a Caché value to an HTML radio button, andcauses it to be checked, eg:
<input type=”radio” name=”colour” value=”r”>
Synonymous with setSessionValue(), this methodcreates the named session variable and assigns a singlevalue to it.
Note that there is no setRadioOff() method. A radiobutton is turned off by setting another value on.
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
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>
Synonymous with setSessionValue(), this methodcreates the named session variable and assigns a singlevalue to it.
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()
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
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):
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
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”>
Synonymous with getSessionValue(), this methodretrieves the value from the named session variable.
getHiddenValue() Maps a submitted HTML hidden field to a Caché value .
<input type=”hidden” name=”myPassword”>
Synonymous with getSessionValue(), this methodretrieves the value from the named session variable.
getRadioValue() Maps the checked value of a submitted HTML radiobutton field to a Caché value .
Synonymous with getSessionValue(), this methodretrieves the value from the named session variable.
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 .
Synonymous with getSessionValue(), this methodretrieves the value from the named session variable.
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()
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
108
getTextArea() Maps the submitted text contained within the specifiedtextarea field into a Caché local array.
Synonymous with mergeFromTextArea()
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
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
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
110
Multi-Value Form FieldsRelevant Fields <input type=checkbox>
<select multiple=multiple>
Associated Methods initialiseCheckboxsetCheckboxOnsetCheckboxOffsetCheckboxValuesinitialiseMultipleSelectsetMultipleSelectOnsetMultipleSelectOffsetMultipleSelectValuesisCheckboxOngetCheckboxValuesisMultipleSelectOngetMultipleSelectValuesaddToSelectedclearAllSelectedclearSelectedmergeFromSelectedmergeToSelectedisSelectedclearSessionByPrefixgetSessionValuessetSessionValues
TextArea FieldsRelevant Fields <textarea>
Associated Methods appendToTextAreaclearTextAreacreateTextAreagetTextAreamergeFromTextAreamergeTextAreaFromRequestmergeToTextAreaclearSessionByPrefix
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
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
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
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
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
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.
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
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
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
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
Associated Design PageTag(s)
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.
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
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
Associated Design PageTag(s)
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.
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
117
addServerToSessionDescription Merges the server array (containing CGI environment
variables) into the session array
Associated Design PageTag(s)
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
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
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.
Associated Design PageTag(s)
<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
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
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.
Associated Design PageTag(s)
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
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
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.
Associated Design PageTag(s)
<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.
sessid The session ID
returnValue n/a
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
121
addToSessionDescription Adds a variable or array to the session object, using the
same name.
Associated Design PageTag(s)
<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
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
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.
Associated Design PageTag(s)
<select><select multiple>
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)
sessid The session ID
returnValue n/a
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
123
appendToTextAreaDescription Appends a line of text to the end of the session text array
for a specified fieldname
Associated Design PageTag(s)
<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
Sessid The session ID
returnValue n/a
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
124
applicationRootPathDescription Returns the EWD application root path (ie the path under
which all your EWD application source directories reside)
Associated Design PageTag(s)
N/a
Example USER> w $$applicationRootPath^%zewdAPI()d:\ewdApps
Parameters DescriptionreturnValue The EWD application root path
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
125
clearAllSelectedDescription Deletes everything in the session selected array, for all
names.
Associated Design PageTag(s)
<input type=checkbox><select multiple>
Example do clearAllSelected^%zewdAPI(sessid)
Parameters Descriptionsessid The session ID
returnValue n/a
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
126
clearListDescription Deletes everything in the session List array, for the
specified fieldname..Deletes all options for the specified drop-down list
Associated Design PageTag(s)
<select><select multiple>
Example do clearList^%zewdAPI(“country”,sessid)
Parameters Descriptionfieldname The <select> tag’s field name
Sessid The session ID
returnValue n/a
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
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
Associated Design PageTag(s)
N/a
Example do clearSchemaFormErrors^%zewdAPI(sessid)
Parameters DescriptionSessid The session ID
returnValue n/a
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
128
clearSelectedDescription Deletes the specified session selected array
Effectively un-checks or un-highlights the associatedcheckbox or drop-down
Associated Design PageTag(s)
<input type=checkbox><select multiple>
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.
sessid The session ID
returnValue n/a
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
129
clearSessionArrayDescription Deletes a named array from the session object
Associated Design PageTag(s)
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.
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
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.
sessid The session ID
returnValue n/a
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
131
clearTextAreaDescription Deletes the specified text array from the session object
Associated Design PageTag(s)
<textarea>
Example do clearTextArea^%zewdAPI(“comments”,sessid)
Deletes any text for the comments field
Parameters DescriptionfieldName Name of the field name
sessid The session ID
returnValue n/a
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
132
convertDateToSecondsDescription Converts the specified date (in $h format) to the number of
seconds since January 1st 1841 ($h=0)
Associated Design PageTag(s)
n/a
Example set secs=$$convertDateToSeconds^%zewdAPI($h)
Parameters Descriptiondate In $h format
returnValue Number of seconds since Jabuary 1st 1841
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
133
convertDaysToSecondsDescription Converts the specified number of days to seconds
Associated Design PageTag(s)
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
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
134
convertSecondsToDateDescription Converts the number of seconds since January 1st 1841 to
the equivalent date in $h format
Associated Design PageTag(s)
n/a
Example USER> w $$convertSecondsToDate^%zewdAPI(5243068622)60683,57422
Parameters Descriptionseconds No of seconds since January 1st 1841
returnValue Date in $h format
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
135
copyListDescription Copies the contents of a List (ie defining the <option> tags
for a <select> tag)
Associated Design PageTag(s)
<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
sessid The session ID
returnValue N/a
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
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.
Associated Design PageTag(s)
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
sessid The session ID
returnValue N/a
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
137
copyRequestValueToSessionDescription Copies a variable or array from the incoming HTTP
request array to the session object
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
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
Associated Design PageTag(s)
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
sessid The session ID
returnValue N/a
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
139
countListDescription Returns the number of members in a <select> tag’s list of
options
Associated Design PageTag(s)
<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
sessid The session ID
returnValue The number of options defined in the list
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
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.
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
141
createJSPCommandDescription Creates a Java Server Pages script block for insertion into
your Design Page.
Associated Design PageTag(s)
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
should be separated with CRLF characters (ie $c(13,10)).
A maximum of 32k of text may be defined.
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.
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
142
createPHPCommandDescription Creates a PHP script block for insertion into your Design
Page.
Associated Design PageTag(s)
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
should be separated with CRLF characters (ie $c(13,10)).
A maximum of 32k of text may be defined.
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.
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
143
createTextAreaDescription Copies a local array of text to the specified text array in the
session object
Associated Design PageTag(s)
<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.
sessid The session ID
returnValue n/a
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
144
decDateDescription Decodes a date from $h format to dd mmm yyyy format
Associated Design PageTag(s)
n/a
Example USER> w $$decDate^%zewdAPI($h)22 Feb 2007
Parameters Descriptiondateh Date in $h format
returnValue Date in dd mmm yyyy format
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
145
deleteAllErrorLogsDescription Clears down the log of errors for all sessions
Associated Design PageTag(s)
n/a
Example D deleteAllErrorLogs^%zewdAPI
Parameters DescriptionreturnValue N/a
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
146
deleteCookieDescription Deletes a named cookie from the user’s browser
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
147
deleteErrorLogDescription Clears down the log of errors for a specified session
Associated Design PageTag(s)
n/a
Example Do deleteErrorLog^%zewdAPI(sessid)
Parameters Descriptionsessid Session ID whose error log is to be clearedreturnValue N/a
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
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.
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
149
deleteFromSessionDescription Deletes a variable or local array from the session object
Associated Design PageTag(s)
May or may not be associated with form fields. Ifassociated with a form field, then this method applies tothe following types:
<input type=text><input type=password><input type=hidden><input type=radio><select>
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
sessid The session ID
returnValue n/a
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
150
deleteFromSessionObjectDescription Deletes a specified property from an EWD session object
Associated Design PageTag(s)
May or may not be associated with form fields. Ifassociated with a form field, then this method applies tothe following types:
<input type=text><input type=password><input type=hidden><input type=radio><select>
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
sessid The session ID
returnValue n/a
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
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
Associated Design PageTag(s)
n/a
Example do deleteSession^%zewdAPI(sessid)
Parameters Descriptionsessid The session ID
returnValue n/a
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
152
deleteSessionObjectDescription Deletes a specified EWD session object
Associated Design PageTag(s)
May or may not be associated with form fields. Ifassociated with a form field, then this method applies tothe following types:
<input type=text><input type=password><input type=hidden><input type=radio><select>
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
sessid The session ID
returnValue n/a
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
153
deleteWarningDescription Deletes the user warning from the session object
Associated Design PageTag(s)
n/a
Example do deleteWarning^%zewdAPI(sessid)
Parameters Descriptionsessid The session ID
returnValue n/a
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
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
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
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
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
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.
Associated Design PageTag(s)
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).
sessid The session ID
returnValue The original or translated version of the error message (seethe description above)
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
157
existsInSessionDescription Determines whether or not a variable or array name exists
in the session object
Associated Design PageTag(s)
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”.
sessid The session ID
returnValue 1 if the variable exists in the session object
0 if it doesn’t exist in the session object
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
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
Associated Design PageTag(s)
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
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
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
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
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
Parameters Descriptionpath Full path of the file
infoArray Called by reference
Returns the file size [infoArray(“size”)] and date of lastmodification [infoArray(“date”)]
returnValue n/a
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
161
fileSizeDescription Returns the size of a specified file.
Associated Design PageTag(s)Example USER> w $$fileSize^%zewdAPI("d:\myFiles\myFOPFile3.txt")
1602
Parameters Descriptionpath Full path of the file
returnValue The size of the file in bytes
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
162
getApplicationRootPathDescription Returns the EWD application root path (ie the path under
which all your EWD application source directories reside)
Associated Design PageTag(s)
N/a
Example USER> w $$getApplicationRootPath^%zewdAPI()d:\ewdApps
Parameters DescriptionreturnValue The EWD application root path
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
163
getCheckboxValuesDescription Creates a local array of HTML checkbox field values that
were checked by the user when the form was submitted
Associated Design PageTag(s)
<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
sessid The session ID
returnValue n/a
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
164
getCookieValueDescription Gets the value of a cookie from the incoming request array
Associated Design PageTag(s)
n/a
Example set value=$$getCookieValue^%zewdAPI(“username”,sessid)
Gets the value of the cookie named username
Parameters DescriptioncookieName Name of the cookie
sessid The session ID
returnValue Value of the cookie
Null if the cookie does not exist.
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
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.
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
Null if the cookie does not exist.
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
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.
Associated Design PageTag(s)
N/a
Example USER> w $$getDefaultFormat^%zewdAPI()pretty
Parameters DescriptionreturnValue The default compilation layout format.
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
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)
Associated Design PageTag(s)
N/a
Example USER> w $$getDefaultMultiLingual^%zewdAPI()0
Parameters DescriptionreturnValue The default multi-lingual mode
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
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)
Associated Design PageTag(s)
N/a
Example USER> w $$getDefaultTechnology^%zewdAPI()php
Parameters DescriptionreturnValue The default compilarion technology
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
169
getHiddenValueDescription Obtain the value of a submitted HTML text field.
Associated Design PageTag(s)
<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”.
sessid The session ID
returnValue The value of the hidden field.
Null if the variable does not exist in the session object
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
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
Associated Design PageTag(s)
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.
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
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
Associated Design PageTag(s)
For use in custom tag processing functions.
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.
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
172
getJSScriptsPathDescription Returns the web server path in which an EWD application's Javascript
[.js] files will be found
Associated Design PageTag(s)
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.
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
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.
Associated Design PageTag(s)
Normally for internal use only
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.
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
174
getJSScriptsRootPathDescription Returns the root web server path in which an EWD application's
Javascript [.js] files will be found (if defined)
Associated Design PageTag(s)
Normally for internal use only
Example Set rootPath=$$getJSScriptsRootPath^%zewdAPI("php")
Parameters Descriptiontechnology The compilation technology
returnValue The web server root path for .js files
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
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
Associated Design PageTag(s)
<select multiple=”multiple”>
Example do getMultipleSelectValues^%zewdAPI("colours",.values,sessid)
A local array named “values” is created which contains the highlightedoptions, eg:
values(“r”)=”r”values(“b”)=”b”
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
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
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.
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
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)
Associated Design PageTag(s)
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
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
178
getOutputRootPathDescription Returns the root file path into which EWD will compile pages for the
specified technology
Associated Design PageTag(s)
Normally for internal use only
Example USER> W $$getOutputRootPath^%zewdAPI("php")d:\php\apps
Parameters Descriptiontechnology The compilation technology
returnValue The compilation output root path.
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
179
getPasswordValueDescription Obtain the value of a submitted HTML password field.
Associated Design PageTag(s)
<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”.
sessid The session ID
returnValue The value of the password field.
Null if the fieldName does not exist in the session object
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
180
getRadioValueDescription Obtain the value of a submitted HTML text field.
Associated Design PageTag(s)
<input type=radio>
Example set colour=$$getRadioValue^%zewdAPI(“colour”,sessid)
Parameters DescriptionfieldName Name of the HTML radio button.
The name must be the same as that of the form field, andmust match in terms of upper/lower case.
Eg If the radio button name is “Colour”, then thefieldName must also be “Colour”, and not “colour” or“COLOUR”.
sessid The session ID
returnValue The value of the radio button checked item.
Null if the fieldName does not exist in the session object
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
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.
Associated Design PageTag(s)
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
sessid The session ID
returnValue The value of the specified name/value pair
Null if the name does not exist in the request array
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
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
Associated Design PageTag(s)
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.
Parameters DescriptionresultSetName Name of the EWD Session ResultSet
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.
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
183
getRootURLDescription Returns the root URL that EWD will generate in all page URLs for a
specified technology
Associated Design PageTag(s)
Normally for internal use only
Example s rootURL=$$getRootURL^%zewdAPI("csp")w rootURL/csp/ewd
Parameters Descriptiontechnology The compilation technology
returnValue The root URL to be used when EWD generates all its page URLs
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
184
getSelectValueDescription Obtain the value of a submitted HTML single-choice
<select> tag.
Associated Design PageTag(s)
<select>
Example set state=$$getSelectValue^%zewdAPI(“state”,sessid)
Parameters DescriptionfieldName Name of the HTML <select> tag.
The name must be the same as that of the form field, andmust match in terms of upper/lower case.
eg If the <select> tag field name is “State”, then thefieldName must also be “State”, and not “state” or“STATE”.
sessid The session ID
returnValue The value of the <select> option that was highlighted andselected.
Null if the fieldName does not exist in the session object
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.
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
185
getServerValueDescription Gets the value of a CGI environment variable from the
incoming server array.
Associated Design PageTag(s)
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
sessid The session ID
returnValue The value of the specified CGI environment variable
Null if the name does not exist in the request array
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
186
getSessionArrayDescription Copies (or more formally, merges) an array in the session
object to a local array
Associated Design PageTag(s)
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.
sessid The session ID
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
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
187
getSessionValueDescription Obtain the value of a simple scalar session variable or
EWD session object
Associated Design PageTag(s)
<input type=text><input type=password><input type=hidden><input type=radio><select>
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
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”.
Object references of any depth can be specified
sessid The session ID
returnValue The value of the session variable
Null if the variable does not exist in the session object
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
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.
Associated Design PageTag(s)
<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.
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
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"
sessid The session ID
returnValue n/a
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
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.
sessid The session ID
returnValue N/a
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
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”
Associated Design PageTag(s)
For use in custom tag processors
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.
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
192
getTagOIDDescription For use in custom tag processing functions.
Locates the first tag in the EWD page DOM that matchesthe specified tag name
Associated Design PageTag(s)
For use in custom tag processors
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.
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
193
getTextAreaDescription Copies the text that was in the submitted textarea field into
a local array
Synonymous with mergeFromTextArea()
Associated Design PageTag(s)
<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”
Parameters DescriptionfieldName Name of the textarea field name
localArrayName Local array name to which the text will be copied
Called by reference
sessid The session ID
returnValue n/a
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
194
getTextFromListDescription Return the text value for a <select> tag’s code value
Associated Design PageTag(s)
<select><select multiple>
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
sessid The session ID
returnValue The text value for the specified code
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
195
getTextValueDescription Obtain the value of a submitted HTML text field.
Associated Design PageTag(s)
<input type=text>
Example set username=$$getTextValue^%zewdAPI(“username”,sessid)
Parameters DescriptionfieldName Name of the HTML text field.
The name must be the same as that of the form field, andmust 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”.
sessid The session ID
returnValue The value of the text field.
Null if the variable does not exist in the session object
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
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.
Associated Design PageTag(s)
N/a
Example set mode=$$getTraceMode^%zewdAPI()
Parameters DescriptionreturnValue Trace mode status.
1 = enabled0 = disabled
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
197
getUploadedFileNameDescription Return the name of the file that was uploaded from the
user’s browser.
Associated Design PageTag(s)
<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
sessid The session ID
returnValue The name of the uploaded file
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
198
getUploadedFileSizeDescription Return the size, in bytes, of the file that was uploaded from
the user’s browser.
Associated Design PageTag(s)
<input type=”file” name=”theFile”>
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”>
Parameters DescriptionfieldName The value of the name attribute in the <input type=”file”>
tag
sessid The session ID
returnValue The size, in bytes, of the uploaded file
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
199
getUploadedFileTypeDescription Return the mime type of the file that was uploaded from
the user’s browser.
Associated Design PageTag(s)
<input type=”file” name=”theFile”>
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”>
Parameters DescriptionfieldName The value of the name attribute in the <input type=”file”>
tag
sessid The session ID
returnValue The mime type of the uploaded file
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
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
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
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
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
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
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
203
initialiseCheckboxDescription Unchecks all the values in the specified HTML checkbox
Usually invoked prior to setting the specific checkedvalues using setCheckboxOn()
Synonymous with clearSelected()
Associated Design PageTag(s)
<input type=checkbox>
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 :
<input type=”checkbox” name=”colours” value=”r”><input type=”checkbox” name=”colours” value=”b”>
To clear both fields, the fieldName would be “colours”
sessid The session ID
returnValue n/a
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
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()
Synonymous with clearSelected()
Associated Design PageTag(s)
<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”
sessid The session ID
returnValue n/a
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
205
instantiateJSPVarDescription Adds the necessary type declaration into the JSP page
Associated Design PageTag(s)
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
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
206
isCheckboxOnDescription Determines whether or not the particular value for an
HTML checkbox was checked by the user when the formwas submitted.
Synonymous with isSelected()
Associated Design PageTag(s)
<input type=”checkbox”>
Example if $$isCheckboxOn^%zewdAPI(“colour”,”red”,sessid)
Parameters DescriptionfieldName The field name of the checkbox
fieldValue The checkbox value being tested
sessid The session ID
returnValue 1 = The specified checkbox value was checked by the user.
0 = The specified value was not checked
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
207
isListDefinedDescription Determines whether or not a List array has been defined for
a specified field name
Associated Design PageTag(s)
<select><select multiple>
Example set exists=$$isListDefined^%zewdAPI(“colour”,sessid)
Parameters DescriptionfieldName The <select> tag’s field name
sessid The session ID
returnValue 1 = List array exists
0 = List array does not exist
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
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.
Synonymous with isSelected()
Associated Design PageTag(s)
<select multiple=”multiple”>
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
sessid The session ID
returnValue 1 = The option with the specified value was selected by theuser.
0 = The option was not selected
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
209
isRadioOnDescription Determines whether or not the specified radio button value
was checked when the form was submitted
Associated Design PageTag(s)
<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
sessid The session ID
returnValue 1 = The field value was checked when the radio button wassubmitted
0 = The field value was not checked
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
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.
Associated Design PageTag(s)
<input type=”checkbox”><select multiple>
Example if $$isSelected^%zewdAPI(“colour”,”red”,sessid)
Parameters DescriptionfieldName The field name being tested
fieldValue The value of the field being tested
sessid The session ID
returnValue 1 = The field value was selected and exists in the Selectedarray
0 = The field value was not selected
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
211
isSelectOnDescription Determines whether or not the specified option value for a
single-choice <select> tag was highlighted when the formwas submitted
Associated Design PageTag(s)
<select>
Example set optionSelected=$$isSelectOn^%zewdAPI(“colour”,”red”,sessid)
Parameters DescriptionfieldName The field name being tested
fieldValue The value of the field being tested
sessid The session ID
returnValue 1 = The option with the specified value was highlighedwhen the <select> tag was submitted
0 = The option was not highlighted
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
212
javascriptFunctionExistsDescription For use in custom tag processing functions.
Determines whether or not the specified Javascript function exists inthe EWD page DOM
Associated Design PageTag(s)
For use in custom tag processing functions.
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
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
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
Associated Design PageTag(s)
For use in custom tag processing functions.
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
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
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
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
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
Associated Design PageTag(s)
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
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
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
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
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
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
218
mergeArrayFromSessionDescription Creates a local array from a session object array
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
219
mergeArrayToSessionDescription Merges the contents of a local array to a simple multi-
dimensional, sparse session array
Associated Design PageTag(s)
n/a
Used for handling and managing programmatically createdpersistent arrays
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
Note: called by reference
sessionArrayName Name of the session array to which the local array is to bemerged
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
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
Note: called by reference
sessionObjectName Name of the EWD Session Object to which the local array is to bemerged
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
n/a
Used for handling and managing programmatically createdpersistent arrays
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
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
222
mergeFromSelectedDescription Creates a local array from the Selected array in the session
object for the specified field name
Associated Design PageTag(s)
<input type=checkbox><select multiple>
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
sessid The session ID
returnValue n/a
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
223
mergeFromSessionDescription Creates a local array from a session object array of the
same name
Associated Design PageTag(s)
n/a
Used for handling and managing programmatically createdpersistent arrays
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.
sessid The session ID
returnValue n/a
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
224
mergeFromTextAreaDescription Copies the text from the text array in the session object for
a specified fieldname, into a local array
Associated Design PageTag(s)
<textarea>
Example do mergeFromTextArea^%zewdAPI(“comments”,.notes,sessid)
Creates a local array named notes from the comments textarea array inthe session object.
Parameters DescriptionfieldName Name of the textarea field name
localArrayName Local array name to which the text will be copied
Called by reference
sessid The session ID
returnValue n/a
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
225
mergeGlobalFromSessionDescription Creates a global from a session object array
Associated DesignPage Tag(s)
n/a
Used for handling and managing programmatically createdpersistent arrays
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
sessid The session ID
returnValue n/a
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
226
mergeGlobalToSessionDescription Merges the contents of a global to a session object array
Associated Design PageTag(s)
n/a
Used for handling and managing programmatically createdpersistent arrays
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
sessid The session ID
returnValue n/a
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
227
mergeRecordArrayToResultSetDescription Merges a local array of name/value pairs into a new (last)
record in an EWD session ResultSet
Associated Design PageTag(s)
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>
Parameters DescriptionresultSetName Name of the EWD Session ResultSet
propertyArray Reference to the local array containing propertyname/value pairs
Called by reference.
sessid The session ID
returnValue n/a
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
228
mergeTextAreaFromRequestDescription Merges text from the incoming request array to the text
array for the matching name in the session object
Associated Design PageTag(s)
<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.
Parameters DescriptionfieldName Name of the textarea field name
requestArray Reference to the request array
Called by reference.
sessid The session ID
returnValue n/a
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
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
Associated Design PageTag(s)
<select><select multiple>
Example set country(1)=”UK~1”set country(2)=”USA~2”set country(3)=”Europe~3”do mergeToList^%zewdAPI(“country”,.country,sessid)
Parameters DescriptionfieldName The <select> tag’s field name
localArrayName The name of the local array that contains the options
Call by reference
sessid The session ID
returnValue n/a
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
230
mergeToSelectedDescription Copies a local array to the Selected array in the session
object for the specified field name
Associated Design PageTag(s)
<input type=checkbox><select multiple>
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
sessid The session ID
returnValue n/a
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
231
mergeToSessionDescription Adds a variable or array to the session object, using the
same name.
This method is synonymous with the addToSession()method
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
232
mergeToTextAreaDescription Copies the text from a local array to the text array in the
session object for a specified fieldname
Associated Design PageTag(s)
<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”
Parameters DescriptionfieldName Name of the textarea field name
localArrayName Local array name from which the text will be copied
Called by reference
sessid The session ID
returnValue n/a
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
233
namespaceDescription Returns the current Cache namespaceAssociated Design PageTag(s)Example S namespace=$$namespace^%zewdAPI()
Parameters DescriptionreturnValu Current namespace
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
234
parseHTMLFileDescription Converts an HTML text file into an XHTML DOM
Associated Design PageTag(s)
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.
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
235
parseHTMLStreamDescription Converts a Stream object that contains HTML into an
XHTML DOM
Associated Design PageTag(s)
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
returnValue Null if no error occurs during parsing. Otherwise it returnsthe error string.
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
236
parseStreamDescription Converts a Stream object that contains HTML or XML
into an EWD DOM
Associated Design PageTag(s)
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
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
237
parseURLDescription Fetches an HTML page as specified by a URL and
converts it into an XHTML DOM
Associated Design PageTag(s)
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
returnValue Null if no error occurs during parsing. Otherwise it returnsthe error string.
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
238
parseXMLFileDescription Converts an XML text file into an EWD DOM
Associated Design PageTag(s)
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
returnValue Null if no error occurs during parsing. Otherwise it returnsthe error string.
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
239
randCharDescription Returns a single alphanumerc character at random
Associated Design PageTag(s)
n/a
Example Set char=$$randChar^%zewdAPI()
Parameters DescriptionreturnValue A single randomly generated alphanumeric character.
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
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
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
241
removeFromListDescription Remove an option from a <select> tag’s drop-down list
array
Associated Design PageTag(s)
<select><select multiple>
Example do removeFromList^%zewdAPI(“country”,1,sessid)
Removes the country who’s code value is 1 from the option list for<select name=”country”>
Parameters DescriptionfieldName The <select> tag’s field name
codeValue The code value of the option to be deleted
sessid The session ID
returnValue n/a
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
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:
<input type=checkbox name=”colours” value=”red”><input type=checkbox name=”colours” value=”blue”>
Parameters DescriptionfieldName Selected Array field name
value Value to be removed from the Selected array
sessid The session ID
returnValue n/a
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
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.
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
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.
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
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
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
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
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
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
returnValue The converted string
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
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
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
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
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
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.
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
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.
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
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
Associated Design PageTag(s)
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
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
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
Associated Design PageTag(s)
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
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
254
sessionObjectPropertyExistsDescription Determines whether or not a specified session object exists
in the Session.
Associated Design PageTag(s)
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
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
255
setApplicationRootPathDescription Sets the EWD application root path (ie the path under
which all your EWD application source directories reside)
Associated Design PageTag(s)
N/a
Example USER> d setApplicationRootPath^%zewdAPI(“d:\ewdApps”)
Parameters DescriptionappRootPath The EWD application root path
returnValue N/a
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
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:
<input type=checkbox name=”colours” value=”red”><input type=checkbox name=”colours” value=”blue”>
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
sessid The session ID
returnValue n/a
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
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:
<input type=checkbox name=”colours” value=”red”><input type=checkbox name=”colours” value=”blue”>
Parameters DescriptionfieldName Name of the HTML checkbox field(s)
value Checkbox value to be checked
sessid The session ID
returnValue n/a
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
258
setCheckboxValuesDescription Checks the values of an HTML checkbox, as specified via
a local array.
Synonymous with mergeToSelected()
Associated Design PageTag(s)
<input type=checkbox>
Example do setCheckboxValues^%zewdAPI("colours",.values,sessid)
If the local array “values” contains:
values(“r”)=”r”values(“b”)=”b”
Then the following checkbox values will be checked when the page isrendered:
<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 that contains the values to bechecked
Called by reference
sessid The session ID
returnValue n/a
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
259
setCookieValueDescription Sets the value of a cookie on the user’s browser
Associated Design PageTag(s)
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.
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
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()
Associated Design PageTag(s)
<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
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
Normally for internal use only
Example D setJSScriptsPathMode^%zewdAPI("php",”fixed”)
Parameters Descriptiontechnology The compilation technology
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
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
263
setJSScriptsRootPathDescription Set the root web server path in which an EWD application's Javascript
[.js] files will be found (if defined)
Associated Design PageTag(s)
Normally for internal use only
Example S rootPath=”c:\myJSPath”D setJSScriptsRootPath^%zewdAPI("php",rootPath)
Parameters Descriptiontechnology The compilation technology
rootPath The web server root path for .js files
ReturnValue N/a
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
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)
Associated Design PageTag(s)
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.
sessid The session ID
returnValue n/a
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
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
sessid The session ID
returnValue n/a
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
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>
Parameters DescriptionfieldName Name of the HTML multiple-choice <select> tag
value Option value to be highlighed
sessid The session ID
returnValue n/a
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
267
setMultipleSelectValuesDescription Selects/highlights the specified options in the named
HTML multiple-choice <select> tag, via a local array ofvalues.
Synonymous with mergeToSelected()
Associated Design PageTag(s)
<select multiple=”multiple”>
Example do setMultipleSelectValues^%zewdAPI("colours",.values,sessid)
If the local array “values” contains:
values(“r”)=”r”values(“b”)=”b”
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>
Parameters DescriptionfieldName Name of the HTML multiple-choice <select> tag
localArrayName The name of the local array that contains the values to beselected
Called by reference
sessid The session ID
returnValue n/a
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
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
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
269
setOutputRootPathDescription Set the root file path into which EWD will compile pages for the
specified technology
Associated Design PageTag(s)
Normally for internal use only
Example D setOutputRootPath^%zewdAPI("php",”d:\php\apps”)
Parameters Descriptiontechnology The compilation technology
rootPath The compilation output root path.
returnValue N/a
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
270
setRadioOnDescription Checks the HTML radio button field with the
corresponding value.
Synonymous with setSessionValue()
Associated Design PageTag(s)
<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
sessid The session ID
returnValue n/a
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
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)
Associated Design PageTag(s)
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.
sessid The session ID
returnValue n/a
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
272
setResponseHeaderDescription Set an HTTP response header
Associated Design PageTag(s)
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
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
273
setRootURLDescription Set the root URL that EWD will generate in all page URLs for a
specified technology
Associated Design PageTag(s)
Normally for internal use only
Example D setRootURL^%zewdAPI("csp",”/csp/ewd”)
Parameters Descriptiontechnology The compilation technology
rootURL The root URL to be used when EWD generates all its page URLs
returnValue N/a
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
274
setSelectValueDescription Highlights the option with the corresponding value in an HTML single-
choice <select> tag.
Synonymous with setSessionValue()
Associated Design PageTag(s)
<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.
sessid The session ID
returnValue n/a
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
275
setSessionArrayDescription Sets an item into an array within the session object
Associated Design PageTag(s)
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
sessid The session ID
returnValue n/a
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
276
setSessionValueDescription Sets the value of a simple session variable or a session
object
Associated Design PageTag(s)
<input type=text><input type=password><input type=hidden><input type=radio><select>
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.
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”.
value The value to be assigned to the session variable or object
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
<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"
sessid The session ID
returnValue n/a
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
278
setTextValueDescription Sets the value of an HTML text field. The value will
appear in the HTML form when the page is rendered.
Synonymous with setSessionValue()
Associated Design PageTag(s)
<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
sessid The session ID
returnValue n/a
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
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.
Associated Design PageTag(s)
<input type=submit>
Example do setWarning^%zewdAPI(“The attachment has been deleted”,sessid)
Parameters DescriptionwarningMessage Defines the text of the warning message
sessid The session ID
returnValue n/a
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
280
stripLeadingSpacesDescription Removes all leading spaces from a text string
Associated Design PageTag(s)
N/a
Example W $$stripLeadingSpaces(“ hello Rob”)hello Rob
Parameters Descriptionstring Text string
returnValue The text string with all leading spaces removed
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
281
stripSpacesDescription Removes all leading and trailing spaces from a text string
Associated Design PageTag(s)
N/a
Example W $$stripLeadingSpaces(“ hello Rob ”)_”x”hello Robx
Parameters Descriptionstring Text string
returnValue The text string with all leading and trailing spaces removed
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
282
stripTrailingSpacesDescription Removes all trailing spaces from a text string
Associated Design PageTag(s)
N/a
Example W $$stripLeadingSpaces(“hello Rob ”)_”x”hello Robx
Parameters Descriptionstring Text string
returnValue The text string with all trailing spaces removed
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
283
suppressResponseHeaderDescription Suppress an HTTP response header from being generated by CSP
Associated Design PageTag(s)
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
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
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.
Associated Design PageTag(s)
Not associated with specific tags.
Example set warning=$$systemMessage^%zewdAPI(“Details have beenupdated”,”advisory”,sessid)
Parameters DescriptionerrorMessage The error message (in the default language).
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
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.
sessid The session ID
returnValue The original or translated version of the error message (seethe description above)
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
286
traceDescription Saves a text string as the last current record in the ^%zewdTrace global
Associated Design PageTag(s)
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
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
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
Associated Design PageTag(s)
N/a
Example D traceModeOn^%zewdAPIParameters Description
returnValue N/a
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
288
traceModeOffDescription Switches trace mode off
Note: The contents of ^%zewdTrace are not deleted
Associated Design PageTag(s)
N/a
Example D traceModeOff^%zewdAPIParameters Description
returnValue N/a
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
289
versionDescription Returns the current version and build number of eXtc Web Developer.
Associated Design PageTag(s)
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
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
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.
Associated Design PageTag(s)
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
returnValue The converted string
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
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.
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
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.
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
310