com.ebasetech.xi.api
Interface WebForm

All Superinterfaces:

BaseForm, Element, EventOwner, MessageContainer, java.io.Serializable, WebFormEventOwner

public interface WebForm
extends BaseForm, WebFormEventOwner

The 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

static java.lang.String	HTTP_PROTOCOL_GET Represents the http GET protocol, for use with the callUrl and gotoUrl methods.
static java.lang.String	HTTP_PROTOCOL_POST Represents the http POST protocol, for use with the callUrl and gotoUrl methods.

Method Summary

void	addFinalPageMessage(int messageNo, java.lang.String[] replaceParameters) Adds a message that will be displayed to the user on the form's final page.
void	addFinalPageMessage(java.lang.String message) Adds a message that will be displayed to the user on the form's final page.
void	callForm(java.lang.String formName) Calls the specified form 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 specified form 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 the Controls object that gives access to all controls available to the form.
Page	getCurrentPage() Returns a Page object representing the current page
Page	getFirstPage() Returns the Page object configured as the form's first page.
Page	getNextPage() Returns a Page object representing the next page or null if no next page is configured.
Pages	getPages() Returns the Pages 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.
Page	getPreviousPage() Returns a Page 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 specified form, 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 specified form, 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() Returns true if use of the back button is supported for the current form.
boolean	isCalledForm() Returns true if this form has been called from another form using method callForm(String, Map).
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.
void	uploadFileFromBrowser() Displays a special upload page to the user and allows the user to upload one or more files to the server.
void	uploadFileFromBrowser(UploadOptions options) Displays a special upload page to the user to allow the user to upload one or more files to the server, with options to override some of the default parameters.

Methods inherited from interface com.ebasetech.xi.api.BaseForm

abort, getAbortMessage, getFields, getLanguage, getResources, getTables, setLanguage

Methods inherited from interface com.ebasetech.xi.api.Element

getElementName, getElementType

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, addWarningMessage, addWarningMessage, addWarningMessage, addWarningMessage, addWarningMessage, existErrorMessages, existMessages, existWarningMessages

Field Detail

HTTP_PROTOCOL_POST

static final java.lang.String HTTP_PROTOCOL_POST

Represents the http POST protocol, for use with the callUrl and gotoUrl methods.

See Also:

Constant Field Values

HTTP_PROTOCOL_GET

static final java.lang.String HTTP_PROTOCOL_GET

Represents the http GET protocol, for use with the callUrl and gotoUrl methods.

See Also:

Constant Field Values

Method Detail

getPages

Pages getPages()

Returns the Pages 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 the Controls 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

gotoPage

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. Any after 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. Any before 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 Http GET 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 parameter ebz i.e. the URL should be of the type domain/ufs/ufsreturn?ebz=xxxx e.g. http://mydomain/ufs/ufsreturn?ebz=1_1283432908172. The full return URL is available via method getReturnUrl() 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 or POST can be specified, where GET 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 parameter ebz i.e. the URL should be of the type domain/ufs/ufsreturn?ebz=xxxx e.g. http://mydomain/ufs/ufsreturn?ebz=1_1283432908172. The full return URL is available via method getReturnUrl() 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 are get and post, the default is get 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 Http GET 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 or POST can be specified, where GET 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 are get and post, the default is get 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 page

popupWindowName - 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 specified form and displays any resulting HTML page to the user. This provides the ability to call another Ebase form and then return to the calling form using method returnFromForm().

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 target form to be called

parameters - 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 specified form and displays any resulting HTML page to the user. This is equivalent to calling method callForm(formName, null).

Parameters:

formName - 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 specified form, terminates execution of the current form and commits the current transaction. Form memory is freed, and return to the current form is not possible. 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 target form

parameters - 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 specified form, terminates execution of the current form and commits the current transaction. This is equivalent to calling method gotoForm(formName, null).

Parameters:

formName - the target form to be called

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

void uploadFileFromBrowser()

Displays 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 of UFSSetup.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 named my_cv.doc will be saved with this name, the second with my_cv1.doc, them my_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 using FileServices.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 value my_cv.doc. If the Cancel button is pressed by the user, this variable will contain a null value.

Further documentation.

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

void uploadFileFromBrowser(UploadOptions options)

Displays a special upload page to the user to allow the user to upload one or more files to the server, with options 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 the Ufs.fileDirectoryName parameter of UFSSetup.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 named my_cv.doc will be saved with this name, the second with my_cv1.doc, them my_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 using FileServices.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 value my_cv.doc. If the Cancel button is pressed by the user, this variable will contain a null value.

The following options are available (see UploadOptions). If an option is not specified, the corresponding system default from UFSSetup.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)

Further documentation.

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 (see UploadOptions)

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 calling generatePdf(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.

Further documentation.

Javascript example:

 form.generatePdf();
 

Since:

V4.4

generatePdf

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. Generates a PDF based on the options specified in the options 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)

In addition to the options available via this method, there are a number of other 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.

Further documentation.

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 (see PdfOptions)

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's next page property. Pages not linked via a next 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 a Page object representing the current page

Returns:

the current page

Since:

V4.4

getFirstPage

Page getFirstPage()

Returns the Page object configured as the form's first page.

Returns:

the first page

Since:

V4.5

getNextPage

Page getNextPage()

Returns a Page 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

void setNextPage(Page page)

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 a Page 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()

Returns true if this form has been called from another form using method callForm(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()

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.

Further documentation.

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

void addFinalPageMessage(int messageNo,
                         java.lang.String[] replaceParameters)
                         throws com.ebasetech.xi.exceptions.FormRuntimeException

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

Further documentation.

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 language EN 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 added

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

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

setPresentationTemplateName

void setPresentationTemplateName(java.lang.String templateName)
                                 throws com.ebasetech.xi.exceptions.FormRuntimeException

Sets the presentation template used by the current form.

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.

Parameters:

templateName - the name of the new presentation template to be applied

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException

Since:

V4.4

isBackButtonSupported

boolean isBackButtonSupported()

Returns true 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 an on error event.

Returns:

the page where a failure occurred or null if no failure has occurred

Since:

V4.4