Package 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 Details

    • 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 Details

    • 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

    • getControlsByModifier

      Control[] getControlsByModifier​(java.lang.String modifier)
      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

      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. As default, the return URL is added automatically by the system as parameter ufsReturnURL.

      Not all servers support the ufsReturnURL parameter. The ufsReturnURL parameter can be excluded from the URL parameters by adding addUfsReturnURL=false to the parameter Map (example 3 below)

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

      Javascript example 3 (do not add ufsReturnURL to the URL parameters): 

       var parms = {};
 parms.cardid = fields.CREDIT_CARD_NO.displayValue;
 parms.amount = fields.PAYMENT_AMOUNT.displayValue;
 parms.returl = form.getReturnUrl();
 parms.addUfsReturnURL = false;
 
 var url = "http://www.xxxmypaymentservice.com"; 
 form.callUrl(url, parms);
      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. As default, the return URL is added automatically by the system as parameter ufsReturnURL.

      Not all servers support the ufsReturnURL parameter. The ufsReturnURL parameter can be excluded from the URL parameters by adding addUfsReturnURL=false to the parameter Map (example 3 below)

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

      Javascript example 3 (do not add ufsReturnURL to the URL parameters): 

       var parms = {};
 parms.cardid = fields.CREDIT_CARD_NO.displayValue;
 parms.amount = fields.PAYMENT_AMOUNT.displayValue;
 parms.returl = form.getReturnUrl();
 parms.addUfsReturnURL = false;
 
 var url = "http://www.xxxmypaymentservice.com"; 
 form.callUrl(url, parms, 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 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 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 name of 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 form with the specified name and displays any resulting HTML page to the user. This is equivalent to calling method callForm(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 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 form with the specified name, terminates execution of the current form and commits the current transaction. This is equivalent to calling method 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.

      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 the FileUploadControl instead
      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

      @Deprecated void uploadFileFromBrowser​(UploadOptions options)
      Deprecated.
      From V5.9 it is recommended to use the FileUploadControl instead
      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()

    • isBackground

      boolean isBackground()
      Returns 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.
      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.

      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

      @Deprecated void addFinalPageMessage​(int messageNo, java.lang.String[] replaceParameters) throws com.ebasetech.xi.exceptions.FormRuntimeException
      Deprecated.
      From V5.0 use addFinalPageMessageText(Text, String[]) instead
      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)

    • addFinalPageMessageText

      void addFinalPageMessageText​(Text text, 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 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.

      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.addFinalPageMessageText("Txt34", [fields.ORDER_NO.value, fields.ORDER_AMOUNT.value]);
      If text Txt34 in language EN 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 files
      replaceParameters - 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.FormRuntimeException
      Changes the Presentation Template used by the current form to the one with the specified name.

      Important: form.setPresentationTemplateName(...) must be on the last line of a script. After the setPresentationTemplateName function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.setPresentationTemplateName("myPresentationTemplate");
      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.FormRuntimeException
      Changes the Presentation Template used by the current form to the one at the specified path.

      The path should be relative to the root of the Form's project or one of its dependent projects. It must start with a forward slash as a path separator.

      The new Theme must have the same Framework and collection of Property Sets as the current Theme otherwise the Form may not look as expected.

      Important: form.setPresentationTemplatePath(...) must be on the last line of a script. After the setPresentationTemplatePath function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.setPresentationTemplatePath("/presentation/myPresentationTemplate");
      Parameters:
      templatePath - the path of the new Presentation Template to be applied
      Throws:
      com.ebasetech.xi.exceptions.FormRuntimeException
      Since:
      V5.0
      See Also:
      setPresentationTemplateName(String)

    • getTheme

      java.lang.String getTheme()
      Returns the path of the theme currently used or null if no theme is configured.
      Returns:
      the theme path
      Since:
      V5.13

    • setTheme

      void setTheme​(java.lang.String theme)
      Changes the Theme used by the current form to the one at the specified path.

      The path should be relative to the root of the Form's project or one of its dependent projects. It must start with a forward slash as a path separator.

      The new Theme must have the same Framework and collection of Property Sets as the current Theme otherwise the Form may not look as expected.

      Important: form.setTheme(...) must be on the last line of a script. After the setTheme function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.setTheme("/themes/myTheme");
      Parameters:
      theme - the path of the new theme to be applied
      Since:
      V5.13
      See Also:
      setPresentationTemplatePath(String)

    • 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

    • isLoadedByServiceWorker

      boolean isLoadedByServiceWorker()
      Returns 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.

      Further documentation.

      Since:
      V5.4

    • useProjectTheme

      void useProjectTheme() throws com.ebasetech.ufs.kernel.FormException
      Change the current Form so it uses its Project's configured Theme.

      The Theme must have the same Framework and collection of Property Sets as the current Theme otherwise the Form may not look as expected.

      Important: form.useProjectTheme(); must be on the last line of a script. After the useProjectTheme() function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.useProjectTheme();
      Throws:
      com.ebasetech.ufs.kernel.FormException - is an error occurs setting the project theme
      Since:
      V5.13
      See Also:
      useFormTheme(), usePresentationTemplate()

    • useFormTheme

      void useFormTheme() throws com.ebasetech.ufs.kernel.FormException
      Change the current Form so it uses its configured Theme.

      The Theme must have the same Framework and collection of Property Sets as the current Theme otherwise the Form may not look as expected.

      Important: form.useFormTheme(); must be on the last line of a script. After the useFormTheme() function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.useFormTheme();
      Throws:
      com.ebasetech.ufs.kernel.FormException - is an error occurs setting the form theme
      Since:
      V5.13
      See Also:
      useProjectTheme(), usePresentationTemplate()

    • usePresentationTemplate

      void usePresentationTemplate() throws com.ebasetech.ufs.kernel.FormException
      Change the current Form so it uses its configured Presentation Template.

      Important: form.usePresentationTemplate(); must be on the last line of a script. After the usePresentationTemplate() function call is executed, the next script configured in the server event will be executed.

      For further information see:

      JavaScript example: 

       form.usePresentationTemplate();
      Throws:
      com.ebasetech.ufs.kernel.FormException - is an error occurs setting presentation template
      Since:
      V5.13
      See Also:
      useProjectTheme(), useFormTheme()

    • isUseProjectTheme

      boolean isUseProjectTheme()
      Returns true if the form uses the project's theme.
      Returns:
      whether the form should use the project theme
      Since:
      V5.13
      See Also:
      useProjectTheme()

    • getProject

      Project getProject()
      Returns the current project for the running form
      Returns:
      current project
      Since:
      V5.13