robinboening-fleximage 1.0.4

data/CHANGELOG.rdoc

@@ -0,0 +1,14 @@
+== fleximage 1.0.2 12-14-2009
+
+* Don't prepend RAILS_ROOT to absolute image directory path
+* Added support for an "image_format" magic database column
+* Fixed an issue with saving temp images in Windows
+* Fixed a temp image vulnerability with directory traversal
+
+== fleximage 1.0.1 12-13-2009
+
+* Now with completely passing tests
+
+== fleximage 1.0.0 12-13-2009
+
+* Initial gem release.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+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.

data/README.rdoc

@@ -0,0 +1,257 @@
+== Installation
+
+Gem: (Recommended)
+  
+  gem install fleximage
+  
+  # in config/environment.rb
+  config.gem 'fleximage'
+
+Plugin:
+  
+  ./script/plugin install git://github.com/Squeegy/fleximage.git
+
+
+= Fleximage
+
+== Overview
+
+Fleximage is a Rails plugin that tries to make image uploading and rendering super easy.
+
+There are 2 pieces involved in making Rails image handling easy.
+
+=== 1. Image Uploads
+
+In this post Rails 2, resource-driven world, Fleximage believes that images should belong directly to a record.  So you simply tell your model class to act as Fleximage, and your model effortlessly gains the ability to handle file uploads.
+
+* Your model gains the ability to interface directly with a +file_field+ form, allowing uploads with zero extra controller or model code.
+* Accept uploads from a web address, pulling in the image from the internet and saving it locally.
+* Image presence validation with customizable form field error messages.
+* Image format validation that will not allow the file to be uploaded unless RMagick can parse it into useable image data.
+* Image pre-processing to keep uploaded images under a certain size, or other on-upload image processing tasks.
+
+
+=== 2. Image Rendering
+
+The other half of the problem comes from the need to send the uploaded images back to the web browser.  Most of the time, you need to display the image in different sizes or formats in different places on your site.  For example, a product image in a store may need a square thumbnail image, a medium image for its focus page, and a large image for an "enlarge this photo" popup.
+
+Fleximage uses a simple templating engine that allows you to re-render images exactly how you need them.  Using the same "master image," many images can be rendered from the same source.  You can even go beyond resizing; there is support for image overlays, text drawing, drop shadows, borders and more.  The rendering engine is flexible and extensible to whatever your dynamic image needs are.
+
+* Renderer implemented as template engine, which fits in perfectly with Rails 2 RESTful style format-sensitive views.
+* Does not need to have everything resized on upload allowing your site layout the change later on, and all images will re-render themselves just right with your new rendering templates.
+* Support for special effects like text, image or logo overlays, borders and shadows.
+* Extensible by adding image operator classes which allow for reusable snippets of direct RMagick code.
+* Requires absolutely zero controller code.
+
+
+= Getting Started
+
+== 1. Installation
+
+Gem: (Recommended)
+  
+  gem install fleximage
+  
+  # in config/environment.rb
+  config.gem 'fleximage'
+
+Plugin:
+  
+  ./script/plugin install git://github.com/Squeegy/fleximage.git
+
+
+== 2. Activating your model
+
+You need to let your model know it should be Fleximage-friendly.  Lets say you have a model for photos.
+  
+  # app/models/photo.rb
+  class Photo < ActiveRecord::Base
+    acts_as_fleximage :image_directory => 'public/images/uploaded_photos'
+  end
+
+The :+image_directory+ option tells the plugin where to store your master images.  This value is relative to your application root, and doesn't need to be in your public directory if you don't want it to be.  This is where the source images will be that all your templates start with.
+
+There are many other options for your model.  Refer to the <tt>Fleximage::Model::ClassMethods</tt> class in the +rdoc+ for more information on these.
+
+
+== 3. The upload form
+
+Your users need a way to upload their images into your site.  Here is how we might render a form to create a photo record.
+  
+  # app/views/photos/new.html.erb
+  
+  <% form_for @photo, :html => { :multipart => true } do |f| %>
+    <p>
+      <b>Name</b><br />
+      <%= f.text_field :name %>
+    </p>
+
+    <p>
+      <b>Author</b><br />
+      <%= f.text_field :author %>
+    </p>
+
+    <p>
+      <b>Upload Image</b><br />
+      <%= f.file_field :image_file %><br />
+      or URL: <%= f.text_field :image_file_url %>
+    </p>
+
+    <p>
+      <%= f.submit "Create" %>
+    </p>
+  <% end %>
+  
+*NOTE*: The ":html => { :multipart => true }" is *VERY* *IMPORTANT*.  Without this snippet your browser will not send binary data to the server.  If things aren't working, check to make sure you have this in your form declaration.
+
+The relevant bit of our form code is:
+
+  <p>
+    <b>Upload Image</b><br />
+    <%= f.file_field :image_file %><br />
+    or URL: <%= f.text_field :image_file_url %>
+  </p>
+
+First there is a file upload field, mapping the the "image_file" attribute of our model.  When the user browses to a local file and uploads it, the model is waiting to accept an uploaded file on this attribute and will automatically open it and save it to disk for you.
+
+Right along side the upload field is a simple text field, which maps to the "image_file_url" property.  Your model also listens for assignment to this attribute to automatically fetch the contents of a URL and save it locally as the master image.
+
+You can have just one of these fields, or both.  The model will know how to do the right thing either way.
+
+When the user submits the form, all you have to do is assign the form contents to your object in standard Rails fashion, and the image is uploaded and saved for you.  Creating a new photo may look like this in your controller:
+  
+  # app/controllers/photos_controller.rb
+  def create
+    @photo = Photo.new(params[:photo])
+    if @photo.save
+      redirect_to photo_url(@photo)
+    else
+      flash[:notice] = 'Your photo did not pass validation!'
+      render :action => 'new'
+    end
+  end
+
+
+== 4. Linking to the generated images
+
+Rails 2 has amazing support for format driven responses.  Given a photo object, by default it would have an HTML view that describes information about that photo.  With Fleximage, the JPG or (GIF or PNG) view can be the image data itself.
+
+A photo HTML view may look like this:
+  
+  # app/views/photos/show.html.erb
+  # http://mysite.com/photos/123
+  
+  <p>
+    <%= image_tag formatted_photo_path(@photo, :jpg) %>
+  </p>
+  <p>
+    <b>Name:</b>
+    <%=h @photo.name %>
+  </p>
+  <p>
+    <b>Author:</b>
+    <%=h @photo.author %>
+  </p>
+
+That image tag uses a Rails route as its +src+.  In this case, that route corresponds to the <tt>.jpg</tt> format of the +photo+ resource, which would give us a URL like:
+
+  http://mysite.com/photos/123.jpg
+
+This is the URL where the image will be.
+
+
+== 5. Rendering the image
+
+Now it's time to actually create a template to render the image.  This happens through a special view with a .+flexi+ extension.  This view template will pull out the master image for you, and send it to the browser as binary data after your processing of it done.
+
+The filename of the template should look like this: <tt>action_name.jpg.flexi</tt>, where +action_name+ is the controller action that will render this view.  The +jpg+ tells the controller to render this view when the +jpg+ format is asked for.  The +flexi+ tells Rails to render this view with the Fleximage template engine, rather than +erb+, +builder+ or other template types.
+
+The syntax of the view is pure ruby, but to process the image the view needs to call +operate+ on the instance of your model.
+
+Here is the view to render a photo record at 320x240:
+  
+  # app/views/photos/show.jpg.flexi
+  # http://mysite.com/photos/123.jpg
+  @photo.operate do |image|
+    image.resize '320x240'
+  end
+
+Calling <tt>@photo.operate { |image| .. }</tt> prepares the model object for image processing and provides a ruby object that will allow you to perform image transformations.  This example just resizes the image to 320x240, however many other operators are included.
+
+Here is a .+flexi+ template that will do much more:
+
+  # app/views/show.jpg.flexi
+  @photo.operate do |image|
+    image.resize '640x480', :crop => true
+    image.image_overlay 'public/images/logo.png',
+      :alignment => :bottom_right,
+      :offset => '20x20'
+    image.border :size => 10, :color => 'green'
+    image.text 'I like Cheese'
+    image.unsharp_mask  
+    image.shadow
+  end
+
+This template will:
+
+* Resize the image to exactly 640x480, cropping off any extra.
+* Add a logo 20 pixels form the lower right corner
+* Add a green 10 pixel border
+* Write "I like Cheese" in the upper left corder
+* Sharpen the image
+* Add a black drop shadow on a white background
+
+For more information on image operators, open up <tt>vendor/plugins/fleximage/rdoc/index.html</tt> in your installed plugin and check out the full for details about each operator:
+
+* Fleximage::Operator::Border
+* Fleximage::Operator::Crop
+* Fleximage::Operator::ImageOverlay
+* Fleximage::Operator::Resize
+* Fleximage::Operator::Shadow
+* Fleximage::Operator::Text
+* Fleximage::Operator::Trim
+* Fleximage::Operator::UnsharpMask
+
+
+= Other Useful Information
+
+== Image output format
+
+You don't want to render JPGs?  That's fine.  Just link to the format you want (:+jpg+, :+gif+ or :+png+) and declare the your template name to match and the image will be rendered properly.  For instance, this will render a +gif+.
+
+  # app/views/photos/show.html.erb
+  <%= image_tag photo_path(@photo, :gif) %>
+  
+  # app/views/photos/show.gif.flexi
+  @photo.operate do |image|
+    @photo.resize '150x150', :crop => true
+  end
+
+The Fleximage template engine will automatically detect the format that is being asked for, and render the right type of image.
+
+== Converting/Upgrading your master image store
+
+Are you upgrading your live app to the new file store creation date based format?  Did you start out with PNG image storage, and later realize you need to store with the more space economic JPG instead?  Not problem, Fleximage provides some rake tasks to help you out.
+  
+Each conversion rake task requires that you tell it the class for which that you are changing the file store.  For example, if you want to change to the new creation date based storage structure, for the class +Photo+, you can run a rake task like this:
+
+  rake fleximage:convert:to_nested FLEXIMAGE_CLASS=Photo
+
+Or if you want to run this on your production database
+
+  rake fleximage:convert:to_nested FLEXIMAGE_CLASS=Photo RAILS_ENV=production
+
+*IMPORTANT*: These tasks manipulate the source files that make up your images.  I take no responsibility if these rake tasks delete all your images.  <b>It is highly advised you back up you master image directory before running any of these tasks on your production site.</b>
+
+Here are all the conversion tasks:
+
+* fleximage:convert:to_nested : Converts your master image store from the flat based path/to/images/123.png format to the creation date based format path/to/images/2008/11/12/123.png based format.  Use this task if you are upgrading from an older version of Fleximage.
+* fleximage:convert:to_flat : Converts your master image store from the creation date based path/to/images/2008/11/12/123.png format to the flat format path/to/images/123.png format.  Note this will leave the date based directories in place, but they will be empty and can be easily manually deleted.
+* fleximage:convert:to_jpg : Converts all your stored master images from PNG format to JPG format.  This will compress your previously lossless master images.
+* fleximage:convert:to_png : Converts all your stored master images from JPG format to PNG format.
+
+After you run any of these tasks, make sure to update your model's class accessors +use_creation_date_based_directories+ and +image_storage_format+ to reflect the state of your image store.  Otherwise, the plugin will not find you master images for rendering.
+
+------
+Copyright (c) 2008 Alex Wayne beautifulpixel.com, released under the MIT license.
+Special Thanks to Chris Vannoy for intelligent code review, suggestions and contributions to making this plugin awesome.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rubygems'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the fleximage plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.verbose = true
+end
+
+
+desc 'Generate documentation for the fleximage plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Fleximage'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "robinboening-fleximage"
+    gem.summary = <<EOF
+Rails plugin for uploading images as resources, with support for resizing, text
+stamping, and other special effects.
+EOF
+    gem.description = <<EOF
+Fleximage is a Rails plugin that tries to make image uploading and rendering
+super easy.
+EOF
+    gem.email = "robin.boening@nethosting4you.de"
+    gem.homepage = "http://github.com/robinboening/fleximage"
+    gem.authors = `git log --pretty=format:"%an"`.split("\n").uniq.sort
+    gem.add_dependency "rmagick"
+    gem.add_dependency "aws-s3"
+    gem.add_development_dependency "rails", "=2.2.2"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available."
+  puts "Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.4

data/autotest.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby -wKU
+$stdout.sync = true
+IO.popen('rstakeout "rake test" lib/fleximage/* lib/fleximage/**/* test/unit/*') do |f|
+  puts f.gets until f.eof?
+end

data/fleximage.gemspec

@@ -0,0 +1,179 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{fleximage}
+  s.version = "1.0.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{Ahmed Adam}, %q{Alex Wayne}, %q{Andrew White}, %q{JJ Buckley}, %q{Jason Lee}, %q{Joshua Abbott}, %q{Koji Ando}, %q{Kouhei Sutou}, %q{Lasse Jansen}, %q{Loïc Guitaut}, %q{Martin Vielsmaier}, %q{Robin Böning}, %q{Squeegy}, %q{Vannoy}, %q{ralph}]
+  s.date = %q{2011-05-29}
+  s.description = %q{Fleximage is a Rails plugin that tries to make image uploading and rendering
+super easy.
+}
+  s.email = %q{ruby@beautifulpixel.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "CHANGELOG.rdoc",
+    "MIT-LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "autotest.rb",
+    "fleximage.gemspec",
+    "init.rb",
+    "lib/dsl_accessor.rb",
+    "lib/fleximage.rb",
+    "lib/fleximage/aviary_controller.rb",
+    "lib/fleximage/blank.rb",
+    "lib/fleximage/helper.rb",
+    "lib/fleximage/image_proxy.rb",
+    "lib/fleximage/legacy_view.rb",
+    "lib/fleximage/model.rb",
+    "lib/fleximage/operator/background.rb",
+    "lib/fleximage/operator/base.rb",
+    "lib/fleximage/operator/border.rb",
+    "lib/fleximage/operator/crop.rb",
+    "lib/fleximage/operator/image_overlay.rb",
+    "lib/fleximage/operator/resize.rb",
+    "lib/fleximage/operator/shadow.rb",
+    "lib/fleximage/operator/text.rb",
+    "lib/fleximage/operator/trim.rb",
+    "lib/fleximage/operator/unsharp_mask.rb",
+    "lib/fleximage/rmagick_image_patch.rb",
+    "lib/fleximage/view.rb",
+    "tasks/fleximage_tasks.rake",
+    "test/fixtures/100x1.jpg",
+    "test/fixtures/100x100.jpg",
+    "test/fixtures/1x1.jpg",
+    "test/fixtures/1x100.jpg",
+    "test/fixtures/cmyk.jpg",
+    "test/fixtures/not_a_photo.xml",
+    "test/fixtures/photo.jpg",
+    "test/mock_file.rb",
+    "test/rails_root/app/controllers/application.rb",
+    "test/rails_root/app/controllers/avatars_controller.rb",
+    "test/rails_root/app/controllers/photo_bares_controller.rb",
+    "test/rails_root/app/controllers/photo_dbs_controller.rb",
+    "test/rails_root/app/controllers/photo_files_controller.rb",
+    "test/rails_root/app/helpers/application_helper.rb",
+    "test/rails_root/app/helpers/avatars_helper.rb",
+    "test/rails_root/app/helpers/photo_bares_helper.rb",
+    "test/rails_root/app/helpers/photo_dbs_helper.rb",
+    "test/rails_root/app/helpers/photo_files_helper.rb",
+    "test/rails_root/app/locales/de.yml",
+    "test/rails_root/app/locales/en.yml",
+    "test/rails_root/app/models/abstract.rb",
+    "test/rails_root/app/models/avatar.rb",
+    "test/rails_root/app/models/photo_bare.rb",
+    "test/rails_root/app/models/photo_custom_error.rb",
+    "test/rails_root/app/models/photo_db.rb",
+    "test/rails_root/app/models/photo_file.rb",
+    "test/rails_root/app/models/photo_s3.rb",
+    "test/rails_root/app/views/avatars/edit.html.erb",
+    "test/rails_root/app/views/avatars/index.html.erb",
+    "test/rails_root/app/views/avatars/new.html.erb",
+    "test/rails_root/app/views/avatars/show.html.erb",
+    "test/rails_root/app/views/layouts/avatars.html.erb",
+    "test/rails_root/app/views/layouts/photo_bares.html.erb",
+    "test/rails_root/app/views/layouts/photo_dbs.html.erb",
+    "test/rails_root/app/views/layouts/photo_files.html.erb",
+    "test/rails_root/app/views/photo_bares/edit.html.erb",
+    "test/rails_root/app/views/photo_bares/index.html.erb",
+    "test/rails_root/app/views/photo_bares/new.html.erb",
+    "test/rails_root/app/views/photo_bares/show.html.erb",
+    "test/rails_root/app/views/photo_dbs/edit.html.erb",
+    "test/rails_root/app/views/photo_dbs/index.html.erb",
+    "test/rails_root/app/views/photo_dbs/new.html.erb",
+    "test/rails_root/app/views/photo_dbs/show.html.erb",
+    "test/rails_root/app/views/photo_files/edit.html.erb",
+    "test/rails_root/app/views/photo_files/index.html.erb",
+    "test/rails_root/app/views/photo_files/new.html.erb",
+    "test/rails_root/app/views/photo_files/show.html.erb",
+    "test/rails_root/config/boot.rb",
+    "test/rails_root/config/database.yml",
+    "test/rails_root/config/environment.rb",
+    "test/rails_root/config/environments/development.rb",
+    "test/rails_root/config/environments/production.rb",
+    "test/rails_root/config/environments/sqlite3.rb",
+    "test/rails_root/config/environments/test.rb",
+    "test/rails_root/config/initializers/inflections.rb",
+    "test/rails_root/config/initializers/load_translations.rb",
+    "test/rails_root/config/initializers/mime_types.rb",
+    "test/rails_root/config/routes.rb",
+    "test/rails_root/db/migrate/001_create_photo_files.rb",
+    "test/rails_root/db/migrate/002_create_photo_dbs.rb",
+    "test/rails_root/db/migrate/003_create_photo_bares.rb",
+    "test/rails_root/db/migrate/004_create_avatars.rb",
+    "test/rails_root/db/migrate/005_create_photo_s3s.rb",
+    "test/rails_root/public/.htaccess",
+    "test/rails_root/public/404.html",
+    "test/rails_root/public/422.html",
+    "test/rails_root/public/500.html",
+    "test/rails_root/public/dispatch.cgi",
+    "test/rails_root/public/dispatch.fcgi",
+    "test/rails_root/public/dispatch.rb",
+    "test/rails_root/public/favicon.ico",
+    "test/rails_root/public/images/rails.png",
+    "test/rails_root/public/index.html",
+    "test/rails_root/public/javascripts/application.js",
+    "test/rails_root/public/javascripts/controls.js",
+    "test/rails_root/public/javascripts/dragdrop.js",
+    "test/rails_root/public/javascripts/effects.js",
+    "test/rails_root/public/javascripts/prototype.js",
+    "test/rails_root/public/robots.txt",
+    "test/rails_root/public/stylesheets/scaffold.css",
+    "test/rails_root/vendor/plugins/fleximage/init.rb",
+    "test/s3_stubs.rb",
+    "test/test_helper.rb",
+    "test/unit/abstract_test.rb",
+    "test/unit/basic_model_test.rb",
+    "test/unit/blank_test.rb",
+    "test/unit/default_image_path_option_test.rb",
+    "test/unit/dsl_accessor_test.rb",
+    "test/unit/file_upload_from_local_test.rb",
+    "test/unit/file_upload_from_strings_test.rb",
+    "test/unit/file_upload_from_url_test.rb",
+    "test/unit/file_upload_to_db_test.rb",
+    "test/unit/has_store_test.rb",
+    "test/unit/i18n_messages_test.rb",
+    "test/unit/image_directory_option_test.rb",
+    "test/unit/image_proxy_test.rb",
+    "test/unit/image_storage_format_option_test.rb",
+    "test/unit/magic_columns_test.rb",
+    "test/unit/minimum_image_size_test.rb",
+    "test/unit/operator_base_test.rb",
+    "test/unit/operator_resize_test.rb",
+    "test/unit/preprocess_image_option_test.rb",
+    "test/unit/require_image_option_test.rb",
+    "test/unit/temp_image_test.rb",
+    "test/unit/use_creation_date_based_directories_option_test.rb"
+  ]
+  s.homepage = %q{http://github.com/Squeegy/fleximage}
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.4}
+  s.summary = %q{Rails plugin for uploading images as resources, with support for resizing, text stamping, and other special effects.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rmagick>, [">= 0"])
+      s.add_runtime_dependency(%q<aws-s3>, [">= 0"])
+      s.add_development_dependency(%q<rails>, ["= 2.2.2"])
+    else
+      s.add_dependency(%q<rmagick>, [">= 0"])
+      s.add_dependency(%q<aws-s3>, [">= 0"])
+      s.add_dependency(%q<rails>, ["= 2.2.2"])
+    end
+  else
+    s.add_dependency(%q<rmagick>, [">= 0"])
+    s.add_dependency(%q<aws-s3>, [">= 0"])
+    s.add_dependency(%q<rails>, ["= 2.2.2"])
+  end
+end
+