Token Text Area

The token text area component changes a text item to a button. When the user types text and the text gets a specific event to change from a text to a button, the input text is changed to a token text area component.

A typical use of this component is to display a number of contacts or phone numbers in a specific area of the screen. When the user to enters text, it is converted to a button, and each button created from entered text forms a token text area component. This component is useful in composing an e-mail or SMS message to a group of addresses, each of which is a clickable item for more actions, such as copying, editing, or removing the address.

Note
This component has been DEPRECATED since Tizen 2.4 and will be deleted in Tizen 3.0.
To support Backward compatibility, please import tau.support-2.3.js.
Since 2.4, this component has been renamed to TextEnveloper. To use this, please refer TextEnveloper component.

Table of Contents

  1. Manual Constructor
  2. HTML Examples
  3. Options
  4. Methods

Default Selectors

By default, all the <div> elements with the data-role="tokentextarea" attribute are displayed as token text area.

Manual Constructor

To manually create a token text area component, use the component constructor from the tau namespace (RECOMMENDED):

<div id="ns-tokentextarea"><div>
<script>
   var token = tau.widget.Tokentextarea(document.getElementById('ns-tokentextarea'));
</script>

If the jQuery library is loaded, you can use its method (support for backward compatibility):

<div id="ns-tokentextarea"><div>
<script>
   $("#ns-tokentextarea").tokentextarea();
</script>

HTML Examples

To create simple token text area from a <div> element using the data-role attribute:

<div data-role="tokentextarea"></div>

Options

Summary

Option Input type Default value Description
data-description string "+ {0}" Manages the message format.
data-label string "To: " Sets a label as a guide for the user.
data-link string null Sets a URL at the anchor button.

Guide Labels

You can provide a custom label to guide the user with the data-label option. For example, while composing an SMS message, a "Send to: " label is a guide for the user to enter a phone number or choose a recipient from the address book.

<div data-role="tokentextarea" data-label="Send to: "></div>

Linked Data

You can provide a link (with the data-link option) to a page that contains data for the user, for example, an address book. The link contains the ID of the page or the URL of other HTML file. If the value is null (default), the anchor button does not work.

<div data-role="tokentextarea" data-link="bar.html"></div>

Message Format

You can manage the message format with the data-description option. The message is displayed when the component status changes to focusout.

<div data-role="tokentextarea" data-description="bar + {0}"></div>

Getting and Setting Options

You can use the option method to get and set custom options for the token text area.

<script>
   var elementToken = document.getElementById("ns-tokentextarea"),
       tokentextarea = tau.widget.TokenTextarea(elementToken);

   /* Get the label */
   tokentextarea.option("label");

   /* Set the label */
   tokentextarea.option("label", "e-mail To:");

   /* Get the link */
   tokentextarea.option("link");

   /* Set the link */
   tokentextarea.option("link", "favorites.html");

   /* Get the message format */
   tokentextarea.option("description");

   /* Set the message format */
   tokentextarea.option("description", "bar + {0}");
</script>

Methods

To call a method on the component, use one of the existing API:

  • TAU API (RECOMMENDED):

    var elementToken = document.getElementById("ns-tokentext"),
        tokentextarea = tau.widget.Tokentextarea(elementToken);
    
    tokentextarea.methodName(methodArgument1, methodArgument2, ...);
    
  • jQuery API (support for backward compatibility):

    $(".selector").tokentextarea("methodName", methodArgument1, ...);
    

Summary

Method Description
add(string messages, number blockIndex) 

Adds a new token text area component button with specified text in the place of the index.

Tokentextarea disable() 

Disables the token text area.

Tokentextarea enable() 

Enables the token text area.

focusIn() 

Ungroups the elements and sets a focus to the input.

focusOut() 

Groups elements and hides the input.

string inputText(string text) 

Manages the component input box text.

number length() 

Returns the block count.

remove(number blockIndex) 

Deletes a token text area component button at the specified index position. If no parameter is defined, all token text area component buttons are deleted.

?string select(number blockIndex) 

Selects the token text area button based on its index value.
If a parameter is set, the token text area button matching the index value is selected.
If a token text area button is selected and the parameter is not set, the method returns the string of the selected button. If no button is selected, the method returns null.

add

Adds a new token text area component button with specified text in the place of the index.

add(string messages, number blockIndex) 

If the index is not set, the token is inserted at the end.

Parameters:

Parameter Type Required/optional Default value Description
messages string Required
blockIndex number Optional

Return value:

No return value

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.add("foobar");
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   $("#ns-tokentext").tokentextarea("add", "foobar");
</script>
disable

Disables the token text area.

Tokentextarea disable() 

The method adds the disabled attribute on the token text area component and changes the look of the component to the disabled state.

Code example (TAU API RECOMMENDED):

<div data-role="tokentexarea" id="ns-tokentext"></div>
<script>
   var elementToken = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   elementToken.disable();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   $("#ns-tokentext").tokentextarea("disable");
</script>
enable

Enables the token text area.

Tokentextarea enable() 

The method removes the disabled attribute from the token text area component and changes the look of the component to the enabled state.

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   var elementToken = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   elementToken.enable();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   $("#ns-tokentext").tokentextarea("enable");
</script>
focusIn

Ungroups the elements and sets a focus to the input.

focusIn() 

Return value:

No return value

Code example (TAU API (support for backward compatibility):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.focusIn(0);
</script>

Code example (jQuery API):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   $("#ns-tokentext").tokentextarea("focusIn");
</script>
focusOut

Groups elements and hides the input.

focusOut() 

Return value:

No return value

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.focusOut(0);
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   $("#ns-tokentext").tokentextarea("focusOut");
</script>
inputText

Manages the component input box text.

string inputText(string text) 

If no parameter is set, the method gets the input box text. If a parameter is set, the parameter text is set in the input box.

Parameters:

Parameter Type Required/optional Default value Description
text string Required

Return value:

Type Description
string

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));

   /* Set the text in the input box */
   tokenWidget.inputText("foobar");

   /* Get the input box text */
   tokenWidget.inputText();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   /* Set the text in the input box */
   $("#ns-tokentext").tokentextarea("inputText", "foobar");

   /* Get the input box text */
   $("#ns-tokentext").tokentextarea("inputText");
</script>
length

Returns the block count.

number length() 

The method retrieves the number of buttons in the token text area component.

Return value:

Type Description
number

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.length();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   $("#ns-tokentext").tokentextarea("length");
</script>
remove

Deletes a token text area component button at the specified index position. If no parameter is defined, all token text area component buttons are deleted.

remove(number blockIndex) 

Parameters:

Parameter Type Required/optional Default value Description
blockIndex number Required

Return value:

No return value

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.remove(1);
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea"
     data-label="Send to: "
     id="ns-tokentext">
</div>
<script>
   $("#ns-tokentext").tokentextarea("remove", 1);
</script>
select

Selects the token text area button based on its index value.
If a parameter is set, the token text area button matching the index value is selected.
If a token text area button is selected and the parameter is not set, the method returns the string of the selected button. If no button is selected, the method returns null.

?string select(number blockIndex) 

Parameters:

Parameter Type Required/optional Default value Description
blockIndex number Required

Return value:

Type Description
?string

Code example (TAU API RECOMMENDED):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   /* Select first block */
   var tokenWidget = tau.widget.TokenTextarea(document.getElementById("ns-tokentext"));
   tokenWidget.add("text 1");
   tokenWidget.add("text 2");
   tokenWidget.select(0);

   /* Get string from selected block */
   tokenWidget.select();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="tokentextarea" id="ns-tokentext"></div>
<script>
   /* Select first block */
   $("#ns-tokentext").tokentextarea("add", "text 1");
   $("#ns-tokentext").tokentextarea("add", "text 2");
   $("#ns-tokentext").tokentextarea("select", "0");

   /* Get string from selected block */
   $("#ns-tokentext").tokentextarea("select");
</script>