e-Forms Payment Template - MITA1 · Public eForms Payment Template 02. Scope This document...

Malta Information Technology Agency, Gattard House, National Road, Blata l-Bajda HMR 9010 Malta Telephone: (+356) 21234710 Facsimile: (+356) 21234701

Web Site: www.mita.gov.mt

e-Forms Payment Template

Date: 06th February 2012

Version: 1.0 Unit: eGov Architecture Department: eGov DEO

Public

Public eForms Payment Template

Page i

Document Control Information

01. Document reference

eForms-REP-eformPaymentTemplate-v1.0.doc

02. Document type

Procedure

03. Security classification

Public

04. Synopsis

This documentation provides details how to make use of the eForms Payment Template

05. Document control

Author Change controller Distribution controller

eGovernment Department eGovernment Department eGovernment Department

06. Modification history

Version Date Comments

Draft 0.1 12/12/2011 Draft version for internal review

Version 1.0 06/02/2012 First version for release


Table of Contents

DOCUMENT CONTROL INFORMATION .................................................................................................................................. I

TABLE OF CONTENTS.............................................................................................................................................................1

01. INTRODUCTION ..........................................................................................................................................................2

02. SCOPE .........................................................................................................................................................................3

03. DEFINITIONS ...............................................................................................................................................................4

04. PAYMENT TEMPLATE ................................................................................................................................................5

05. NAMING CONVENTIONS ............................................................................................................................................6

06. LAYOUT .......................................................................................................................................................................7

06.1 PAYMENT TEMPLATE...................................................................................................................................................7 06.1.1 Page Layout ....................................................................................................................................................7

07. REQUIRED HIDDEN FIELDS ......................................................................................................................................8

07.1 PAYMENT TEMPLATE...................................................................................................................................................8

08. LOCALISATION............................................................................................................................................................9

09. ERROR LOGGING .....................................................................................................................................................10

10. MITA EXTERNAL JAVASCRIPT ................................................................................................................................11

PLEASE DO NOTE THAT THE SCRIPTS WITHIN THIS TEMPLATE ARE NOT TO BE ALTERED....................................11 10.1 AVAILABLE SERVER-SIDE SCRIPTS ............................................................................................................................11

10.1.1 CSForm_OnOpen() .......................................................................................................................................11 10.1.1.1 CheckManualPayment() ..............................................................................................................................................12 10.1.1.2 CheckMyBillsPayment()...............................................................................................................................................13 10.1.1.3 PopulatePaymentDetails() ...........................................................................................................................................14 10.1.1.4 setVisibilityOnRadioButton () .......................................................................................................................................15

10.1.2 CSForm_OnSubmit() .....................................................................................................................................16 10.2 AVAILABLE CLIENT-SIDE SCRIPTS..............................................................................................................................18

10.2.1 Variables........................................................................................................................................................18 10.2.2 Funtions.........................................................................................................................................................20

10.2.2.1 CSForm_OnLoad() ......................................................................................................................................................20 10.2.2.2 jsLoadedHook() ...........................................................................................................................................................21 10.2.2.3 MITALOScriptCallExternalFunctionsOnLoad()............................................................................................................22 10.2.2.4 loadcssfile(filename) ....................................................................................................................................................23 10.2.2.5 loadjsfile(filename).......................................................................................................................................................23 10.2.2.6 radPayOnline_OnButtonClick() ...................................................................................................................................23 10.2.2.7 radBankTransfer_OnButtonClick() ..............................................................................................................................23 10.2.2.8 radBankTransfer_OnButtonClick() ..............................................................................................................................24 10.2.2.9 radSendCheque_OnButtonClick() ...............................................................................................................................24 10.2.2.10 radInternetBanking_OnButtonClick()...........................................................................................................................24 10.2.2.11 ChangeOption(thevalue)..............................................................................................................................................25 10.2.2.12 CSForm_OnSubmit() ...................................................................................................................................................26 10.2.2.13 getDefaultErrorMessage(lang) ....................................................................................................................................27 10.2.2.14 btnSubmit_OnClick()....................................................................................................................................................27 10.2.2.15 MITALOGreyOutPage(greyout, options, lockScrollbar, language)..............................................................................27

11. FURTHER ASSISTANCE...........................................................................................................................................28


01. Introduction

E-Forms are currently being implemented as part of the eGovernment Services. At times there might be the case when the user needs to submit a payment for the application form. In order to cater for this feature a template page has been created to be used. In this document the components and features found in the Payment template are to be explained hence the developer will be guided how to tackle it in a way to keep the template as uniform as possible. These guidelines are to be instructed using explanations, illustrations as well as code snippets.


02. Scope

This document describes the Payment template features. One of these features is the page itself, which consists of an aggregation of form fields, hidden fields, as well as specific buttons, which, in turn, automate a number of other features. Other sections, as specified in the Table of Contents, will also be examined. One important thing to notice is the naming conventions, which are to be tackled according to the template components. Besides the template layout and its components this document will guide the developer throughout the use of the Logger functionality as well as provide a clearer idea of the role localisation plays when template components are constructed. In addition, both libraries and external JavaScripts will be explained.


03. Definitions

Term Description

Administrator A person responsible for the management of all or part of a service, system or resource according to the level of permissions assigned.

Backend An application used to change web content and configure services.

Branding The specification for layout and design, look and feel, usability and functionality to be followed by every Government of Malta website.

Citizen Any user who is a natural person, including an e-Citizen.

Configuration A set of attributes and parameters required for a service to work.

Criteria A set of values to be used to select a set of data.

CSS Cascading Style Sheets are files that determine the look of HTML websites.

e-Citizen A Maltese National ID card holder who has acquired an e-ID login profile and who may therefore make use of the online eGovernment services.

e-ID The eGovernment electronic logging ID system.

e-Forms The platform used to deliver eServices to the Government of Malta.

e-Mail Electronic mail is a method of exchanging digital messages in text or HTML formats with attachments over a network.

eGov DEO The eGovernment Direction, Execution and Operations Department is responsible for the delivery of government information and services, and interaction, within government entities, with the public, and with other external entities, over electronic means.

eGovernment Electronic Government, usually used in the context of e-Government services, referring to those services which the Government can provide through an electronic medium such as Internet, mobile etc.

GMICT Government of Malta ICT.

Government The Government of Malta.

Government Entities Authorities, Corporations, Agencies and commercial public sector entities in which the Government has a majority shareholding and which are not listed on the stock exchange.

HTML Hypertext Markup Language defines the structure and layout of a web document through the use of tags and attributes.

ICT Information and Communication Technologies.

LiquidOffice Platform provided by Autonomy which caters for the creation of the eForms and process workflows

MITA Malta Information Technology Agency, the Contracting Authority for the purposes of the Public Contracts Regulations.

Parameter A value that can be varied (usually within configuration) to change the behaviour of a service or function.

Parameter Store Data repository for parameters that need to be localized.

Profile The set of details/particulars required by a system for an item.


04. Payment Template

After submitting the form the user might need to submit a form fee. Payment through eForms might be done using one of four options. These options are available according to which payment methods are available for the specific form. When one of the four options is chosen, then the user will be redirected to the specific template as necessary since the different payment methods do require different data.


05. Naming Conventions

Each component within each eForm page is to be named according to naming conventions to enhance uniformity. More details about the naming conventions of the profile fields can be found in the document named Naming Conventions and Considerations for eForms Development whilst further details about the naming conventions about the side menu buttons and the previous and next menu buttons can be found in the eForms Page Template document in the Naming Conventions Section.


06. Layout

06.1 Payment Template

As mentioned in section 04 Payment Template there might be the case when the user is asked to pay a fee in order to submit the form. The user might submit the payment using one of four payment methods. These are the following:

• Online Payment • Bank Transfer • Cheque • Internet Banking

06.1.1 Page Layout

This template is a one page template in which different sections are present where the user is presented the amount which needs to be paid and the payment methods by which the payment can be submitted.

The data fields above are not to be filled in by the user but they are to be generated automatically. They are shown in the figure below. Please do note that the amount due is to be set automatically according to the form fee. The user needs to choose the payment method. Following that the user will be redirected to the page of the respective payment method chosen.


07. Required Hidden Fields

07.1 Payment Template

Hidden Field Name

Description

Initial Value

hdnAmountDue Stores the amount due of the

applicant according to the default amount set to the form being submitted.

hdnFullEventID Stores the full event ID (set from the process)

hdnLanguage Stores the language code for the user’s selected language

Should be mapped to the ‘languageCode’ profile field

hdnLocalizedFields Stores a comma delimited list of fields that have been localized in order for these not to be localized again at a later stage

hdnOptChosen Hidden field containing the applicant’s selected method of payment in numeric format.

hdnPaymentBankDetails

Stores the bank name in case the user is to select to submit the payment using a cheque.

hdnPaymentChequeDetails

Hidden field to store the cheque details which is to be needed in case the user asks to pay using a cheque

hdnPaymentURL Hidden field created to store the URL of the page which the user will be redirected to after choosing the payment method.

hdnProcessID Needs to be manually set in each application form to the WebFormProcessID. Is used to retrieve all the relevant form info from DB.

Initial Value should be set to WebFormProcessID

hdnProcessName Used to store the process name (as stored in the Service Property table)

hdnProcessStatus Stores the current status of the process (ex: vetting, approval, committee, returned to applicant, etc..) Value is set from code behind on submit.

hdnProviderKey Stores the provider key of the form’s provider

Should be set to the supplied provider key


08. Localisation

Details about how the localisation is implemented within the eForm templates are to be found in the eForms Application Template document in Section 07 Localisation section.


09. Error Logging

Details about how the error logging is implemented within the eForm templates are available in the eForms Application Template document in Section 09 Error Logging section.


10. MITA External Javascript

Please do note that the scripts within this template are not to be altered.

10.1 Available Server-Side Scripts

10.1.1 CSForm_OnOpen()

The first function which is to be executed once the Payment Template is to open is the CSForm_OnOpen() . In the code below an array is to be created in order to hold the field name of the payment method together with its corresponding label names. These fields are set not to be visible. Besides that the initialisation of the form and the localisation required are also to take place in this function.

Localisation code in CSForm_OnOpen function CSForm_OnOpen() { try {

var fieldArray = ["radPayOnline", "lblPayOnline", "radBankTransfer", "lblBankTransfer", "radSendCheque", "lblSendCheque" , "radInternetBanking", "lblInternetBanking"];

// reset the visibility on the radio buttons

CSForm = FormUtils.setFieldsHidden(CSForm, fiel dArray, false);

The user details are to be obtained from the method getCurrentUser() while the process name is to be obtained using the hidden field named hdnProcessName . After that the hdnAmountDue field is needed. This field is initially set for each form since every form has its particular fee in order to be submitted. In this function this field is fetched to be shown in the textbox of the template which is to hold the amount due of the application. Besides that the code below shows how the populateLoginInfo() function is executed which is to load the login data, from the server as required.

Obtaining the hidden field of the amount due value and load essential data

var usr = CSServer.getCurrentUser(); var processName = CSForm.getField("hdnProcessName") .getValue(); // initialize the form and perform the localization CSForm = FormUtils.initializeForm(CSForm, CSServer, false, "eForms"); // set the amount due display equal to the hidden field value CSForm.getField("txtAmountDue").setValue(CSForm.get Field("hdnAmountDue").getValue()); // load login data, date and form name FormUtils.populateLoginInfo(CSForm, CSServer, "lblL oginName", "lblLoginDate", "lblFormName");

Each form is to own particular payment details such as the payment methods that are accepted by the particular form. These payment methods are obtained using the function called getPaymentDetails() as found in the Payment class. This function accepts the particular form to be submitted and the connector agent as parameters. Following that the logic to set the payment options is called using the function populatePaymentDetails( ) which accepts the payment


methods of the form as parameters. This function is to populate the radio button list of the Payment template with the available payment methods. This code is shown below. Obtaining the payment methods the form supports to populate the payment methods options

var paymentDetails = Payment.getPaymentDetails( CSForm, "eForms"); // call logic for setting the payment options populatePaymentDetails(paymentDetails);

Following that the myBills URL would be built. Please do note that this would only be present in case the form accepts payment using myBills.

Consequently a check is to be performed whether the payment had already been performed or not. In order to do this both the tables of the myBills and of the manual Payments are analysed to decipher whether the payment had had been performed using the form’s event ID. This check needs to be performed for two reasons. The first reason would be to identify whether the payment options need to be present or not. The second reason is so that if the record is not present in any of the tables a new record containing the payment details would be created in a table held at the Loqus which states that the payment had been submitted. The code taking care of these steps is found below.

10.1.1.1 CheckManualPayment()

This function is to check whether the payment of the form to be submitted had already been performed as manual payment or not. This is done by checking whether the event ID of the form is present in the manual payment table. The manual payment table holds data about payments submitted using cheques, internet banking or bank transfers. The first thing to be performed is to set a Boolean variable named authorised to false. This variable is to hold the value of the check performed i.e. whether the manual payment’s record is present within the table or not. In order to check whether the payment’s record is present within the table or not, the function manualPaymentFound() is used which can be found in the Payment class

Building myBills URL // constructs the URL which will be used for the pa yment

CSForm.getField("hdnPaymentURL").setValue(Parameter s.getInternalParam("myBillsURL") + "?LO__REF=" + CSForm.getField("hdnFullEventID" ).getValue() + "_" + CSForm.getField("hdnProcessID").getValue());

Verifying whether the payment had been performed if ((!CheckManualPayment()) && (!CheckMyBillsPaymen t())) {

Payment.makePayment(CSForm, CSServer, "eForms", pay mentDetails, CSForm.getField("txtAmountDue").getValue(),

CSForm.getField("lblPaymentFormTitle").getV alue()); }


Consequently an array is created. This is meant to hold the radio button list field names and their respective labels. The code implemented for these steps is shown below.

If the manual payment is found, then a message is to appear. In order to obtain the message one needs to make sure that the localisation features are obtained as necessary hence the values of the hidden fields named hdnLanguage , hdnProviderKey and the hdnProcessName are to be obtained. In case the payment is found, the radio button list would be unnecessary at this stage hence it is to be set to be hidden. Other than that if the manual payment is not found then the submit button would be set to hidden so that the user would need to choose the payment method and submit the corresponding details before actually choose to submit the payment. The steps mentioned are implemented as shown in the code below.

10.1.1.2 CheckMyBillsPayment()

This function is to check whether the payment of the form to be submitted had already been performed using myBills or not. This is done by checking whether the event ID of the form is present in the myBills template. Please do note that this function is mostly the same as the function named CheckManualPayment(). The only difference from the mentioned function is mainly how the variable authorised is loaded since in this case the variable authorised is the result of the method named myBillsPaymentFound() which is found in the Payment class and it is to hold the result of whether the payment had already been performed using myBills or not This function is shown below:

Checking whether the payment had been performed and loading the radio button list options with their respective labels

function CheckManualPayment() { var authorised = false; authorised = Payment.manualPaymentFound(CSForm, " eForms"); var fieldArray = ["radPayOnline", "lblPayOnline", "radBankTransfer",

"lblBankTransfer", " radSendCheque", "lblSendCheque", "radInternetBankin g", "lblInternetBanking"];

The steps to be performed when determining whether the payment had been performed or not if (authorised) {

CSForm.getField("lblPaymentWarning").setValue(Local ization.internationalize("PAYMENT_AUTH", CSForm.getField("hdnLanguage").getValue(), CSForm.getField("hdnProviderKey").getValue(), CSForm.getField("hdnProcessName").getValue())); CSForm = FormUtils.setFieldsHidden(CSForm, fieldArr ay, true); CSForm.setStatusCode(1);

} else { CSForm.getField("btnSubmit").setHidden(true); } return authorised;


10.1.1.3 PopulatePaymentDetails()

This function is meant to populate the payment details of the form. It basically takes care of identifying which are the payment methods that the form accepts hence using these methods to populate the radio button list options as required. In this method first a jsonObj is initialised to hold the payment methods as is accepted by the respective form. Besides that the hidden fields holding the Cheque details and the Bank details are to be set using values found in the payment details retrieved.

Then a loop is to be initialised which is to be iterated for the maximum number of payment methods found to be supported by the form. In this loop two (2) variables are to be initialised. One holding the method name and another one to hold the result of whether the payment is used in the form or not.

Determine whether the payment had already been performed using myBills function CheckMyBillsPayment() { var authorised = false;

var fieldArray = ["radPayOnline", "lblPayOnline", " radBankTransfer", "lblBankTransfer", "radSendCheque", "lblSendCheque",

"radInternetBanking", "lblInt ernetBanking"];

var authorised = false; authorised = Payment.myBillsPaymentFound(CSForm, "m yBills"); if (authorised) {

CSForm.getField("lblPaymentWarning").setValue(Local ization.internationalize("PAYMENT_AUTH", CSForm.getField("hdnLanguage").getValue(), CSForm.getField("hdnProviderKey").getValue(), CSForm.getField("hdnProcessName").getValue())); CSForm = FormUtils.setFieldsHidden(CSForm, fieldArr ay, true); CSForm.setStatusCode(1);

} else { CSForm.getField("btnSubmit").setHidden(true); CSForm = FormUtils.setFieldsHidden(CSForm, fiel dArray, false); } return authorised; }

Putting the payment methods in a json object while setting some required function populatePaymentDetails(paymentDetails) { try { var jsonObj = eval('(' + paymentDetails.payMet hods + ')') CSForm.getField("hdnPaymentChequeDetails").set Value(paymentDetails.chequeDetails); CSForm.getField("hdnPaymentBankDetails").setVa lue(paymentDetails.bankDetails);


Another loop is to be used within this loop which is meant to iterate for how many payment methods the form is to support. In this loop if the payment method name found in the variable (previously set) is to match the id of the payment supported by the form, then its value is captured. If the payment method is found within the form then the payment method is to be shown in the radio button list, otherwise it won’t be shown. After iterating through this inner loop, the methodNameFound value is to be set to true. If the respective payment method is not found to be supported by the loop then the respective payment method won’t be shown as an option for the user. The implementation code of this function is the following:

10.1.1.4 setVisibilityOnRadioButton ()

This function is to make visible the radio button list options. The first step this function is to do is to empty the contents of the hidden field named hdnOptChosen. Consequently the payment methods are to be shown as needed. Please do note that if the field or the label is to be left empty then that particular field / label is to be set as hidden. The implementation code of the following function is found below.

Function PopulatePaymentDetails()

function populatePaymentDetails(paymentDetails) { try { var jsonObj = eval('(' + paymentDetails.payMethods + ')') CSForm.getField("hdnPaymentChequeDetails").setValue(paymentDetails.chequeDetails); CSForm.getField("hdnPaymentBankDetails").setValue(paymentDetails.bankDetails); // iterate for the maximum number of payment types we should have for (var i = 1; i < 5; i++) { var payMethodName = "PayMethod" + i; var methodNameFound = false; for (var j = 0; j < jsonObj.PaymentMethods.length; j++) { if (payMethodName === jsonObj.PaymentMethods[j].id) { var payMethodValue = jsonObj.PaymentMethods[j].value; // set visibility of control setVisibilityOnRadioButton(payMethodName, payMethodValue === "0"); methodNameFound = true; } } if (methodNameFound === false) { setVisibilityOnRadioButton(payMethodName, true); } } } catch(e) { serverErrorHandler(e); } }


10.1.2 CSForm_OnSubmit()

This function is to be executed once the user clicks on the Submit button. First the initial localisation of the variables required are to be performed while an array is to be initialised to set up the options and labels with regards to the radio button list. The implementation code of these two (2) initialisations is shown in the following code:

Function setVisibilityOnRadioButton() function setVisibilityOnRadioButton(payMethodName, setHidden) { try { var fieldName; var labelName; CSForm.getField("hdnOptChosen").setValue(""); if (payMethodName == "PayMethod1")

{ fieldName = "radPayOnline"; labelName = "lblPayOnli ne";

} else if (payMethodName == "PayMethod2")

{ fieldName = "radBankTransfer"; labelName = "lblBank Transfer";


{ fieldName = "radSendCheque"; labelName = "lblSendCh eque";


{ fieldName = "radInternetBanking"; labelName = "lblI nternetBanking";

}

if ((fieldName != undefined) && (fieldName != " ")) { CSForm.getField(fieldName).setHidden(setHidde n); } if ((labelName != undefined) && (labelName != " ")) { CSForm.getField(labelName).setHidden(setHidde n); } } catch(e) { serverErrorHandler(e); } }

Initialising the localisation variables needed and field array in the function CSForm_OnSubmit()

var language = CSForm.getField("hdnLanguage").getVa lue(); var providerKey = CSForm.getField("hdnProviderKey") .getValue(); var processName = CSForm.getField("hdnProcessName") .getValue();

var fieldArray = ["radPayOnline", "lblPayOnline", " radBankTransfer",

"lblBankTransfer", "radSendCheque", "lblSendCheque" , "radInternetBanking", "lblInternetBanking"];


At this point the payment opted by the user is to be taken into consideration by considering the value in the hidden field named hdnOptChosen. The value is to be evaluated as shown in the code below. At this stage the payment method chosen by the applicant is to be evaluated. In fact if the user choose to pay either by manual payment, bank transfer or internet banking, the CheckManualPayment() method is to be called. This is due to the fact that for each of the three payment methods mentioned there must be a manual verification that the payment had been successfully performed hence it needs to be inserted in the Manual Payment Table. Hence if the CheckManualPayment() is to return the value as true, then the a message that the payment had been successfully made is to be shown to the applicant while the template components are to be set as hidden. In these three (3) methods chosen the data needed to be inserted is to be evaluated. In case any of the compulsory fields is to be left empty then the payment cannot be set to be successfully performed. In case that myBills are being used, if the payment would result to being successful a message is to appear while the unnecessary fields are set to be hidden.

Evaluating the payment method chosen by the applicant switch (CSForm.getField("hdnOptChosen").getValue()) { case "1": if(CheckManualPayment())

{ CSForm.getField("lblPaymentWarning").setValue(Local ization.internationalize("PAYMENT_AUTH", language, providerKey, processNa me));

CSForm = FormUtils.setFieldsHidden(CSForm , fieldArray, true); CSForm.setStatusCode(1); }

if((CSForm.getField("txtPaymentReferenceNo").getVal ue().length < 1) || (CSForm.getField("txtPaymentClearingBank").getValue ().length < 1)) {

CSForm.setStatusCode(-2); }

break; case "2": if(CheckManualPayment()) {

CSForm.getField("lblPaymentWarning").setValue(Local ization.internationalize("PAYMENT_AUTH", language, providerKey, processNa me));

CSForm = FormUtils.setFieldsHidden(CSForm , fieldArray, true); CSForm.setStatusCode(1); } if((CSForm.getField("txtPaymentChequeNo").g etValue().length < 1) || (CSForm.getField("txtPaymentClearingBank ").getValue().length <1)) { CSForm.setStatusCode(-2); } break;

case "3": if(MyBillsPaymentFound()) {


CSForm = FormUtils.setFieldsHidden(CSForm , fieldArray, true); CSForm.setStatusCode(1); } break;


10.2 Available Client-Side Scripts

Please do note that the scripts within these templates are not to be altered. 10.2.1 Variables

In the client side scripts of this template there are some variables which are needed. The first variable which is to be declared is the localisedStrings. This variable is to hold the text which is to be shown in the lblPaymentMessage when the payment method is chosen by the user. This variable is declared as shown below. Please do note that the message shown to the user upon the selection of the payment is to be different according to the payment method chosen.

case "4": if(CheckManualPayment()) {


CSForm = FormUtils.setFieldsHidden(CSForm , fieldArray, true); CSForm.setStatusCode(1); } if((CSForm.getField("txtPaymentReferenceNo" ).getValue().length < 1) || (CSForm.getField("txtPaymentClearingBank"). getValue().length <1)) { CSForm.setStatusCode(-2); } break; }

Initialising variable localizedStrings

var localizedStrings= { PayOnline: {

en:'The online payment is carried out in a separate window that closes after producing t he receipt. The form will then be listed in your ma ilbox sections as follows: \ nSuccessful payments in the “In progress” section \ nDeclined payments or aborted payments in the “Atte ntion Required” section. \nYou can re-open forms within the Attenti on Requ ired section to continue an online payment or choose an alternativ e method where applicable. \nClick “Go” to submit and return to th e eForms page.', mt:'Il- ħlas online huwa mwettaq f’tieqa separata li tinag ħlaq wara li ti ġi provduta l-ir ċevuta. Il-formola mbag ħad ti ġi elenkata fil- kaxxa postali tieg ħek ta ħt wa ħda minn dawn it-taqsimiet: \n Ħlasijiet li rnexxew fit- taqsima "Fil-progress"; \n Ħlasijiet li gew rifjutati jew abortiti fit-taqsima "Attenzjoni Me ħtiega". \nTista\' terga\' tifta ħ il-formoli fit-taqsima "Attenzjoni Me ħtie ġa" biex tkompli l- ħlas online jew tag ħzel metodu ta’ ħlas alternattiv fejn applikabbli. \nAg ħfas "Ibg ħat" biex tibg ħat il-formola u ter ġa lura ġol-pa ġna tal-eForms.'

}, BankTransfer: {

en:'You have chosen to pay by In ternet Banking. Kindly make a payment to one of the accounts above. Click "Go" to submit the bank transaction reference number.', mt:'Inti g ħażilt li t ħallas mill-Internet Banking. Ġentilment nitolbuk tg ħamel ħlas lil wie ħed mill-kontijiet mni żżla hawn fuq. Ag ħfas "Ibg ħat" biex tibg ħat in-numru ta’ referenza tat-tran żazzjoni tal-bank.'


The next variables to be declared are the messages that are to be loaded on loading the page. The message in the MITALOLoadingMsg variable is to be loaded when the black screen is shown to the user while waiting to load the form. The message in the MITALODidNotLoadMsg variable is to be loaded in case the page did not load successfully. Please do note that the variable holds the message in the two (2) languages i.e. Maltese and English. The initialisation of these two (2) variables is shown below.

The next variable to be initialised is the paymentTypes which is to hold the radio buttons label and the method to be called once the button to choose the payment has been clicked by the user. The initialisation of this variable is shown below.

},

SendCheque: {

en:'The Form will be processed when cheque is recei ved and verified. Click "Go" to submit the cheque number.', mt:'Il-Formola se ti ġi pprocessata meta i ċ- ċekk ji ġi r ċevut u vverifikat. Agħfas "Ibg ħat" biex tibg ħat in-numru ta ċ- ċekk.'

}, InternetBanking: {

en:'You have chosen to pay by Internet Banking. Key in the reference above into the appropriate field of the Internet Banking and 24 X 7 Services in line with the specific instructions of your respect ive bank. Click "Go" to continue.', mt:'Inti g ħażilt li t ħallas mill-Internet Banking. Da ħħal ir- referenza provduta hawn fuq fil-kaxxa rispettiva tal-Internet Banking u s- Servizzi 24 X 7 skond l-istruzzjonijiet spe ċifikati mil-bank tieg ħek. Ag ħfas "Ibg ħat" biex tkompli.'

} }

Initialising variables MITALOLoadingMsg and MITALODidNotLoadMsg var MITALOLoadingMsg = { 'en':'Loading...Please Wait.', 'mt':'Il- pagna qieghda tiela... Jekk jghogbok ste nna ftit.' }; var MITALODidNotLoadMsg = { 'en':'The page did not load. Please refresh the p age to try loading the form again.', 'mt':'Il- pagna ma telghatx. Jekk jghogbok iffris ka l- pagna biex terga tipprova ttellaghha.' };

Initialising variable paymentTypes var paymentTypes = [ {'radio':'radPayOnline', 'control':'radPayOnline_OnButtonClick()' }, {'radio':'radBankTransfer', 'control':'radBankTransfer_OnButtonClick()' }, {'radio':'radSendCheque', 'control':'radSendCheque_OnButtonClick()'


Following that a series of local variables are to be initialised. The variables are the following:

Name Description jsRetries This variable is to hold the retries to attempt to

load the JavaScript file.

jsMaxRetries This variable is to hold the amount of maximum retries to attempt to load the JavaScript file until which if reached no more retries will be performed.

isLoaded This variable is to hold the value of whether the page had been loaded successfully or not

MITA_DEFAULT_ERRORMSG_MT This variable is to hold the error message in the Maltese language to be displayed to the user in case the page does not manage to load successfully.

MITA_DEFAULT_ERRORMSG_EN This variable is to hold the error message in the English language to be displayed to the user in case the page does not manage to load successfully.

The implementation of these five (5) variables is shown below.

10.2.2 Funtions

In the client side scripts of this template there are a number of functions which had to be implemented. 10.2.2.1 CSForm_OnLoad()

This function is to be called on the loading of the page. The first thing to be executed in this function is that if the form is to be published in HTML, then the black screen is to be called hence the navigation buttons are to be disabled until the page is fully loaded. Besides that the localisation of the language initially selected by the user is to be performed as well. Following that the JavaScript required files are to be loaded. The implementation of these statements is shown below.

}, {'radio':'radInternetBanking', 'control':'radInternetBanking_OnButtonClick()' } ];

Initialising the five (5) local variables dealing with the loading of the page var jsRetries = 0; var jsMaxRetries = 50; var isLoaded = false; var MITA_DEFAULT_ERRORMSG_MT = "Kien hemm problema waqt li l- pagna kient tiela"; var MITA_DEFAULT_ERRORMSG_EN = "An error occurred w hile the page was loading";


In order for the payment to be performed the user is to be presented with the amount to be paid. The amount stored is in Euro cents hence it needs to be multiplied by 100 to determine the Euro amount. Besides that the value of the lblPaymentMessage is to emptied while the Submit button is to be shown. The code implementation of these steps is shown below.

10.2.2.2 jsLoadedHook()

This function is to be check whether the external scripts have loaded by attempting to call external functions. It has a finite number of attempts before giving up. The first thing this function is to perform is to check whether the MITA Library and the MITA Payment Library have been loaded or not. This is implemented in the code below in a try catch statement.

Function CSForm_OnLoad (part 1) function CSForm_OnLoad() { try { if(CSForm.getPubType() == "HTML") { // disable navigation buttons until page is fully loaded. The navigation button will be automatically reenabled from the // external javascript MITALOGreyOutPage(true, {}, "Y", CSForm.getField("hdnLanguage").getValue()); //load MITA external javascript loadjsfile("../scripts/MITA/mita.v0.2.js"); setTimeout("jsLoadedHook();",200); }

Function CSForm_OnLoad (part 2) var amtDue = CSForm.getField("txtAmountDue").getVal ue() * 100; CSForm.getField("lblPaymentMessage").setValue(" "); CSForm.getField("btnSubmit").setHidden(false); } catch (e) { CSClient.alert(getDefaultErrorMessage(CSForm.getFie ld("hdnLanguage").getValue())); } }

Function jsLoadedHook (part 1) function jsLoadedHook() { if (isLoaded) return; try { if (mita.loaded() === false) throw "MITA library not fully loaded"; if (mitaPayment.loaded() === false) throw "MITA payment library not fully loaded" ; isLoaded = true;


If an error is caught, the jsRetries variable value is to be incremented while the JQuery would still be loading. If the maximum retries amount has not been reached, another attempt of loading would occur. In case the maximum retries amount has been reached, then the user is to be noted with a message that the page had not been loaded successfully hence he won’t wait indefinitely. This is implemented in the code below.

10.2.2.3 MITALOScriptCallExternalFunctionsOnLoad()

This function is to take care of calling any initialisation functions from the external script as required. In this function, first an array is to be initialised holding the payment message, the payment warning message and the form name. Then the external JavaScript function using the array declared is to be called to set the overflow. Following that the setting of the default selected payment is to be performed using the external JavaScript. The radio button options are to be repositioned on the page using a function from the external JavaScript. The implementation of this function is shown below.

// ca ll the function that will start setting the form en vironment by calling functions from the external javascript MITALOScriptCallExternalFunctionsOnLoad(); } catch (err) {

Function jsLoadedHook (part 2) // JQuery is still loading jsRetries += 1; // Check that the maximum retries have not been exceeded if (jsRetries < jsMaxRetries) { setTimeout("jsLoadedHook()", 200 * jsRetries) ; } else { // the applicant needs to be informed that th e page did not load rather than having him wait indefinately var dark=document.getElementById('MITADarke nScreenObject'); // Get the object. if (dark !== undefined) { var language = CSForm.getField('hdnLanguage ').getValue() || 'en'; var loading = dark.getElementsByTagName('im g'); loading[0].src = "/images/error.gif"; loading[0].alt = MITALODidNotLoadMsg[langua ge]; for (i = 0; i < dark.childNodes.length; i++ ) { if (dark.childNodes[i].nodeType === 3) { dark.childNodes[i].nodeValue = MITALODi dNotLoadMsg[language]; } } } } } }


10.2.2.4 loadcssfile(filename)

This function is to be used to add an external CSS file to the form. For more details please refer to the eForm Application Template document in section 10.1 Client-Side Scripts. 10.2.2.5 loadjsfile(filename)

This function is to be used to add an external JavaScript file to the form. For more details please refer to the eForm Application Template document in section 10.1 Client-Side Scripts. 10.2.2.6 radPayOnline_OnButtonClick()

This function is to be loaded whenever the Pay Online payment method is chosen. As soon as it is chosen by the user the option is set to the position value of the selected radio button. The value of the other radio buttons is set to 0. The implementation of this function is shown below.

10.2.2.7 radBankTransfer_OnButtonClick()

This function is to be loaded whenever the Bank Transfer payment method is chosen. As soon as it is chosen by the user the option is set to the position value of the selected radio button. The value of the other radio buttons is set to 0. The implementation of this function is shown below.

Function MITALOScriptCallExternalFunctionsOnLoad()

function MITALOScriptCallExternalFunctionsOnLoad() { // add multiline fields to this array in order to set their overflow to 'auto', i.e. their scroll bar will be visible only when required var arrayOfFields = ['lblPaymentMessage', 'lblP aymentWarning', 'lblFormName']; // call external javascript method using the ar ray declared above for setting the overflow mita.setOverflow(arrayOfFields, "auto"); // set default selected radio button mitaPayment.setDefaultSelectedPayment(paymentTy pes); // reposition radio button //mita.repositionRadioButtons(["radPayOnline","radB ankTransfer","radSendCheque","radInternetBanking"]); mitaPayment.repositionRadioButtons(paymentTypes ); }

Function radPayOnline_OnButtonClick() function radPayOnline_OnButtonClick() { ChangeOption(CSForm.getField("radPayOnline").getV alue()); CSForm.getField("radBankTransfer").setValue("0"); CSForm.getField("radSendCheque").setValue("0"); CSForm.getField("radInternetBanking").setValue("0 "); }

Function radBankTransfer_OnButtonClick() function radBankTransfer_OnButtonClick() { ChangeOption(CSForm.getField("radBankTransfer").g etValue());


10.2.2.8 radBankTransfer_OnButtonClick()

This function is to be loaded whenever the Bank Transfer payment method is chosen. As soon as it is chosen by the user the option is set to the position value of the selected radio button. The value of the other radio buttons is set to 0. The implementation of this function is shown below.

10.2.2.9 radSendCheque_OnButtonClick()

This function is to be loaded whenever the Send Cheque payment method is chosen. As soon as it is chosen by the user the option is set to the position value of the selected radio button. The value of the other radio buttons is set to 0. The implementation of this function is shown below.

10.2.2.10 radInternetBanking_OnButtonClick()

This function is to be loaded whenever the Internet Banking payment method is chosen. As soon as it is chosen by the user the option is set to the position value of the selected radio button. The value of the other radio buttons is set to 0. The implementation of this function is shown below.

CSForm.getField("radPayOnline").setValue("0"); CSForm.getField("radSendCheque").setValue("0"); CSForm.getField("radInternetBanking").setValue("0 "); }

Function radBankTransfer_OnButtonClick() function radBankTransfer_OnButtonClick() { ChangeOption(CSForm.getField("radBankTransfer").g etValue()); CSForm.getField("radPayOnline").setValue("0"); CSForm.getField("radSendCheque").setValue("0"); CSForm.getField("radInternetBanking").setValue("0 "); }

Function radSendCheque_OnButtonClick() function radSendCheque_OnButtonClick() { ChangeOption(CSForm.getField("radSendCheque").get Value()); CSForm.getField("radPayOnline").setValue("0"); CSForm.getField("radBankTransfer").setValue("0"); CSForm.getField("radInternetBanking").setValue("0 "); }

Function radInternetBanking_OnButtonClick() function radInternetBanking_OnButtonClick() { ChangeOption(CSForm.getField("radInternetBanking" ).getValue()); CSForm.getField("radPayOnline").setValue("0"); CSForm.getField("radBankTransfer").setValue("0"); CSForm.getField("radSendCheque").setValue("0"); }


10.2.2.11 ChangeOption(thevalue)

This function is to be called as soon as the user selects a radio button. The first thing to be performed by this function is to set the value of the hidden field hdnOptChosen to the value of the radio button as chosen by the user. According to which payment method is chosen, extra data needs to be further submitted by the applicant. For example if the payment is to be performed using a cheque the bank name and the cheque number are needed. For purpose two arrays had to be declared namely the hideFieldArray and the showFieldArray. The first array declared is to hold the textboxes and the corresponding labels which are not needed for the particular payment method. The second array declared is to hold the textboxes and the corresponding labels of the further data needed. Besides that the lblPaymentMessage and the lblPaymentWarning values are to emptied. The implementation of these stages is shown below.

The next step would be to determine the components to be put in the arrays according to the payment method chosen by the applicant. Following that the function togglePaymentOptions() is to be called to pass on the components specified to be shown or hidden on the page. These steps are repeated for the four (4) payment methods.

Function ChangeOption(thevalue) part 1 function ChangeOption(thevalue) { try { CSForm.getField("hdnOptChosen").setValue(theval ue); var hideFieldArray; var showFieldArray; CSForm.getField("lblPaymentMessage").setValue(" "); CSForm.getField("lblPaymentWarning").setValue(" ");

Function ChangeOption(thevalue) part 2 switch(thevalue) { case "1": // bank transfer hideFieldArray = ["txtPaymentChequeNo", "lb lPaymentChequeNo"]; showFieldArray = ["txtPaymentReferenceNo", "lblPaymentReferenceNo",

"txtPaymentClearingBank", "lbl PaymentClearingBank", "lblPaymentWarning"];

mitaPayment.togglePaymentOptions(hideFieldA rray, showFieldArray,

["txtPaymentReferenceNo", "txtPaymentClearingBank"] , ["txtPaymentChequeNo"], "lblPaymentWarning", localizedStrings["BankTransfer"][CSForm.getField("h dnLanguage").getValue()]);

break; case "2": // send cheque hideFieldArray = ["txtPaymentReferenceNo", "lblPaymentReferenceNo"]; showFieldArray = ["txtPaymentChequeNo", "lb lPaymentChequeNo",

"txtPaymentClearingBank", "lblPaymentClearingBank", "lblPaymentWarning"];


["txtPaymentChequeNo", "txtPaymentClearingBank"], ["txtPaymentReferenceNo"], "lblPaymentWarning", localizedStrings["SendCheque"][CSForm.getField("hdn Language").getValue()]);


10.2.2.12 CSForm_OnSubmit()

This function is to be called if the applicant is to opt to pay using MyBills. As soon as the user selects the Pay Online option the MyBills popup needs to be opened according to the URL found in the hdnPaymentURL hidden field. There might be the case that the MyBills popup would be blocked according to the internet browser settings. If this would be the case the user is to be notified hence will be able to allow popups. The implementation of this function is shown below.

break; case "3": //pay online hideFieldArray = ["txtPaymentReferenceNo", "lblPaymentReferenceNo",

"txtPaymentChequeNo", "lblPaymentChequeNo", "txtPaymentClearingBank", "lblPaymentClearingBank"] ;

mitaPayment.togglePaymentOptions(hideFieldA rray, showFieldArray, [],

["txtPaymentReferenceNo", "txtPaymentChequeNo", "txtPaymentClearingBank"], "lblPaymentMessage", localizedStrings["PayOnline"][CSForm.getField("hdnL anguage").getValue()]);

break; case "4": // internet banking hideFieldArray = ["txtPaymentChequeNo", "lb lPaymentChequeNo"]; showFieldArray = ["txtPaymentReferenceNo", "lblPaymentReferenceNo",

"txtPaymentClearingBank", "lbl PaymentClearingBank", "lblPaymentWarning"];


["txtPaymentReferenceNo", "txtPaymentClearingBank"] , ["txtPaymentChequeNo"], "lblPaymentWarning", localizedStrings["InternetBanking"][CSForm.getField ("hdnLanguage").getValue()]);

break; } } catch (e) { CSClient.alert(e.message); } }

Function CSForm_OnSubmit() function CSForm_OnSubmit() { if (CSForm.getField("hdnOptChosen").getValue() == = "3") { var newWin = window.open(CSForm.getField("hdnPa ymentURL").getValue()); if (newWin && newWin.top) { // popup has opened return true; } else { // popup has been blocked so we need to alert user CSClient.alert("The MyBills page has been blo cked by your popup blocker.");


10.2.2.13 getDefaultErrorMessage(lang)

The purpose of this function is to display the client-side error messages to the user. For more details please refer to the eForm Application Template document in section 10.1 Client-Side Scripts. 10.2.2.14 btnSubmit_OnClick()

This function is to be called upon final submission of the application. The purpose of this function is to validate the form before fully submitting it. This is due to the fact that if the form is not validated before submission, the payment would be written in the database without being validated by the process. The function called at this stage is the validationExecute() which is implemented in the external library. It is meant to return a popup in case of both successful or unsuccessful result upon validation. The implementation of these steps is shown below:

10.2.2.15 MITALOGreyOutPage(greyout, options, lockScrollbar, language)

This function is to take care of greying out the form of greying out the form on load to stop the user from using the form until all the scripts are loaded. For more details please refer to the eForm Application Template document in section 10.1 Client-Side Scripts.

return false; } } else { return true; } }

Function btnSubmit_OnClick() function btnSubmit_OnButtonClick() { try { // validate form before submitting... we need t o do this otherwise, we'll be

writing a payment in the // database before the form has been validated by the process mita.validationExecute({action: 'validate', sho wPopup:true,

displaySummary:false,submit:true}); } catch(err) { CSClient.alert(err.message); CSClient.alert(MITA_CUSTOM_SUBMITERROR); } }


11. Further Assistance

If you have a question about this eForms Component guide, or you encounter an issue, please

contact us on [email protected].

e-Forms Payment Template - MITA1 · Public eForms Payment Template 02. Scope This document...

Documents

Transcript of e-Forms Payment Template - MITA1 · Public eForms Payment Template 02. Scope This document...