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.Modifier and Type | Field and Description |
---|---|
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. |
Modifier and Type | Method and Description |
---|---|
void |
addFinalPageMessage(int messageNo,
java.lang.String[] replaceParameters)
Deprecated.
From V5.0 use
addFinalPageMessageText(Text, String[]) instead |
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 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.
|
java.lang.String |
getPresentationTemplatePath()
Returns the path 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 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()
Returns
true if use of the back button is supported for the current form. |
boolean |
isBackground()
Returns
true if this form is running in background e.g. |
boolean |
isCalledForm()
Returns
true if this form has been called from another form using method callForm(String, Map) . |
boolean |
isLoadedByServiceWorker()
Returns
true 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()
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. |
abort, getAbortMessage, getFields, getLanguage, getResources, getTables, getTexts, getTimezone, setLanguage, setTimezone
getElementName, getElementType
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
static final java.lang.String HTTP_PROTOCOL_POST
POST
protocol, for use with the callUrl
and gotoUrl
methods.static final java.lang.String HTTP_PROTOCOL_GET
GET
protocol, for use with the callUrl
and gotoUrl
methods.Pages getPages()
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");
Pages
Controls getControls()
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";
Controls
void gotoPage(Page page)
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);
page
- the target pagevoid callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)
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);
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.callUrl(String, Map, String)
,
gotoUrl(String, Map, String)
,
displayUrl(String, boolean, String)
,
getReturnUrl()
void callUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)
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);
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.callUrl(String, Map)
,
gotoUrl(String, Map, String)
,
displayUrl(String, boolean, String)
,
getReturnUrl()
void gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters)
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);
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.gotoUrl(String, Map, String)
,
callUrl(String, Map, String)
,
displayUrl(String, boolean, String)
void gotoUrl(java.lang.String url, java.util.Map<java.lang.String,java.lang.Object> parameters, java.lang.String httpProtocol)
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);
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.gotoUrl(String, Map)
,
callUrl(String, Map, String)
,
displayUrl(String, boolean, String)
void displayUrl(java.lang.String url)
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);
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
displayUrl(String, boolean, String)
,
callUrl(String, Map, String)
,
gotoUrl(String, Map, String)
void displayUrl(java.lang.String url, boolean popup, java.lang.String popupWindowName)
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);
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.displayUrl(String)
,
callUrl(String, Map, String)
,
gotoUrl(String, Map, String)
void callForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)
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) ..
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.gotoForm(String, Map)
,
returnFromForm()
,
isCalledForm()
,
getCallingFormName()
void callForm(java.lang.String formName)
callForm(formName, null)
.formName
- the name of the target form to be calledcallForm(String, Map)
,
gotoForm(String, Map)
,
returnFromForm()
,
isCalledForm()
,
getCallingFormName()
void gotoForm(java.lang.String formName, java.util.Map<java.lang.String,java.lang.Object> parameters)
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);
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.callForm(String, Map)
void gotoForm(java.lang.String formName)
gotoForm(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.
formName
- the name of the target formgotoForm(String, Map)
,
callForm(String, Map)
void returnFromForm()
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();
callForm(String, Map)
void uploadFileFromBrowser()
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):
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.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)); }
void uploadFileFromBrowser(UploadOptions options)
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):
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.UploadOptions
). If an option is not specified, the corresponding system default from
UFSSetup.properties
is used.
Ufs.fileDirectoryName
)Ufs.maxUploadFileSize
)Ufs.uploadFileTypes
)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)); }
options
- options to override the default upload parameters (see UploadOptions
)void generatePdf()
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.
Javascript example:
form.generatePdf();
java.lang.String generatePdf(PdfOptions options)
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
):
PdfOptions
for the 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);
options
- options to control generation and appearance of the PDF (see PdfOptions
)Page[] getAllPages()
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.Page getCurrentPage()
Page
object representing the current pagePage getFirstPage()
Page
object configured as the form's first page.Page getNextPage()
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.
void setNextPage(Page page)
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.
page
- the next pagePage getPreviousPage()
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.
java.lang.String getReturnUrl()
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)
;
boolean isCalledForm()
true
if this form has been called from another form using method callForm(String, Map)
.
Otherwise returns false.true
if this form has been called by another formcallForm(String, Map)
,
getCallingFormName()
boolean isBackground()
true
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.java.lang.String getCallingFormName()
callForm(String, Map)
,
isCalledForm()
void addFinalPageMessage(java.lang.String message)
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");
message
- the message to be addedaddFinalPageMessage(int, String[])
@Deprecated void addFinalPageMessage(int messageNo, java.lang.String[] replaceParameters) throws com.ebasetech.xi.exceptions.FormRuntimeException
addFinalPageMessageText(Text, String[])
instead
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 language
EN
contains text:messageNo
- the message number to be addedreplaceParameters
- an array of values to replace any substitutable parameters in the message defined as &&com.ebasetech.xi.exceptions.FormRuntimeException
addFinalPageMessage(String)
void addFinalPageMessageText(Text text, java.lang.String[] replaceParameters) throws com.ebasetech.xi.exceptions.FormRuntimeException
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 language
EN
contains text: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 &&com.ebasetech.xi.exceptions.FormRuntimeException
addFinalPageMessage(String)
java.lang.String getPresentationTemplateName()
getPresentationTemplatePath()
java.lang.String getPresentationTemplatePath()
getPresentationTemplateName()
void setPresentationTemplateName(java.lang.String templateName) throws com.ebasetech.xi.exceptions.FormRuntimeException
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.
templateName
- the name of the new presentation template to be appliedcom.ebasetech.xi.exceptions.FormRuntimeException
setPresentationTemplatePath(String)
void setPresentationTemplatePath(java.lang.String templatePath) throws com.ebasetech.xi.exceptions.FormRuntimeException
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");
templatePath
- the name of the new presentation template to be appliedcom.ebasetech.xi.exceptions.FormRuntimeException
setPresentationTemplateName(String)
boolean isBackButtonSupported()
true
if use of the back button is supported for the current form.
Otherwise returns false.true
if use of the back button is supportedPage getAbortPage()
on error
event.boolean isLoadedByServiceWorker()
true
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.