generators/scribd_fu/scribd_fu_generator.rb generators/scribd_fu/templates/scribd_fu.yml lib/scribd_fu/attachment_fu.rb lib/scribd_fu/paperclip.rb spec/database.yml spec/scribd_fu.yml spec/scribd_fu_spec.rb spec/spec_helper.rb @@ -1,191 +1,64 @@ h1. Scribd_fu -A Ruby on Rails plugin that streamlines interaction with the Scribd service -(scribd.com), and even works Attachment_fu or Paperclip! +A Ruby on Rails plugin that streamlines interaction with Scribd.com's iPaper service, and works along side of either Attachment_fu or Paperclip +h1. Big Changes! v2.0 OMGZ! -h2. What it does +Please make sure to read below if you're using an older version of ScribdFu. Pretty much everything has changed. Don't fret, it's now easier and cleaner. ScribdFu has been taken out into the backyard and given a thorough scrubbing. It's now lean, mean, fully tested, and works beautifully with Attachment_fu, Paperclip, and Amazon's S3 service. -Scribd_fu hides out in the shadows like a document converting ninja, just -waiting to process your data into a convenient Flash format (like YouTube) with -the help of the black majick of Scribd.com. Imagine embedding huge documents -right inline with your web UI, no downloading, no necessary programs on the -client side (except for Flash) to view your data. It's pretty damned cool. +h2. What it does +Scribd_fu hides out in the shadows like a document converting ninja, just waiting to process your data into a convenient Flash format (like YouTube) with the help of the black majick of Scribd.com. Imagine embedding documents inline with your web UI &mdash; no downloading, no required programs on the client side (except for Flash) to view your data. It's pretty damned cool, and free to boot! h2. Requirements -Scribd_fu requires the rscribd gem for talking to scribd, and either the wicked -awesome Attachment_fu plugin or the equally awesome Paperclip plugin. - - -h2. How to Install & Use - -Scribd_fu depends on rscribd, so installing it as a gem should also pull in -rscribd. First, add Scribd_fu to your list of gems in -<tt>config/environment.rb</tt>: - -<pre>config.gem 'mdarby-scribd_fu', :lib => 'scribd_fu'</pre> - -Note that this will only work if you have http://gems.github.com in your list of -gem sources: - -<pre>$ gem source -a http://gems.github.com</pre> - -Then run: - -<pre>$ sudo rake gems:install</pre> +Scribd_fu requires the rscribd gem via @sudo gem install rscribd@ (along with either the Attachment_fu plugin or the Paperclip gem) -To install it and the rscribd gem. If you don't add github as a gem source, you -can add the <tt>:source</tt> option to the <tt>config.gem</tt> call; however, -this means you will have to separately require the rscribd gem, since using -<tt>:source</tt> will not search for the rscribd gem in your regular sources. +h2. How to Install -Then, install either Paperclip or Attachment_fu. +h3. ScribdFu requires a base plugin -h3. Attachment_fu +ScribdFu is awesome, but it needs help from either "Attachment_fu":http://github.com/technoweenie/attachment_fu/tree/master or "Paperclip":http://github.com/thoughtbot/paperclip/tree/master -If you want to install Attachment_fu, you should probably use the git -repository on github: +h3. Install ScribdFu -<pre>$ script/plugin install git://github.com/technoweenie/attachment_fu.git</pre> +<pre>sudo gem install mdarby-scribd_fu --source 'http://gems.github.com'</pre> -h3. Paperclip - -If you'd rather use Paperclip (the most important advantage, with respect to -Scribd_fu, will be being able to have more than one document-related column in a -single model), you should probably require it as a gem dependency rather than -using it in plugin form. In Rails 2.1 or greater: - -<pre>config.gem 'paperclip'</pre> - -Then run: - -<pre>$ rake gems:install</pre> - -To install it. +h3. Add ScribdFu to your environment.rb +<pre>config.gem 'mdarby-scribd_fu', :lib => 'scribd_fu', :source => 'http://gems.github.com'</pre> h2. How to Use -h3. Shared steps - -* Sign up for Scribd (it's totally free) at - http://www.scribd.com/publisher/signup_api. -* Run <tt>script/generate scribd_config</tt> and fill out the new - config/scribd.yml file with your Scribd login credentials. - -h3. Attachment_fu - -Enter the below line into any attachment_fu-using model whose attachment you'd like to -Scribdify: - -<pre>acts_as_scribd_document</pre> +* Sign up for "Scribd.com's API access":http://www.scribd.com/developers/signup_api (it's totally free) -Add the following fields into a new migration for the target model (and run the -migration!): +* Run @./script/generate scribd_fu_config@ and fill out @config/scribd_fu.yml@ file with your Scribd account info. -<pre>t.integer :scribd_id -t.string :scribd_access_key</pre> +* If you're using AttachmentFu, add @has_ipaper_and_uses 'AttachmentFu'@ to your model that uses ScribdFu -Scribd_fu will use these to track scribd-related information. +* If you're using Paperclip, add @has_ipaper_and_uses 'Paperclip'@ to your model that uses ScribdFu -Now, when you upload a file to that model, Scribd_fu will automatically handle -the scribd side of things for you. No muss, no fuss. Files are uploaded to -scribd when the model is saved. If the file fails to upload to scribd, the model -save will fail. +* Add the following fields into a new migration for the target model: -Scribd_fu also provides the <tt>validates_as_scribd_document</tt> validation, -which verifies that the document's information is being saved correctly (i.e., -that the <tt>content_type</tt>, <tt>scribd_id</tt>, and -<tt>scribd_access_key</tt> are present) and that the attachment is scribdable to -begin with (that is to say, that the content type of the file is a scribdable -content type). +<pre> + t.integer :ipaper_id + t.string :ipaper_access_key +</pre> -Note that Scribd_fu will only upload the file to Scribd. Scribd then has to -convert it to their iPaper format. Usually this is a pretty fast operation, but -if you want to be safe or have a contingency plan in case someone tries to -access the document and it isn't converted yet, the set of methods -<tt>conversion_complete?</tt>, <tt>conversion_successful?</tt>, and -<tt>conversion_error?</tt> can be used to determine the current conversion -status of the document. Also note that if you try to display a file that hasn't -been converted to scribd yet, the iPaper viewer will actually say that it is -still converting complete with a spinner, so these methods will often not be -necessary. +Scribd_fu will use these to track Scribd-related information. -To view a Scribd document, just throw the below code into your view (where -<tt>@document</tt> is an object of your Scribd/Attachment_fu model): -<pre><%= display_scribd(@document) %></pre> -That's it! +Now, when you upload a file to that model, Scribd_fu will automatically handle the Scribd side of things for you. Files are uploaded to Scribd after the model is saved. No muss, no fuss. Scribd's conversion of your document is usally quite fast, but if you want a contingency plan, the @conversion_processing?@, @conversion_complete?@, @conversion_successful?@, and @conversion_error?@ instance methods can be used to determine the conversion status of the document. -h3. Paperclip - -For each attachment that you want to be scribdable, mark it using the -<tt>has_scribdable_attachment</tt> method. For example, if I had the line: - -<pre>has_attached_file :document</pre> - -And I wanted the <tt>document</tt> attachment to be scribdable, I would add: - -<pre>has_scribdable_attachment :document</pre> - -In addition, you have to add two columns for each scribdable attachment. These -are <tt>_scribd_id</tt> and <tt>_scribd_access_key</tt>, both prefixed by the -attachment name. For the above example, we would have the following migration -statements: - -<pre>t.integer :document_scribd_id -t.string :document_scribd_access_key</pre> - -Scribdable attachments can also be validated using the -<tt>validates_attachment_scribdability</tt> validation: - -<pre>validates_attachment_scribdability :document</pre> - -This validation checks that the content type, scribd id, and access key are all -available, and it verifies that the content type is a scribdable content type. - -As mentioned in the Attachment_fu section, Scribd_fu will only upload the file -to Scribd. Scribd then has to do the actual conversion to iPaper. For tracking -the status of this conversion, you have three methods, each of which take the -attachment whose status you want: - -* <tt>conversion_complete?</tt> -- e.g., - <tt>model.conversion_complete?(:document)</tt> -* <tt>conversion_successful?</tt> -- e.g., - <tt>model.conversion_successful?(:document)</tt> -* <tt>conversion_error?</tt> -- e.g., - <tt>model.conversion_error?(:document)</tt> - -Also note that if you try to display a file that hasn't been converted to scribd -yet, the iPaper viewer will actually say that it is still converting with a -spinner, so these methods will often not be necessary. - -To view a Scribd document, just throw the below code into your view (where -<tt>@model</tt> is an object of your Scribd/Paperclip model, and -<tt>document</tt> is the name of the scribdable attachment): - -<pre><%= display_scribd(@model, :document) %></pre> - -That's it! +h2. Viewing the iPaper Document +Just add @<%= document.display_ipaper %>@ into your view (where @document@ is an object of your ScribdFu model). That's it! h2. Access -You can set the default access on all documents by setting the 'access' key in -the scribd.yml file to either 'private' or 'public'. - -You can also override the default access level and control access on a -per-document basis by setting the 'is_public' attribute to either true or false. -If this column is not defined, the default option in the scribd.yml will be -used. - -Please note that setting the access level only works before the document is -initially uploaded to Scribd. - +You can set the access level on all documents by setting the @access@ key in the scribd_fu.yml file to either 'private' or 'public'. ScribdFu assumes that you'd like to keep your documents private. h2. About the Author -My name is Matt Darby. I’m a 29 year old professional Web Developer and IT Manager. I am the IT Manager and Lead Web Developer at Dynamix Engineering and recently earned a Master’s Degree in Computer Science from Franklin University in Columbus, OH. +My name is "Matt Darby.":http://blog.matt-darby.com I’m an IT Manager and pro-web-dev at for "Dynamix Engineering":http://dynamix-ltd.com and hold a Master’s Degree in Computer Science from "Franklin University":http://www.franklin.edu in sunny "Columbus, OH.":http://en.wikipedia.org/wiki/Columbus,_Ohio -Feel free to check out my "blog":http://blgo.matt-darby.com or to "recommend me":http://workingwithrails.com +Feel free to check out my "blog":http://blog.matt-darby.com or "recommend me":http://www.workingwithrails.com/person/10908-matt-darby README.textile @@ -1 +1 @@ -require File.dirname(__FILE__) + "/rails/init" +require File.join(File.dirname(__FILE__), "lib", "scribd_fu") \ No newline at end of file init.rb @@ -1,108 +1,250 @@ -require 'attachment_fu/methods' -require 'paperclip/methods' - module ScribdFu - # A list of content types supported by scribd. - CONTENT_TYPES = ['application/pdf', 'image/jpeg', 'image/pjpeg', - 'image/gif', 'image/png', 'image/x-png', 'image/jpg', - 'application/msword', 'application/mspowerpoint', - 'application/vnd.ms-powerpoint', 'application/excel', - 'application/vnd.ms-excel', 'application/postscript', - 'text/plain', 'application/rtf', - 'application/vnd.oasis.opendocument.text', - 'application/vnd.oasis.opendocument.presentation', - 'application/vnd.oasis.opendocument.spreadsheet', - 'application/vnd.sun.xml.writer', - 'application/vnd.sun.xml.impress', - 'application/vnd.sun.xml.calc', - # OOXML, AKA `the MIME types from hell'. Seriously, these are long enough to - # start their own dictionary... + + ConfigPath = "#{RAILS_ROOT}/config/scribd_fu.yml".freeze + + # A list of content types supported by iPaper. + ContentTypes = [ + 'application/pdf', + 'application/msword', + 'application/mspowerpoint', + 'application/vnd.ms-powerpoint', + 'application/excel', + 'application/vnd.ms-excel', + 'application/postscript', + 'text/plain', + 'application/rtf', + 'application/vnd.oasis.opendocument.text', + 'application/vnd.oasis.opendocument.presentation', + 'application/vnd.oasis.opendocument.spreadsheet', + 'application/vnd.sun.xml.writer', + 'application/vnd.sun.xml.impress', + 'application/vnd.sun.xml.calc', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.openxmlformats-officedocument.spreadsheetml.template', 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'application/vnd.openxmlformats-officedocument.presentationml.slideshow', 'application/vnd.openxmlformats-officedocument.presentationml.template', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', - 'application/vnd.openxmlformats-officedocument.wordprocessingml.template'] + 'application/vnd.openxmlformats-officedocument.wordprocessingml.template' + ] + + # Available parameters for the JS API + # http://www.scribd.com/publisher/api/api?method_name=Javascript+API + Available_JS_Params = [ :height, :width, :page, :my_user_id, :search_query, + :jsapi_version, :disable_related_docs, :mode, :auto_size ] - def self.included(base) - base.extend ActsAsScribdDocument + class ScribdFuError < StandardError #:nodoc: end - module ActsAsScribdDocument - # Synonym for <tt>has_scribdable_attachment(nil)</tt>. - def acts_as_scribd_document - has_scribdable_attachment + class ScribdFuUploadError < ScribdFuError #:nodoc: + end + + + class << self + + def included(base) #:nodoc: + base.extend ClassMethods end - # Marks the given +attribute+ as a scribdable document file. If +attribute+ - # is nil, assumes this is an Attachment_fu model and deals with the setup - # accordingly; otherwise, assumes a +paperclip+ model and sets up scribding - # related to the particular given attribute. - def has_scribdable_attachment(attribute = nil) - class_eval do - include ScribdFu::InstanceMethods + # Login, store, and return a handle to the Scribd user account + def scribd_user + begin + # Ensure we can login to Scribd, and get a handle on the account + Scribd::API.instance.key = config[:key] + Scribd::API.instance.secret = config[:secret] + @scribd_user = Scribd::User.login(config[:user], config[:password]) + rescue + raise ScribdFuError, "Your Scribd credentials are incorrect" + end + end - if attribute.nil? - include ScribdFu::AttachmentFu::InstanceMethods - else - include ScribdFu::Paperclip::InstanceMethods # ignored if already done + # Upload a file to Scribd + def upload(obj, file_path) + begin + res = scribd_user.upload(:file => "#{file_path}", :access => access_level) + obj.update_attributes({:ipaper_id => res.doc_id, :ipaper_access_key => res.access_key}) + rescue + raise ScribdFuUploadError, "Sorry, but #{obj.class} ##{obj.id} could not be uploaded to Scribd" + end + end - add_scribd_attribute attribute # class method added by above include - end + # Delete an iPaper document + def destroy(document) + document.destroy + end + + # Read, store, and return the ScribdFu config file's contents + def config + raise ScribdFuError, "#{ConfigPath} does not exist" unless File.file?(ConfigPath) + + # Load the config file and strip any whitespace from the values + @config ||= YAML.load_file(ConfigPath).each_pair{|k,v| {k=>v.to_s.strip}}.symbolize_keys! + end + + # Get the preferred access level for iPaper documents + def access_level + config[:access] || 'private' + end + + # Load, store, and return the associated iPaper document + def load_ipaper_document(id) + begin + @document ||= scribd_user.find_document(id) + rescue + raise ScribdFuError, "Scribd Document ##{id} not found!" end end + end - module InstanceMethods - # Sets up Scribd configuration info when this module is included. - def self.included(base) - base.extend ClassMethods + module ClassMethods - mattr_reader :scribd_config, :scribd_login + # Load and inject ScribdFu goodies + def has_ipaper_and_uses(str) + check_environment + load_base_plugin(str) - begin - require 'rscribd' - rescue LoadError - raise RequiredLibraryNotFoundError.new('rscribd could not be loaded') + include InstanceMethods + + after_save :upload_to_scribd # This *MUST* be an after_save + before_destroy :destroy_ipaper_document + end + + private + + # Configure ScribdFu for this particular environment + def check_environment + load_rscribd + check_config + check_fields end - begin - unless @@scribd_login - @@scribd_config = YAML.load_file("#{RAILS_ROOT}/config/scribd.yml").symbolize_keys - @@scribd_config = @@scribd_config[:scribd] + def check_config + ScribdFu::config + end - # Ensure we can connect to the Service - Scribd::API.instance.key = @@scribd_config['key'].to_s.strip - Scribd::API.instance.secret = @@scribd_config['secret'].to_s.strip + # Load the rscribd gem + def load_rscribd + begin + require 'rscribd' + rescue LoadError + raise ScribdFuError, 'Please install the rscribd gem' + end + end - @@scribd_login = Scribd::User.login @@scribd_config['user'].to_s.strip, @@scribd_config['password'].to_s.strip + # Load Attachment_Fu specific methods and files + def load_attachment_fu + require 'scribd_fu/attachment_fu' + include ScribdFu::AttachmentFu::InstanceMethods + end + + # Load Paperclip specific methods and files + def load_paperclip + require 'scribd_fu/paperclip' + include ScribdFu::Paperclip::InstanceMethods + end + + # Ensure ScribdFu-centric attributes exist + def check_fields + fields = %w{ipaper_id ipaper_access_key}.inject([]){|stack, f| stack << "#{name}##{f}" unless column_names.include?(f); stack} + raise ScribdFuError, "These fields are missing: #{fields.to_sentence}" if fields.size > 0 + end + + # Load either AttachmentFu or Paperclip-specific methods + def load_base_plugin(str) + if str == 'AttachmentFu' + load_attachment_fu + elsif str == 'Paperclip' + load_paperclip + else + raise ScribdFuError, "Sorry, only Attachment_fu and Paperclip are supported." end - rescue - raise "config/scribd.yml file not found, or your credentials are incorrect." end + + end + + module InstanceMethods + + def self.included(base) + base.extend ClassMethods end - def access_level - if self.respond_to?(:is_public) && self.is_public != nil - scribd_access = self.is_public ? 'public' : 'private' - else - scribd_access = scribd_config['access'] - end + # Upload the associated file to Scribd for iPaper conversion + # This is called +after_save+ and cannot be called earlier, + # so don't get any ideas. + def upload_to_scribd + ScribdFu::upload(self, file_path) if scribdable? + end - scribd_access + # Checks whether the associated file is convertable to iPaper + def scribdable? + ContentTypes.include?(get_content_type) && ipaper_id.blank? end - end - module ClassMethods - # Sets up the scribd_options accessor, a before_destroy hook to ensure the - # deletion of associated Scribd documents, and an after_save hook to upload - # to scribd. - def self.extended(base) - base.class_inheritable_accessor :scribd_options + # Responds true if the conversion is converting + def conversion_processing? + !(conversion_complete? || conversion_successful? || conversion_error?) + end - base.before_destroy :destroy_scribd_documents - base.before_validation :upload_to_scribd + # Responds true if the conversion is complete -- note that this gives no + # indication as to whether the conversion had an error or was succesful, + # just that the conversion completed. + def conversion_complete? + ipaper_document && ipaper_document.conversion_status != 'PROCESSING' end + + # Responds true if the document has been converted. + def conversion_successful? + ipaper_document && ipaper_document.conversion_status =~ /^DISPLAYABLE|DONE$/ + end + + # Responds true if there was a conversion error while converting to iPaper. + def conversion_error? + ipaper_document && ipaper_document.conversion_status == 'ERROR' + end + + # Responds the Scribd::Document associated with this model, or nil if it does not exist. + def ipaper_document + @document ||= ScribdFu::load_ipaper_document(ipaper_id) + end + + # Destroys the scribd document for this record. This is called +before_destroy+ + def destroy_ipaper_document + ScribdFu::destroy(ipaper_document) if ipaper_document + end + + # Display the iPaper document in a view + def display_ipaper(options = {}) + alt = options.has_key?(:alt) ? options[:alt] : "" + + <<-END + <script type="text/javascript" src="http://www.scribd.com/javascripts/view.js"></script> + <div id="embedded_flash">#{alt}</div> + <script type="text/javascript"> + var scribd_doc = scribd.Document.getDoc(#{ipaper_id}, '#{ipaper_access_key}'); + #{js_params(options)} + scribd_doc.write("embedded_flash"); + </script> + END + end + + + private + + # Check and collect any Javascript params that might have been passed in + def js_params(options) + opt = [] + + options.each_pair do |k, v| + opt << "scribd_doc.addParam('#{k}', '#{v}');" if Available_JS_Params.include?(k) + end + + opt.compact.join("\n") + end + end + end + +# Let's do this. +ActiveRecord::Base.send(:include, ScribdFu) if Object.const_defined?("ActiveRecord") \ No newline at end of file lib/scribd_fu.rb @@ -1,7 +1,7 @@ Gem::Specification.new do |s| s.name = "scribd_fu" - s.version = "1.2.3.2" - s.date = "2009-03-18" + s.version = "2.0" + s.date = "2009-03-29" s.summary = "Quick and easy interactions with Scribd's iPaper service" s.email = "matt@matt-darby.com" s.homepage = "http://github.com/mdarby/scribd_fu/tree/master" scribd_fu.gemspec README Rakefile generators/scribd_config/scribd_config_generator.rb generators/scribd_config/templates/scribd.yml install.rb lib/attachment_fu/methods.rb lib/paperclip/methods.rb lib/scribd_fu_helper.rb rails/init.rb uninstall.rb 0f7d1c4fd15303b901e61e9be514f83cb6f07dcd Matt Darby matt@matt-darby.com http://github.com/mdarby/scribd_fu/commit/446846151cf1c86ae833b89ce5318a224708d619 446846151cf1c86ae833b89ce5318a224708d619 2009-03-29T06:31:17-07:00 2009-03-29T06:31:17-07:00 ScribdFu v2.0 has landed ScribdFu has been completely rewritten and spec'd. It now works seamlessly with AttachmentFu, Paperclip, and Amazon S3. Its implementation and usage has been thoroughly refactored and simplified. 056d01c60d41d4d62b8c9d4e916db4fedb586402 Matt Darby matt@matt-darby.com