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.

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

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

add(string messages, number blockIndex) 

Tokentextarea disable() 

Tokentextarea enable() 

focusIn() 

focusOut() 

string inputText(string text) 

number length() 

remove(number blockIndex) 

?string select(number blockIndex) 

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>