Behind the scenes: Redesigning and coding the Highrise sidebar modules
I’ve wanted to redesign the Highrise sidebars for a long time. They’ve felt cluttered and messy to me, and as we add more features to Highrise the mess will only multiply. So I was glad to have the chance this week to redesign the sidebar modules. The visual side of the redesign was straightforward, but implementing the design in code required a few tricks. Here’s a look behind the scenes at the coding decisions we made for the new Highrise sidebars.
“Subjects” in Highrise
Which sidebar modules am I talking about? In Highrise you can keep track of People, Companies, and Cases. These all have the same basic code and UI. You can keep notes about them, set tasks for the future, and manage some common types of metadata. Since People, Companies and Cases share so much plumbing, we’ve abstracted them as subjects. A subject is anything in Highrise that you can attach notes and tasks to. When you look at a subject’s page, you see a sidebar with some modules for adding or editing metadata such as contact information, background information (a kind of static text description), dates to remember for that subject, and more. The screenshot below shows a subject page with the sidebar modules highlighted.
Redesigning the modules
Each module has a header like “Contact Bob” or “Dates to remember” and data below. In the original design, modules can be either “active” or “empty” based on whether they have any data in them. Empty modules have a grey header and an “add” link floated right. Active modules have a light blue header and an “edit” link on the right. We made this distinction so your eye would more easily catch active modules when you’re looking for information. The idea was good, but the original implementation looked messy with its mix of grey and blue, scattered red action links, and lack of separation between 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' , !@subject.background.blank? , {} ]
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?
