h1. Scribd_fu

A Ruby on Rails plugin that streamlines interaction with the Scribd service (scribd.com), and even works Attachment_fu or Paperclip!

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 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. 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 config/environment.rb:

<pre>config.gem ‘mdarby-scribd_fu’, :lib => ‘scribd_fu’</pre>

Note that this will only work if you have gems.github.com in your list of gem sources:

<pre>$ gem source -a gems.github.com</pre>

Then run:

<pre>$ sudo rake gems:install</pre>

To install it and the rscribd gem. If you don’t add github as a gem source, you can add the :source option to the config.gem call; however, this means you will have to separately require the rscribd gem, since using :source will not search for the rscribd gem in your regular sources.

Then, install either Paperclip or Attachment_fu.

h3. Attachment_fu

If you want to install Attachment_fu, you should probably use the git repository on github:

<pre>$ script/plugin install git://github.com/technoweenie/attachment_fu.git</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.

h2. How to Use

h3. Shared steps

• Sign up for Scribd (it’s totally free) at www.scribd.com/publisher/signup_api.

• Run script/generate scribd_config 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>

Add the following fields into a new migration for the target model (and run the migration!):

<pre>t.integer :scribd_id t.string :scribd_access_key</pre>

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 complete 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): <pre><%= display_scribd(@document) %></pre> That’s it!

h3. Paperclip

For each attachment that you want to be scribdable, mark it using the has_scribdable_attachment method. For example, if I had the line:

<pre>has_attached_file :document</pre>

And I wanted the document 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 _scribd_id and _scribd_access_key, 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 validates_attachment_scribdability 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:

• 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):

<pre><%= display_scribd(@model, :document) %></pre>

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.

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.

Feel free to check out my “blog”:blgo.matt-darby.com or to “recommend me”:workingwithrails.com