Difference between #3 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 thisThis wiki will be
explainedexplain 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
it 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);
	}

}
~~~

We extend CInputWidget, the base widget for input field. This masterclass
give useparent class gives us the attributes 'model' and
'attribute'.

AndNow, instead of the file field in our form we can
place:

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

Excellent! Now we have a widget wichwhich works exactly
how worked CHtml::activeFileField(), weCHtml::activeFileField()
worked.

We can move forward forto use
uploadifyuploadify.



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


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

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

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


~~~
[php]
	publicpublic 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);
	}
{
   $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)
publishpublishes the directory and
returnreturns the path created.

The other options publishinstructions publishes the script
and css file. Please note that we includeare including the
yii version of jquery (),jquery, not the uploadify one
forto avoid conflicts. 

### Register the script

Our objective is to register this script:the following js
script, and to reserve us the possibility to customize it.

~~~
[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>
~~~

And 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:this:

~~~
[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 default standard options (uploader,
script , cancelImg,,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 possiblitypossibility 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.beginning.

ForTo register the script we need only the id, we can
generate the id with CHtml, respecting any choucechoice of
the user:

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

And finally register the script:

~~~
[php]
Yii::app()->clientScript->registerScript($id,	"$(document).ready(function()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- Create a widget
Download
- Download the library somewhere
Publish
- Publish the library
Include
- Include needed script/css
Prepare
- 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 wasis only to give a structure in wich easy
inlcudewhich to include all needed file.