Copyright (c) 2008 Ma Generation, Francois Zaninotto, Gabriele Santini, William Garcia
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
sfAssetsLibrary plugin
The sfAssetsLibraryPlugin is a full-featured multimedia asset library plugin. Not only does it allow you to upload and organize your media files (images, PDF documents, Flash objects, and so on) via a web interface, it also stores metadata about each file for easy retrieval or automated copyright and legend inclusion. It is the perfect companion for rich text editors like TinyMCE.
Screenshot
Prerequisites
This plugin for symfony 1.0 needs a two other components to work:
Note: If ImageMagick is installed (no need for the PEAR Imagick package, the plugin calls the convert script of the basic Image Magic library), then the image thumbnails will be of better quality. See the "Configuration" section below for the way to activate ImageMagick support in the plugin.
Installation
1 - Install the plugin.
The easiest way to install sfAssetsLibraryPlugin is to use the symfony command line:
> php symfony plugin-install http://plugins.symfony-project.com/sfAssetsLibraryPlugin
Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory. You will also have to copy the contents of the myproject/plugins/sfAssetsLibraryPlugin/web/ directory into a myproject/web/sfAssetsLibraryPlugin/ directory.
2 - Build the data structures
Rebuild the model and generate the SQL code for the new tables:
> php symfony propel-build-model
> php symfony propel-build-sql
Create the new tables in your database. Use the generated data/sql/plugins.sfAssetsLibraryPlugin.lib.model.schema.sql file for that. For instance, with MySQL:
> mysql -uroot -p mydb < data/sql/plugins.sfAssetsLibraryPlugin.lib.model.schema.sql
3 - Configure your project to use the plugin features
Enable the sfAsset module in your backend application, via the settings.yml file.
// in myproject/apps/backend/config/settings.yml
all:
.settings:
enabled_modules: [sfAsset](default,)
Configure the path to the root assets directory in the app.yml file:
// in myproject/config/app.yml
all:
sfAssetsLibrary:
upload_dir: media
In the above example, uploaded files will be stored under the web/media directory.
4 - Clear the cache to enable the autoloading to find the new classes:
> php symfony cc
5 - Use the bundled sfassetlibrary-create-root pake task (or sfalcr to go fast) to initialize the root asset directory in the filesystem and in the database. The name of the root asset directory will be read from the app.yml configuration you just defined:
> php symfony sfassetlibrary-create-root backend
Note: *nix users must call this command with the same user group as the http server, because it will need write access to this directory.
6 - You can now start using the plugin by browsing to the backend module's default page:
http://myproject/backend_dev.php/sfAsset
Configuration
You can modify the plugin settings by way of the configuration. Here is a list of the settings you can change in your application's app.yml:
# in apps/backend/config/app.yml
all:
sfAssetsLibrary:
upload_dir: media # Asset library root, under the web/ dir
check_type: false # Set to true if you want to restrict the type of assets
types: [txt, archive, pdf, xls, doc, ppt]('image',) # Accepted asset types if check_type is true
thumbnail_dir: thumbnail # Where the image thumbnails are stored
use_ImageMagick: false # Set to true if you have the convert command
thumbnails: # Name and size (in pixels) of the thumbnails created at upload
small: # Displayed in the list page
width: 84
height: 84
shave: true # Cut strips to constraint the image size
large: # Displayed in the details page
width: 194
height: 152
search_pager_size: 20 # Number of resuts per page
mass_upload_size: 5 # Number of file upload controls displayed in the mass upload form
The sfAsset module
The sfAsset module provides four main features:
Browse through your media files like in a filesystem.
Read or change metadata for a particular file
Perform usual filesystem operztions on your files and folder (add, move, rename, delete)
Search for a particular media file from its filename, description, author, etc.
The module has two main views (list and edit) that you can easily customize by using your own CSS or overriding some of their numerous partials in your application. The templates are organized the same way as the admin generated modules, so applying your own look and feel to the sfAssetsLibrary should be easy.
The module is fully i18n'ed, and the plugin comes with English and French translations.
Using the assets from the library in your applications
Uploaded assets end up under the sfConfig::get('sf_web_root').sfConfig::get('app_sfAssetsLibrary_upload_dir') directory. The path to a particular media file appears in its details page fo the sfAsset module, so if you need to use it somewhere in your application, just copy this path. Alternatively, if you need to include an image tag to an asset you retrieved from the database, you can use the asset_image_tag() helper:
<?php use_helper('sfAsset') ?>
<?php echo asset_image_tag($sf_asset) ?>
Importing assets from an existing library
Whether you want to add assets to your library from an existing sfMediaLibrary(/plugins/sfMediaLibraryPlugin sfMediaLibrary), or to cleanup your database of removed files, you will probably need to synchronize the assets database with a directory.
Fortunately, the plugin comes with a pake task to do just that: sfassetlibrary-synchronize (or sfals to go fast):
> php symfony sfassetlibrary-synchronize [[dirname](app]) --notVerbose --removeOrphanAssets --removeOrphanFolders
For instance, to import an existing Media Library under web/uploads/media to the sfAssetsLibrary, just type:
> php symfony sfassetlibrary-synchronize backend /path/to/project/web/uploads/media --removeOrphanAssets --removeOrphanFolders
You can call this task as many times you want, since it only performs database and filesystem operations when the two sources are not in sync.
Using the assets library with TinyMCE
If you want to use the sfAssetsLibrary plugin as a replacement for tinyMCE's file browser for image insertion, you must first initiate the plugin with a helper in the template:
<?php use_helper('sfAsset') ?>
<?php echo init_asset_library() ?>
The next thing to do is to pass a special JavaScript callback function to the TinyMCE object at initialization. This is done with the tinymce_options option of the textarea_tag() helper:
<?php echo textarea_tag('content', *, array (
'rich' => true,
'tinymce_options' => 'file_browser_callback:"sfAssetsLibrary.fileBrowserCallBack"',
)); ?>
That's it, the TinyMCE file browser is now the sfAssetsLibrary's one.
Tip: For use with an admin generated module, place the init_asset_library() call in the _edit_header.php partial in the templates/ directory of the module. To define the callback in a generator.yml, do as follows:
generator:
class: sfPropelAdminGenerator
param:
model_class: Post
theme: default
edit:
fields:
content: { params: rich=true tinymce_options=\'file_browser_callback:"sfAssetsLibrary.fileBrowserCallBack"\' }
Using the Assets Library input_file helper
Traditionally, when an asset has to be referenced in a form, a file input is used (<input type='file'>). It allows the user to upload a file from his computer to the server, and this file can be further embedded in a rich text content.
Using the sfAssetsLibraryPlugin, you can change this control into some sort of file input that refers to the assets library, or, to put it differently, to the files located on the server in web/media. The plugin comes with a special helper for that purpose, the input_sf_asset_tag(). Use is just like a regular input_tag():
<?php use_helper('sfAsset') ?>
<?php echo form_tag('foo/bar') ?>
<?php echo input_sf_asset_tag('my_asset_field', *) ?>
</form>
This input is not a real file input tag, meaning that the chosen asset file will not be posted with the request. Instead, the action will be able to retrieve the asset file path relative to the web root, exactly what is needed to display it. Incidentally, this means that your form doesn't need to be set multipart.
Optionally, you can restrict the choice of possible assets in this input to images only, as follows:
<?php echo input_sf_asset_tag('my_asset_field', '', array('images_only' => true)) ?>
TODO
- Check Windows compatibility
- Make list of ignored files and folders configurable in synchronize task
- 100% model coverage for unit tests
- Make thumbnails for PDF files (if ImageMagick is installed)
- Drag and drop manipulation for file and folders
- Screencast to show installation and usage
Changelog
2008-06-12 | 0.8.1 Beta
- francois: Fixed initialization task
- francois: Translated remaining strings
- francois: Fixed helper declaration problems
- francois: Added mass upload
- francois: Fixed popup layout
2008-06-11 | 0.8.0 Beta
- wgarcia, blacksun, francois: Initial version
François Zaninotto 
Gabriele Santini 
