Behind the scenes: Redesigning and coding the Highrise sidebar modules

For the first redesign (above) we cleaned up the modules. Active modules are now wrapped entirely in a light grey box with a tiny drop shadow. We killed the blue header style, relying instead on the space between modules to separate them. Empty modules no longer have a header. They are grey boxes collapsed down to a single link to add the content relevant to that module. Finally we replaced all the red links with grey links in order to put the focus on the data within active modules rather than all the possible actions. One last tweak: we changed the text for “About [subject’s name]” to “Add background information.” We’ve gone back and forth a number of times on the language for this feature, and at this stage we decided to try “background info” on for size again.

The first redesign was a big improvement. But we didn’t like the way active and empty modules looked mixed together. The dim bar in between those two active modules creates a kind of striped look that we want to avoid. The problem was worse on subjects with more sidebar modules, like companies or cases. So we decided to group all the active modules together on the top, and then group the empty modules on the bottom. The result is much cleaner, and it’s easier to scan when you load up a subject in order to quickly grab some info like an email address or birthday.

The re-ordered sidebar was a winner. But it came at a price. We couldn’t just change the CSS and call it a day. Now we also had to write code to re-order the sidebar modules dynamically based on whether they were empty or active. Ruby’s power and flexibility really came in handy for this job.

The code

I said earlier that people, companies, and cases are handled by the same plumbing because we abstracted them as subjects. The result of this abstraction is that whether you are looking at a person, a company or a case, the sidebar is rendered by the same template: subjects/_sidebar.rhtml.

(This kind of “view polymorphism” has been subject to a lot of internal debate since we first released the app. It makes maintenance both easier and harder because the code has less repetition on one hand but on the other it is less intention-revealing due to the abstractions and indirection.)

This is what the original template code looked like to render the subject sidebars:

in app/views/subjects/_sidebar.rhtml:

  <% if @subject.is_a?(Party) %>
    <%= render(:partial => 'parties/contact_info') %>
  <% end %>

  <% if show_company_contact_info?(@subject) %>
    <%= render(:partial => 'parties/contact_info', :object => @subject.company) %>
  <% end %>

  <%= render :partial => 'backgrounds/show' %>
  <%= render :partial => 'contact_dates/index' %>

  <% if @subject.is_a?(Kase) %>
    <%= render :partial => 'kases/parties' %>
  <% end %>

  <% if @subject.is_a?(Company) %>
    <%= render :partial => 'companies/people' %>
  <% end %>

Don’t worry too much about the individual partials and conditions. The key point is that each partial is a sidebar module, and each module is conditioned based on the particular subject we are rendering. A different mixture of partials will be rendered depending on whether the subject is a person, a company or a case, but they’ll always render in the same order.

We want to re-order these partials dynamically based on whether each module is active or empty. That means we need to represent the possible partials, the conditions for displaying them, and also the conditions for determining whether they are active or empty within some kind of data structure. So we popped open our Rails subjects_helper.rb and represented this information in an array.

in app/views/helpers/subjects_helper.rb:

  def sidebar_modules_to_sort
    returning [] do |m|
            # partial to render       module_is_active?                 options                          render the module for this subject?
      m << ['parties/contact_info'  , show_contact_info_module_on_top?, {}                             ] if @subject.is_a?(Party)
      m << ['parties/contact_info'  , true                            , {:object => @subject.company}  ] if show_company_contact_info?(@subject)
                                        #necessarily true per the condition at right
      m << ['backgrounds/show'      , [email protected]?     , {}                             ]
      m << ['contact_dates/index'   , @contact_dates.any?             , {}                             ]
      m << ['collections/parties'   , @subject.parties.any?           , {}                             ] if looking_at_collection?
      m << ['companies/people'      , @subject.people.any?            , {}                             ] if @subject.is_a?(Company)
    end
  end

The helper method sidebar_modules_to_sort returns a parent array full of child arrays, one for each module with an element for the template path, a true/false value to show if it is active, and an options hash for the render method. The conditions that used to determine whether each partial should be rendered now determine whether each child array should be included in the parent array. Thanks to that boolean in the second element of each child array, we can partition the parent array into two groups: those where the second element which represents that the module is ‘active’ are true, and those were that element is false. We use another helper method to partition and reassemble the array into groups.

in app/views/helpers/subjects_helper.rb:

  def sidebar_modules_in_order
    active_group, empty_group  = sidebar_modules_to_sort.partition {|m| m[1]}
    active_group.concat empty_group
  end

Finally we return to our sidebar template to do the actual rendering.

in app/views/subjects/_sidebar.rhtml:

<%= sidebar_modules_in_order.map {|m| render sidebar_module_partial(m)}.join %>

This line in the template takes the sorted array of sidebar modules and replaces each element in the array with the rendered partial. Then the join method converts each element to a string and concatenates them. sidebar_module_partial is a call to one more helper. This helper assembles the arguments for render out of the elements provided in the array. It looks like this:

in app/helpers/subjects_helper.rb:

  def sidebar_module_partial(m)
    m[2].merge({:partial => m[0]})
  end

In the snippet above, sidebar_module_partial takes the third element of each module array, which is either an empty hash or some special options for render, and merges a key specifying the template path onto that hash.

We definitely could’ve hidden these rendering gymnastics behind a helper, perhaps called render_sidebar_modules or something similar. However we’ve decided for style reasons to avoid calling render from within our helpers. Therefore we decided to use a helper to merely fill in the arguments to the call to render within the template itself.

In the end, we have a new sidebar design and some clean and intention-revealing code. This was a fun chance for me to expand my Ruby knowledge by dipping into the nuts and bolts of arrays and hashes. Thanks to Jamis for reviews and advice when I knew there had to be “a better way.” We hope you enjoy the new sidebar modules in Highrise.

Related: What belongs in a helper method?