e-Forms Application Template - MITA1 · 2012-01-20 · Unclassified eForms Application Template 01....

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 Application Template

Date: 31/10/2011

Version: 0.1 Unit: eGov Architecture Department: eGov DEO

Unclassified

Unclassified eForms Application Template

Page i

Document Control Information

01. Document reference

eForms-TMP-Documentation-v0.1.doc

02. Document type

Procedure

03. Security classification

Unclassified

04. Synopsis

Document brief description

05. Document control

Author Change controller Distribution controller

Marquita Formosa <Enter Name> <Enter Position / Department>

<Enter Name and Position or Team>

This document may be viewed and/or downloaded from the IMS On-Line, which maintains the latest issues of all documents and forms.

06. Authorisation

Issuing authority Approval authority

Signature / Date Signature / Date

<Enter Name> <Enter Position / Department>

<Enter Name> <Enter Position / Department>

07. Modification history

Version Date Comments

Draft 0.1 31/10/2011 Draft version for internal review

Version 1.0 dd/mm/yyyy First version for release

08. Acknowledgements

09. References

10. Distribution list

<To be filled as applicable according to the security classification of the document / report>


Table of Contents

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

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

01. INTRODUCTION ..........................................................................................................................................................3

02. SCOPE .........................................................................................................................................................................4

03. DEFINITIONS ...............................................................................................................................................................5

04. NAMING CONVENTIONS ............................................................................................................................................6

04.1 FORM FIELDS .............................................................................................................................................................6 04.2 PAGES .......................................................................................................................................................................6 04.3 SIDE MENU BUTTONS .................................................................................................................................................7 04.4 PREVIOUS AND NEXT BUTTONS ...................................................................................................................................7 04.5 MENU SCROLL BUTTONS.............................................................................................................................................7 04.6 OTHER .......................................................................................................................................................................7

05. LAYOUT .......................................................................................................................................................................9

05.1 PROFILE FIELDS .........................................................................................................................................................9 05.2 PAGE LAYOUT ............................................................................................................................................................9 05.3 MENU STRUCTURE .....................................................................................................................................................9 05.4 PREVIOUS AND NEXT BUTTONS .................................................................................................................................10 05.5 SPECIFIC USES OF RECTANGLE OBJECTS ....................................................................................................................11 05.6 SPECIAL KEYS ..........................................................................................................................................................11 05.7 LIGHTBOX.................................................................................................................................................................12 05.8 ATTACHMENTS – CHANGED DIALOG............................................................................................................................12

05.8.1 Button Navigation ..........................................................................................................................................14 05.9 SIGNATURE ..............................................................................................................................................................15

06. REQUIRED HIDDEN FIELDS ....................................................................................................................................16

06.1 HIDDEN FIELDS IN THE MAIN FORM ............................................................................................................................16

07. LOCALISATION..........................................................................................................................................................18

07.1 LOCALISATION OF LABELS, DROPDOWN LISTS AND TABLES ...........................................................................................18 07.2 LOCALISATION OF BUTTONS ......................................................................................................................................18 07.3 LOCALISATION OF TOOLTIPS ......................................................................................................................................19 07.4 LOCALISATION OF IMAGES .........................................................................................................................................19

08. SCRIPTS ....................................................................................................................................................................20

08.1 MANDATORY FUNCTIONS - NOT TO BE AMENDED.........................................................................................................20 08.1.1 PDF Preview..................................................................................................................................................20 08.1.2 Black screen ..................................................................................................................................................20 08.1.3 Error message display...................................................................................................................................22 08.1.4 Initialising data using the Java Script ............................................................................................................23 08.1.5 Adding an external CSS file to the form ........................................................................................................24 08.1.6 Adding an external Java Script file to the form ..............................................................................................24 08.1.7 Dropdowns and Combo fields .......................................................................................................................25

08.1.7.1 Scenario 1: Country and town .....................................................................................................................................25 08.1.7.2 Scenario 2: Applicant Title...........................................................................................................................................26

08.2 EXPLANATION OF THE MAIN FUNCTIONS ......................................................................................................................28 08.2.1 Save ..............................................................................................................................................................28 08.2.2 PDF Preview..................................................................................................................................................28 08.2.3 Validation.......................................................................................................................................................29

09. ERROR LOGGING .....................................................................................................................................................31

09.1 SERVER-SIDE ERROR HANDLING ................................................................................................................................31 09.2 CLIENT-SIDE ERROR HANDLING ..................................................................................................................................32


10. MITA EXTERNAL JAVASCRIPT ................................................................................................................................33

10.1 CLIENT - SIDE SCRIPTS .............................................................................................................................................33 10.2 AVAILABLE SERVER - SIDE SCRIPTS...........................................................................................................................36 10.3 LOADING EXTERNAL SCRIPTS ....................................................................................................................................37

11. FURTHER ASSISTANCE...........................................................................................................................................39


01. Introduction

E-Forms are currently being implemented as part of the eGovernment Services. Each form is to own a number of pages while each page in the form template is to own a number of components. These components should be reusable in order for each page in the form to remain as consistent as possible and also to speed up the form creation process. This document highlights the common components and features and guides developers on how to use them within a context of creating a form using a standardized Application Template. These guidelines provide instructions, explanations as well as code snippets.


02. Scope

This document describes the e-Form application 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, the mandatory and the main functions for common components used within this template, both as 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.

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. Naming Conventions

The following naming convention is one of the building blocks on which the Application Form Template was built. In order to afford a certain degree of automation, the external components rely on the naming convention to distinguish between the different types of fields and handle each accordingly. For this reason, it is important to adhere to the naming convention described in the Naming Conventions Document and summarized below. In addition to this, some components must have a specific name, depending on the functionality. These will be highlighted further on in this section. 04.1 Form Fields

The naming convention set for the fields within an e-Form were initially set in order for the fields to be easily maintained when needed. All fields within the form should abide by this convention since Localization and other features, including Menu Navigation, depend on it. The following naming convention should be used when building fields within e-Forms.

<prefix ><field name > The prefix is a three character word which is meant to denote hence distinguish the type of control being used. One should note that the whole list of the prefixes to be used can be found in the Naming Conventions Document. The field name of a field must indicate the information the field it is to hold. Meaningful names are to be used while no use of underscores or special characters is to be present. Pascal Case is to be used when naming components. The linking between labels, the input fields (text fields, dropdowns/ lists, radio buttons, etc.) and tool tips is achieved by comparing the field names. If the field names (excluding the prefix) match, then these items are considered to be linked. The localization component will then use the field name to retrieve the label text value from the Parameter Store according to the language selected by the applicant. Similarly, the component will use the field name with a description suffix (_tooltip) to retrieve the tool tip from the Parameter Store. Hence the tool tip would be retrieved using <fieldname_tooltip> as the parameter name. More details about the abbreviations of the naming conventions within the templates are to be found in the Naming Conventions Document. 04.2 Pages

Pages within a form must also abide by the naming convention. The reason behind this is mainly to enhance the maintainability of the pages so that they could be easily identified when needed but also to allow for navigation buttons to be logically linked to the appropriate page. The following naming convention should be used when building pages within e-Forms.

<prefix ><page name > Every page must be prefixed with “pg ”. This is meant to denote hence distinguish pages from other controls being used. The page name should vary according to the purpose of the page. For instance, the Person Details page should be called pgPersonDetails.


The name given to the page should correspond to the field name (without prefix) given to the Menu button. The Menu buttons are those buttons found in the Side Menu of the template (under the section named Form Sections). Please refer to section 04.4 Side Menu Buttons to identify the naming convention of the Side Menu Buttons. 04.3 Side Menu Buttons

The Side Menu Buttons are to abide with a naming convention initially set. The button must be prefixed with “btn ”, as per naming convention. Furthermore, in order to enable navigation through the provided code, the following naming convention should be adopted.

<btnMenuPg><page number><page name> For example, the menu button on the first page of the form linking to the Person Details page would be named btnMenuPg1PersonDetails. Please note that the page name should correspond to the name of the page (sans prefix) given to the page you want this button to access. 04.4 Previous and Next Buttons

The naming convention of the previous and next buttons should be as follows: btnPrevButtonPg<the page number> for previous buttons e.g. btnPrevButtonPg1 btnNextButtonPg<the page number> for next buttons e.g. btnNextButtonPg1 These two buttons should be present in each page of the form accordingly. They should be named according to the naming convention stated in section 04.2 Pages. . 04.5 Menu Scroll Buttons

Should a form require more than the standard 15 buttons, two special scroll/ paging buttons, which would usually not appear on the form, will become visible. This is described in more detail in section 05.3 Menu Structure. The menu paging controls have to adhere to the following naming convention:

<btnMenuScroll><direction><Pg><page number> For instance, the buttons on the first page of the form would be named as follows: btnMenuScrollUpPg1 (for the button used for paging upwards) btnMenuScrollDownPg1 (for the button used for paging downwards) 04.6 Other

The template sports two specifically used rectangle objects. The Liquid Office designer does not allow you to change the names of rectangle objects, but rather, it assigns to them a default name, such as Rectangle_1. In the case of the Helper Rectangle and the Button Highlight, described in section 05.5 Special uses for Rectangle Objects, we have given these objects specific names in order to be able to tie some specific functionality to them.


The Help Rectangle should be specifically named RectHelperBackground while the Button Highlight should be named RectBtnBackground. In order to use these rectangles on next pages, please copy and paste existing object from the template in order to maintain correct naming.


05. Layout

05.1 Profile Fields

When a user logs on in order to fill in a form using one’s e-id some fields will have their initial value pre-filled from the user’s profile. These pre-filled fields are the user’s name, surname, id number, language of choice and so on. Please note that for an unauthenticated user, the values of the mentioned fields cannot be pre-filled from the profile. The values in these fields would be the name of the profile field so some attention needs to be given when handling these fields.

05.2 Page Layout

Each and every form is to be set to paged rather than continuous. Navigation through these pages can be carried out in two ways. The first option would be by using the Menu buttons on the left side of the page which can be seen in the page below. The other option available is to use the Previous and Next buttons situated at the bottom of the page as shown in the figure below. 05.3 Menu Structure

Each e-Form template offers a menu structure consisting of 15 buttons on each page of the form. Not all buttons will be in use. Any button which does not have any text after being localized will automatically be disabled. The navigation code for the menu buttons was made generic so each button will own same code. Please note that the following code should be included in every Menu button onButtonClick() code, except for buttons which handle the Attachment Page. This calls a function which is readily provided in the template and which shouldn’t be altered.


The MITALOScriptGotoMenuPage() function essentially calls an external JavaScript function to take care of displaying the required page and handle any error, should there be any. This functionality should work out of the box, provided that the page and menu buttons were named as specified.

Menu Button onClick() Code function btnMenuPg1About_OnButtonClick() { MITALOScriptGotoMenuPage(CSEvent.getTarget().getName()); }

Should a form require more than the standard 15 buttons, button paging in the menu structure is supported. In such a case, the “additional buttons” should be superimposed on the standard buttons. The template will then automatically display an “up” and a “down” button beneath the menu. These buttons will take care of paging the menu items. Below one is to find how the “up” and “down” buttons will look like. The onClick() operation of these buttons should call the MITALOScriptScrollUp() function from paging upwards or the MITALOScriptScrollDown() function for paging downwards. These two functions call functions provided in the external JavaScript to handle the paging of the menu buttons, and handle any errors which might occur. The onClick() operations for paging upwards and downwards are to be found below. This code should be inserted in the scroll buttons located on every page.

Scroll Page Up onClick() Code function btnMenuScrollUpPg1_OnButtonClick() { MITALOScriptScrollUp(); }

Scroll Page Down onClick() Code function btnMenuScrollDownPg1_OnButtonClick() { MITALOScriptScrollDown(); }

05.4 Previous and Next Buttons

The previous and next buttons images as used in the HTML are to be loaded dynamically depending upon the localization. Provided that the buttons are correctly named, the correct and localized image will be automatically loaded according to the language initially chosen by the user. With regards to the code, the navigation of the pages was designed to be generic, so when creating a new page, provided that the specified naming convention is followed, the navigation can be catered for with a single line of code as shown below.

Previous Button onClick() code function btnPrevButtonPg1_OnButtonClick() { if (isLoaded) mita.gotoPreviousPage(); }


Next Button onClick() code function btnNextButtonPg1_OnButtonClick() { if (isLoaded) mita.gotoNextPage(); }

The external JavaScript should automatically detect which is the current page and which is the previous and next page. No special consideration should be given when the next or previous page is the attachment page. Although the attachment page is handled in a different way from the other page, the caller code remains the same. Please refer to section 04.4 Previous and Next Buttons in the Naming Convention section for more details on how these buttons should be named. 05.5 Specific uses of rectangle objects

Each page found in each eForm is to contain two specific uses for rectangle objects: • Help Box • Button Highlight. The Help Rectangle, specifically named RectHelperBackground should be placed on the right-hand side of the form, in the help section. The template will then automatically take care of formatting this box’s colour to give it a gradient shade. This rectangle is to hold information with regards to the data to be entered by the user. The data held is meant to guide the applicant throughout the filling of the application. The data in this rectangle is to be loaded dynamically according to the data which is needed to be filled in by the user. Please note that when creating a new help box one should either copy this rectangle from another page or else find it in the Custom Field Gallery in order to ensure that the naming remains constant. The Button Highlight is a special rectangle which is to be set behind the button that denotes the current page, e.g. when viewing the “About” page, the “About the Form” button should be highlighted. Like the Help Rectangle, this is specifically named; RectBtnBackground. The following is an example of the Button Highlight. The Button Highlight is blue by default. However, please do not attempt to change the colour of this rectangle from the form itself as this is overridden by the external JavaScript and doing so would be futile. The reason why the control of the button colour is kept in the external JavaScript is simple. Firstly, the forms need to be standardised and hence, having differently coloured highlight buttons would defeat the purpose. Secondly, because of the previously described menu paging mechanism, the external script needs to be able to switch the colour of the rectangle as is required. Basically, upon turning a menu page, the colour of the rectangle will automatically switch to white. Upon turning back to the page which contains the button corresponding to the current page, the colour will automatically be reverted to blue. 05.6 Special Keys

Provider Key At the top right corner of the first page of the template there is a hidden Provider Key which shouldn’t be left empty. The developer is expected to fill out this field with the provider key which shall be


provided to him as an identity. If this field is left empty, a warning message will be displayed as soon as the form is loaded, informing the user/ developer that this field was left empty. In the following figure one is to see how this message box is to appear. Process Name Like the Provider Key, the Process Name must also be given a default value when the form is created. Unlike the Provider Key, the Process Name field is hidden. To view and edit it, click on the Field List tab in the Form Designer in order to get a list of available fields. Check the “Show hidden fields” check box to display the hidden fields. Locate the hdnProcessName field, right click and open the Properties. You can then insert the initial value. Failure to fill in the process name will result in a message box opening up on load reminding you to insert this each and every time the form is loaded. 05.7 Lightbox

This template supports the use of inline frames and Light Box features through the use of Fancybox and JQuery. Fancybox is currently being used for three things:

• Loading the Attachment page • Displaying modal confirmation boxes • Displaying the Validation Summary

For these three functions, all the code is currently implemented in the external JavaScript. Hence, no additional code or considerations needs to be undertaken in the form other than the calling code for opening the attachment page and, in specific cases, for triggering validation.

05.8 Attachments – changed dialog

Each application might need some attachments in order for its process to begin. The template caters for two types of attachments; attachments when the user is authenticated and attachments when the user is unauthenticated. The difference between the two types of attachment pages is as follows. For authenticated users, the attachment page will be loaded as a separate asp page within an iframe. This custom attachment page will inform the user which attachments are required. When the user is not authenticated, this custom page cannot be used since it requires a session, which an unauthenticated user would not have. In this case, the default LiquidOffice attachment page will be used. However, if the user is an authenticated user, the Attachment Page will open up in a Lightbox as shown below. Once the attachments are attached, the Lightbox can be closed by clicking on the close button (X) on the upper right corner of the Lightbox.


Once the Lightbox is closed, control should be returned to the main form. For an unauthenticated user, the attachment page within the form should be displayed. This page should tell the user which documents are expected to be attached. A button should allow the user to go to the LO attachment page (the one seen below).

The Attach button in the above diagram should have the following code implemented.


Anonymous Attach onClick() Code // When the user is Anonymous, clicking on this but ton will redirect him to the LO Attachment //form. This button should not be displayed if the user is logged in. function btnAttach_OnButtonClick() { // set the next page in the hidden field so that when we come back from the attachments page // we know where to go CSForm.getField("hdnReturnFromAttachmentPage").se tValue(CSExt.VisiblePage + 1); // call function to redirect to generic attachmen t page cs_ManageAttachments('/lfserver'); }

When using the LiquidOffice default Attachment Page, there are two disadvantages.

1. The user can attach any document he wants. There is very little control over which document is which.

2. When going back to the form, by default the form takes you back to the first page. The first line of code displayed above caters for the second issue. Before being redirected to the Attachments page, the next page to display when we come back is stored in a hidden field. When the form is reloaded after returning from the attachment page, the common components automatically search for that hidden field and redirect the user to the specified page.

05.8.1 Button Navigation

When the user is to request to go to the attachments page the MITALOScriptGotoAttachmentPage(CSEvent.getTarget(). getName()); method is to be executed. The following code is the code which is to be run if the user is on page 1 i.e. the About Page. Please note that the navigation of the buttons on the other pages is to be amended as requested.

Menu Attachment button onClick() Code

function btnMenuPg1Attachments_OnButtonClick() { MITALOScriptGotoAttachmentPage(CSEvent.getTarget( ).getName()); }

The method to be executed can be found in the external JavaScript. It is meant to check the user login whether the user is unauthenticated or not. Following that the method is to execute accordingly. The method is implemented as shown in the code below.


Attachment client-side script

function MITALOScriptGotoAttachmentPage(target) { try { mita.showAttachmentPageFromMenu(target); } catch(err) { CSClient.alert(MITA_CUSTOM_CALLINGEXTERNALERROR) ; } }

05.9 Signature

When it comes to signing the form, the template implements the LiquidOffice default Signature control. The signature on the template is configured to validate all the input fields before allowing the user to sign. After a form is signed, all the fields other than the navigation buttons are locked. Please note that any control which you do not want to be locked needs to be explicitly set in the Signature’s properties. Although this is the suggested best practice, should a form require the signature to behave in a different manner, this can be modified easily since it uses default LiquidOffice behaviour. There were two modifications made to the Signature.

1. The signature uses the validation engine created by MITA as the primary validation method. It still validates the fields using the LiquidOffice mechanism as secondary validation methods.

2. Each form, on submit, checks whether the form has been signed and allows the user to be redirected to the signature page.

With regards to the first point, this is done automatically and there is no need to add any additional code. For the second point, however, the following code needs to be added to the client-side submit button click. The code, in this case, calls an external function to check whether the form was signed. If it wasn’t, a validation summary will tell you that the form was not signed. The summary will also provide a link to the signature control.

Client-side Submit onClick() code

function btnSubmitForm_OnButtonClick() { try { if (isLoaded) { // first we need to check whether the form wa s saved mita.submitFormValidateSignature("sigSignatur e"); } } catch(err) { CSClient.alert(MITA_CUSTOM_SUBMITERROR); } }


06. Required Hidden Fields

06.1 Hidden Fields in the Main Form

Hidden Field Name

Description

Initial Value

hdnApplicantType Used to determine whether the form is being filled in by the applicant himself, by a professional on behalf of the applicant, by an agent on behalf of the applicant, etc..

hdnLoginType Used to distinguish between the different groups of users in the AD (ex: eID, CORP, LO, ..)

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

hdnEmailAddress Used to store the contact email address (as stored in the Service Property table)

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

hdnAmountDue Stores the amount due, to be used in the payment form later on in the process

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

hdnThankYouPage Stores thank you page URL Should be mapped to ‘_IISThankYouPageURL’ profile field

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

hdnRole applicant/approving officer Initial value should be set to ‘A’ hdnStage Attachment Stage Initial value should be set to ‘A’ hdnURLAttach Stores attachments URL Should be mapped to

‘_IISAttachmentURL’ profile field hdnUsernameAttach Stores attachment username hdnSessionAttach Stores attachment session ID 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

hdnProviderKey Stores the provider key of the form’s provider

Should be set to the supplied provider key

hdnInvalidFields Stores the list of invalid fields along with the localized error message.

This field is automatically populated using the Validation Task.


hdnReserved01 Hidden field reserved for future requirements















hdnAutoSaveInterval Hidden field containing the time interval for the AutoSave functionality

hdnPDFPath Hidden field containing the name of the PDF file generated for preview

hdnReturnFromAttachmentPage

Hidden field containing the page index of the page following the Attachments page

1

hdnLastCommentToUser

Hidden Field containing the last comment sent by the approval authority to the user

hdnFormVersionNo Hidden Field containing the Form’s Version No.

1.0


07. Localisation

The form template caters for Maltese and English. The form is loaded according to the language set in the user’s profile. The user should be able to set this by selecting the language on the eForms portal. Hence, the language field initial value takes that of the profile field. 07.1 Localisation of labels, dropdown lists and tables

Field titles cannot be localized, so, in order to simplify the localization aspect of the form, which is to make most of the localization happen on the server-side, the titles were removed. The labels were created using read-only text fields. Please note that the Localization Field object can be found in the Designer’s Custom Gallery . In order for the system to distinguish the labels from the normal text fields, the labels were prefixed with “lbl” while the text fields were prefixed with “txt”. For details please refer to section 04.1 Form Fields. The common library allows you to localize a form from the server-side just by calling the function below. This method should be called at form loading time. Localization.internationalizeForm(CSForm);

Localization of both dynamic and static dropdowns is also handled through this function call. However, there are some settings which need to be applied on the template. Static dropdowns are the easiest to configure. The Display name entered in the list will be used as the localization key for the retrieval of the localized value from the Parameter Store. Dynamic lists work a bit differently. The tables which should be configured should cater for both Maltese and English, together with a default value. The Maltese field name should be suffixed by _MT while the English field name should be suffixed by _EN. The following is an example.

Default Field Name Maltese Field name English Field Name countryValue countryValue_MT countryValue_EN

The list should be configured to use the default value. The system will then load either the Maltese or the English version according to the user’s selected language at loading time. If the field is not found, then the default field is loaded. The configuration of the localization controls is explained in more detail in the Internationalization Developer’s Guide document. With regards to tables, the localization component supports only static tables. 07.2 Localisation of Buttons

Following the language chosen by the user as preferred language; the buttons are loaded and localized. This is to be done by the MITA External JavaScript which is meant to take care of loading the external localised version of the buttons according to the language needed. Provided that the text was entered in the Parameter Store following the defined naming convention, these should be automatically loaded with no extra effort. For more details please refer to the localisation document named e-Forms Internationalisation.


07.3 Localisation of tooltips

Follow the naming convention relating to fields and their tooltips together with the language chosen by the user; the MITA external JavaScript will take care of loading the localized version of the tooltips. 07.4 Localisation of images

Should an image need to be localized, then there are two ways to go about resolving the situation:

a.) Use DOM from the client-side to change the image b.) Allow the localization component to change this

For automatically localizing images, create the images as image buttons. Prefix the buttons with “img” and suffix them with the language code. Superimpose the images so that one is exactly on top of the other. Let the Localization component do the work at load time. Please note, however, that on some browsers you might need to change the CSS style on the button to remove the shading and borders of the image. You can do this by retrieving the button by name using DOM and then setting the "buttonNoBorder" CSS class provided in the MITA CSS for this purpose.


08. Scripts

08.1 Mandatory Functions - Not to be amended

08.1.1 PDF Preview

This function is meant to allow the user to see the application in PDF format. Once the user submits the application a popup will appear asking the user whether he wants to Open, Save or Cancel. The open option allows the user to view the application in PDF format while the save option allows the user to save the application in PDF format on one’s machine for later reference.

08.1.2 Black screen

This function is meant to black out (and lock) the screen as soon as the form starts loading. This is important due to the fact that the user shouldn’t be allowed to click buttons or enter data while the form is still loading. During the time in which the screen is blacked out, external scripts are loaded and the localisation and other important fundamental functions are carried out in the background.

The following code is found in the internal scripts and is to cater for this function.


Code for blacking out the page on load

// this function takes care of blacking out the scr een (or remove blackout) while the form is //loading function MITALOGreyOutPage(greyout, options, lockSc rollbar, language) { // Pass true to gray out screen, false to ungray // options are optional. This is a JSON object with the following (optional) properties // opacity:0-100 // Lower number = less grayout higher = more of a blackout // zindex: # // HTML elements with a h igher zindex appear on top of the gray out // bgcolor: (#xxxxxx) // Standard RGB Hex col or code // grayOut(true, {'zindex':'50', 'bgcolor':'#000 0FF', 'opacity':'70'}); // Because options is JSON opacity/zindex/bgcolo r are all optional and can appear // in any order. Pass only the properties you n eed to set. var options = options || {}; var zindex = options.zindex || 50; var opacity = options.opacity || 90; var opaque = (opacity / 100); var bgcolor = options.bgcolor || '#000000'; var dark=document.getElementById('MITADarkenScre enObject'); if (!dark) { // The dark layer doesn't exist, it's never be en created. So we'll // create it here and apply some basic styles. var tbody = document.getElementsByTagName("bod y")[0]; var tnode = document.createElement('div'); // Create the layer. tnode.style.position='absolute'; // Position absolutely tnode.style.top='0px'; // In the top tnode.style.left='0px'; // Left corner of the page tnode.style.width='100%'; tnode.style.height='100%'; tnode.style.paddingTop = "200px"; tnode.style.overflow='hidden'; // Try to avoid making scroll bars tnode.style.display='none'; // Start out Hidden tnode.style.color = "white"; tnode.style.fontFamily = "Tahoma"; tnode.style.fontSize = "20px" tnode.id='MITADarkenScreenObject'; // Name it so we can find it later tbody.appendChild(tnode); // Add it to the web page dark=document.getElementById('MITADarkenScreen Object'); // Get the object. var msg = MITALOLoadingMsg[language]; var txtNode = document.createTextNode(msg); var br = document.createElement('br'); var loading = document.createElement('img'); loading.border = '0px'; loading.align = 'middle'; loading.src = '/scripts/images/loading.gif' loading.alt = msg dark.appendChild(loading); dark.appendChild(br); dark.appendChild(br); dark.appendChild(txtNode); } if (greyout) { // Calculate the page width and height if( document.body && ( document.body.scrollWid th || document.body.scrollHeight ) ) { var pageWidth = document.body.scrollWidth+ 'px'; var pageHeight = document.body.scrollHeigh t+'px'; } else if( document.body.offsetWidth ) { var pageWidth = document.body.offsetWidth+'p x'; var pageHeight = document.body.offsetHeight+ 'px'; }


else { var pageWidth='100%'; var pageHeight='100%'; } //set the shader to cover the entire page and make it visible. dark.style.opacity=opaque; dark.style.MozOpacity=opaque; dark.style.filter='alpha(opacity='+opacity+')' ; dark.style.zIndex=zindex; dark.style.backgroundColor=bgcolor; dark.style.width= pageWidth; dark.style.height= pageHeight; dark.style.display='block'; if(lockScrollbar === 'Y') document.body.style.overflow = 'hidden'; } else { dark.style.display='none'; document.body.style.overflow = 'auto'; } }

Please do note that the function to go back to the regular screen is to be found in the external script. Should an error occur and the processing cannot continue, the message on the black screen will change informing the user that an error occurred and that he should refresh the page or abort. 08.1.3 Error message display

Errors might occur unexpectedly, which is why it is important that these are correctly handled. The getDefaultErrorMessage(lang) function takes care of displaying the default error message to the user should an error occur before the form is localised. This ensures that the user will see an error message in his language of choice. Error messages are customised and localised according to the error itself in the external JavaScript. Please note that if the error message required is not available due to an error in the external JavaScript then a default message should be displayed.

Code for displaying Default Error Messages from the Form’s Client-Side Script

// this function takes care of displaying the error message. If the error message required is // not available due to an error in the external ja vascript, then it displays the default // message. function getDefaultErrorMessage(lang) { var message; if ((lang !== undefined) &&(lang !== "") && (la ng.length > 0)) { message = eval("MITA_DEFAULT_ERRORMSG_" + lan g.toUpperCase()); } else { message = MITA_DEFAULT_ERRORMSG_EN; } return message; }


08.1.4 Initialising data using the Java Script

The function MITALOScriptCallExternalFunctionsOnLoad() is to be called when data is initialised using the external JavaScript. When the function is called, functions from the external JavaScript are to be called. This function might cause an error since the functions it might not be executed successfully hence the function would be needed to be called again. Each function is called from the JavaScript more than once and it has a number of retries for how many times it can be called. Hence when the function is to be called again, a check is to be made to verify whether the number of tries has been exceeded or not; if not the function is to retry calling the function again.

Code for initialising data using the external Java Script from the Form’s Client-Side Script function MITALOScriptCallExternalFunctionsOnLoad() { trace("MITALOScriptCallExternalFunctionsOnLoad( )"); try { // set a hook for automatically refreshing dr opdowns in order not to require the user to // remove focus from the dropdown before the onchange method is triggered mita.setBlurOnChange(["ddlAppCorrCountry", "d dlAppCountry", "ddlAppTtl"]); // initialize signature field mita.initializeSignature("sigSignature"); // add multiline fields to this array in orde r to set their overflow to 'auto', i.e. // their scroll bar will be visible only when required var arrayOfFields = ['lblDescOfActivityDtls', 'lblInfoOnAppText', 'lblSignatureDisclaimer' , 'lblSaveFormInst', 'lblSubmitFormInst', 'lblWithdrawInst', 'lblA lsoSigned', 'lblSignatureSubmitInst', 'lblDateLastSaved', 'lbl DateLastSaved_1', 'lblDateLastSaved_2', 'lblDateLastSaved_3', 'l blFormName', 'lblFormName_1', 'lblFormName_2', 'lblFor mName_3', 'lblAttachmentTypeDesc_1', 'lblAttachmentTypeDesc_2 ', 'txtLastCommentToUser', 'txtExternalRemarksH', ' lblFormTtlAbout', 'lblFormTitlePersonalDtl s', 'lblFormTitleAttachments', 'lblFormTitleSignature', 'lblFormTitleComments','lblFormTtlSubmit', 'lblFormName_7', 'lblDat eLastSaved_6', 'lblFormName_5', 'lblDateLastSaved_4']; // call external javascript method using the array declared above for setting the // overflow mita.setOverflow(arrayOfFields, "auto"); // set Malta as the default selected dropdown value // but check whether they don't already have a value selected first if (CSForm.getField("hdnProcessStatus").getVa lue() === "Fill" || CSForm.getField("hdnProcessStatus").getVa lue() === "") { if (CSForm.getField("lblDateLastSaved").g etValue().length <= 0) { mita.setDefaultOption("ddlAppCountry", "Malta"); mita.setDefaultOption("ddlAppCorrCountr y", "Malta"); mita.switchVisibilityOfTextAndListUsing Default(CSForm.getField("ddlAppCountry"), "ddlAppTown", "txtAppTown", "malta"); mita.switchVisibilityOfTextAndListUsing Default( CS Form.getField("ddlAppCorrCountry"), "d dlAppCorrTown", "txtAppCorrTown", "malta"); } } // populate the email address for the compete nt authority from the hidden field and // format the email field button to display a ppropriately mita.setupEmailField('btnCAEmail', 'hdnEmailA ddress'); // call this method to determine whether to d isplay the first page or whether to display // the last page we were on before going to t he attachment page mita.checkReturnFromAttachment(); //setup auto save


mita.setupAutoSave(); } catch (err) { CSClient.alert(err.message); trace("MITALOScriptCallExternalFunctionsOnLoa d() Exception"); trace(err); } }

08.1.5 Adding an external CSS file to the form

This function allows you to add external CSS files to the respective form. As seen in the function code below first all the initial essential attributes of a CSS file should be inserted. Finally if the file is found and is recognised as a CSS file, the file is to be added to the form as necessary.

Code for adding an external CSS file to the form

function loadcssfile(filename) { try { var fileref=document.createElement("link"); fileref.setAttribute("rel", "stylesheet"); fileref.setAttribute("type", "text/css"); fileref.setAttribute("href", filename); if (typeof fileref!="undefined") { document.getElementsByTagName("head")[0].appe ndChild(fileref); } } catch(err) { CSClient.alert(err.message); CSClient.alert(MITA_CUSTOM_LOADEXTERNALERROR); } }

08.1.6 Adding an external Java Script file to the form

This function is used to add a external Java Script files to the respective form. This function should always be used, at least once; in order to load the MITA provided external JavaScript which automated the template.

Code for adding an external JavaScript file to the form

function loadjsfile(filename) { try { var fileref=document.createElement('script'); if (typeof fileref!="undefined") { var headID = document.getElementsByTagName("h ead")[0]; fileref.type = 'text/javascript'; fileref.src = filename; //add script to page header headID.appendChild(fileref); return fileref; } }


catch (err) { CSClient.alert(err.message); CSClient.alert(MITA_CUSTOM_LOADEXTERNALERROR); } }

08.1.7 Dropdowns and Combo fields

In the Personal Details page of each e-Form a number of dropdown lists are needed. For instance, there are to be used for the user to select the Applicant’s country and town. Most often, when using dropdown lists, the contents of the list are either retrieved from a fixed list or else from a datasource in the database. However, there are circumstances where the complete list is not known, such as the Applicant’s town when the country is not Malta. At this point, the user will have to decide. What data he needs to input. In the template, this can be implemented in one of two ways. Either use a combination of dropdowns and text input fields as in Scenario 1 below, or else use Combo boxes as in Scenario 2. 08.1.7.1 Scenario 1: Country and town

These two dropdown lists are to be needed to complete the Permanent Address and the Correspondence Address sections. These were implemented using two different cases in points. The first case in point would be that of a user who permanently reside in Malta. In this case the list of the Maltese towns is to be loaded automatically in a dropdown list for the user to select as shown in the figure below.

The second case would be that the applicant is to reside permanently in a foreign country. In this case the town field would change to a text field which would let the user to type in the residing town as shown in the figure below.

The implementation code below shows how this is to be implemented. Please note that on initialisation the default value of the country is set to “Malta” while the Maltese towns are to be shown


in a combo box. When the function below is called it is to check whether the country chosen is still the default value. If it changed the text field will be shown instead of the combo box. This function is to be implemented both in the Permanent Address section and the Correspondence Address section.

Code for manipulating the town field. // On change function for the applicant country dro pdown. When the country is set to malta, the town dropdown is enabled. // Otherwise, the town can only be entered as text. function ddlAppCountry_OnChange() { try { mita.switchVisibilityOfTextAndListUsingDefault( CSForm.getField("ddlAppCountry"), "ddlAppTown", "txtAppTown", "malta"); } catch(err) { CSClient.alert(MITA_CUSTOM_LOADERROR); } }

Please note that the default value of the dropdown list holding the countries can change but this is not recommended since this e-Gov facility has been created first and foremost to cater for the Maltese citizens. 08.1.7.2 Scenario 2: Applicant Title

This dropdown list is needed to give the possibility to the user to choose the title. Different titles are given as options for the user to choose. The Applicant title dropdown list was implemented to mimic the behaviour of a combo box. Although Liquid Office supports out-of-the-box use of combo boxes, these cannot be easily localized on the fly. For this reason, the dropdown list can be manipulated in order to behave list a combo box, as described below. If the applicant’s title is not found on the list, the applicant can choose the “[Other…]” option as shown in the figure below.


The option for adding [Select One] and [Other…] or their localized version is carried out on the server-side javascript. On Open, the addDropdownOptions can be called stating the form and dropdown to use. Boolean flags can be used to select whether to show the [Select One], the [Other…], and whether to set [Select One] as the default value.

Code for inserting “[Select One]” and “[Other…]” in the Title dropdown list // populate other options in the dropdown list ("Se lect One" and "Other") Localization.addDropdownOptions(CSForm, CSForm.getF ield("ddlAppTtl"), true, true, refresh);

In the case that the user chooses the [Other…] option, the applicant is to be given the possibility to enter another title hence a text field is to appear as shown below. This functionality is handled using three (3) functions found in the client-side scripts. The first function is the OnChange() function which is to be executed whenever a value in the dropdown list is selected. If the [Other…] option is chosen, the text field becomes visible, superimposing the dropdown list. Once txt field loses focus, such as when the user inserts a value and than tabs out, the text field will once again become hidden and the dropdown list becomes visible again, displaying the new value. This function is implemented in the code below.

Code for showing the text field in case the [Other… ] option is chosen.

// this function sets the selected value in the tit le text field. It also checks whether the // text field is hidden. If it isn't then the focus is set on it. The user should then either // add a new value (added to the list onBlur) or le ave it empty. function ddlAppTtl_OnChange() { mita.setValueInTextbox("txtAppTtl", CSForm.getField(CSEvent.g etTarget().getName()).getValue()); }

Please note that whenever the applicant enters another value for the title field and opts to save the application, the value of the text field should also be saved. This needs to be done so that when the user reopens the form, the value he has inserted will be once again populated in the list. For this reason, the value selected in the dropdown list, will always be saved in the equivalent textbox. The next function to be implemented is the OnFocus() for the text field. This function is to empty the text field from any other saved titles previously inserted by the user to prepare it for the user’s input. This function is implemented in the code below.

Code for erase any data previously saved in the tex t field. // this function clears out the title text, prepari ng it for user input. function txtAppTtl_OnFocus() { // clear entry CSForm.getField(CSEvent.getTarget().getName()).se tValue(""); }


The last function to be implemented is the OnBlur() function on the text box. This function puts the value inserted by the user in the dropdown list. This is triggered when the field loses focus, such as when the user tabs out. If the text field is left empty by the user, then the dropdown list will be once again displayed with no additional entry being inserted. This function is implemented in the code below.

Code for inputting another value in the combo box. // code for allowing a localized "add other" to the drop down list. This function allows the // user to add a new item to the list function txtAppTtl_OnBlur() { // we need to add the content of the text box to the title dropdown list. Then we need to // select the new entry in the dropdown list and clear the txtAppTtl field mita.addNewItemToListFromTextbox(CSEvent.getTarge t().getName(), "ddlAppTtl"); }

Please note that the text field described above is a hidden field which, in the designer, superimposes the dropdown list. The visibility of the textbox is set conditionally. The text box only becomes available when the selected value is either “[Other…]” or “[Ieħor…]”. This condition is set through the expression builder in the LiquidOffice Designer.

Expression controlling Visibility of the Title text box

[ddlAppTtl] != "[Other...]" and [ddlAppTtl] != "[Ieħor...]" 08.2 Explanation of the main functions

08.2.1 Save

This button’s main purpose is to save the e-form on which the user is to apply for the government service needed. This enables the user to save the application while still remaining on the form. The user should be allowed to both save and continue manually and to set an auto save that will be triggered at specific time interval. The reasoning behind this functionality is that a form might take a long time to complete and the user might, for some reason, be distracted from completing the form before his session expires. In such cases, we do not want the user to lose all his work. It gives the possibility to the user to go back to the application, if his session expires, and still find his form in the inbox. A thing to be noted is that while the application is saved in full, the attachments will not be saved so when the user goes back to the form, he will need to upload the attachments again. This enhancement is considered to be implemented in the future. 08.2.2 PDF Preview

The PDF Preview should allow the user to open the form in its PDF format. Data that he has inserted in the form but has not yet saved should also be populated in the PDF Preview. The Open PDF works in the following manner: A button click triggers a call to the server-side scripting to generate a PDF and return the name of the pdf. The client then triggers a request to the PDFPreview servlet in order to open/ save the PDF file. Buttons used for opening the PDF should call the LO Client-side method pdfPreview() .


Code for generating a PDF File for Preview

function pdfPreview(target) { try { mita.previewPDF(target); } catch(err) { CSClient.alert(MITA_CUSTOM_CALLINGEXTERNALERROR ); } }

On the server-side, the LO server-side method getPDFFileName() should be modified in order to cater for the call triggered by the pdfPreview() function. The getPDFFileName() function accepts 4 parameters:

• the form • the html document within the form • the name of the PDF template to load • the path location in which the PDF template is published

This function needs to be modified in order for the developer to be able to load his data in the required PDF file.

Code for obtaining the function of the PDF File gen erated on Preview

function getPDFFileName() { var path = FormUtils.getPDFFile(CSForm, CSDoc, "M ITAeFormsPDFTemplate", "Forms"); if (path !== "") { CSForm.getField("hdnPDFPath").setValue(path); } }

08.2.3 Validation

Validation within e-Forms plays an important role hence several validation controls are to be used. An XML schema is to be used to implement the validations so that a form validation rule set will be created. With the new validation engine, validation messages will be bubbles on the invalid field rather than the default LO dialog boxes.


An alternate display of the validation errors is the Validation summary, shown below. The validation summary is triggered when the whole form is validated on signing and on submit. The summary will display a list of fields which are invalid. Clicking on the provided link will take the user to the page on which the error exists.

There are three places where these validations will be triggered:

1.) On tab out of a field, the field is immediately validated. Ignoring an error message will still allow the user to continue to insert data in the form.

2.) On Signing the whole form is validated. The form will not allow the user to sign until the

validation is successful.

3.) After submission, the form is once again validated, this time from the server side to insure that the validation was completed and that the validation was not bypassed.

Please note that the field validations have to be configured per form in the parameter store. For further validation details and for detail on how to build the configuration XML please take a look at the eForms Validation document.


09. Error Logging

By error logging one means the logging of the full error including the stack trace at the point of origin as an internal exception. This facilitates the search for similar internal errors when one would have met the same internal (non-Java Script) error before. Please note that this is not just a one step action. In fact one should also log the full details of the error occurred even the second time one meets this error since at that point in time one would be able to provide more information with regards to the error occurred. For this reason the e-Forms Logger Component has been created. The steps how to install this component are found in the Logger Document. This component is meant to be a guide for the developers and administrators who are to be assigned to log the errors occurred. 09.1 Server-side error handling

When handling exceptions with regards to server-side exceptions one should note that Java Script is able to support the use of the try-catch blocks as well as the use of multiple catch blocks within the same try. The code below shows a try-catch surrounding the call to the intitializeForm() method. function CSForm_OnOpen() { try { initializeForm(); } catch (e) { // call the script error handling method serverErrorHandler(e); } }

Error handling mechanisms are needed to an extent that if more than one instance is present on the server-side script one would need to repeat the error handling code each time when needed. Hence a separate method was created called the serverErrorHandler . For further details please refer to the Error Handling Document. One should note that as stated in the document previously mentioned, being an error which is a wrapped Java Exception the Logger will have to be called from within the custom component in order to parse the error in order to pass on the proper error message to the JavaScript. This would lead to another benefit since if the error is thrown from Java Script then no parsing is to be needed. The code below is to determine all the steps carried out in the case of an error to be thrown. function serverErrorHandler(error) { // we need to log this error and then display a message to the user var processName = CSForm.getField("hdnProcessNam e").getValue(); var providerKey = CSForm.getField("hdnProviderKe y").getValue(); Logger.error(providerKey, processName, error.mes sage, error, Logger.DetailLevel.HIGH); CSForm.setStatusMsg(error.message); }


09.2 Client-side error handling

One should note that handling an error on the client-side, the Logger component cannot be implemented. Hence a simple error message is to be reported to the user as shown in the figure below. function CSForm_OnLoad() { try { MITALOScriptLoadForm(); } catch (e) { // Tell the user that an error has occurred CSClient.alert(getDefaultErrorMessage(lang)); } } Please refer to the Error Handling Document for more details.


10. MITA External Javascript

10.1 Client - Side Scripts

The following is a list of functions which are within the LiquidOffice client-side scripts.

Script Name

Can Modify Parameters Required Description

MITALOScriptLoadForm() No Takes care of calling methods

for greying out the screen and loading the external javascript.

MITALOScriptScrollDown(); No

Takes care of calling external functions for scrolling the Menu downwards and handling external errors accordingly.

MITALOScriptScrollUp(); No

Takes care of calling external functions for scrolling the Menu upwards and handling external errors accordingly.

MITALOScriptGotoMenuPage() No

Target button name Takes care of calling external functions in order to navigate to a required Form Page using the menu.

MITALOScriptGotoAttachmentPage() No

Target button name Takes care of calling external functions in order to navigate to the attachments page using the menu.

MITALOScriptSaveForLater() No

Takes care of calling the external save function for saving the form for later and handles errors accordingly.

MITALOScriptCallExternalFunctionsOnLoad() Yes

Takes care of calling any initialization functions from the external script as required.

MITALOGreyOutPage() No

Boolean (whether or not to grey out), JSON options, Boolean (whether to lock Scrollbar), String (user’s selected language)

Takes care of greying out the form on load to stop the user from using the form until all the scripts are loaded.

pdfPreview No

Target button name Calls the relevant external function for displaying the PDF preview.

jsLoadedHook No

Checks whether the external scripts have loaded by attempting to call external methods. It has a finite number of attempts before giving up.

getDefaultErrorMessage No

Displays the client-side error messages to the user.


loadcssfile No

CSS file name Function for adding an external CSS file to the form

loadjsfile No

Javascript file name function for adding an external javascript file to the form

The following is a list of external functions called from the client-side LO scripts. Please note that these methods cannot be modified by the developer.

Script Name

Parameters Required Description

mita.setListSelectionInTextBox();

String textbox name String dropdown list name

This sets the selection of the dropdown list in the corresponding text box.

mita.gotoNextPage();

To be used when the user requests to go to the next page of the application.

mita.gotoPreviousPage();

To be used when the user requests to go to the previous page of the application.

mita.saveAndExit(); Triggers the standard LO save and exist mechanism

mita.submitFormValidateSignature()

String Signature field name

Checks whether the signature field was filled in, i.e. whether the form was signed

mita.withdrawForm()

Triggers the standard LO cancel mechanism

mita.switchVisibilityOfTextAndListUsingDefault()

Field for controlling dropdown list String field name of dependant list String field name for dependant text field String deciding value

Used when a dropdown list decides whether a dependant field is displayed as a text field or as a dropdown list. The deciding value decides whether the dependant dropdown should be displayed (if the selected value on the controlling dropdown is the same as the deciding value) or whether the text field should be used.

mita.doMailTo() String Form Title String email set in hidden field

Opens the default mail client in another window in order to send an email to the Competent Authority.

mita.addNewItemToListFromTextbox()

String Target control name String Drop down list name

Used to add the content of the text box to the dropdown list. Then we need to select the new entry in the dropdown list and clear the text field. This is used primarily to mimic the behaviour of a combo box.


mita.setValueInTextbox()

String textbox name

String Target dropdown list name

This function sets the selected value in the text field. It also checks whether the text field is hidden. If it isn't, then the focus is set on it. The user should then either add a new value (added to the list onBlur) or leave it empty. This is used primarily to mimic the behaviour of a combo box.

mita.setBlurOnChange()

An array of drop down list names to which the hook should

be applied.

Sets a hook for automatically refreshing dropdowns in order not to require the user to remove focus from the dropdown before the onchange method is triggered.

mita.initializeSignature() String Signature field name Initializes the Signature in order for this to use the new validation engine

mita.setOverflow()

Array of Field names for which the overflow should be modified

String overflow style

Sets the overflow of the specified multiline field. It is suggested that this is set to “auto”.

mita.setDefaultOption()

String Drop down list name String Default value

To be used to set the selected value of a dropdown list to the default value

mita.setupEmailField() String Button name String Hidden field

Populates the email address for the competent authority from the hidden field and format the email field button to display appropriately

mita.checkReturnFromAttachment()

Call this method to determine whether to display the first page or whether to display the last page we were on before going to the attachment page

mita.setupAutoSave();

The form is being auto saved at particular time intervals. This function is to be called on form initialization to setup the autosave functionality.

mita.previewPDF() String target button name

This function calls the server in order to generate the pdf file for preview. Then it attempts to open the file using the file name returned by the server.

mita.loaded()

Checks whether the MITA external files were loaded

mita.showNextMenuControls()

To be used to show the Next button when needed for each page accordingly.

mita.showPrevControls()

To be used to show the Previous when needed for each page accordingly.

mita.navigateMenuUsingButtons()

Target

To be used to navigate pages using menu buttons.

mita.showAttachmentPageFromMenu() Target

Takes care of correctly opening up the Attachment page.


10.2 Available Server - Side Scripts

The following are the most common component functions which need to be called from the server-side LO script.

Script Name

Required Parameters

Description

Logger.error();

Provider key Process name error message exception Logger.Detail Level

Logs an error in the error log.

FormUtils.populateNonStandardInputInList()

String text field name, String dropdown list name Form

Populate non-standard text from a text field in a dropdown list.

FormUtils.checkAttachmentsUploaded()

Form Connect Agent name

This function checks whether all expected attachment uploads were attached for an authenticated user.

FormUtils.populateLoginInfo()

Form, Server, String Login Name Field String Login Date Field String Form Name field

Populates the login data, date and form name on all pages of the form

FormUtils.setDateInField()

Form String Date Received field

Populates the fields starting with the specified string with the current date.

FormUtils.setDateLastSaved()

Form, String Date Last Saved field name with no prefix

Saves the date when the form was last saved and populates it on all pages of the form.

FormUtils.ifEIDSetReadOnly()

Form Array of field name which need to be locked when the user logs in using an EID account

Checks whether the user is currently logged in with an EID account and locks the relevant fields if he is.

FormUtils.initializeForm()

Form, Server, Boolean set Auto Save, String Connect Agent Name

Initialize the form and performs the localization.

FormUtils.saveForm

Form DOM Document String Date Last Saved field name (without prefix)

Saves the current form in the user’s inbox.


FormUtils.getPDFFile()

Form DOM Document String name of PDF template String path where PDF template is published

Generates a flat PDF from the current form and returns the location of the file.

Localization.internationalize()

String Parameter Key, String language code, String provider key, String process name

Localizes the given parameter key in the specified language

Localization.addDropdownOptions();

Form, dropdown list, Boolean insert “Select One”, Boolean insert “Other”, Boolean refresh list

Inserts additional options to the dropdown list ("Select One" and "Other")

Localization.storeLocalizedFields()

Form

Store the names of the fields that were already localized.

10.3 Loading External Scripts

In order to execute a method from the external Java Script, the Java Script itself needs to be loaded. The function to load the Java Script is to be called from the CSForm_OnLoad() method which is the initial method to be run when the user requests to view the eForm. The code below shows the statements used to load the external Java Script. //load MITA external javascript loadjsfile("../scripts/MITA/mita.v0.2.js"); setTimeout("jsLoadedHook()", 200);

The code below is the code implemented in the method jsLoadedHook(). This method is to be used to load external Java Script using hooks. The variables used in this method are the global variables noted below var jsRetries = 0; var jsMaxRetries = 50; var isLoaded = false;

function jsLoadedHook() { if (isLoaded) return; try { if (mita.loaded() === false)


throw "MITA library not fully loaded"; isLoaded = true; // call the function that will start setting th e form environment by calling // functions from the external javascript MITALOScriptCallExternalFunctionsOnLoad(); } catch (err) { // 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 // Get the object. var dark=document.getElementById('MITADarkenS creenObject'); 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]; } } } } } }

The maximum number of attempts for the loading of the Java Script file is 50. In case of no loading to occur, the form won’t be loaded hence the black screen is to remain active.


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 Application Template - MITA1 · 2012-01-20 · Unclassified eForms Application Template 01....

Documents

Transcript of e-Forms Application Template - MITA1 · 2012-01-20 · Unclassified eForms Application Template 01....