tokeninput Integrates the jQuery Tokeninput plugin into an active text field.

  1. Description
  2. Requirements
  3. Usage
  4. Resources
  5. Changes


TokenInput displays a text input field for a model attribute and applies the jQuery Tokeninput plugin on it. From the jQuery Tokeninput plugin site: "Tokeninput is a jQuery plugin which allows your users to select multiple items from a predefined list, using autocompletion as they type to find each item.".

Important notes
  • Currently only string attributes are supported.
  • Currently only server-backed search is supported, no local data search.
  • Tokens are added using the token value for both tokenValue (default: 'id') and propertyToSearch (default: 'name'), i.e. {'id': value, 'name': value}.
  • In production (YII_DEBUG not defined or set to false), a minified version of the JS file is loaded (minified with
  • The included Tokeninput plugin is version 1.6.0 enhanced with the pull request 'Allow creation of tokens on the fly' (

The widget will automatically pre-populate the token input with the value of the attribute.

The 'cssFile' property can be defined to use a custom CSS file. If it is not defined, one of the default plugin CSS files will be used based on the value of $options['theme']. If this option is not defined, 'token-input.css' will be used, otherwise 'token-input-[theme].css' will be used. Look at the css files in the extension's 'css' directory for available themes.


Yii 1.0.1 or above.


Extract the content of the package in the extensions directory, create a controller action to handle search requests and insert the widget in a view.

Sample controller action

This sample retrieves 10 tokens from a MongoDB database and sorts them alphabetically (uses the directmongosuite extension):

public function actionSearch($q)
	$term = trim($q);
	$result = array();

	if (!empty($term))
		$cursor = Tag::model()->query()->findCursor(array('name' => new MongoRegex('/' . $term . '/i')), array('name'), array('name' => 1), 10);
		if (!empty($cursor) && $cursor->count())
			foreach ($cursor as $id => $value)
				$result[] = array('id' => $value['name'], 'name' => $value['name']);

	header('Content-type: application/json');
	echo CJSON::encode($result);
Sample usage in a form
<div class="row">
	<?php echo $form->labelEx($model,'tags'); ?>
	<?php $this->widget('ext.tokeninput.TokenInput', array(
		'model' => $model,
		'attribute' => 'tags',
		'url' => array('tag/search'),
		'options' => array(
			'allowCreation' => true,
			'preventDuplicates' => true,
			'resultsFormatter' => 'js:function(item){ return “<li><p>” + + “</p></li>” }',
			'theme' => 'facebook',
	)); ?>
	<?php echo $form->error($model,'tags'); ?>
  • 'model' (required): CModel, the data model associated with this widget.
  • 'attribute' (required): string, the attribute associated with this widget.
  • 'url' (required): mixed, URL or an action route that can be used to create the URL to handle search requests.
  • 'options' (optional): array, the initial JavaScript options that should be passed to the jQuery Tokeninput plugin. Please see the plugin's homepage for available options.
  • 'cssFile' (optional): string, the CSS file to use. Please see description above for more details.



v0.3 - 24 Jan. 2012:

  • Use 'CJavaScript:encode' instead of 'CJSON:encode' for encoding the JS options. This preserves value types and allows adding JS functions by pre-pending them with 'js:' (see example).
  • When pre-populating, use the JS options 'tokenValue' and 'propertyToSearch' if defined, otherwise use their default values 'id' and 'name' respectively.
  • Fix token creation code of the jQuery plugin to use 'propertyToSearch' where appropriate.

v0.2 - 17 Jan. 2012:

  • Do not process the attribute value with 'strtolower()' when pre-populating.
  • Added a helper static function 'tokenize()' that splits a value by a delimiter and use it when pre-populating. Can be helpful to use the same function used by the widget, outside of it (for consistency, e.g. when saving to a db as array).
10 0
1 687 downloads
Yii Version: 1.1
License: (not set)
Category: User Interface
Developed by: Haykel
Created on: Jan 10, 2012
Last updated: 9 years ago


show all

Related Extensions