It used to be you would monkeypatch the CGI class to get Flash uploaders to work due to issues with Flash. With the introduction of Rack in Rails 2.3 things now work quite differently. What we will do is create some rack middleware to intercept traffic from Flash to deal with it’s quirks. I have created a small example application of an mp3 player and uploader. You will probably want to download it, as it contains a few files not displayed in this article. You can clone it from the github project page.

First lets create a simple Song model:

./script generate model Song title:string artist:string length_in_seceonds:integer track_file_name:string track_content_type:string track_file_size:integer

title, artist, and length_in_seconds are meta-data we will pull from the ID3 tags of the uploaded mp3 file, and the rest will be used by Paperclip to handle the attachment. Lets add the paperclip attachment and a few simple validations to our new Song model:

class Song < ActiveRecord::Base
 
  has_attached_file :track,
                    :path => ":rails_root/public/assets/:attachment/:id_partition/:id/:style/:basename.:extension",
                    :url => "/assets/:attachment/:id_partition/:id/:style/:basename.:extension"
 
  validates_presence_of :title, :artist, :length_in_seconds
  validates_attachment_presence :track
  validates_attachment_content_type :track, :content_type => [ 'application/mp3', 'application/x-mp3', 'audio/mpeg', 'audio/mp3' ]
  validates_attachment_size :track, :less_than => 20.megabytes
 
  attr_accessible :title, :artist, :length_in_seconds
 
  def convert_seconds_to_time
    total_minutes = length_in_seconds / 1.minutes
    seconds_in_last_minute = length_in_seconds - total_minutes.minutes.seconds
    "#{total_minutes}m #{seconds_in_last_minute}s"
  end
end

Next comes an upload form and some containers to hold the SWFUploader:

- form_tag songs_path, :multipart => true do
  #swfupload_degraded_container
    %noscript= "You should have Javascript enabled for a nicer upload experience"
    = file_field_tag :Filedata
    = submit_tag "Add Song"
  #swfupload_container{ :style => "display: none" }
    %span#spanButtonPlaceholder
  #divFileProgressContainer

The container that holds the SWFUploader will be hidden until we know the user can support it. Initially a standard file upload form will display. A number of things can go wrong, so we need to think about a few levels of degradation here. The user might not have flash installed, the user might have an outdated version of flash, he might not have javascript installed or enabled(which is needed to load the flash), and there may be a problem downloading the flash swf file. Yikes. Luckily using the swfobject library we can easily handle all these potential issues.

If the user is missing javascript, he will see the message in the noscript tag and be presented a standard upload control.

If the user is missing flash or it is outdated, he will be presented a dialog with an upgrade link. Otherwise he can use the standard upload control.

If everything goes okey-dokey, then some function handlers we write will hide the the degradation container, and display the flash container.

Oh, and just so you know the current version of Flash Player for linux do not fire the event that monitors upload progress, so you will not get the status bar until the upload finishes. No work around for that right now.

So lets initialize the SWFUpload via some javascript. Many tutorials out there seem to put the authentication token and session information in the URL, but there are some options with current version of SWFUpload to POST and avoid that.

:javascript
  SWFUpload.onload = function() {
    var swf_settings = {
 
      // SWFObject settings
      minimum_flash_version: "9.0.28",
      swfupload_pre_load_handler: function() {
        $('#swfupload_degraded_container').hide();
        $('#swfupload_container').show();
      },
      swfupload_load_failed_handler: function() {
      },
 
      post_params: {
        "#{session_key_name}": "#{cookies[session_key_name]}",
        "authenticity_token": "#{form_authenticity_token}",
      },
 
      upload_url: "#{songs_path}",
      flash_url: '/flash/swfupload/swfupload.swf',
 
      file_types: "*.mp3",
      file_types_description: "mp3 Files",
      file_size_limit: "20 MB",
 
      button_placeholder_id: "spanButtonPlaceholder",
      button_width: 380,
      button_height: 32,
      button_text : '<span class="button">Select Files <span class="buttonSmall">(20 MB Max)</span></span>',
      button_text_style : '.button { font-family: Helvetica, Arial, sans-serif; font-size: 24pt; } .buttonSmall { font-size: 18pt; }',
      button_text_top_padding: 0,
      button_text_left_padding: 18,
      button_window_mode: SWFUpload.WINDOW_MODE.TRANSPARENT,
      button_cursor: SWFUpload.CURSOR.HAND,
      file_queue_error_handler : fileQueueError,
      file_dialog_complete_handler : fileDialogComplete,
      upload_progress_handler : uploadProgress,
      upload_error_handler : uploadError,
      upload_success_handler : uploadSuccess,
      upload_complete_handler : uploadComplete,
 
      custom_settings : {
        upload_target: "divFileProgressContainer"
      }
    }
    var swf_upload = new SWFUpload(swf_settings);
  };

You will want to check out the official SWFUpload docs to understand what all of these variable do. There are many handlers we have to define to handle various events, and if you clone the project you can review them in detail.

We also need to set styles for the containers that will be generated. You can see the Sass file I created for SWFUpload here, and another one for Ryan Bates nifty_generators.

Another quirk we have to be aware of when dealing with flash uploads is that everything gets a content-type of an octet stream. We will use the mime-types library to identify it for validation. Keep in mind it only uses the extension to determine the file type. (I haven’t tested it yet, but I believe mimetype-fu will actually check file-data and magic numbers). By default SWFUpload calls the file parameter ‘Filedata’.

  def create
    require 'mp3info'
 
    mp3_info = Mp3Info.new(params[:Filedata].path)
 
    song = Song.new
    song.artist = mp3_info.tag.artist
    song.title = mp3_info.tag.title
    song.length_in_seconds = mp3_info.length.to_i
 
    params[:Filedata].content_type = MIME::Types.type_for(params[:Filedata].original_filename).to_s
    song.track = params[:Filedata]
    song.save
 
    render :text => [song.artist, song.title, song.convert_seconds_to_time].join(" - ")
  rescue Mp3InfoError => e
    render :text => "File error"
  rescue Exception => e
    render :text => e.message
  end

Another annoyance with flash uploads is that it doesn’t send cookie data. That is why we are sending the session information in the POST data. We will intercept requests from Flash, check for the session key, and if so inject it into the cookie header. We can do this with some pretty simple middleware.

require 'rack/utils'
 
class FlashSessionCookieMiddleware
  def initialize(app, session_key = '_session_id')
    @app = app
    @session_key = session_key
  end
 
  def call(env)
    if env['HTTP_USER_AGENT'] =~ /^(Adobe|Shockwave) Flash/
      params = ::Rack::Request.new(env).params
      env['HTTP_COOKIE'] = [ @session_key, params[@session_key] ].join('=').freeze unless params[@session_key].nil?
    end
    @app.call(env)
  end
end

This is a modified version from code the appears in a few tutorials about flash uploads. It will allow the session information to be in the query string *or* POST data. Next we have to make sure this middleware gets put to use so in config/initializers/session_store.rb add:

ActionController::Dispatcher.middleware.insert_before(ActionController::Base.session_store, FlashSessionCookieMiddleware, ActionController::Base.session_options[:key])

And that’s, uhh, all there is too it. Again, I really suggest you checkout the example project. It also uses the nifty WordPress Audio Player flash control to play the music you upload!

In Rails 2.x, the default way it generates the javascript to send a a RESTful command via POST request looks something like this:

<a href="/foos/1" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form'); f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method'); m.setAttribute('value', 'delete'); f.appendChild(m);var s = document.createElement('input'); s.setAttribute('type', 'hidden'); s.setAttribute('name', 'authenticity_token'); s.setAttribute('value', 'VGcSbbdenz7ZCMDWl7LugKC2KFldp7oKdgdvjGyb4Zo='); f.appendChild(s);f.submit(); };return false;">Destroy</a> |

Yuck. It’s creating a new form, setting a hidden input fields for the submission method and csrf token, and then submitting it. Not only is it obtrusive, that gets inserted at every location there is a delete or update link.

First lets extend jquery with PUT and DELETE methods. Well call this jquery.rest.js:

;(function($){
  $.put = $.update = function(uri, data, callback, type = 'json') {
    if ($.isFunction(data)) callback = data, data = {}
    return $.post(uri, $.extend(data, { _method: 'put' }), callback, type)
  }
 
  $.delete = $.del = $.destroy = function(uri, data, callback, type = 'json') {
    if ($.isFunction(data)) callback = data, data = {}
    return $.post(uri, $.extend(data, { _method: 'delete' }), callback, type)
  }
{)(jQuery)

The previous code will POST data while always including a ‘_method’ parameter. Using this code is as simple as a normal jQuery ajax call:

$('.deletable').click(function() {
  $.delete('/videos/delete', {
    'video_id': $(this).attr('id');
  });
});

That example might iterate through all elements with the deletable class, and then sent the DELETE method when clicked.

Now in a Rails app we also need to include the CSRF token in all POST, PUT, and DELETE requests. The way I go about this is to put this at the bottom of my applications layout:

$(document).ready(function() {
  window.AUTH_TOKEN = '#{form_authenticity_token}';
  $(document).ajaxSend(function(event, request, settings) {
    if (typeof(window.AUTH_TOKEN) == "undefined") return;
    // IE6 fix for http://dev.jquery.com/ticket/3155
    if (settings.type == 'GET' || settings.type == 'get') return;
    settings.data = settings.data || "";
    settings.data += (settings.data ? "&" : "") + "authenticity_token=" + encodeURIComponent(window.AUTH_TOKEN);
  });
});

This will extend the parameters of any ajax request with the authenticity token. I hope this short guide gives you a better idea how to do REST in an unobtrusive way.

What we can do instead is just send the id and position of the single element that has moved, and use acts_as_list to adjust the positions in the database. Lets say we have an unordered list of Video models (I am using HAML in this example):

%h3= "Videos"
%ul(class="sortable")
  - @videos.each do |video|
    %li{ :id => "video_#{video.id}" }= video.title

That might output something like this:

<h3>Videos</h3>
<ul class='sortable'>
  <li id='video_5'>Batman Begins</li>
  <li id='video_6'>Ghostbusters</li>
  <li id='video_7'>Indiana Jones and the Temple of Doom</li>
 </ul>

We have the video’s database id’s in each of the element id’s, and we have given the ul element the sortable class so we can select it later. Now lets select that ul element and make it ‘sortable’:

$(function() {
  $('.sortable').sortable();
}

With that we can now drag each list item around. Now comes the important part. When we finish dragging a single list element we will send a single ajax request to the server that contains the numeric value of the element’s id, and it’s position in the list:

  $(function() {
    $('.sortable').sortable({
      stop: function(event, ui) {
        $(ui.item).effect("highlight");
        var video_id = $(ui.item).attr('id').replace(/[^\d]+/g, ''))
        var position = ui.item.prevAll().length;
        $.post('/videos/update_position', {
          'video_id': video_id,
          'position': position
         });
         $(ui.item).effect("highlight");
      }
    });
  })

Couple of notes:

ui.item is the DOM element we are dragging

$(ui.item).attr(‘id’).replace(/[^\d+]+/g, ”)) is pulling out the list item’s DOM id and removing anything that isn’t numeric, so we are left with the model’s ID

ui.item.prevAll().length is what gives us the list item’s position in relation to it’s parent ul

Now our controller action can be as simple as:

Video.find(params[:video_id]).insert_at(params[:position])

Again this requires acts_as_list. I believe this should never do more that 4 queries: One to find the model, one to update it’s position, and possibly two more to shift what was above and below it previously. Hopefully this saves you some SQL queries on larger lists.

First we need to make sure Ruby is installed via a cpanel script:

sudo /script/installruby

Now we can install the passenger gem:

sudo gem install passenger

Next, compile the apache2 module

sudo passenger-install-apache2-module

The installer may tell you that the the Apache development headers are needed and will suggest ‘yum install httpd-devel’. Since cPanel compiles it’s own version of apache, yum is configured to ignore that package. That is OK, because the program we need is already installed, we just have to tell Passenger where to find it.

APXS2=/usr/local/apache/bin/apxs PATH=$PATH:/usr/local/apache/bin passenger-install-apache2-module

Everything should go OK this time, and the installer will give you a few lines to add to your apache config file. It’s best practice with cPanel not to put these in your main httpd.conf, but rather the pre_main_global.conf:

vi /usr/local/apache/conf/includes/pre_main_global.conf
 
LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-X.X.X/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-X.X.X
PassengerRuby /usr/bin/ruby

Now we need to setup passenger to run on a per virtual host basis. Open up the httpd.conf file and find the virtual host you want to run a Rails app and add this line:

Include "/usr/local/apache/conf/userdata/std/2/username/domain_name/*.conf"

Replace username with the username of the account.

Now we need to create the directory we just specified, and also create a configuration file letting passenger know it should load for this host:

mkdir -p /usr/local/apache/conf/userdata/std/2/username/domain_name/
vi /usr/local/apache/conf/userdata/std/2/username/domain_name/rails.conf
 
RailsBaseURI /

To make sure those files load, run this:

/scripts/ensure_vhost_includes --user=username

We need to make sure cPanel records the changes we have for when it rebuilds those files, so run the following two commands:

/usr/local/cpanel/bin/apache_conf_distiller --update
/usr/local/cpanel/bin/build_apache_conf

We can now restart apache:

/etc/init.d/httpd restart

Since by default the Apache Document Root for each host is /home/username/public_html, you will probably need to symlink that to your applications public directory:

ln -s /home/username/railsapp/public /home/username/public_html

To restart that application, you just need to touch the restart.txt file:

touch /home/username/railsapp/tmp/restart.txt

And there you have it, a working high performance rail application server on cPanel! For more information on tuning the Passenger configuration, read the complete docs.