Working with Portlets apotomo-1.0

Since we’re actually building some form of dashboard in a Rails app, why not use jQuery UI Portlets to make it more awesome?

Our widgets now look fuckin’ cool – styled as portlets with a jQuery theme. You can drag and rearrange them, too!

Using a jQuery UI theme

Things are pretty with jQuery. Let’s use the theme eggplant. I like eggplants. Just use good olive oil when frying ’em, and do not forget the salt and pepper.

 %html
 %head
   = javascript_include_tag "jquery-1.4.2.min"
   = javascript_include_tag "jquery-ui-1.8.5.custom.min"
   
   = stylesheet_link_tag "app"
   = stylesheet_link_tag "eggplant/jquery-ui-1.8.5.custom"
   
 %body
  = yield

We just add the eggplant theme stylesheet (line 7).

Drawing the Dashboard

Reading the portlets example source it turns out that we have to alter the dashboard view a bit.

 %h1 My Dashboard
 
 #dashboard
   .column
     = render_widget 'parrot'
   .column
     = render_widget 'bin'
 
 :javascript
  $(function() {
    $(".column").sortable({
      connectWith: '.column'
    });
    
    $(".portlet").addClass("ui-widget ui-widget-content ui-helper-clearfix ui-corner-all")
      .find(".portlet-header")
        .addClass("ui-widget-header ui-corner-all")
        .prepend('<span class="ui-icon ui-icon-minusthick"></span>')
        .end()
      .find(".portlet-content");
    
    $(".portlet-header .ui-icon").click(function() {
      $(this).toggleClass("ui-icon-minusthick").toggleClass("ui-icon-plusthick");
      $(this).parents(".portlet:first").find(".portlet-content").toggle();
    });
  });

That’s two columns (line 4-7) and a bit JavaScript I copied from the example.

Widgets get Portlets

Portlets have some styling requirements and expect some divs and classes. Why not use a layout?

   def display
     @tweets = Tweet.find(:all)
    render :layout => "portlet"
  end

The same in the trashbin.

   def display
     render :layout => "portlet"
   end

Layouts

Yeah, widgets can have layouts, too. That makes sense as soon as your widgets start sharing certain view blocks.

- widget_div :class => :portlet, :id => "portlet-#{widget_id}" do
  .portlet-header
    = @title || "Eggplant portlet!"
  .portlet-content(id=widget_id)
    = yield

The helper widget_div just creates a div with the specified options (line 1).

Line 4 will render to something like

  <div class='portlet-content' id='parrot'>

As the class name implies, this is the content block of our widget.

Simplify views

Now that the layout does all the wrapping work, we should remove calls to widget_div in our views.

 %ul
   - for tweet in @tweets
     %li{'data-id' => tweet.id}
       = tweet.text

Replace gets update

Now what happens if you post a new tweet?

The state adds the tweet (line 10) and replaces the content block itself with the re-rendered view (line 13).
This is not exactly what we want – see on the right.

   def process_tweet(evt)
    Tweet.new(:text => evt[:text]).save

    @tweets = Tweet.find(:all) # this is wet!
    replace :view => :display
  end

The generated JavaScript from replace (line 13) would look like this.

$("#twitter").replaceWith("<ul>...");

Solution: the update helper

As the re-rendered view “<ul>...” is not wrapped with the layout, this breaks the .portlet-content div.

According to the jQuery API on replaceWith, the solution is using html instead. Apotomo provides the #update helper for exactly that. Damn, that’s so simple!

     @tweets = Tweet.find(:all)
    render :layout => "portlet"
  end
  
  def process_tweet(evt)
    Tweet.new(:text => evt[:text]).save

Don’t forget to use update in all trigger states of portlets.

    @tweets = Tweet.find(:all) # this is wet!
    replace :view => :display
  end

And in the bin.

   def trash(evt)
     Tweet.find(evt[:id]).delete
    trigger :tweetDeleted
    
    update :view => :display
  end

Thanks to José Alberto for “inspiring” me to write this guide. Te quiero, también! ;-)

Apotomo is a Nick Sutterer product.