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.

License

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.

Release 0.8.2 - 23/06/2008

Release 0.8.1 - 12/06/2008

Release 0.8.0 - 11/06/2008

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.4 depends on sfThumbnailPlugin
to create thumbnails of image files. If this plugin is not yest installed, the symfony
plugin dependency system will install it when you install sfAssetsLibraryPlugin.

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 sfAssetsLibraryPlugin

Alternatively, if you don't have PEAR installed, you can download the latest package
attached to this plugin's page and extract it under your project's plugins/
directory. You can also refer to the plugin's Subversion repository by doing a
checkout or an svn:externals of http://svn.symfony-project.com/plugins/sfAssetsLibraryPlugin/branches/1.3.

If you use one of these alternative methods, you must publish the plugin assets by
calling the plugin:publish-assets symfony task.

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 asset:create-root task 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 asset:create-root

*nix users must call this command with the same user group as the http
server, because it will need write access to this directory. Alternatively,
chmod 777 or chgrp can be used.

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:

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 operations 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, French, Italian,
and German translations.

It's very important that you point the main module from your links (e.g. a navigation menu)
to the route @sf_asset_library_root. Skipping this passage could lead to problems with layout,
since the popup layout is different from the "standard" one.

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')?><?phpecho asset_image_tag($sf_asset)?>

Importing assets from an existing library

Whether you want to add assets to your library from an existing 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 task asset:synchronize to do just that:

If you use the configuration above, you can add tinyMCE to all your textarea's with class
"rich" (with generator.yml in admin generator, or with form templates otherwise).

That's it, the TinyMCE file browser is now the sfAssetsLibrary's one.

For use with an admin generated module, place the init_asset_library() call
in the _assets.php partial in the templates/ directory of the module. If you miss
that template, just copy it from the cache auto-generated module.
To add class in a generator.yml, do as follows:

Using the form's widget

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 widget
for that purpose, the sfWidgetFormAssetInput. Use is just like a regular widget:

publicfunction configure(){$this->widgetSchema['asset_id'] = new sfWidgetFormAssetInput();
// usually you don't need to define validator, it should be already defined in generated form$this->validatorSchema['asset_id'] = new sfValidatorPropelChoice('model' => 'sfAsset');
}

If not in admin generator, remember to use use_javascripts_for_form($form) in your form's template.

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: