kpitn / scribd_fu

A Ruby on Rails plugin that streamlines interactions with the Scribd service

Scribd_fu

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

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.

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.

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:

config.gem 'mdarby-scribd_fu', :lib => 'scribd_fu'

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

$ gem source -a http://gems.github.com

Then run:

$ sudo rake gems:install

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.

Attachment_fu

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

$ script/plugin install git://github.com/technoweenie/attachment_fu.git

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:

config.gem 'paperclip'

Then run:

$ rake gems:install

To install it.

How to Use

Shared steps

• Sign up for Scribd (it’s totally free) at
  http://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.

Attachment_fu

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 run the
migration!):

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 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</tt> is an object of your Scribd/Attachment_fu model): <pre><%= display_scribd(document) %>
That’s it!

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:

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_accesskey, 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!

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.

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 or to recommend me