ActsAsImageHolder
=================
This plugin handles the work with image-fields, such as validation,
resizing, watermarking, files organizations etc.
Example
=======
A simple example might be like that. A user unit which has a field
'avatar' which will contain a file-name of his avatar and all the
avatars will be saved in the "#{RAILS_ROOT}/public/images/userpics"
directory.
class User < ActiveRecord::Base
acts_as_image_holder :image_field => 'avatar',
:output_directory => 'userpics'
end
More complex example, this time there are two blob-fields one 'image'
will keep the image source, the second 'thumb', will contain the image
thumbnail. All the incomming images will be resized to fit the size of
600x400, the system will check that they are in type of gif, png or
jpeg and then will automatically generate a thumbnail which will fit
the size of 200x150 and will be in format of jpeg.
class Image < ActiveRecord::Base
acts_as_image_holder :image_field => 'image',
:resize_to => '600x400',
:allowed_types => [:gif, :png, :jpeg],
:thumb_field => 'thumb',
:thumb_size => '200x150',
:thumb_type => :jpeg
end
Each time there will be defined methods to direct assignment the
files, like that
User.new.image_field = File.open('some/your/file.png', 'rb')
Image.image = File.open('some/file/of/yours.jpg', 'rb')
Sure you can put right there the user uploaded images, use mass
assignment, etc. Everything will be handled automatically.
Options
=======
You can pass to the method the following options.
[*] Output directory options
:output_directory - relative to "#{RAILS_ROOT}/public/images" or an
absolute directory path.
:subdirectories - a string which will be put in the
Time.now.strftime method and will generate
subdirectories inside the output-directory.
NOTE: if the output-directory is not specified, it assumes that you
want to save your images as blobs inside your database
[*] Image specification options
:image_field - the name of the main image field in your record, by
default is 'image'
:image_type_field - name of the field where you would like to track
each image type. the system will put strings like
'gif', 'png', 'jpeg' into the field when the image
will be assigned
:original_field - if specified the original incomming image will be
stored in here
:convert_to - :png/:gif/:jpeg - if specified all the incomming
images will be converted to the sepcified type
:resize_to - a string like '123x123' which meant width and height
if specified all the incomming images will be
proportionally resiezed to fit the given size.
:jpeg_quality - if you set the config to convert incomming images to
jpegs, you can specify the jpeg-quality with the option
:allowed_types - list like [:png, :jpeg] if specified all the
incomming images will get validated against the rule
:required - boolean marke which shows if the image field should
be treated as a required one during the validation
:maximum_bytes - integer maximum size of the incomming images
:watermark - the watermarking options (see below)
[*] Thumbnailing options
:thumb_field - the name of the field which will contain the thumb
file name or the thumb-blob. if specified the thumbs
will be generated automatically each time the main
image field assigned
:thumb_size - string like '123x123' which meant as width-height,
if specified thumbs will be created to fit the size
:thumb_type - :png/:gif/:jpeg - if specified all the thumbs will
be created in the given type
:thumb_quality - the jpeg-thumbnails quality
:thumb_watermark - the thumbnail watermarking options (see below)
[*] Shortified versions of the options
:directory == :output_directory
:subdirs == :subdirectories
:field == :image_field
:type_field == :image_type_field
:original == :original_field
:type == :convert_to
:size == :resize_to
:quality == :jpeg_quality
Several Images Processing
=========================
If have several images on your model, you can specify them by passing
a list of image-definitions like that
class Image < ActiveRecord::Base
acts_as_image_holder :image_fields => [
{ :image_field => 'main_image', ...},
{ :image_field => 'optional_image',..}
],
:outout_directory => 'uploaded'
end
or you can use a shortified interface like this
class Image < ActiveRecord::Base
acts_as_image_holder :images => [
{ :field => 'main_image', :type_field => '...'},
{ :field => 'optional_image',..}
],
:outout_directory => 'uploaded'
end
Sure, each image can have several thumbnails if you like. And you can
use the short notation as well
class Image < ActiveRecord::Base
acts_as_image_holder :image_field => 'full_size',
:thumbs => [
{ :field => 'small_size',
:size => '100x100',
:type => :jpeg
}, {
:field => 'average_size',
:size => '200x200'
}
]
end
Watermarking
============
With the plugin you can automatically put watermarks on your incomming
images. You can use a simple text or a file which should be
watermarked over the image. The definition might look like that
class Image < ActiveRecord::Base
acts_as_image_holder :field => 'full_version',
:watermark => {
:text => "That's mine!",
:font => {
:size => 40,
:family => "Arial",
:weight => :bold
},
:color => 'red'
}
end
You can watermark the thumbnails as well if you like so.
class Image < ActiveRecord::Base
acts_as_image_holder :field => 'full_version',
:watermark => {...}
:thumb_field => 'thumb',
:thumb_watermark => {...}
# or like that
acts_as_image_holder :field => 'full_version',
:watermark => {...}
:thumbs => [
{ :field => 'thumb',
:watermark => {...}
}
.....
]
end
Watermarking Options
====================
:text - the text string for the watermark
:font - the font definitions for the text watermark
:size - the font size in pixels
:family - the font family string "Arial"/"Helvetica"
:weight - the font weight name :bold/:bolder/:normal
:style - the font style :italic/oblique
:stretch - the space between the chars
:color - the text color, it can be in any standard format #FFF,
#FFFFFFF, string color name, rgb(), etc
:stroke - if you want a stroked text, put the color in here
:stroke_width - the stroke width in pixels, 1 pixel by default
:undercolor - the background color for your text if you need
:text_align - the text align right/left/center
:file - the name of an image-file or a file object which should be
placed over your image
:position - where to put your text. There are several options
possible, but they are pretty much standard. Use arrays
like [:top, :left], [:center, :right], [:bottom, :center],
or just :top, :left, :center, etc. Or some compas like
directions :south, :southeast, :north, etc.
:offset - offset of your watermark from the image ages in pixels
:rotate - integer degrees, how the watermark should be rotated
(clockwise)
:shade - the shade effect options. An array like
[bool, int, int]
:shadow - the shadow effect options. An array like
[left_offset=4, top_offset=4, blureness=4, opacity=1]
:shadow_color - the shadow effect color if you need so.
Additional Methods
==================
In addition you will have several more options on your model which
will help you to handle images inside of the model if need so
If you use filestorage for your images, then for each image and
thumbnail you will have a method named like "#{field_name}_url" which
will return the url address of the image.
Then you will have the following methods
resize_file(File/String file_pointer, String size,
String format, Integer quality)
resize_file(String blob, String size, String format, Integer quality)
watermark_file(File/String file_pointer, Hash options)
watermark_blob(String blob, Hash options)
That's it. Enjoy!
--
Copyright (c) 2008 Nikolay V. Nemshilov, released under the MIT license