Country Select

This component can be found under the Sybrin.Identity namespace and is called CountrySelectComponent.

Full name: Sybrin.Identity.CountrySelectComponent.

It is a component that provides basic country selection functionality in the form of a simple UI. The Web SDK requires a country code for data extraction and it's recommended that you use this component to obtain said country code.

With default styling, the country select component appears as follows:

Country Select Component

The "Next" button will remain disabled until a country has been selected. Selection is confirmed upon clicking the "Next" button and then the onCountrySelected event will fire.

Initialization

The country select component can be initialized using the following code:

HTML

<div id='country-select'></div>

JavaScript

// Option 1: Passing an id
var component = new Sybrin.Identity.CountrySelectComponent({ 
    id: 'country-select'
});

// Option 2: Passing a DOM element
var element = document.getElementById('country-select');
var component = new Sybrin.identity.CountrySelectComponent({ 
    element: element
});

component.initialize();

The Sybrin Web SDK provides the option to either pass down the ID of the element you wish to use for component initialization, or to pass the element directly.

Please note that 'country-select' is just an example in this context and the ID may be changed as desired as long as it matches the value passed down during component initialization in JavaScript.

During initialization, the country select component allows for a number of configuration options that may be passed down using an object literal. The parameters that may be used on the object include the following:

Required:

• id (string): ID of the element you wish to use for component initialization. Not required if element is passed.

• element (HTMLElement): Element you wish to use for component initialization. Not required if id is passed.

Optional:

• defaultCountry (string): The country code of the country that must be selected by default.

• documentTypeName (string): The document type name to filter country selection by. If a document type name is passed down, only countries that support the specified document type will be shown. Please see document type overrides & filtering for a list of accepted values.

• countries (Sybrin.Identity.Country[]): Explicit country filter. Please see country overrides & filtering for details.

• translations ({ [key: string]: string }): An object literal representing a dictionary lookup that will be used for translating the component. Please see the translations section on this page for a list of all translatable text, as well as the localization page for a detailed description on how to implement localization.

Warning: Initialization will fail if the intended host element does not exist yet.

Always ensure that the initialize function is only called after the DOM is loaded.

Country Overrides & Filtering

When creating an instance of the country select component, the SDK allows for a documentTypeNamestring parameter, which will be used to filter countries based on the document type. Additionally, the SDK allows for a countries parameter which can be used for more specific override options. The countries parameter is a collection of Sybrin.Identity.Country where each instance has the properties code, name and enabled.

• code (string): The unique identifier (Alpha-3 standard country code) used to target a country to override.

• name (string): Can be used to override the display name of the targeted country.

• enabled (boolean): Can be used to filter out the targeted country (if set to false)

Supported country codes are:

• Ghana: 'GHA'

• Kenya: 'KEN'

• Malawi: 'MWI'

• Mozambique: 'MOZ'

• South Africa: 'ZAF'

• Uganda: 'UGA'

• United States of America: 'USA'

• Zimbabwe: 'ZWE'

• Other: 'GEN'

Advanced filtering and override example:

JavaScript

var component = new Sybrin.Identity.CountrySelectComponent({
    id: 'viewport',
    documentTypeName: 'idcard',
    countries: [
        new Sybrin.Identity.Country({ code: 'ZAF', name: 'Southern Africa' }),
        new Sybrin.Identity.Country({ code: 'UGA', enabled: false })
    ]
});

By specifying documentTypeName as 'idcard', it will only show countries that support the ID Card document type. The first country instance in the countries collection overrides 'ZAF', which is South Africa, to display as Southern Africa instead. The second instance filters 'UGA', which is Uganda, out so that it doesn't appear as part of the list even though the Ugandan ID Card document type is supported.

Destruction

The country select component may be removed from the UI by calling the destroy() function on it.

Example:

component.destroy();

Functions

Initialize

initialize(): void

Initializes the component's DOM and events.

Destroy

destroy(): void

Destroys the component's DOM and events.

Set Translations

setTranslations(translations?: { [key: string]: string; }): void

Changes the component's translations to the provided values and updates the DOM accordingly.

Events

The country select component offers one event for reacting to country selection. To hook onto the event, simply assign a function to it.

The following option is available:

• onCountrySelected(alpha3Code: string, alpha2Code: string, numericCode: string)

On Country Selected

This function is called when a country is selected. To hook onto the event, you may use the following code:

component.onCountrySelected = function(alpha3Code, alpha2Code, numericCode) {
    console.log('The selected country Alpha-3 code is: ', alpha3Code);
    console.log('The selected country Alpha-2 code is: ', alpha2Code);
    console.log('The selected country numeric code is: ', numericCode);
}

The alpha3Code, alpha2Code and numericCode parameters are all of type string.

Styling

The country select component is structured a follows:

<div class="sybrin-identity-container sybrin-sdk-container">
    <div class="sybrin-identity-component-section sybrin-sdk-component-section">
        <div class="sybrin-identity-list sybrin-sdk-list sybrin-custom-scrollbar">
            <div class="sybrin-identity-card sybrin-sdk-card sybrin-country-KEN">
                <div class="sybrin-identity-card-image">
                    <img src="data:image/png;charset=utf-8;base64,">
                </div>
                <div class="sybrin-identity-text sy-i-translation-20">
                    Kenya
                </div>
            </div>
        </div>
    </div>
    <div class="sybrin-identity-button-section sybrin-sdk-button-section">
        <button disabled="disabled" class="sybrin-identity-next sybrin-identity-flow-button sybrin-sdk-flow-button sy-i-translation-28">Next</button>
    </div>
</div>

The classes and elements specified above may be used to freely style the country select component as desired. To do so, simply create a stylesheet and include it in the project, then style according to the above classes and elements.

The element with the sybrin-identity-card class repeats for every country option. The above example only uses Kenya as an example, however the same element would repeat for each country option in the list, using the relevant country code for the CSS class and the relevant country name in the display text.

Styling implementation example:

HTML

index.html

<html>
<head>
    <link rel="stylesheet" type="text/css" href="styles.css" media="screen"/>
</head>
<body>
    <div id='component'></div>
</body>
</html>

CSS

styles.css

.sybrin-identity-flow-button {
    background: #963296;
    border: 2px solid #963296;
}

.sybrin-identity-selected {
    background-color: #963296;
    box-shadow: none;
}

Before Styling

After Styling

Translations

This component is affected by the following translation keys:

Translation Key	Description	Default/Source
sy-i-translation-19	Display name for Ghana	Ghana
sy-i-translation-20	Display name for Kenya	Kenya
sy-i-translation-21	Display name for Malawi	Malawi
sy-i-translation-22	Display for Mozambique	Mozambique
sy-i-translation-23	Display name for Philippines	Philippines
sy-i-translation-24	Display name for South Africa	South Africa
sy-i-translation-25	Display name for Uganda	Uganda
sy-i-translation-26	Display name for Zimbabwe	Zimbabwe
sy-i-translation-27	Display name for other	Any other country
sy-i-translation-28	Caption of the button that proceeds to the next step	Next
sy-i-translation-86	Display name for United States of America	United States of America