Parent | Child | Previous | Next
 

Enter Code Control

Description

An interface for entering a two-factor authentication code that provides animated feedback when the code is incorrect.

Discussion

The Enter Code control prompts the user to enter a code with a fixed number of characters. The control displays a box for each character. Once the user has entered values into each of the boxes, the onComplete event fires, which you can use to validate the code and initiate the next step in the process.

Enter Code control
Enter Code control

The Enter Code control includes a "shake" behavior that is triggered using JavaScript. The shake behavior can be used to indicate the value in the Enter Code control is invalid -- a behavior often seen in systems that use two-factor authentication.

The Enter Code control shaking because an incorrect code was entered
If the user enters an invalid code, you can shake the control to alert the user that the code is invalid

To add an Enter Code control to your UX, select the [More...] button from the Data Controls toolbox.

Open the More controls dialog
Open the More controls dialog

Then select the EnterCode control.

Select EnterCode from the list
Select EnterCode from the list

Control Properties

Once you have added the control to your UX you can can configure it using the Control properties property.

Enter Code control properties
Enter Code control properties

Property
Description
Number of characters

The number of characters in the code. Default value is 6.

Allow digits

Whether the code can include numbers. Default value is checked.

Allow lowercase characters

Whether the code can include lower case letters. Default value is unchecked.

Allow uppercase characters

Whether the code can include upper case letters. Default value is unchecked.

Allow symbols

Whether the code can include symbols. Default value is unchecked.

ClassName

One or more CSS class names to apply to the data entry boxes. Default value is blank.

Style

In-line CSS styling for the data entry boxes. The default value is shown below.

outline:none;border: 1px solid #d7d3d3; border-radius: 4px; padding: 6px 0px;
Spacing between data entry boxes

Spacing between boxes in CSS units. Default value is 2px.

onComplete Function

Name of the Javascript function to call when the user has entered a value in every data entry box. Your JavaScript function must validate the code entered and perform all necessary actions to either indicate that the code is invalid or proceed to the next step in the process.

You can call the Enter Code control's shake() method to indicate the code is invalid. (See below)

Implementing the onComplete Function

When every data entry box has a value, the onComplete function is called. The onComplete function does the work of validating the value entered in the control to determine whether or not the code is valid. Validation may often occur server-side. To validate the code server-side, your JavaScript function needs to make an Ajax Callback. For example, the dataEntered() function shown below makes an Ajax Callback to an Xbasic function called "validateCode".

function dataEntered() { 
    {dialog.object}.ajaxCallback('','','validateCode')
}

The validateCode() function checks the submitted value of the "EnterCode" control against the expected value. In this example, the expected value is always the same -- "123456". If the value of the "EnterCode" control matches, JavaScript is returned to display a popup message. If the value doesn't match, it returns JavaScript to shake the "EnterCode" control.

function validateCode as c (e as p)
    ' Get the value for the Enter Code control named "EnterCode":
    dim codeSubmitted as c  = e.dataSubmitted.EnterCode
    dim js as c 

    if codeSubmitted = "123456" then 
        ' Code is valid. Display a popup message.
        js = "alert('code is valid');"
    else
        ' Code is invalid. Shake the EnterCode control.
        js = "var obj = {dialog.object}.getControl('EnterCode'); obj.shake();"
    end if 

    ' Return JavaScript to execute on the client
    return js

end function

The above example can be adapted to perform a more complicated check, such as validate a two-factor authentication code you sent to the user's device using another method. It can also be changed to do something, such as navigate to another .a5w page or panel, instead of displaying a JavaScript alert() if the validation succeeds.

Client-side Methods

In addition to the standard methods for working with Data Controls, you can use the below methods for the Enter Code JavaScript control object to manipulate the Enter Code control. Use {dialog.object}.getControl() to get the Enter Code control's JavaScript object:

shakeControlObj.shake()

Triggers the Enter Code control's shake animation. The shake animation is used to indicate the value is incorrect.

Videos

Using the Enter Code Control

A common design pattern when building applications that prompt the user to enter a two-factor authentication code (for example a login screen) is to provide data entry boxes for the user to type in the code. As the user types the code, focus is automatically moved to the next box. Once the user has typed in all of the characters in the code, an Ajax callback is made to the server to validate the code. If the code is not valid, the control shakes (thus giving feedback to the user that they have not entered a valid code).

In this video we show how an Enter Code control can be added to an UX component.

Download Component

2021-12-03

See Also