stash-magic 0.0.2 → 0.0.3

data/README.rdoc

@@ -1,3 +1,5 @@
+"I switch off the light. Where does it go?" -- Famous Koan
+
 = Stash Magic (BETA)
 
 Stash Magic provides a very simple interface for dealing with file system attachments in a database and help you with thumbnails or other styles via ImageMagick (hence, the name). Features are:
@@ -9,77 +11,91 @@ Stash Magic provides a very simple interface for dealing with file system attach
 - Easy to understand (one file) module 
 
 This is still in Beta version built with simplicity in mind.
+It tries to do a lot with less code that anybody would be able to understand quickly.
 Don't hesitate to contact me for any improvement, suggestion, or bug fixing.
 
 I've made the design choice not to build a Sequel plugin because I'd like StashMagic to work with other ORMs in the future.
+I'm pretty sure that if it doesn't already work with ActiveRecord, only changing a couple of names would fix it.
 So any test or help is welcome.
 
+= How to install
+
+  gem install stash-magic
+
+Use Sudo if you want to install it for all users of your server:
+
+  sudo gem install stash-magic
+
+If you have Ruby 1.9, this is most likely that you have to replace the command gem by gem19:
+
+  sudo gem19 install stash-magic 
+
 = How to use
 
 First you have to require the module:
 
-	require 'stash_magic'
-	
+  require 'stash_magic'
+  
 And then inside your model class, you have to include the module and declare where your public directory is:
 
-	class Treasure < ::Sequel::Model
-	  include ::StashMagic
-	  self.public_root = ::File.expand_path(::File.dirname(__FILE__)+'/public')
-	end
-	
+  class Treasure < ::Sequel::Model
+    include ::StashMagic
+    self.public_root = ::File.expand_path(::File.dirname(__FILE__)+'/public')
+  end
+  
 The module has a method to do both in one line though:
 
-	class Treasure < ::Sequel::Model
-	  ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
-	end
-	
+  class Treasure < ::Sequel::Model
+    ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
+  end
+  
 After that, for each attachment you want, you need to have a column in the database as a string. And then you declare them with method Model#stash:
 
-	class Treasure < ::Sequel::Model
-	  ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
-		
-	  stash :map
-	  stash :stamp
-	end
-	
+  class Treasure < ::Sequel::Model
+    ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
+    
+    stash :map
+    stash :stamp
+  end
+  
 This method accepts an optional hash as a second argument which is not used by the module itself, but could be handy for you as you can have it in the stash reflection:
 
-	class Treasure < ::Sequel::Model
-	  ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
-		
-	  stash :map
-	  stash :stamp, :accept_gif => false, :limit => 512000
-	end
-	
+  class Treasure < ::Sequel::Model
+    ::StashMagic.with_public_root ::File.expand_path(::File.dirname(__FILE__)+'/public')
+    
+    stash :map
+    stash :stamp, :accept_gif => false, :limit => 512000
+  end
+  
 The method Treasure.stash_reflection would return:
 
-	{ 
-	  :map => {}, 
-	  :stamp => {:accept_gif => false, :limit => 512000} 
-	}
-	
+  { 
+    :map => {}, 
+    :stamp => {:accept_gif => false, :limit => 512000} 
+  }
+  
 When building your html forms, just make sure that your stash inputs are of the type 'file', and StashMagic will deal with everything else. The getters will return a hash with the following values:
 
-	@treasure_instance.map    # { :name => 'map.pdf', :type => 'application/pdf', :size => 1024 }
-	@treasure_instance.stamp  # nil if there is no stamp yet
-	
+  @treasure_instance.map    # { :name => 'map.pdf', :type => 'application/pdf', :size => 1024 }
+  @treasure_instance.stamp  # nil if there is no stamp yet
+  
 Please note that the file name will always be the name of the attachment with the extention of the file you've uploaded (pdf, jpg ...) 
 This makes StashMagic internals a lot easier for dealing with styles (ex: thumbnails) as we'll see later.
-	
+  
 You can also use the setters to delete an attachment:
 
-	@treasure_instance.map = nil   # Will delete this attachment as expected
-	
+  @treasure_instance.map = nil   # Will delete this attachment as expected
+  
 When you want to use attachment in your application, you can retrieve the file url like that:
 
-	@treasure_instance.file_url(:map)                # The original file
-	@treasure_instance.file_url(:map, 'thumb.gif')   # The picture in a thumb.gif style (see next chapter to learn about styles)
-	
+  @treasure_instance.file_url(:map)                # The original file
+  @treasure_instance.file_url(:map, 'thumb.gif')   # The picture in a thumb.gif style (see next chapter to learn about styles)
+  
 You might also want to do things on the server side like changing rights on the image or whatever. For that purpose, there is a third argument which is a boolean. When set to true, it will give you the absolute path to the file:
 
-	@treasure_instance.file_url(:map, nil, true)            # /absolute/path/to/public/stash/Treasure/1/map.pdf
-	@treasure_instance.file_url(:map, 'thumb.gif', true)    # /absolute/path/to/public/stash/Treasure/1/map.thumb.gif
-	
+  @treasure_instance.file_url(:map, nil, true)            # /absolute/path/to/public/stash/Treasure/1/map.pdf
+  @treasure_instance.file_url(:map, 'thumb.gif', true)    # /absolute/path/to/public/stash/Treasure/1/map.thumb.gif
+  
 = Thumbnails and Other Styles
 
 One of the main requirements of StashMagic was to provide a way to deal quite easily with styles, and to deal with them whenever you want to, not only automaticaly when you save an attachment. The reason for that last point is because I was working at the same time on a cropping tool and realized That I needed to be able to create styles whenever I wanted without changing the way my attachment manager works.
@@ -88,8 +104,8 @@ The simpliest solution I came up with was to be quite strict with names. So far,
 
 Say for example you have an attachment called :portrait and you want a version called "mini" which is gonna be a gif. Your style should be called:
 
-	mini.gif
-	
+  mini.gif
+  
 I just find it makes sense and saves one argument on some methods that are already verbose.
 
 Now if you really want to create styles, you need to have ImageMagick installed. ImageMagick is a very good and complete graphic library. You'll find more on the link below, but for the time being, just think of it as a Photoshop in command line:
@@ -105,8 +121,8 @@ Even though StashMagic provides a builder for ImageMagick scripts, I suggest you
 
 So for the couragous amongst you, here is the way you create a very simple style for the portrait attachment:
 
-	@treasure_instance.convert :portrait, '-resize 100x75', 'mini.gif'
-	
+  @treasure_instance.convert :portrait, '-resize 100x75', 'mini.gif'
+  
 The middle argument is the piece of script used in the main ImageMagick command called: convert
 It is everything that happens between the source and the destination (hence its position in the list of arguments).
 
@@ -116,10 +132,10 @@ This will create your mini version of the portrait. The url for this image will
 
 If you master ImageMagick, you can really do a lot with that. Nevertheless here is what you can use, as I have to admit that some things like geometry are not easy to get the first time. Here is the so-called string builder:
 
-	@treasure_instance.image_magick :portrait, 'mini.gif' do
+  @treasure_instance.image_magick :portrait, 'mini.gif' do
     im_resize(100, 75)
-	end
-	
+  end
+  
 Not really much easier huh ?!?
 
 Ok so in the builder, you can use some pre-defined operations (prefixed with 'im_' standing for ImageMagick) that will occur in the order you write them. It is quite limited for the moment, but I will complete the list in time. Here is that list:
@@ -128,7 +144,7 @@ Ok so in the builder, you can use some pre-defined operations (prefixed with 'im
 
 This is the most simple one. It is for when you know how to write a piece of the script. For example you could use:
 
-	im_write("-negate")
+  im_write("-negate")
 
 It will negate the image at this stage.
 
@@ -164,35 +180,65 @@ Simply negate the image
 
 Here a more complete example for the builder:
 
-	@treasure_instance.image_magick :portrait, 'mini.gif' do
-	  im_negate
+  @treasure_instance.image_magick :portrait, 'mini.gif' do
+    im_negate
     im_crop(200,100,20,10)
     im_resize(200, 100, '^', 'North')
-	end
-	
+  end
+  
 Which will secretly do something like:
 
-	convert /path/to/portrait.jpg -negate -crop 200x100+20+10 +repage -resize '200x100^' -gravity North -extent 200x100 /path/to/portrait.mini.gif
-	
+  convert /path/to/portrait.jpg -negate -crop 200x100+20+10 +repage -resize '200x100^' -gravity North -extent 200x100 /path/to/portrait.mini.gif
+  
 = How to create thumbnails on the flight (The Hook)
 
 It is of course possible. StashMagic provides a hook called after_stash which takes the attachment_name as an argument. This hook is implemented by default and create automaticaly for every image a thumbnail called 'stash_thumb.gif'.
 
 What you have to do is overwrite the hook. For example, say you want every attachment to have a 200x200 perfect squared version:
 
-	after_stash(attachment_name)
-	  image_magick(attachment_name, 'square.jpg') { im_resize(200, 200, '^') }
-	end
-	
+  after_stash(attachment_name)
+    image_magick(attachment_name, 'square.jpg') { im_resize(200, 200, '^') }
+  end
+  
 Of course you can do something different for any attachment. You just need to use the attachment name in a case statement for example. Or you can do something different depending on the type of file using the getters. For example:
 
-	after_stash(attachment_name)
-	  attachment_hash = self.send(attachment_name)
-	  image_magick(attachment_name, 'square.jpg') { im_resize(200, 200, '^') } if attachment_hash[:type][/^image\//]
-	end
-	
+  after_stash(attachment_name)
+    attachment_hash = self.send(attachment_name)
+    image_magick(attachment_name, 'square.jpg') { im_resize(200, 200, '^') } if attachment_hash[:type][/^image\//]
+  end
+  
 Will do the same but only if the mime type of the file starts with 'image/' (which means it's an image).
 
+= How my files are then saved on my file system
+
+I like to believe that one don't have to think about that as long as the module provides enough methods to do what you need to do.
+Nevertheless, here is how files are organized:
+
+First of all, StashMagic puts everything it has in a folder called 'stash', so that if you use a deployment system, only one location is not to deploy on the live version. For example, while using Git, your .gitignore would have this line:
+
+  public/stash/*
+
+After that, you've got one folder per model class. And inside this folder, one folder per entry simply named after its ID number. At the end point, you have the attachments, named after the attachment name, and the extention is the original extention if that is the main file, or the style name if this is a style. Here is an example:
+
+  |
+  +- public
+     +- stash
+        +- Treasure
+           +- 1
+           |  +- map.jpg
+           |  +- map.mini.gif
+           |  +- instructions.pdf
+           |  \- instructions.cover.jpg 
+           \- 2
+              +- map.jpg
+              +- map.mini.gif
+              +- instructions.pdf
+              \- instructions.cover.jpg
+
+Please note that the class name is a simple #to_s. I've realized recently that methods like underscore or pluralize are computing for nothing in 99% of cases. I might consider them better when they will be in the Standard library. But as a side effect, try to avoid class names that are spelled the same once lowercased, as systems (at least unix based) are not case sensitive. I can give you an example straight away:
+
+  BootStrap
+  BootsTrap 
 
 = More Details
 
@@ -207,6 +253,7 @@ The project is speced with
 
 - 0.0.1   Begins
 - 0.0.2   Add im_negate to the ImageMagick builder
+- 0.0.3   Fix image destruction when there is nothing to destroy
 
 == Copyright
 

data/spec.rb

@@ -199,6 +199,11 @@ describe ::StashMagic do
     F.exists?(Treasure::PUBLIC+'/stash/Treasure/'+@t.id.to_s+'/instructions.pdf').should==true
   end
   
+  it "Should not raise when the setter tries to destroy files when there is nothing to destroy" do
+    lambda { @t = Treasure.create(:instructions=>nil) }.should.not.raise
+    lambda { @t.update(:instructions=>nil) }.should.not.raise
+  end
+  
   it "Should have ImageMagick string builder" do
     @t = Treasure.create(:map=>@img)
     

data/stash_magic.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s| 
   s.name = 'stash-magic'
-  s.version = "0.0.2"
+  s.version = "0.0.3"
   s.platform = Gem::Platform::RUBY
   s.summary = "Simple Attachment Manager"
   s.description = "A simple attachment system that also handles thumbnails or other styles via ImageMagick. Originaly tested on Sequel ORM but purposedly easy to plug to something else."

data/stash_magic.rb

@@ -33,12 +33,12 @@ module StashMagic
         #   :name=>"model[attachment]"
         # }
         #
-        # GETTER
+        # SETTER
         define_method name.to_s+'='  do |upload_hash|
           return if upload_hash=="" # File in the form is unchanged
           
           if upload_hash.nil?
-            destroy_files_for(name)
+            destroy_files_for(name) unless self.send(name).nil?
             super('')
           else
           
@@ -53,7 +53,7 @@ module StashMagic
             
           end
         end
-        # SETTER
+        # GETTER
         define_method name.to_s do
           eval(super.to_s)
         end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: stash-magic
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Mickael Riga
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-18 00:00:00 +01:00
+date: 2010-12-08 00:00:00 +00:00
 default_executable: 
 dependencies: []