sfDoctrineJCroppablePlugin
Effortlessly add images to your models with an incredibly easy-to-use javascript
image cropper (jcrop).
The plugin will also automatically create and save the cropped images for you,
in sizes you can configure.
Installation
To install the plugin for a symfony project, the usual process is to use the
symfony command line:
php symfony plugin:install --install-deps sfDoctrineJCroppablePlugin
sfDoctrineJCroppablePlugin depends on the excellent sfImageTransformPlugin, but
until I can figure out how to specify that dependancy in the package then you'll
have to install it yourself (it's getting late!)
php symfony plugin:install sfImageTransformPlugin
If for some reason this fails (eg you're running symfony 1.3) then you can
manually download the tgz file from
http://plugins.symfony-project.org/get/sfImageTransformPlugin/sfImageTransformPlugin-1.2.0.tgz
and then ask symfony to install the downloaded file
php symfony plugin:install sfImageTransformPlugin-1.2.0.tgz
If you're using symfony 1.3 then you may find there's not yet a version of
sfImageTransformPlugin for it, but we have found that version 1.2 (the latest as
of this writing) works just fine.
Enable the plugins if necessary by editing config/ProjectConfiguration.class.php:
$this->enablePlugins(array('sfDoctrinePlugin', 'sfImageTransformPlugin', 'sfDoctrineJCroppablePlugin'));
Symfony 1.2 & Doctrine 1.0
If you're using symfony 1.2 which comes with doctrine 1.0 this plugin will not
be able to delete the old versions of it's images when it creates new ones. This
is because we've not been able to find a way of getting the old filename.
Upgrading to doctrine 1.1 fixes this and is a reasonably straightforward
exorcise. There is a good guide here:
http://www.brandonturner.net/blog/2009/05/doctrine11-with-symfony12/
Symfony 1.3 comes with doctrine 1.2 and so this is not an issue.
Usage
You'll first want to edit your config/doctrine/schema.yml to add the behaviour
to one of your models:
Person:
actAs:
JCroppable:
images: [ mugshot ]
columns:
first_name: { type: string(128), notnull: true }
last_name: { type: string(128), notnull: false }
Here we have told the plugin we want one jcroppable image field called mugshot.
The plugin will take care of the creation of the relevant fields in the person
table.
Now we've updated/created our schema, we can tell symfony to rebuild our
database.
Caution! This step will erase any data in the database that is not included in any
fixtures:
php symfony doctrine:build-all-reload
Next let's configure sfImageTransform to use the gd library and to auto-detect
images' mime-types (apps/backend/config/app.yml)
all:
sfImageTransformPlugin:
default_adapter: GD
mime_type:
auto_detect: true
library: gd_mime_type
If you haven't aleady done so let's create an admin module for our person model:
php symfony doctrine:generate-admin backend Person --module=person
The plugin also depends on the jquery & jcrop libraries, so you must download
them (http://deepliquid.com/content/Jcrop.html) and place the two js files
(jquery.Jcrop.min.js & jquery.min.js) in web/js, and the css file
(jquery.Jcrop.css) in web/css:
web/js/jquery.min.js
web/js/jquery.Jcrop.min.js
web/css/jquery.Jcrop.css
Now we need to tell our module's view to include them. We can do this
specifically for our module by editing
apps/backend/modules/person/config/view.yml, or for the whole application by
editing apps/backend/config/view.yml:
default:
javascripts: [jquery.min.js, jquery.Jcrop.min.js]
stylesheets: [jquery.Jcrop.css]
We're almost finished now! Just two things left to do. First we have to
configure the widget & validator for our jcroppable image field. Add the
following calls to configure the widgets & validators to the form's confgure
function (lib/form/doctrine/PersonForm.class.php):
public function configure()
{
$this->getObject()->configureJCropWidgets($this);
$this->getObject()->configureJCropValidators($this);
}
And finally create the upload directory for the images to be stored in and make
them writable:
mkdir -p web/uploads/images/Person
chmod 777 web/uploads/images/Person
That's it! Now if you followed the instructions carefully then you should be
able to aim your browser at your backend app's person module and add a few
people and their mug shots.
To show the images in your frontend templates, simply pass a Person object, and
call the getImageSrc() function, passing the desired size, eg
<img src="<?php echo $person->getImageSrc('mugshot', 'thumb') ?>" alt="Mug shot!" />
Configuration
Now the above example has used a load of default values which you'll almost
definitely want to configure. Here's an example of some config you can place in
your config/app.yml:
all:
sfDoctrineJCroppablePlugin:
models:
Person:
directory: people
images:
mugshot:
padding: { percent: 35, color: #ffffff }
ratio: 1.5
sizes:
thumb: { width: 450 }
main: { width: 675 }
Let's run through these options:
- directory - overrides the default web/uploads/images/Person to instead be
web/uploads/people
- padding - adds padding to the image, of the specified color, using either a
'percent' or 'pixels' value
- ratio - fixes the aspect ratio of the cropper and therefore the generated
cropped images
- sizes - allows you to specify any number of different sized images to be
created. You specify the width ad the height will be calculated using the
ratio if there is one, otherwise it will be variable according to the
selected crop. The default sizes are thumb (width 120px) &
main (width 360px)
Rich Birch 