Interface WebForm
- All Superinterfaces:
BaseForm
,Element
,EventOwner
,MessageContainer
,java.io.Serializable
,WebFormEventOwner
public interface WebForm extends BaseForm, WebFormEventOwner
WebForm
interface represents an interactive web form, which is a form being executed by an online user. This is the root object
for an interactive form and provides access to elements within the form. It also provides many methods to control form processing e.g.
gotoPage(), callForm(), callUrl(), generatePdf() etc.- Since:
- V4.4
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
HTTP_PROTOCOL_GET
Represents the httpGET
protocol, for use with thecallUrl
andgotoUrl
methods.static java.lang.String
HTTP_PROTOCOL_POST
Represents the httpPOST
protocol, for use with thecallUrl
andgotoUrl
methods. -
Method Summary
Modifier and Type Method Description void
addFinalPageMessage(int messageNo, java.lang.String[] replaceParameters)
Deprecated.void
addFinalPageMessage(java.lang.String message)
Adds a message that will be displayed to the user on the form's final page.void
addFinalPageMessageText(Text text, java.lang.String[] replaceParameters)
Adds a message that will be displayed to the user on the form's final page.void
callForm(java.lang.String formName)
Calls the form with the specified name and displays any resulting HTML page to the user.void
callForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)
Calls the form with the specified name and displays any resulting HTML page to the user.void
callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)
Calls the specified URL and displays any resulting HTML page to the user.void
callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)
Calls the specified URL and displays any resulting HTML page to the user.void
displayUrl(java.lang.String url)
Displays the specified URL in a pop-up browser window.void
displayUrl(java.lang.String url, boolean popup, java.lang.String popupWindowName)
Displays the specified URL in the user's browser, optionally in a pop-up browser window.void
generatePdf()
Generates a PDF for the current page and displays this to the user in a popup window.java.lang.String
generatePdf(PdfOptions options)
Generates a PDF from one or more pages, with options to display to the user and save the generated file.Page
getAbortPage()
Returns the current page after a failure has occurred, or null if no failure has occurred or there is no current page.Page[]
getAllPages()
Returns an array of Page objects containing all pages within the form.java.lang.String
getCallingFormName()
Returns the name of the calling form or null if no calling form exists.Controls
getControls()
Returns theControls
object that gives access to all controls available to the form.Control[]
getControlsByModifier(java.lang.String modifier)
Returns an array of controls in the form that have the named modifier.Page
getCurrentPage()
Returns aPage
object representing the current pagePage
getFirstPage()
Returns thePage
object configured as the form's first page.Page
getNextPage()
Returns aPage
object representing the next page or null if no next page is configured.Pages
getPages()
Returns thePages
object that gives access to all pages available to the form.java.lang.String
getPresentationTemplateName()
Returns the name of the presentation template currently used or null if no presentation template is configured.java.lang.String
getPresentationTemplatePath()
Returns the path of the presentation template currently used or null if no presentation template is configured.Page
getPreviousPage()
Returns aPage
object representing the previous page displayed or null if there is no previous page.java.lang.String
getReturnUrl()
Returns a Url for use with the callUrl() method.void
gotoForm(java.lang.String formName)
Transfers control to the form with the specified name, terminates execution of the current form and commits the current transaction.void
gotoForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)
Transfers control to the form with the specified name, terminates execution of the current form and commits the current transaction.void
gotoPage(Page page)
Goes immediately to the specified page and terminates the event currently being executed; no statements past this method call will be executed.void
gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)
Displays the specified URL in the user's browser, terminates execution of the current form and commits the current transaction.void
gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)
Displays the specified URL in the user's browser, terminates execution of the current form and commits the current transaction.boolean
isBackButtonSupported()
Returnstrue
if use of the back button is supported for the current form.boolean
isBackground()
Returnstrue
if this form is running in background e.g.boolean
isCalledForm()
Returnstrue
if this form has been called from another form using methodcallForm(String, Map)
.boolean
isLoadedByServiceWorker()
Returnstrue
if this form is being loaded by a client Javascript service worker.void
returnFromForm()
Returns from a called form to the calling form.void
setNextPage(Page page)
Sets the next page to be displayed when the user navigates forwards using a next page button.void
setPresentationTemplateName(java.lang.String templateName)
Sets the presentation template used by the current form using the template name or id.void
setPresentationTemplatePath(java.lang.String templatePath)
Sets the presentation template used by the current form using the template path.void
uploadFileFromBrowser()
Deprecated.From V5.9 it is recommended to use theFileUploadControl
insteadvoid
uploadFileFromBrowser(UploadOptions options)
Deprecated.From V5.9 it is recommended to use theFileUploadControl
insteadMethods inherited from interface com.ebasetech.xi.api.BaseForm
abort, getAbortMessage, getFields, getLanguage, getResources, getTables, getTexts, getTimezone, setLanguage, setTimezone
Methods inherited from interface com.ebasetech.xi.api.Element
getElementName, getElementType
Methods inherited from interface com.ebasetech.xi.api.MessageContainer
addErrorMessage, addErrorMessage, addErrorMessage, addErrorMessage, addErrorMessage, addErrorMessageText, addErrorMessageText, addErrorMessageText, addInfoMessage, addInfoMessage, addInfoMessageText, addInfoMessageText, addInfoMessageText, addWarningMessage, addWarningMessage, addWarningMessage, addWarningMessage, addWarningMessage, addWarningMessageText, addWarningMessageText, addWarningMessageText, existErrorMessages, existInfoMessages, existMessages, existWarningMessages
-
Field Details
-
HTTP_PROTOCOL_POST
static final java.lang.String HTTP_PROTOCOL_POSTRepresents the httpPOST
protocol, for use with thecallUrl
andgotoUrl
methods.- See Also:
- Constant Field Values
-
HTTP_PROTOCOL_GET
static final java.lang.String HTTP_PROTOCOL_GETRepresents the httpGET
protocol, for use with thecallUrl
andgotoUrl
methods.- See Also:
- Constant Field Values
-
-
Method Details
-
getPages
Pages getPages()Returns thePages
object that gives access to all pages available to the form. An individual page can then be accessed using its page name as shown in the examples below.Javascript example:
var p1 = pages.PAGE1; var p2 = pages.getPage("PAGE2");
- Returns:
Pages
- Since:
- V4.4
-
getControls
Controls getControls()Returns theControls
object that gives access to all controls available to the form. An individual control can then be accessed using its control name as shown in the examples below.Javascript example:
controls.TEXTCONTROL1.hide(); form.getControls().BUTTONCONTROL2.backgroundColor = "Red";
- Returns:
Controls
- Since:
- V4.4
-
getControlsByModifier
Returns an array of controls in the form that have the named modifier.Modifiers provide a way of flagging one or more controls so they can be found programmatically, e.g. a group of Field Controls might be changed from enterable to display only. Modifiers are assigned to controls at design time using the Modifiers property. Any number of modifiers can be assigned - modifiers are entered as a comma delimited list.
Javascript example:
for each (var ctrl in form.getControlsByModifier("FINANCE")) { if (!system.securityManager.hasRole("FINANCE_CONTROLLER")) { ctrl.hide(); } }
- Parameters:
modifier
-- Returns:
- an array of controls that have the named modifier
- Since:
- V5.9
- See Also:
Control.hasModifier(String)
-
gotoPage
Goes immediately to the specified page and terminates the event currently being executed; no statements past this method call will be executed. Anyafter page
event configured on the current page will not be executed; this is in contrast to navigating to a page using a page navigation control such as a Next Page Button Control. Anybefore page
events configured for the target page are executed before the page is displayed.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.If the target page contains a Previous Page Button Control or a Page Navigation Panel Control, a previous page button linking to the current page will be displayed on the target page.
Javascript example:
form.gotoPage(pages.ORDER_PAGE);
- Parameters:
page
- the target page- Since:
- V4.4
-
callUrl
void callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)Calls the specified URL and displays any resulting HTML page to the user. Use this method to call a URL based application that will subsequently return to Ebase e.g. a payment gateway. This method calls the specified URL using the HttpGET
protocol.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.The called application can set any Ebase form field values on return by adding them to the return URL. Form field names can be specified in either upper case or lower case.
Execution of the current script is suspended and resumes with the next statement when the called application returns. The current transaction is committed prior to calling the application, and a new transaction is started when the called application returns.
In order to return to Ebase, the called application must be supplied with a return URL. This return URL should invoke the
ufsreturn
servlet and include the Ebase form session id parameterebz
i.e. the URL should be of the typedomain/ufs/ufsreturn?ebz=xxxx
e.g.http://mydomain/ufs/ufsreturn?ebz=1_1283432908172
. The full return URL is available via methodgetReturnUrl()
and can be passed to the called application if required as shown in the example below. This return URL is also added automatically by the system as parameter ufsReturnURL.The return call can be made using either Http protocol GET or POST. Care should be taken to ensure that the domain name (or host name or ip address) used on the return URL is the same as the one used to initially invoke the Ebase form. If these domain names are different, an error page will be displayed with the message:
The request has timed out - please try again
On return, the ebz parameter is used to load the appropriate form context and execution of the form is resumed from the point where the callUrl() method was executed. If the ebz parameter is not supplied on the return URL, the most recent form context will be used.
It is best practice to pass any parameters to a called application via the parameters Map (example 1 below). However, if parameters are added to the URL directly, these should be encoded (example 2 below). Parameters passed via the parameters Map should not be encoded as this is done automatically by the system.
Javascript example 1 (using parameters Map):
var parms = {}; parms.cardid = fields.CREDIT_CARD_NO.displayValue; parms.amount = fields.PAYMENT_AMOUNT.displayValue; parms.returl = form.getReturnUrl(); form.callUrl("http://www.xxxpaymentservice.com", parms);
Javascript example 2 (adding parameters directly to url):
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.CREDIT_CARD_NO.displayValue, encoding); var parm2 = encoder.encode(fields.AMOUNT.displayValue, encoding); var returl = encoder.encode(form.getReturnUrl(), encoding); var url = "http://www.xxxmypaymentservice.com" + "?cardid=" + parm1 + "&amount=" + parm2 + "&returl=" + returl; form.callUrl(url, null);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.givemethecash.com
parameters
- a Map of key/value pairs where key is a parameter name and value is the parameter value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a property name and value is the property value. See example 1 above.- Since:
- V4.4
- See Also:
callUrl(String, Map, String)
,gotoUrl(String, Map, String)
,displayUrl(String, boolean, String)
,getReturnUrl()
-
callUrl
void callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)Calls the specified URL and displays any resulting HTML page to the user. Use this method to call a URL based application that will subsequently return to Ebase e.g. a payment gateway.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.The called application can set any Ebase form field values on return by adding them to the return URL. Form field names can be specified in either upper case or lower case.
Execution of the current script is suspended and resumes with the next statement when the called application returns. The current transaction is committed prior to calling the application, and a new transaction is started when the called application returns.
Http protocol of either
GET
orPOST
can be specified, whereGET
is the default.
Note: when POST is specified, the system writes an additional HTML page to the browser to invoke the specified URL. This page is added to the browser's history cache and interferes with the operation of the browser back button. The result is that the user will not be able to use the back button to navigate back from the called URL to the Ebase form. For this reason, it is recommended that POST is only used when there is no alternative, or for forms which do not support the back button.In order to return to Ebase, the called application must be supplied with a return URL. This return URL should invoke the
ufsreturn
servlet and include the Ebase form session id parameterebz
i.e. the URL should be of the typedomain/ufs/ufsreturn?ebz=xxxx
e.g.http://mydomain/ufs/ufsreturn?ebz=1_1283432908172
. The full return URL is available via methodgetReturnUrl()
and can be passed to the called application if required as shown in the example below. This return URL is also added automatically by the system as parameter ufsReturnURL.The return call can be made using either Http protocol GET or POST. Care should be taken to ensure that the domain name (or host name or ip address) used on the return URL is the same as the one used to initially invoke the Ebase form. If these domain names are different, an error page will be displayed with the message:
The request has timed out - please try again
On return, the ebz parameter is used to load the appropriate form context and execution of the form is resumed from the point where the callUrl() method was executed. If the ebz parameter is not supplied on the return URL, the most recent form context will be used.
It is best practice to pass any parameters to a called application via the parameters Map (example 1 below). However, if parameters are added to the URL directly, these should be encoded (example 2 below). Parameters passed via the parameters Map should not be encoded as this is done automatically by the system.
Javascript example 1 (using parameters Map):
var parms = {}; parms.cardid = fields.CREDIT_CARD_NO.displayValue; parms.amount = fields.PAYMENT_AMOUNT.displayValue; parms.returl = form.getReturnUrl(); form.callUrl("http://www.xxxpaymentservice.com", parms, form.HTTP_PROTOCOL_GET);
Javascript example 2 (adding parameters directly to url):
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.CREDIT_CARD_NO.displayValue, encoding); var parm2 = encoder.encode(fields.AMOUNT.displayValue, encoding); var returl = encoder.encode(form.getReturnUrl(), encoding); var url = "http://www.xxxmypaymentservice.com" + "?cardid=" + parm1 + "&amount=" + parm2 + "&returl=" + returl; form.callUrl(url, null, form.HTTP_PROTOCOL_GET);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.givemethecash.com
parameters
- a Map of key/value pairs where key is a parameter name and value is the parameter value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a property name and value is the property value. See example 1 above.httpProtocol
- supported values areget
andpost
, the default isget
if null is specified.- Since:
- V4.4
- See Also:
callUrl(String, Map)
,gotoUrl(String, Map, String)
,displayUrl(String, boolean, String)
,getReturnUrl()
-
gotoUrl
void gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)Displays the specified URL in the user's browser, terminates execution of the current form and commits the current transaction. Form memory is freed, and return to the Ebase form is not possible. Navigation back to the form using the browser back button is not possible. This method uses the HttpGET
protocol.Execution of this method immediately terminates the event currently being executed, no statements past this method call will be executed. This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.It is best practice to pass any parameters via the parameters Map (example 1 below). However, if parameters are added to the URL directly, these should be encoded (example 2 below). Parameters passed via the parameters Map should not be encoded as this is done automatically by the system.
Javascript example 1 (using parameters Map):
var parms = {}; parms.status = fields.APPL_STATUS.displayValue; parms.next = "MENU"; form.gotoUrl("mainmenu.jsp", parms);
Javascript example 2 (adding parameters directly to url):
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.APPL_STATUS.displayValue, encoding); var parm2 = "MENU"; var url = "http://www.xxx.com" + "?status=" + parm1 + "&next=" + parm2; form.gotoUrl(url, null);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.xxx.com
parameters
- a Map of key/value pairs where key is a parameter name and value is the parameter value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a property name and value is the property value. See example 1 above.- Since:
- V4.4
- See Also:
gotoUrl(String, Map, String)
,callUrl(String, Map, String)
,displayUrl(String, boolean, String)
-
gotoUrl
void gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)Displays the specified URL in the user's browser, terminates execution of the current form and commits the current transaction. Form memory is freed, and return to the Ebase form is not possible. Navigation back to the form using the browser back button is not possible.Execution of this method immediately terminates the event currently being executed, no statements past this method call will be executed. This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.Http protocol of either
GET
orPOST
can be specified, whereGET
is the default.
It is best practice to pass any parameters via the parameters Map (example 1 below). However, if parameters are added to the URL directly, these should be encoded (example 2 below). Parameters passed via the parameters Map should not be encoded as this is done automatically by the system.
Javascript example 1 (using parameters Map):
var parms = {}; parms.status = fields.APPL_STATUS.displayValue; parms.next = "MENU"; form.gotoUrl("mainmenu.jsp", parms, form.HTTP_PROTOCOL_GET);
Javascript example 2 (adding parameters directly to url):
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.APPL_STATUS.displayValue, encoding); var parm2 = "MENU"; var url = "http://www.xxx.com" + "?status=" + parm1 + "&next=" + parm2; form.gotoUrl(url, null, form.HTTP_PROTOCOL_GET);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.xxx.com
parameters
- a Map of key/value pairs where key is a parameter name and value is the parameter value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a property name and value is the property value. See example 1 above.httpProtocol
- supported values areget
andpost
, the default isget
if null is specified.- Since:
- V4.4
- See Also:
gotoUrl(String, Map)
,callUrl(String, Map, String)
,displayUrl(String, boolean, String)
-
displayUrl
void displayUrl(java.lang.String url)Displays the specified URL in a pop-up browser window.When a URL is constructed dynamically, any parameters added should be encoded (example below).
Javascript example (encoding url parameters):
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.PARM1.displayValue, encoding); var parm2 = encoder.encode(fields.PARM2.displayValue, encoding); var url = "http://www.xxx.com" + "?p1=" + parm1 + "&p2=" + parm2; form.displayUrl(url);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.google.com
- Since:
- V4.4
- See Also:
displayUrl(String, boolean, String)
,callUrl(String, Map, String)
,gotoUrl(String, Map, String)
-
displayUrl
void displayUrl(java.lang.String url, boolean popup, java.lang.String popupWindowName)Displays the specified URL in the user's browser, optionally in a pop-up browser window.When popup is false, the URL replaces the form page currently displayed. To navigate back to the form page, the user must then click on the browser back button. This mode of operation is only possible when the form has back button support enabled; when back button support is disabled, the user will be unable to navigate back to the form.
When a URL is constructed dynamically, any parameters added should be encoded (example below).
Javascript example:
var encoder = java.net.URLEncoder; var encoding = "UTF-8"; var parm1 = encoder.encode(fields.PARM1.displayValue, encoding); var parm2 = encoder.encode(fields.PARM2.displayValue, encoding); var url = "http://www.xxx.com" + "?p1=" + parm1 + "&p2=" + parm2; form.displayUrl(url, true, null);
- Parameters:
url
- the target url to be called, which can be either relative or absolute. When absolute, is should start with the protocol e.g.http://www.google.com
popup
- when true, the url is displayed in a popup window; when false, the url is displayed in the same window as the current form pagepopupWindowName
- when popup is true, specifies the name of the popup window. Window names "_blank", "_parent" and "_top" can be used as well as named windows. A value of null will result in a new window being created for each document displayed.- Since:
- V4.4
- See Also:
displayUrl(String)
,callUrl(String, Map, String)
,gotoUrl(String, Map, String)
-
callForm
void callForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)Calls the form with the specified name and displays any resulting HTML page to the user. This provides the ability to call another Ebase Xi form and then return to the calling form using methodreturnFromForm()
.Parameters are passed to the called form via form fields. Any such fields must have the URL Parameter property set in the called form. When passing a form field value from the calling form, the field's
stringValue
property should be used (see examples below).Parameters are returned from the called form using form fields with the Return field property set. All form fields in the called form that have this property setting are returned to the calling form. These fields must have the same name in both the calling and called forms.
Execution of the current script is suspended and resumes with the next statement when the called form returns. The current transaction is committed prior to calling the form, and a new transaction is started when the called form returns.
Javascript example:
Note: In form ORDER_DISPLAY, fields ORDER_ID, CUSTOMER_ID and CREDIT_LIMIT have property URL Parameter set and field ORDER_UPDATED has property Return field set.var parms = {}; parms.ORDER_ID = fields.ORDER.stringValue; parms.CUSTOMER_ID = fields.CUSTOMER.stringValue; parms.CREDIT_LIMIT = 9999; form.callForm("ORDER_DISPLAY", parms); /// ..process returned field values if (fields.ORDER_UPDATED.value) ..
- Parameters:
formName
- the name of the target form to be calledparameters
- a Map of key/value pairs where key is a field name in the target form and value is the corresponding value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a field name and value is the corresponding value. See example above.- Since:
- V4.4
- See Also:
gotoForm(String, Map)
,returnFromForm()
,isCalledForm()
,getCallingFormName()
-
callForm
void callForm(java.lang.String formName)Calls the form with the specified name and displays any resulting HTML page to the user. This is equivalent to calling methodcallForm(formName, null)
.- Parameters:
formName
- the name of the target form to be called- Since:
- V4.4
- See Also:
callForm(String, Map)
,gotoForm(String, Map)
,returnFromForm()
,isCalledForm()
,getCallingFormName()
-
gotoForm
void gotoForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)Transfers control to the form with the specified name, terminates execution of the current form and commits the current transaction. Form memory is freed, and return to the current form is not possible by any method including the browser back button. Navigation back to the current form using the browser back button is not possible.Execution of this method immediately terminates the event currently being executed, no statements past this method call will be executed.
This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.Parameters are passed to the target form via form fields. Any such fields must have the URL Parameter property set in the called form. When passing a form field value from the calling form, the field's
stringValue
property should be used (see examples below).Javascript example: Note: In form ORDER_DISPLAY, fields ORDER_ID, CUSTOMER_ID and CREDIT_LIMIT have property URL Parameter set.
var parms = {}; parms.ORDER_ID = fields.ORDER.stringValue; parms.CUSTOMER_ID = fields.CUSTOMER.stringValue; parms.CREDIT_LIMIT = 9999; form.gotoForm("ORDER_DISPLAY", parms);
- Parameters:
formName
- the name of the target formparameters
- a Map of key/value pairs where key is a field name in the target form and value is the corresponding value. Null can be specified to indicate that there are no parameters. In Javascript, an Object can be used where key is a field name and value is the corresponding value. See example above.- Since:
- V4.4
- See Also:
callForm(String, Map)
-
gotoForm
void gotoForm(java.lang.String formName)Transfers control to the form with the specified name, terminates execution of the current form and commits the current transaction. This is equivalent to calling methodgotoForm(formName, null)
. Form memory is freed, and return to the current form is not possible by any method including the browser back button. Navigation back to the current form using the browser back button is not possible.Execution of this method immediately terminates the event currently being executed, no statements past this method call will be executed.
This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.- Parameters:
formName
- the name of the target form- Since:
- V4.4
- See Also:
gotoForm(String, Map)
,callForm(String, Map)
-
returnFromForm
void returnFromForm()Returns from a called form to the calling form. Throws a RuntimeException if the current form is not a called form. Stops execution of the current form immediately, no further script statements are executed.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.Parameters are returned from the called form using form fields with the Return field property set. All form fields in the called form that have this property setting are returned to the calling form. These form fields must have the same name in both the calling and called forms.
Javascript example:
form.returnFromForm();
- Since:
- V4.4
- See Also:
callForm(String, Map)
-
uploadFileFromBrowser
@Deprecated void uploadFileFromBrowser()Deprecated.From V5.9 it is recommended to use theFileUploadControl
insteadDisplays a special upload page to the user and allows the user to upload one or more files to the server. Script processing is suspended when this method is executed and resumes with the next statement when the user clicks either the Upload or Cancel button on the upload page. This method only supports the upload of a single file.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.Uploaded files are saved on the server in the directory specified in the
Ufs.fileDirectoryName
parameter ofUFSSetup.properties
. The file name on the server is generated from the last portion of the file name on the client system with a number added if necessary for uniqueness e.g. the first upload of a file namedmy_cv.doc
will be saved with this name, the second withmy_cv1.doc
, themmy_cv2.doc
etc. In addition, any spaces in the file name will be changed to underscores ( _ ) to ensure valid filenames when a Windows file is being saved on a Unix or Linux server. Files can be renamed after upload if necessary usingFileServices.moveFile()
.Uploaded files can be added as attachments to email messages or used for any other purpose.
The following system variables are set as a result of executing this command (see example below):
- $FILE_NAME is set with the full path name of the uploaded file as saved on the server system. If the Cancel button is pressed by the user, this variable will contain a null value.
- $FILE_NAME_USER is set with the last portion of the file name on the client system
e.g. if the user has uploaded
C:\My Documents\my_cv.doc
, then $FILE_NAME_USER will contain the valuemy_cv.doc
. If the Cancel button is pressed by the user, this variable will contain a null value.
Javascript example:
// display the upload page... form.uploadFileFromBrowser(); // Processing resumes here after the upload.. var fname = system.variables.$FILE_NAME.value; var fnameUser = system.variables.$FILE_NAME_USER.value; if (fname) { // Show info message if file uploaded successfully event.owner.addWarningMessage("File " + fnameUser + " uploaded as " + FileServices.getAbsoluteFilePath(fname)); }
- Since:
- V4.4
-
uploadFileFromBrowser
Deprecated.From V5.9 it is recommended to use theFileUploadControl
insteadDisplays a special upload page to the user to allow the user to upload one or more files to the server, withoptions
to override some of the default parameters. Script processing is suspended when this method is executed and resumes with the next statement when the user clicks either the Upload or Cancel button on the upload page. This method only supports the upload of a single file.This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a
RuntimeException
is thrown.Uploaded files are saved on the server in the directory specified in
options
, or if this is omitted in the directory specified in theUfs.fileDirectoryName
parameter ofUFSSetup.properties
. The file name on the server is generated from the last portion of the file on the client system with a number added if necessary for uniqueness e.g. the first upload of a file namedmy_cv.doc
will be saved with this name, the second withmy_cv1.doc
, themmy_cv2.doc
etc. In addition, any spaces in the file name will be changed to underscores ( _ ) to ensure valid filenames when a Windows file is being saved on a Unix or Linux server. Files can be renamed after upload if necessary usingFileServices.moveFile()
.Uploaded files can be added as attachments to email messages or used for any other purpose.
The following system variables are set as a result of executing this command (see example below):
- $FILE_NAME is set with the full path name of the uploaded file as saved on the server system. If the Cancel button is pressed by the user, this variable will contain a null value.
- $FILE_NAME_USER is set with the last portion of the file name on the client system
e.g. if the user has uploaded
C:\My Documents\my_cv.doc
, then $FILE_NAME_USER will contain the valuemy_cv.doc
. If the Cancel button is pressed by the user, this variable will contain a null value.
UploadOptions
). If an option is not specified, the corresponding system default fromUFSSetup.properties
is used.- specify the target directory on the server (default property
Ufs.fileDirectoryName
) - specify the maximum file size that can be uploaded (default property
Ufs.maxUploadFileSize
) - specify the file types that can be uploaded (default property
Ufs.uploadFileTypes
) - specify the accepted MIME types - used by supporting browsers to constrain the file types shown in the browse panel (no default)
Javascript example:
var opts = new UploadOptions(); opts.directory = "c:/temp"; // Backslashes should be escaped e.g. c:\\temp opts.maxFileSize = "5M"; // Files larger than 5MB can't be uploaded opts.acceptedMimeTypes = [ "image/*" ]; // Limit the file types shown in the browse panel opts.fileTypes = [ "png", "gif", "jpg" ]; // Only these file types can be uploaded form.uploadFileFromBrowser(opts); // Invoke the upload // Processing resumes here after the upload.. var fname = system.variables.$FILE_NAME.value; var fnameUser = system.variables.$FILE_NAME_USER.value; if (fname) { // Show info message if file uploaded successfully event.owner.addWarningMessage("File " + fnameUser + " uploaded as " + FileServices.getAbsoluteFilePath(fname)); }
- Parameters:
options
- options to override the default upload parameters (seeUploadOptions
)- Since:
- V4.5
-
generatePdf
void generatePdf()Generates a PDF for the current page and displays this to the user in a popup window. This method is equivalent to callinggeneratePdf(PdfOptions)
with a null options parameter.There are a number of page design considerations that affect the appearance of a generated PDF e.g. how scrollable controls such as tables expand to display all content, how page breaks are handled, margins, headers and footers, page size and orientation, page numbering, print page styling etc. The Page Designer allows configuration of a number of properties for individual controls which address these considerations.
Javascript example:
form.generatePdf();
- Since:
- V4.4
-
generatePdf
Generates a PDF from one or more pages, with options to display to the user and save the generated file. Generates a PDF based on the options specified in theoptions
parameter.Any page created in the Form Designer can be output either to a web browser or to a PDF or to both of these. This means that the same page designer is used to create both web and print pages. There is no explicit declaration that a particular page is a print page; instead any page can be output as a PDF by invoking this method.
The following options are available (see
PdfOptions
):- display the PDF to the user (default true)
- save the PDF as a file on the server (default false)
- display the PDF as a popup (default true)
- display all HTML form input elements (textfields, textareas) as display only. This is useful when the length of data in the element may exceed the specified display size and the generated PDF should automatically expand to display all data. (default true)
- which pages to include in the PDF (default is the current page)
- the file path when the PDF is saved (See
PdfOptions
for the default) - the popup window name (no default)
Javascript example:
var opts = new PdfOptions(); opts.display = true; opts.save = true; opts.popup = true; opts.reportMode = true; opts.filePath = "C:/temp/pdf123.pdf"; opts.popupWindowName = "pdf1"; opts.pages = [pages.PAGE_2, pages.PAGE_4]; var fileName = form.generatePdf(opts);
- Parameters:
options
- options to control generation and appearance of the PDF (seePdfOptions
)- Returns:
- the file path of the saved document when the save option is selected, or null
- Since:
- V4.4
-
getAllPages
Page[] getAllPages()Returns an array of Page objects containing all pages within the form. The first page in the array is the form's first page and subsequent pages will be in display order when the pages are linked via each page'snext page
property. Pages not linked via anext page
property are added at the end of the array and can appear in any order.- Returns:
- an array of pages in display order
- Since:
- V4.4
-
getCurrentPage
Page getCurrentPage()Returns aPage
object representing the current page- Returns:
- the current page
- Since:
- V4.4
-
getFirstPage
Page getFirstPage()Returns thePage
object configured as the form's first page.- Returns:
- the first page
- Since:
- V4.5
-
getNextPage
Page getNextPage()Returns aPage
object representing the next page or null if no next page is configured.This is the page that will be displayed to the user when a Next Page Button Control is clicked or when the next page button within a Page Navigation Panel Control is clicked.
- Returns:
- the next page
- Since:
- V4.4
-
setNextPage
Sets the next page to be displayed when the user navigates forwards using a next page button.Sets the page that will be displayed to the user when a Next Page Button Control is clicked or when the next page button within a Page Navigation Panel Control is clicked.
- Parameters:
page
- the next page- Since:
- V4.4
-
getPreviousPage
Page getPreviousPage()Returns aPage
object representing the previous page displayed or null if there is no previous page.A previous page always exists except when the form's first page is displayed at the start of form processing. This is the page that will be displayed to the user when a Previous Page Button Control is clicked or when the previous page button within a Page Navigation Panel Control is clicked.
- Returns:
- the previous page
- Since:
- V4.4
-
getReturnUrl
java.lang.String getReturnUrl()Returns a Url for use with the callUrl() method.This Url is used by external applications to return to the current form after the external application has been called with method
callUrl(String, Map, String)
;- Returns:
- the return url
- Since:
- V4.4
-
isCalledForm
boolean isCalledForm()Returnstrue
if this form has been called from another form using methodcallForm(String, Map)
. Otherwise returns false.- Returns:
true
if this form has been called by another form- Since:
- V4.4
- See Also:
callForm(String, Map)
,getCallingFormName()
-
isBackground
boolean isBackground()Returnstrue
if this form is running in background e.g. it's a scheduled form, a deployment form or running in batch mode. Otherwise returns false.- Since:
- V5.3
-
getCallingFormName
java.lang.String getCallingFormName()Returns the name of the calling form or null if no calling form exists.- Returns:
- the calling form name
- Since:
- V4.4
- See Also:
callForm(String, Map)
,isCalledForm()
-
addFinalPageMessage
void addFinalPageMessage(java.lang.String message)Adds a message that will be displayed to the user on the form's final page.A form's final page is an optional special page which is only displayed to the user in certain circumstances. It is displayed when a Finish button Control is clicked or a finish button within a Page Navigation Control Panel is clicked. The final page is configured via a form's properties and has limited configuration options.
A final page message can be added at any time during form processing. These messages are typically used to provide feedback to indicate that the user's request has been successfully processed e.g. feedback any generated reference id, or inform the user that a confirmation email has been sent.
To add a multi-lingual final page message, use method
addFinalPageMessage(int, String[])
Javascript example:
form.addFinalPageMessage("Your request has been received successfully - reference number is " + fields.REF_NO.value); form.addFinalPageMessage("An email confirmation of this transaction has been sent");
- Parameters:
message
- the message to be added- Since:
- V4.4
- See Also:
addFinalPageMessage(int, String[])
-
addFinalPageMessage
@Deprecated void addFinalPageMessage(int messageNo, java.lang.String[] replaceParameters) throws com.ebasetech.xi.exceptions.FormRuntimeExceptionDeprecated.From V5.0 useaddFinalPageMessageText(Text, String[])
insteadAdds a message that will be displayed to the user on the form's final page. This method supports the addition of a pre-defined message that supports multiple languages and the substitution of variables.A message is added using its message number. Numbered messages are defined within each project using the Messages Editor - double click on the Messages element within each project in the designer tree. Within each message, a substitutable variable is identified by &&. Any substitutable variables in the message are replaced with values in the
replaceParameters
parameter (see example below).A form's final page is an optional special page which is only displayed to the user in certain circumstances. It is displayed when a Finish button Control is clicked or a finish button within a Page Navigation Control Panel is clicked. The final page is configured via a form's properties and has limited configuration options.
A final page message can be added at any time during form processing. These messages are typically used to provide feedback to indicate that the user's request has been successfully processed e.g. feedback any generated reference id, or inform the user that a confirmation email has been sent.
Javascript example:
form.addFinalPageMessage(1005, [fields.ORDER_NO.value, fields.ORDER_AMOUNT.value]);
If message 1005 in languageEN
contains text:
Order && received, total value &&
this might be displayed as:
Order 1002345 received, total value 99.67- Parameters:
messageNo
- the message number to be addedreplaceParameters
- an array of values to replace any substitutable parameters in the message defined as &&- Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
- Since:
- V4.4
- See Also:
addFinalPageMessage(String)
-
addFinalPageMessageText
void addFinalPageMessageText(Text text, java.lang.String[] replaceParameters) throws com.ebasetech.xi.exceptions.FormRuntimeExceptionAdds a message that will be displayed to the user on the form's final page. This method supports the addition of a message from a configured text and supports multiple languages and the substitution of variables.A message is added using its text id, where the text has been defined using the form/component text editor or in linked texts files, in which case they can be shared by multiple forms/components. Within each text, a substitutable variable is identified by &&. Any substitutable variables in the text are replaced with values in the
replaceParameters
parameter (see example below).A form's final page is an optional special page which is only displayed to the user in certain circumstances. It is displayed when a Finish button Control is clicked or a finish button within a Page Navigation Control Panel is clicked. The final page is configured via a form's properties and has limited configuration options.
A final page message can be added at any time during form processing. These messages are typically used to provide feedback to indicate that the user's request has been successfully processed e.g. feedback any generated reference id, or inform the user that a confirmation email has been sent.
Javascript example:
form.addFinalPageMessageText("Txt34", [fields.ORDER_NO.value, fields.ORDER_AMOUNT.value]);
If text Txt34 in languageEN
contains text:
Order && received, total value &&
this might be displayed as:
Order 1002345 received, total value 99.67- Parameters:
text
- the text to be added as a message, texts can be defined in form/component texts or in linked texts filesreplaceParameters
- an array of values to replace any substitutable parameters in the message defined as &&- Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
- Since:
- V5.0
- See Also:
addFinalPageMessage(String)
-
getPresentationTemplateName
java.lang.String getPresentationTemplateName()Returns the name of the presentation template currently used or null if no presentation template is configured.- Returns:
- the presentation template name
- Since:
- V4.4
- See Also:
getPresentationTemplatePath()
-
getPresentationTemplatePath
java.lang.String getPresentationTemplatePath()Returns the path of the presentation template currently used or null if no presentation template is configured.- Returns:
- the presentation template path
- Since:
- V5.0
- See Also:
getPresentationTemplateName()
-
setPresentationTemplateName
void setPresentationTemplateName(java.lang.String templateName) throws com.ebasetech.xi.exceptions.FormRuntimeExceptionSets the presentation template used by the current form using the template name or id.The system locates the specified template by searching all folders in all linked projects starting from the project of the owning form; the first template with the requested name is used.
This statement must be the last statement executed within a script - it cannot be followed by additional Javascript statements!
Changing the presentation template can lead to a loss of styling and should be done with care. Each control can be linked to styling properties contained within named property sets within a presentation template. If property sets with the same names do not exist in the new template, styling will be lost.
- Parameters:
templateName
- the name of the new presentation template to be applied- Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
- Since:
- V4.4
- See Also:
setPresentationTemplatePath(String)
-
setPresentationTemplatePath
void setPresentationTemplatePath(java.lang.String templatePath) throws com.ebasetech.xi.exceptions.FormRuntimeExceptionSets the presentation template used by the current form using the template path. The path should be relative to the root of the form's project or one of its dependent projects, and should use a forward slash as a path separator.This statement must be the last statement within a script - it cannot be followed by additional Javascript statements!
Changing the presentation template can lead to a loss of styling and should be done with care. Each control can be linked to styling properties contained within named property sets within a presentation template. If property sets with the same names do not exist in the new template, styling will be lost.
Javascript example:
form.setPresentationTemplatePath("/Templates/Template1");
- Parameters:
templatePath
- the name of the new presentation template to be applied- Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
- Since:
- V5.0
- See Also:
setPresentationTemplateName(String)
-
isBackButtonSupported
boolean isBackButtonSupported()Returnstrue
if use of the back button is supported for the current form. Otherwise returns false.- Returns:
true
if use of the back button is supported- Since:
- V4.4
-
getAbortPage
Page getAbortPage()Returns the current page after a failure has occurred, or null if no failure has occurred or there is no current page. This is intended to be used in anon error
event.- Returns:
- the page where a failure occurred or null if no failure has occurred
- Since:
- V4.4
-
isLoadedByServiceWorker
boolean isLoadedByServiceWorker()Returnstrue
if this form is being loaded by a client Javascript service worker. This will be true when the form is configured within a PWA as the start form or as an offline resource and is being loaded so that the page HTML and any associated web resources can be cached on client devices by the service worker.Typically this method would be used to control initialisation of the form and/or first page so that the correct page is returned to the service worker to be cached.
- Since:
- V5.4
-
addFinalPageMessageText(Text, String[])
instead