YiiFileManagerFilePicker ¶

1. Developent Status
2. Source Repository (Bitbucket)
3. Author
4. License
5. Requirements
6. Features
7. Dependencies
8. Screenshots
9. Installation
10. Using the widget
11. jQuery-UI
12. Beauty Urls
13. Image Thumbnail

A widget for Yii Framework based web applications, allows your web users to manage their files online (multiple ajax uploader, file manager).

Developent Status ¶

PRODUCTION

Source Repository (Bitbucket) ¶

https://bitbucket.org/christiansalazarh/yiifilemanagerfilepicker

Author ¶

• Christian Salazar christiansalazarh@gmail.com @salazarchris74 (bluyell yii forum profile)
• Google+ Profile

License ¶

• Free BSD

Requirements ¶

• Yii 1.1.13 (use CJavaScriptExpression to handle javascript events)
• PHP 5.3.3-7 (not tested in lower php versions)

Features ¶

• File Browser (pictures, non-pictures)
• Rename Files
• Delete Files
• Automatic Picture Thumbnail (no large files crunched)
• Ajax based.
• Multiple File Uploader with Progress bar (ajax based)
• Css Customizable
• Html Customizable
• Extensible
• Event handlers (client-side / server-side)

Dependencies ¶

This widget depends on YiiFileManager Extension in order to handle the user's files. You must first install it.

Screenshots ¶

Installation ¶

• Install it in your protected/extensions/ folder

cd yourapp/protected/extensions/
git clone https://bitbucket.org/christiansalazarh/yiifilemanagerfilepicker.git

• Register the extension path in your config/main file

'import'=>array(
	'application.models.*',
	'application.components.*',
	'application.extensions.yiifilemanager.*',
	'application.extensions.yiifilemanagerfilepicker.*', // <<--THIS
),

• install a static action in any controller.

_about using a different controller: by default the widget points to "site"Controller, you must locate the required static action in this controller.

if you require a different controller (ie: AnotherController.php) then you are required to declare it in your component class, in the method: 'yiifileman_data', see below the method yiifileman_data to view an example.

class SiteController extends Controller {
	public function actions()
	{
	return array(
		'captcha'=>array(
		'class'=>'CCaptchaAction','backColor'=>0xFFFFFF,),
		'page'=>array('class'=>'CViewAction',),
		'yiifilemanagerfilepicker'=>array(
	'class'=>
		'ext.yiifilemanagerfilepicker.YiiFileManagerFilePickerAction'),
	);
	}
...
}

• copy the provided client class

'protected/extensions/yiifilemanagerfilepicker
    (..continue..)/demo-component/MyYiiFileManViewer.php'
#into your own:
'protected/components/MyYiiFileManViewer.php'

In the following code the method documentation has been removed here for clarification, full code is provided in demo-component/MyYiiFileManViewer.php.

Be carefull with Yii::app()->fileman, this is the this file manager previously installed, see about Dependencies.

<?php
class MyYiiFileManViewer extends YiiFileManagerFilePicker
		implements IYiiFileManagerFilePicker
{
	public function yiifileman_classname(){
		return __CLASS__;
	}

	public function yiifileman_data(){
		return array(
			'gallery_size'=>array(160,120),
			// for demostration:	
				'identity'=>'123456', 
			// USE IN A REAL SITUATION: 
				//	'identity'=>Yii::app()->user->id,
			'fileman'=>Yii::app()->fileman,		// <-- BE CAREFULL
			'allow_multiple_selection'=>true,
			'allow_rename_files'=>true,
			'allow_delete_files'=>true,
			'allow_file_uploads'=>true,
                        // change it only if you're not using siteController
			// 'controller'=>'site', 
                        // 'controller'=>'/mymodule/mycontroller', (for modules)
		);	
	}

	public function build_file_viewer_url($file_id){
		return parent::build_file_viewer_url($file_id);
	}

	public function yiifileman_filter_file_list($list, $extra=array()){
		return $list;
	}

	public function yiifileman_get_image_substitution(
		$file_info, $local_path, $mimetype){
	// your code here
		return parent::yiifileman_get_image_substitution($file_info,
			$local_path,$mimetype);
	}

	public function yiifileman_on_action($action, $file_ids){
		// action taken: "select" or "delete"

		// call parent to perform default stuff
		return parent::yiifileman_on_action($action, $file_ids);
	}

	public function yiifileman_accept_file($filename,$filesize, $mimetype,
		$is_server_side, &$reason){
		return true;
	}
}

Using the widget ¶

Once you have installed the required class (see installation steps) now you can insert the widget in any view. Because the component is extensible, then you must provide the required html layout for your file picker

Suppose you require your user to click an icon in order to display the widget, so simply: create a link or anything else and pass its jquery selector to the widget: 'launch_selector'=>'#file-picker',

Now, suppose you doesnt require a launch icon, so put Nothing in the 'launch_selector' widget attribute, this cause the widget to display it's content inmediatly in the 'list_selector' (ie: #file-picker-view)

the layout pointed by the selector '#file-picker-viewer' will be used to render the file picker. later you'll find a jQueryUI example using this widget.

• copy the demo icons in order to make this demo works: (demo icons are not a dependency)

(demo icons)
'yourapp/protected/extensions/yiifilemanagerfilepicker/demo-images'  
to:
'yourapp/images/'

• copy this content into any view, as demo use: 'protected/views/site/index.php'

<!-- using protected/views/site/index.php AS DEMO, you can use any view -->
<div>Select a Background image: <a href='#' id='file-picker'>click here</a>
	<img src='' width='50%' id='selected-image' />
</div>

<!-- required div layout begins -->
<div id='file-picker-viewer'>
	<div class='body'></div>
	<hr/>
	<div id='myuploader'>
		<label rel='pin'><b>Upload Files
			<img style='float: left;' src='images/pin.png'></b></label>
		<br/>
		<div class='files'></div>
		<div class='progressbar'>
			<div style='float: left;'>
				Uploading your file(s), please wait...</div>
			<img style='float: left;' src='images/progressbar.gif' />
			<div style=
				'float: left; margin-right:10px;'class='progress'>
			</div>
			<img style='float: left;' class='canceljob' 
				src='images/delete.png' title='cancel the upload'/>
		</div>
	</div>
	<hr/>
	<button id='select_file' class='ok_button'>Select File(s)</button>
	<button id='delete_file' class='delete_button'>
		Delete Selected File(s)</button>
	<button id='close_window' class='cancel_button'>Close Window
		</button>
</div>
<!-- required div layout ends -->

<hr/>Logger:<br/><div id='logger'></div>

<?php
	// the widget
	//
	$this->widget('application.components.MyYiiFileManViewer'
	,array(
		// layout selectors:
		'launch_selector'=>'#file-picker',
		'list_selector'=>'#file-picker-viewer',
		'uploader_selector' => '#myuploader',
		// messages:
		'delete_confirm_message' => 'Confirm deletion ?',
		'select_confirm_message' => 'Confirm selected items ?',
		'no_selection_message' => 'You are required to select some file',
		// events:
		'onBeforeAction'=>
			"function(viewer,action,file_ids) { return true; }",
		'onAfterAction'=>
			"function(viewer,action,file_ids, ok, response) { 
				if(action == 'select'){ 
				  // actions: select | delete
				  $.each(file_ids, function(i, item){ 
				  $('#logger').append('file_id='+item.file_id 
				  + ', <img src=\''+item.url+'&size=full\'><br/>');
				});
			}
		}",
		// 'onBeforeLaunch'=>"function(_viewer){ }",
		'onClientSideUploaderError'=>
			"function(messages){ 
				$(messages).each(function(i,m){  alert(m); }); 
			}
		",
		'onClientUploaderProgress'=>"function(status, progress){
			$('#logger').append(
				'progress: '+status+' '+progress+'%<br/>');
			}",
		));
?>
<!-- end of protected/views/site/index.php -->

jQuery-UI ¶

It is very simple to display this widget into a jQueryUI based dialog, the same applies to a different UI providers. the jqueryUI sample code is located in the repository in bitbucket

Beauty Urls ¶

This components allows you to publish gallery images using friendly urls. Suppose you want this friendly URL for gallery items:

http://mywebsite/file/1981dc12 (1981dc12 is the file_id, not file names!)

then create the following .htaccess rule:

RewriteRule ^file/(.*)$ index.php?r=/site/yiifilemanagerfilepicker/&class=MyFileManViewer&method=viewer&file_id=$1

Now, declare it in your class 'protected/components/MyYiiFileManViewer.php'

public function build_file_viewer_url($file_id){
  return "http://mywebsite.com/file/".$file_id;
  //instead of default: return parent::build_file_viewer_url($file_id);
}

Image Thumbnail ¶

this component automatically build a thumbnail for every file shown in the gallery (picture or not).

first of all, this is the action path required to view a file thumbnail in the gallery, by default the method build_file_viewer_url is called every time a gallery item must be published, so in that method you decide how the url must be published, the default implementation create ugly urls like this one:

index.php?r=/site/yiifilemanagerfilepicker/&class=MyFileManViewer&method=viewer&file_id=THE_ID

this URL by default will show a thumbnail in the specified size exposed in your class component, in the 'gallery_size' array entry (160x120 as default), changing this value in your class definition will produce thumbnails in the required size.

...
	public function yiifileman_data(){
		return array(
			'gallery_size'=>array(160,120),
....

How to display an image in its original size ?

So simple as adding an extra argument to the url: '&size=full'

index.php?r=/site/yiifilemanagerfilepicker/&class=MyFileManViewer&method=viewer&file_id=THE_ID&size=full

Using this URL in the SRC attribute for a given IMG tag will display the picture, so, this is sufficient to display the file in full size:

  <img src='index.php?r=/site/yiifilemanagerfilepicker/&class=MyFileManViewer&method=viewer&file_id=THE_ID&size=full' />

About non-picture files thumbnails

As you know, TXT documents are not images, so what thumbnail can we show in place of it ? Easy, you decide what image can be shown every time using your component class:

this method is automatically invoked whenever a file must be displayed in the gallery, the core code will detect the local_path to your file and the mimetype:

public function yiifileman_get_image_substitution(
	$file_info, $local_path, $mimetype){

  // use the detected mimetype and local_path to decide which image
  // better suite your needs...OR simply use the default stuff:
  return parent::yiifileman_get_image_substitution(
      $file_info, $local_path,$mimetype);
}