Postal Address

Overview

The Postal Address is a component that provides input fields to enter and validate the address information. The address information includes the address lines, city, state, country, and postal code.

The Postal Address component provides the following customizations for the developer.

• Hide one or more fields at design time for different flows. For example, while implementing the Domestic Beneficiary functional flow, the component can hide all the fields except for Address Line 1 and City, and for the International Beneficiary functional flow, the developer can customize the component to display all the fields.
• Set different sets of mandatory or optional fields for other flows. For example, for the Same Bank Transfer functional flow, all the fields in the component can be marked as optional, and while implementing the International Beneficiary functional flow, Address Line 1, City, Postal Code, and Country fields can be made as mandatory.
• Configure the maximum length for the different input fields. For example, a developer can set the maximum length of the City field as 30 and the Postal Code field as 10.

NOTE: The Postal Address component is used inside the Mobile Banking application.

Postal Address Contracts

The Postal Address component provides the contracts given below.

• Service Parameters
• Data Mapping
• Data Formatting
• Conditional Mapping Key
• Conditional Mapping
• Address
• Country and State Selector
• Keyword Search In DropDown
• onError Event
• onTextEntered Event
• setContext Method

Service Parameters

The Service Parameters contract of the Postal Address component sets the service details to configure the two APIs: GetAllCountries and GetAllRegions. These APIs retrieve the content for the drop-down list of countries and states. The developer cannot modify these APIs but can change the parameters used inside the Service Parameter contract.

Here is a sample of the JSON object provided in the Service Parameter of the Postal Address component.

{
	"GetAllCountries": {
		"ServiceType": "customverb",
		"Service": "RBObjects",
		"Object": "Country",
		"Verb": "getAllCountries",
		"Criteria": {}
	},
	"GetAllRegions": {
		"ServiceType": "customverb",
		"Service": "RBObjects",
		"Object": "States",
		"Verb": "getAllRegions",
		"Criteria": {}
	}
}

The Service Parameter contract provides the following key-value pairs for customization.

Data Mapping

The Data Mapping contract of the Postal Address component maps the widget IDs with the data to be displayed. The component retrieves the data for mapping from Context Data Object or Service response.

The Data Mapping contracts provide keys for every input field in the component. The keys in the Data Mapping contract corresponding to each field are AddressLine1, AddressLine2, AddressLine3, AddressLine4, City, Country, State, and PostalCode. The name of these keys is not modifiable. But a developer can modify the values assigned to each key as per requirement.

The Postal Address component provides four fields to configure Address Lines. To disable an Address Line field, a developer can remove the key corresponding to the field from the Data Mapping contract.

Here is a sample of the JSON object provided in the Data Mapping of the Postal Address component.

{
	"AddressLine1": {
		"placeholder": "${i18n{i18n.common.addressLine1}}",
		"maxTextLength": 35,
		"restrictCharSet": "&^%$#@",
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryAddressLine1Msg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthAddressLine1Msg}}"
	},
	"AddressLine2": {
		"placeholder": "${i18n{i18n.common.addressLine2}}",
		"maxTextLength": 35,
		"restrictCharSet": "^&%$#@",
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryAddressLine2Msg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthAddressLine2Msg}}"
	},
	"AddressLine3": {
		"placeholder": "${i18n{i18n.common.addressLine3}}",
		"maxTextLength": 35,
		"restrictCharSet": "^&%$#@",
		"mandatoryValidation": {
			"isMandatory": "false",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryAddressLine3Msg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthAddressLine3Msg}}"
	},
	"City": {
		"placeholder": "${i18n{i18n.common.cityWithColon}}",
		"maxTextLength": 35,
		"restrictCharSet": "^&%$#@",
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryCityMsg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthCityMsg}}"
	},
	"Country": {
		"placeholder": "${i18n{i18n.common.countryWithColon}}",
		"maxTextLength": 35,
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryCountryMsg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthCountryMsg}}"
	},
	"State": {
		"placeholder": "${i18n{i18n.common.stateWithColon}}",
		"maxTextLength": 35,
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryStateMsg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthStateMsg}}"
	},
	"PostalCode": {
		"placeholder": "${i18n{i18n.common.postalCodeWithColon}}",
		"maxTextLength": 35,
		"restrictCharSet": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
		"mandatoryValidation": {
			"isMandatory": "true",
			"mandatoryMsg": "${i18n{i18n.common.mandatoryPostalCodeMsg}}"
		},
		"characterLimitExceedMsg": "${i18n{i18n.common.lengthPostalCodeMsg}}"
	}
}

Every key/field in the Data Mapping contract is assigned a JSON object with the following key-value pairs.

Data Formatting

Data formatting property adds a new formatting type or overrides an existing formatting type in the default JSON format.

By default, the Postal Address component does not contain any value for this key.

{}

Conditional Mapping Key

The Conditional Mapping Key is used to define mapping based on a criterion. The property specifies the value for performing the conditional data mapping check.

By default, the Postal Address component does not contain any value for this key.

""

Conditional Mapping

The Conditional Mapping property key maps the widget with data from Collection Object or service response as per the Conditional Mapping key.

By default, the Postal Address component does not contain any customization for this key.

{}

Address

The Address group contains contracts specific to the Postal Address component that sets the UI (text and widgets) for entering the address. The Address group of the Postal Address component contains the following contracts.

• Display Title
• Address Title
• Widget Type for Country and State
• Selected Country Value Configuration in Dropdown
• Selected State Value Configuration in Dropdown
• FilteredStateValueConfiguration

Display Title

This field enables and disables the header of the component. If the value of this field is true/ On, the component displays the header. If the value of this field is false/ Off, the component does not display the header.

Address Title

This field provides the header text of the component.

${i18n{i18n.common.addressDetails}}

Widget Type for Country and State

This field sets the type of widget that the user can use to select the State and Country of the Address.

Selected Country Value Configuration in Dropdown

This contract and the Data Mapping (Country) contract map the values from the DropDown component for the Country field to the corresponding Label widget for display.

{
	"Name": "${countryMasterData.lblOption}",
	"Code": "${countryMasterData.countryCode}"
}

Selected State Value Configuration in Dropdown

This contract and the Data Mapping (State) contract map the values from the drop-down component for the State field to the corresponding Label widget for display.

${stateMasterData.lblOption}

FilteredStateValueConfiguration

The Postal Address component updates the State field as per the user-selected value in the Country field. When the user selects a Country, the application retrieves an array containing the names of all the states for filtering. This service response from the back-end is usually in the form of a JSON object or an array of JSON objects.

For example, if the Service Parameter uses the objectName object State API call, the FilteredStateValueConfiguration contract assigns the following values.

• To assign an array of records, provide the value: ${Collection.objectName}.
• To assign an object containing the key value for filtering, provide the value: ${Collection.objectName.arrayKeyName}.

${Collection.States}

Country and State Selector

The Country and State Selector group contain contracts to set the content for the State and Country drop-down lists. This group comprises of the following contracts.

• Row Template
• Selected Row Template
• Header Template
• Dropdown DataMapping
• Height Of Dropdown
• Default Placeholder Config

Row Template

The Row Template contract sets the Segment row template for the drop-down lists in the component.

A developer can set the value for this contract in two formats.

• String Format: The dynamic row template ID in a String format. For example: flxTempSort7, where flxTempSort7 is the row template ID.
• JSON Format: This format supports inter-app access while using composite apps. The developer must provide both the Microapp Name and the template ID as a JSON object in this format.

{
	"templateID": "flxTempSort7",
	"microAppName": "ResourcesMA"
}

Selected Row Template

The Selected Row Template contract sets the Segment row template for the row selected by the user.

A developer can set the value for this contract in two formats.

• String Format: The dynamic row template ID in a String format. For example: flxTempSort1, where flxTempSort1 is the row template ID.
• JSON Format: This format supports inter-app access while using composite apps. The developer must provide both the Microapp Name and the template ID as a JSON object in this format.

{
	"templateID": "flxTempSort1",
	"microAppName": "ResourcesMA"
}

Header Template

The Header Template contract sets the section header template for the drop-down lists in the component.

A developer can set the value for this contract in two formats.

• String Format: The dynamic row template ID is provided in a String format. For example: flxTempDropdown1, where flxTempDropdown1 is the template ID.
• JSON Format: This format supports inter-app access while using composite apps. The developer must provide both the Microapp Name and the template ID as a JSON object in this format.

{
	"templateID": "flxTempDropdown1",
	"microAppName": "ResourcesMA"
}

Dropdown DataMapping

This field maps the UI elements for the Country and State drop-down lists.

{
	"Country": {
		"mainHeaderTitle": {
			"lblDropdownHeaderTitle": "Country"
		},
		"segDropdown": {
			"segmentMasterData": "${CNTX.records}",
			"segmentUI": {
				"sectionHeader": [{
					"groupingParam": {
						"sectionHeaderTitle": "Please select a country code"
					},
					"lblDropdownSectionTitle": "Please select a country code"
				}],
				"segmentRowData": {
					"lblCountry": "${segmentMasterData.Name}",
					"countryCode": "${segmentMasterData.Code}"
				}
			}
		}
	},
	"State": {
		"mainHeaderTitle": {
			"lblDropdownHeaderTitle": "State"
		},
		"segDropdown": {
			"segmentMasterData": "${CNTX}",
			"segmentUI": {
				"sectionHeader": [{
					"groupingParam": {
						"sectionHeaderTitle": "Please select a State"
					},
					"lblDropdownSectionTitle": "Please select a State"
				}],
				"segmentRowData": {
					"lblCountry": "${segmentMasterData.Name}",
					"stateCode": "${segmentMasterData.id}"
				}
			}
		}
	}
}
	

Important Considerations

To map data with the widgets inside the segmentUI key, a developer must follow any of these formats.

• To map a plain string, provide the text in the String format. For example, follow the format given below to map a text with the lblCountry Label.
  

  "lblCountry": "Country Name"

• To map an i18n value, provide the i18n key in a String format. For example, follow this format to map the lblCountry Label with the i18n key for Amount.
  

  "lblCountry": "${i18n{i18n.common.countryCode}}"

• To map a context or a collection object, provide the value in a String format. In the following example, the lblCountry Label is mapped to the Account Type data retrieved from the Context Data Object.
  

  "lblCountry": "${segmentMasterData.countryName}"

• While designing a new template, follow proper widget naming conventions. For example, the name of a Label widget must start with lbl, and the name of an Image widget must start with img.

Height Of Dropdown

This contract configures how the drop-down lists appear on the screen.

Full Screen

Default Placeholder Config

This contract configures the default placeholders for the Country and State drop-down lists.

{
	"countryDefaultPlaceholder": "Select a country",
	"stateDefaultPlaceholder": "Select a state"
}

Keyword Search In DropDown

The Postal Address component uses the Keyword Search component as a child component. The Keyword Search In DropDown group in the Postal Address component provides fields to customize this child component. It contains the following contracts.

• Enable Search In DropDown
• Keyword Search DataMapping

Enable Search In DropDown

This contract enables the search functionality in the Country and State drop-down lists.

true/false

Keyword Search DataMapping

This field is applicable only if the value of Enable Search In DropDown contract is true. The Keyword Search DataMapping contract maps the UI elements in the Keyword Search component with data.

{
	"Country": {
		"txtSearchBox": {
			"placeholder": "Search Country",
			"restrictChar": "#@",
			"maxCharacters": "10",
			"rightPaddinginDP": "80",
			"skins": {
				"focus": "flxWhitePrimary500S",
				"regular": "flxWhiteGrey200S"
			}
		},
		"btnCancel": {
			"text": "Cancel"
		}
	},
	"State": {
		"txtSearchBox": {
			"placeholder": "Search State",
			"restrictChar": "#@",
			"maxCharacters": "10",
			"rightPaddinginDP": "80",
			"skins": {
				"focus": "flxWhitePrimary500S",
				"regular": "flxWhiteGrey200S"
			}
		},
		"btnCancel": {
			"text": "Cancel"
		}
	}
}

onError Event

The OnError event handles any error that occurs during the user journey. The onError passes an error object to the parent widget containing the information about the error and where it had happened.

var errordata = {
	"level": "ComponentViewController",
	"method": "setWidgetTemplate",
	"error": err
};
this.onError(errordata);

onTextEntered Event

This event is triggered when the user enters the data in the input field.

this.onTextEntered(data);

setContext Method

This method must be invoked from the parent component or form controller. This method passes data between the parent and component.

this.view.postaladdress.setContext(contextData);

Context Object

A context object is a JSON object used to pass the data required for the component. The context variable helps the component get the data using the following parameters.

• AddressLine1
• AddressLine2
• City
• Country
• State
• PostalCode

NOTE: A developer can modify the values assigned to these keys but cannot change the name of these keys.

Here is a sample of the Context JSON Object used inside the component.

var contextData = {
	"AddressLine1": "This is addressline 1",
	"AddressLine2": "This is addressline 2",
	"City": "This is City",
	"Country": "Afghanistan",
	"State": "Balkh",
	"PostalCode": "6789835"
};