README.markdown in imagery-0.0.6 vs README.markdown in imagery-0.2.0
- old
+ new
@@ -1,10 +1,8 @@
Imagery
=======
-(See documentation at [http://labs.sinefunc.com/imagery/doc](http://labs.sinefunc.com/imagery/doc))
-
## Image manipulation should be simple. It should be customizable. It should allow for flexibility. Imagery attempts to solve these.
### Imagery favors:
1. Simplicity and explicitness over magic DSLs.
@@ -12,110 +10,90 @@
3. Flexibility and extensibility.
4. Not being tied to any form of ORM.
1. Simplicity and Explicitness
------------------------------
-To get started using Imagery you only need ImageMagick, ruby and Imagery of
+To get started using Imagery you only need GraphicsMagick, ruby and Imagery of
course.
# on debian based systems
- sudo apt-get install imagemagick
- # or maybe using macports
- sudo port install ImageMagick
+ sudo apt-get install graphicsmagick
+ # or maybe using homebrew
+ brew install graphicsmagick
[sudo] gem install imagery
Then you may proceed using it.
require 'rubygems'
require 'imagery'
- Photo = Class.new(Struct.new(:id))
-
- i = Imagery.new(Photo.new(1001))
- i.root = '/some/path/here'
- i.sizes = { :thumb => ["48x48^", "48x48"], :large => ["480x320"] }
+ i = Imagery.new(:photo, "1001", thumb: ["48x48^", "48x48"])
i.save(File.open('/some/path/to/image.jpg'))
- File.exist?('/some/path/here/public/system/photo/1001/thumb.png')
+ File.exist?('public/photo/1001/thumb.jpg')
# => true
- File.exist?('/some/path/here/public/system/photo/1001/large.png')
+ File.exist?('public/photo/1001/original.jpg')
# => true
- File.exist?('/some/path/here/public/system/photo/1001/original.png')
- # => true
-
- # the defaut is to use the .id and the name of the class passed,
- # but you can specify a different scheme.
-
- i = Imagery.new(Photo.new(1001), `uuidgen`.strip, "photos")
- i.root = '/some/path/here'
- i.file == '/some/path/here/public/system/photos/1c2030a6-6bfa-11df-8997-67a71f1f84c7/original.png'
- # => true
-
2. OOP Principles (that we already know)
----------------------------------------
### Ohm example (See [http://ohm.keyvalue.org](http://ohm.keyvalue.org))
- # Imagery will use ROOT_DIR if its available
- ROOT_DIR = "/u/apps/site/current"
-
class User < Ohm::Model
include Ohm::Callbacks
after :save, :write_avatar
def avatar=(fp)
@avatar_fp = fp
end
def avatar
- @avatar ||=
- Imagery.new(self).tap do |i|
- i.sizes = { :thumb => ["48x48^", "48x48"], :medium => ["120x120"] }
- end
+ Imagery.new :avatar, id,
+ :thumb => ["48x48^", "48x48"],
+ :medium => ["120x120"]
end
protected
def write_avatar
- avatar.save(@avatar_fp[:tempfile]) if @avatar_fp
+ avatar.save(@avatar_fp[:tempfile]) if @avatar_fp
end
end
# Since we're using composition, we can customize the dimensions on an
# instance level.
class Collage < Ohm::Model
attribute :width
attribute :height
def photo
- @photo ||=
- Imagery.new(self).tap do |i|
- i.sizes = { :thumb => ["%sx%s" % [width, height]] }
- end
+ Imagery.new :photo, id, :thumb => ["%sx%s" % [width, height]]
end
end
# For cases where we want to use S3 for some and normal filesystem for others
- class S3Photo < Imagery::Model
+ class S3Photo < Imagery
include Imagery::S3
- s3_bucket 'my-bucket'
+
+ s3_bucket "my-bucket"
end
# then maybe some other files are using cloudfront
- class CloudfrontPhoto < Imagery::Model
+ class CloudfrontPhoto < Imagery
include Imagery::S3
- s3_bucket 'my-bucket'
- s3_distribution_domain 'assets.site.com'
+
+ s3_bucket "my-bucket"
+ s3_distribution_domain "assets.site.com"
end
# some might be using S3 EU, in which case you can specify the s3_host
class CustomS3Host < Imagery::Model
include Imagery::S3
- s3_host 'http://my.custom.host'
- s3_bucket 'my-bucket-name'
+ s3_host "http://my.custom.host"
+ s3_bucket "my-bucket-name"
end
3. Flexibility and Extensibility
--------------------------------
### Existing plugins: Faking and S3
@@ -129,25 +107,22 @@
ENV["AMAZON_SECRET_ACCESS_KEY"]
you can do this by setting it on your .bash_profile / .bashrc or just
manually setting them somewhere in your appication
- ENV["AMAZON_ACCESS_KEY_ID"] = '_access_key_id_'
- ENV["AMAZON_SECRET_ACCESS_KEY"] = '_secret_access_key_'
+ ENV["AMAZON_ACCESS_KEY_ID"] = "_access_key_id_"
+ ENV["AMAZON_SECRET_ACCESS_KEY"] = "_secret_access_key_"
Now you can just start using it:
- Photo = Class.new(Struct.new(:id))
-
- class Imagery::Model
+ class Imagery
include Imagery::S3
- s3_bucket 'my-bucket'
+ s3_bucket "my-bucket"
end
- i = Imagery.new(Photo.new(1001))
- i.root = '/tmp'
- i.save(File.open('/some/path/to/image.jpg'))
+ i = Imagery.new :photo, 1001
+ i.save(File.open("/some/path/to/image.jpg"))
#### Imagery::Faking
When doing testing, you definitely don't want to run image
resizing everytime. Enter Faking.
@@ -171,16 +146,16 @@
class Test::Unit::TestCase
include Imagery::Test
end
# now when you do some testing... (User assumes the user example above)
- imagery do |is_real|
- user = User.new(:avatar => { tempfile: File.open('avatar.jpg') })
+ imagery do |enabled|
+ user = User.new(:avatar => { tempfile: File.open("avatar.jpg") })
user.save
- if is_real
- assert File.exist?(user.avatar.file)
+ if enabled
+ assert File.exist?(user.avatar.root("original.jpg"))
end
end
Running your test suite:
@@ -191,11 +166,11 @@
### Extending Imagery
By making use of standard Ruby idioms, we can easily do lots with it.
Exensibility is addressed via Ruby modules for example:
- module Imagery
+ class Imagery
module MogileStore
def self.included(base)
class << base
attr_accessor :mogile_config
end
@@ -212,15 +187,13 @@
# remove the mogile stuff here
end
end
end
- # Now just include the module however, whenever you want
- module Imagery
- class Model
- include Imagery::MogileStore
- self.mogile_config = { :foo => :bar }
- end
+ # Now just include the module to use it.
+ class Imagery
+ include Imagery::MogileStore
+ self.mogile_config = { :foo => :bar }
end
### Note on Patches/Pull Requests