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

Description ¶

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 http://jscompress.com).
• The included Tokeninput plugin is version 1.6.0 enhanced with the pull request 'Allow creation of tokens on the fly' (https://github.com/loopj/jquery-tokeninput/pull/219).

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.

Requirements ¶

Yii 1.0.1 or above.

Usage ¶

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);
	Yii::app()->end();
}

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>” + item.name + “</p></li>” }',
			'theme' => 'facebook',
		)
	)); ?>
	<?php echo $form->error($model,'tags'); ?>
</div>

Properties ¶

• '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.

Resources ¶

• jQuery Tokeninput plugin homepage
• Discussion thread on the Yii forums
• Bitbucket repository

Changes ¶

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).