A Ruby on Rails plugin that streamlines interaction with the Scribd service (scribd.com), and even works with attachment_fu or Paperclip!
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.
Scribd_fu requires the rscribd gem for talking to scribd, and either the wicked awesome attachment_fu plugin or the equally awesome Paperclip plugin.
If you’re using Rails 2.1 or greater, you probably want to add rscribd to your required gems. Add this line to config/environment.rb in the initializer block:
config.gem 'rscribd'
Once you do this, you can just do:
$ rake gems:install
Instead of running the gem install below.
If you’re using Rails pre-2.1:
$ gem install rscribd
If you want to install attachment_fu, you should probably use the git repository on github. If you’re using Rails 2.1 or greater:
$ script/plugin install git://github.com/technoweenie/attachment_fu.git
Otherwise, clone the git repository into your app’s vendor/plugins directory:
$ cd vendor/plugins && git clone git://github.com/technoweenie/attachment_fu.git
And remember to get rid of the .git directory:
$ rm -Rf attachment_fu/.git
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:
config.gem 'paperclip'
Then run:
$ rake gems:install
To install it.
If you’re using Rails pre-2.1, you can still get it as a plugin by cloning the git repository into your app’s vendor/plugins directory:
$ cd vendor/plugins && git clone git://github.com/thoughtbot/paperclip.git
And remember to get rid of the .git directory:
$ rm -Rf paperclip/.git
-
Sign up for Scribd (it’s totally free) at www.scribd.com/publisher/signup_api.
-
Copy the vendor/plugins/scribd_fu/scribd.yml.example file to config/scribd.yml and fill it out with your Scribd login credentials.
Enter the below line into any attachment_fu-using model whose attachment you’d like to Scribdify:
acts_as_scribd_document
Add the following fields into a new migration for the target model (and update your schema!):
t.integer :scribd_id t.string :scribd_access_key
Scribd_fu will use these to track scribd-related information.
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.
Scribd_fu also provides the validates_as_scribd_document validation, which verifies that the document’s information is being saved correctly (i.e., that the content_type, scribd_id, and scribd_access_key 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).
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 conversion_complete?, conversion_successful?, and conversion_error? 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 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 @document is an object of your Scribd/Attachment_fu model):
<%= display_scribd(@document) %>
That’s it!
For each attachment that you want to be scribdable, mark it using the has_scribdable_attachment method. For example, if I had the line:
has_attached_file :document
And I wanted the document attachment to be scribdable, I would add:
has_scribdable_attachment :document
In addition, you have to add two columns for each scribdable attachment. These are _scribd_id and _scribd_access_key, both prefixed by the attachment name. For the above example, we would have the following migration statements:
t.integer :document_scribd_id t.string :document_scribd_access_key
Scribdable attachments can also be validated using the validates_attachment_scribdability validation:
validates_attachment_scribdability :document
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:
-
conversion_complete?– e.g.,model.conversion_complete?(:document) -
conversion_successful?– e.g.,model.conversion_successful?(:document) -
conversion_error?– e.g.,model.conversion_error?(: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 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 @model is an object of your Scribd/Paperclip model, and document is the name of the scribdable attachment):
<%= display_scribd(@model, :document) %>
That’s it!
You can make your Scribd documents private or public, to choose, just modify the scribd.yml file and enter ‘private’ or ‘public’ in the ‘access’ key.
My name is Matt Darby. I’m a 28 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.
Feel free to check out my blog (blog.matt-darby.com) or to recommend me on workingwithrails.com