Difference between #1 and #2 of How to create a wrapper for a js library

unchanged
Title
How to create a wrapper for a js library
unchanged
Category
How-tos
unchanged
Tags
wrapper, js, uploadify
changed
Content
In this wiki will be explained how to include a javascript library in a widget.

We will use as example [uploadify](http://www.uploadify.com/
"uploadify"), a flash/javascript plugin for file uploading.

Our example: uploadify
------------------

Let's imagine we have a page with a file field, and we want to exchange with a
uploadify.

The first step is to create a widget that will replace this file field.


Creating the widget
------------------
Let's create a file in components named ZUploadify:


~~~
[php]
<?php

class ZUploadify extends CInputWidget
{

	public function run()
	{

		echo CHtml::activeFileField($this->model,
$this->attribute);		$this->render('ZUploadify',
array('model'=>$this->model, 'attribute'=>$this->attribute));
	}

}
~~~

We extend CInputWidget, the base widget for input field. This masterclass give
use the attributes 'model' and 'attribute'.

And instead of the file field in our formIn
components/views we can place:add:

~~~
[php]
<?php $this->widget('ZUploadify', array('model'=>$model,
'attribute'=>'file')); ?>
~~~

Excellent! Now we have a widget wich works exactly how worked
CHtml::activeFileField(), we can move forward for use uploadify



Import uploadify
----------------


Following [uploadify's documentation](http://www.uploadify.com/documentation/
""), we have to download the package and import in the web page.

Let's save the package in protected/compoments/assets for now. 

Now we have to publis this directory and to include the files. All simple as:


<?php echo CHtml::activeFileField($model, $attribute);?>
~~~
[php]
	public function run()
	{

		$assetsFolder=
Yii::app()->assetManager->publish(Yii::getPathOfAlias('application.components.assets.uploadify'));
		Yii::app()->clientScript->registerCssFile($assetsFolder.'/uploadify.css');
		Yii::app()->clientScript->registerScriptFile($assetsFolder.'/swfobject.js');
		Yii::app()->clientScript->registerScriptFile($assetsFolder.'/jquery.uploadify.v2.1.4.min.js');
		Yii::app()->clientScript->registerCoreScript('jquery');

		echo CHtml::activeFileField($this->model, $this->attribute);
	}

~~~

The first instruction (assetsManger->publish) publishAnd instead
of the directory and return the path created.

The other options publish the script and css file. Please note
thatfile field in our form we include the yii version of
jquery (), not the uploadify one for avoid conflicts. 

### Register the script

Our objective is to register this script:can place:

~~~
[php]
<script type="text/javascript">
$(document).ready(function() {
  $('#file_upload').uploadify({
    'uploader'  : '/uploadify/uploadify.swf',
    'script'    : '/uploadify/uploadify.php',
    'cancelImg' : '/uploadify/cancel.png',
    'folder'    : '/uploads',
    'auto'      : true
  });
});
</script><?php $this->widget('ZUploadify',
array('model'=>$model, 'attribute'=>'file')); ?>
~~~

And to reserve us the possiblity of customize it.
Let's add a property options:

~~~
[php]
public $options;
~~~

And thenExcellent! Now we prepare the options like that:

~~~
[php]
$options= CJavaScript::encode(array_merge(
			array(
				'uploader'  => $assetsFolder.'/uploadify.swf',
				'script'    => $assetsFolder.'/uploadify.php',
				'cancelImg' => $assetsFolder.'/cancel.png',
				'folder'    => '/uploads',
				'auto'      => true
			),
			$this->options
		));
~~~

The options are made up by some standard options (uploader, script , cancelImg,
folder and auto) that will be merged with the user defined options.

User defined options will take precedence (they are the second array in
array_merge), so we will have the possiblity of override the default
ones.

This options will be encoded with Cjavascript::encode(), a magic
function that allow to give javascript functions as parameters, we have just to
write 'js:' at the begining.

For register the script we need only the id,widget wich works exactly
how worked CHtml::activeFileField(), we can generate the id with
CHtml, respecting any chouce of the user:

~~~
[php]
		if (isset ($htmlOptions['id']))
			$id= $htmlOptions['id'];
		else
			$id= CHtml::activeId($this->model, $this->attribute);
~~~

And finally register the script:

~~~
[php]
Yii::app()->clientScript->registerScript($id,	"$(document).ready(function()
{ $('#$id').uploadify($options);});");
~~~

That's it, ourmove forward for use uploadify widget is
ready to be used. 

Conclusion
------------------

In summary:

Create a widget
Download the library somewhere
Publish the library
Include needed script/css
Prepare options and register the script

Here is the complete result:

~~~
[php]
<?php

class ZUploadify extends CInputWidget
{

	public $options = array();
	public function run()
	{

		$assetsFolder=
Yii::app()->assetManager->publish(Yii::getPathOfAlias('application.modules.administrator.components.assets.uploadify'));
		Yii::app()->clientScript->registerCssFile($assetsFolder.'/uploadify.css');
		Yii::app()->clientScript->registerScriptFile($assetsFolder.'/swfobject.js');
		Yii::app()->clientScript->registerScriptFile($assetsFolder.'/jquery.uploadify.v2.1.4.min.js');
		Yii::app()->clientScript->registerCoreScript('jquery');

		$options= CJavaScript::encode(array_merge(
			array(
				'uploader'  => $assetsFolder.'/uploadify.swf',
				'script'    => $assetsFolder.'/uploadify.php',
				'cancelImg' => $assetsFolder.'/cancel.png',
				'folder'    => '/uploads',
				'auto'      => true
			),
			$this->options
		));

		if (isset ($htmlOptions['id']))
			$id= $htmlOptions['id'];
		else
			$id= CHtml::activeId($this->model, $this->attribute);


		Yii::app()->clientScript->registerScript($id,	"$(document).ready(function()
{ $('#$id').uploadify($options);});");
		echo CHtml::activeFileField($this->model, $this->attribute,
$this->htmlOptions);
	}
}
~~~




For any customization, follow the documentation of uploadify. The work of Yii
framework was only to give a structure in wich easy inlcude all needed file.








Import uploadify