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 is supported since Tizen 2.0. |
By default, all the <div>
elements with the data-role="tokentextarea"
attribute are displayed as token text area.
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>
To create simple token text area from a <div>
element using the data-role
attribute:
<div data-role="tokentextarea"></div>
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. |
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>
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>
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>
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>
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, ...);
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. |
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 valueCode 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 valueCode 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 valueCode 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 valueCode 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>