Animated Text Field

Animated Text Field

Asset Version: 1.0.0
  • Version 1.0.0
Last Published: Apr 11, 2017 By: Kony Team
51 0 0 8
Energize your textboxes using this bigger and better version. The animated textboxes component creates better user interactions, giving superior quality to your application, right out of the box. Labels for text entry fields can be animated thereby creating enhanced user experience for the end user. This also enables greater visibility for the label, which makes the data entry operation seamless. This component can be used in almost any situation where some kind of data entry is involved.

Requirements

  • Visualizer Enterprise
 

Devices

 

Platforms

Features

  • Text box with animation to placeholder text when user taps it
  • Advanced and intuitive UI element for mobile apps
  • Enhanced user experience and interaction
  • Useful component as a data entry field.

Platforms Supported

  • Android Phone Native
  • iPhone Native

Prerequisites

  • Kony account
  • Kony Visualizer Enterprise
  • A Kony Reference Architecture app created in Kony Visualizer

The Animated Text field component is a custom widget that consists of a TextBox widget with a placeholder text. The behavior of the component is: when a user clicks or taps the text box, the placeholder text moves up with an animation and points the text cursor in the text box, which indicates the user to type text.

Here is a use case that describes the use of the Animation Text Field component.

Use Case

Consider a case that you are developing a registration form, which is one of the screens in your mobile app. In the registration form, you can use the Animated Text Field component for all data entry fields to enhance the user experience.

Animated Text field is a ready-to-use component. You can import the Animated Text field component into your app (created in Kony Visualizer) and use the component where ever required. The Animated Text Field component also facilitates a set of properties, events, and APIs that helps you customize the text box, animation, and the functionality.

The following sections help you use the Animated Text field component in your app.

Prerequisites

Before you start using the Animated Text Field component, ensure you have the following:

  1. Kony account
  2. Kony Visualizer 7.3
  3. A Kony Reference Architecture app in Visualizer. You can create a Kony Reference Architecture app in Visualizer using the following procedure:
    1. Open Kony Visualizer.
    2. On the File Menu, click New Project. The New Project dialog appears.
    3. In the Project Name box, type a name for your project.
    4. Select Kony Reference Architecture, and click Create.

Importing the Animated Text Field Component

Before you start importing the component to Kony Visualizer, you must download the component from the Kony Marketplace website. You can import the marketplace components only into the apps that are of the Kony Reference Architecture type.

To import the Animated Text Field component, do the following:

  1. Open your app project in Kony Visualizer.
  2. In the Project Explorer, click the context menu arrow of KonyLibrary, and then click Import Library. The Open dialog appears.
  3. Navigate to the location where you downloaded the component (zip file) on your computer, select the component, and click Open. In the Collections library, you will see a new component added.

When you import a component, the component is imported to Visualizer's workspace, but not directly into your app. Thus, after you import a component, you must add the component to your app.

Adding an Animated Text Field Component to your App

You can add the Animated Text Field component to the FlexForms, FlexContainer, and FlexScrollContainer widgets.

To add the Animated Text Field component, do the following:

  1. Open your app, and then open the form to which you want to add the component.
  2. From the Collections tab, drag the component onto the form on the Visualizer canvas. The component is added to the form.
    You can also see a new element, component.ui.textbox in the Components section on the Templates tab.

After adding a component to a form, you can configure the component the way you want it using the Look, Skin, and Action tabs on the Properties pane. Configuring the properties on the Properties pane is similar to configuring the properties of any widget in Kony Visualizer. For more information, refer Button Widget.

You can also see that a new tab, Component, is added on the Properties pane. The Component tab contains assorted properties relevant to the component that allow you to customize the component as required. The properties on the Component tab are categorized as Pass Through and Custom properties. The Pass Through properties are the default properties of individual widgets in the component. The Custom properties are user-defined properties based on the use case of the component.

Note:

Changes made to the Custom properties are reflected only at the run time, but not at the design time (Visualizer Canvas).

You can also add an Animated Text Field component dynamically. To do so,

  1. In the Project Explorer, on the Projects tab, click the context menu arrow of Modules, and then click New JS module. A new JavaScript file opens in the Code Editor.
  2. Copy and paste the following code snippet in the JavaScript file.
    /* creating a component's Object */
    var textboxComponent = new component.ui.textbox({
                    "clipBounds": true,
                    "height": "10%",
                    "id": "textbox",
                    "isVisible": true,
                    "centerX": "50%",
                    "centerY": "50%",
                    "width" : "80%",
                    "skin": "slFbox",
                    "zIndex": 1
                   }, {}, {});
    /* Setting component's pass-through and custom properties */
    textboxComponent.placeholderText = "Username";
    textboxComponent.maxTextLength = 10;
    textboxComponent.secureTextEntry = false;
    textboxComponent.textBoxText = "";
    textboxComponent.placeholderSkin = " sknTextBoxComponent424242Op60";
    textboxComponent.placeholderFocusSkin = " sknPlaceholderAnimated";
    textboxComponent.underlineSkin = " sknTextBoxComponent424242BGOp60";
    textboxComponent.underlineFocusSkin = " sknUnderlineAnimated";
    textboxComponent.textboxSkin = " sknTextBoxComponent";
    /*Adding Component to the Form*/
    this.view.add(textboxComponent);

    In the code snippet, you can edit the properties of the component as you require. For more information, see Setting Properties.

  3. Save the file.

Setting Properties

The properties provided on the Component tab allow you to customize the UI elements in the Animated Text Field component. You can set the properties directly on the Component tab or by writing a JavaScript. This section provides information about how to set the properties by writing a JavaScript.

PlaceholderText
Category: Pass Through
Description: Specifies a placeholder text to be displayed in the Text field.
Syntax: placeholderText
Type: String
Read/Write: Read + Write
Example:
this.view.Component_Name.placeholderText = "Sample Text";
maxTextLength
Category: Pass Through
Description: Specifies the maximum number of characters accepted by the Text field. Using the property, you can limit a user to enter the text up to a specified length.
Syntax: maxTextLength
Type: Number
Read/Write: Read + Write
Example:
this.view.Component_Name.maxTextLength = 12;
secureTextEntry
Category: Pass Through
Description: Controls whether or not to mask the text in the Text field.
Syntax: secureTextEntry
Type: Boolean
Read/Write: Read + Write
Remarks If the secureTextEntry field is set to true, the Text field behaves as a password field that masks the text entered.
Example:
this.view.Component_Name.secureTextEntry = true;
underlineVisibility
Category: Pass Through
Description: Controls whether or not the underline below the Text field is visible.
Syntax: underlineVisibility
Type: Boolean
Read/Write: Read + Write
Remarks By default, the underlineVisibility property is set to true.
Example:
this.view.Component_Name.underlineVisibility = true;
placeholderSkin
Category: Custom
Description: Specifies the skin to be applied to the placeholder text.
Syntax: placeholderSkin
Type: String
Read/Write: Read + Write
Remarks
  • Before you set the property, ensure that the skin ID that you specify already exists in your app project.
  • The skin ID assigned to the property must be the skin of the Label.
Example:
this.view.Component_Name.placeholderSkin = "sknTextBoxComponent01";
placeholderFocusSkin
Category: Custom
Description: Specifies the skin to be applied to the placeholder text when the Text field is in focus.
Syntax: placeholderFocusSkin
Type: String
Read/Write: Read + Write
Remarks
  • Before you set the property, ensure that the skin ID that you specify already exists in your app project.
  • The skin ID assigned to the property must be the skin of the Label.
Example:
this.view.Component_Name.placeholderFocusSkin = "sknPlaceholderAnimated";
underlineSkin
Category: Custom
Description: Specifies the skin to be applied to the underline below the Text field.
Syntax: underlineSkin
Type: String
Read/Write: Read + Write
Remarks
  • Before you set the property, ensure that the skin ID that you specify already exists in your app project.
  • The skin ID assigned to the property must be the skin of the Label.
Example:
this.view.Component_Name.underlineSkin = "sknTextBoxComponent02";
underlineFocusSkin
Category: Custom
Description: Specifies the skin to be applied to the underline when the Text field is in focus.
Syntax: underlineFocusSkin
Type: String
Read/Write: Read + Write
Remarks
  • Before you set the property, ensure that the skin ID that you specify already exists in your app project.
  • The skin ID assigned to the property must be the skin of the Label.
Example:
this.view.Component_Name.underlineFocusSkin = "sknUnderlineAnimated";
textboxSkin
Category: Custom
Description: Specifies the skin ID to be applied to the Text field.
Syntax: textboxSkin
Type: String
Read/Write: Read + Write
Remarks Before you set the property, ensure that the skin ID that you specify already exists in your app project.
Example:
this.view.Component_Name.underlineFocusSkin = "sknUnderlineAnimated";

Defining Events

You can define events to be executed when an action is performed. You can configure the events directly on the Actions tab or by writing a JavaScript. To configure the events on the Actions tab, click the Edit button against each event. For more information, refer Add Actions.

textBoxTouchStart Event
Description: The event is invoked when a user touches the surface of the Text field.
Syntax: textBoxTouchStart()
textBoxTouchEnd Event
Description: The event is invoked when a user releases the touch from the surface of the Text field.
Syntax: textBoxTouchEnd()
textBoxTouchMove Event
Description: The event is invoked continuously until a user ends the touch moment on the surface of the Text field.
Syntax: textBoxTouchMove()
textBoxTextChange Event
Description: The event is invoked when the text in the Text field changes.
Syntax: textBoxTextChange()
Remarks: The event will not be invoked when the text is changed through a program.
onTextBoxDone event
Description: The event is invoked when a user clicks on the keyboard action label.
Syntax: onTextBoxDone()

APIs

The following API pertains to the Animated Text Field component:

getText

The API retrieves the text entered in the Text field.

Syntax
getText()

Parameters
None.

Return Value

Text [String]:
Returns the text entered in the Text field.

Example
var textboxText = this.view.componentID.getText();
alert(textboxText);