Difference between #2 and #1 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()
	{

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

}
~~~

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

In components/viewsAnd instead of the file field in our
form we can add:place:

~~~
[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()
	{

And instead of		$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) publish the file
field in our formdirectory and return the path created.

The other options publish the script and css file. Please note that we
can place:include the yii version of jquery (), not the
uploadify one for avoid conflicts. 

### Register the script

Our objective is to register this script:

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

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

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

And then 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 widget
wich works exactly how worked CHtml::activeFileField(),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, we can move forward for
usegenerate 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, our 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