Pick your layer

I've been noticing that some of our newer Rails developers are having trouble picking which layer (Model, View or Controller) a method belongs in. Here are some heuristics I've picked up along the way - in no particular order.

1 - Don't put it into a library unless it really has nothing to do with the rest of your site (or you want to package it up to hand to other people).

I've recently noticed a few methods being added to a library I wrote that like this: my_method(@my_object) This is a prime candidate for going into the MyObject model itself. Especially when the body of said method just accesses some related objects eg:

# instead of:
module MyLibrary
  def my_method(my_obj)
    my_obj.sub_classes.map {|sc| [sc.name, sc.id] }
  end
end
# put it on the model
class MyModel < ActiveRecord::Base
  has_many :sub_classes
  def my_method
    return [] if sub_classes.blank?
    sub_classes.map {|sc| [sc.name, sc.id] }
  end
end

2 - A model should know how to deal with itself

I'd like to say that everything that can go into a model should... but that's not quite true. Anything data-related, however, is a prime candidate. A model should know how to deal with it's own data. It should know how to calcuate and derive from its own data. It should know how to pull stuff out of related objects, and to parse other objects into a form that allows it to stuff data into itself.

I've seen too many of these sorts of calculations going into views or helpers, or getting stuck in the middle of controller-code. These will only come back to bite you later, when the client suddenly realises they want the report to also be generated into pdf or graphical form as well...

If it can go on the model, put it there, because you'll always have access to the methods on your model.

3 - Don't put html into your model

By all means put display-names and other, similar methods that produce displayable information... but don't put html into it. After all, right now you may be concentrating on web-only delivery of your data... but who's to say the client won't be asking for xml next week... and pdf the week after that... followed by CSV?

Make your model-based display methods text-only eg:

class MyModel < ActiveRecord::Base
  def good_display_name
    name || "Unspecified"
  end
  def bad_display_name
    "<div class=\"left_aligned_red_box\">#{good_display_name}</div>"
  end
end

4 - Put format-specific display functions in the helpers

If you're displaying a selection of a certain class of objects (eg Dates) in a specific format in multiple places across the site, and want consistency of appearance (a Good Thing), feel free to add a display helper to the ApplicationHelper file, or even update the generic display function for that class in your environment.rb

  # eg add these to application helper
  def display_percentage(num)
    return "" unless num
    "#{number_with_precision(num,2)}%"
  end
  def display_date(date)
    return "" unless date
    date.strftime("%a %d/%m/%Y")
  end
  def display_datetime(datetime)
    return "" unless datetime
    "#{display_date(datetime)} #{datetime.strftime("%H:%M")}"
  end

Note that you can over-ride the default datetime display in rails using the following (in environment.rb or similar) then use "to_s" or "to_s(:datetime)" in your views.

ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!(
   :default => "%a %d/%m/%Y",
   :datetime  => "%a %d/%m/%Y %H:%M"
 )

Rails gotchas: ruby-enhanced yaml != rails-enhanced yaml

I you've just added some funky ruby-generated something into your yaml fixture and are suddenly getting this error message:

Fixture::FormatError: a YAML error occurred parsing /myproject/config/../test/fixtures/widgets.yml. Please note that YAML must be consistently indented using spaces. Tabs are not allowed. Please have a look at http://www.yaml.org/faq.html
The exact error was:
  SyntaxError: compile error
(erb):8: syntax error, unexpected ')'
_erbout.concat "  created_at: "; _erbout.concat(( '1 January 2006'.to_date.to_s(:db) -).to_s); _erbout.concat "\n"
                                                                                       ^

Check to make sure you haven't done the "good" thing and used -%>. It appears that YAML files don't like the whitespace-eating ending... you can only use: %>

Rails gotchas: Kamikaze data migrations

This is a pernicious little gotcha I've encountered a couple of times, generally by using somebody else's plugins. The problem with it is that it usually doesn't actually affect the developer - just anybody else that uses the system. This can lead to the developer refusing to believe that there is a problem.[1]

So what am I talking about here?

I'm talking about a certain type of data migration that explodes as you run it, sometimes even causing the database to get stuck in a nasty halfway-inbetween state where you can neither continue migrating up... or roll back to a previous stable state.

"But migrations are transactional" I hear you cry. Sure they are. That doesn't stop this particular error from occurring... and *still* leaving the db in a nasty stuck state - honest, just gimme a chance to explain why.

Picture this: You've been happily developing away building the next generation of your category-killer Web 2.0 Widget application when you suddenly realise that your widgets need to refer to pieces instead of parts. So, like a good agile developer you:

• Create a new Piece resource with all the bells and whistles.
• Create and run the migration that a) creates the pieces table b) data migrates widgets so they point at pieces instead of parts c) drops the parts table.
• Update all references in your code from pieces to parts.
• Remove all the part code from controllers/views etc.

All goes smoothly. rake test runs flawlessly and you check in your code. You continue on your merry way, adding more functionality and reflecting on your brilliance...

...until a user of your code emails you to say that your migration breaks and has left their db in some wierd state that doesn't let them migrate up or down.

The problem is that when you (the developer) ran the migration, you still had the Part class in app/models and the Widget class still had references like "has_one :part" in them. When your user downloads your system, however, it may be several changes later... and the system has no recollection of a Part class or how they relate to Widgets. So when you have a data migration such as:

   Widget.find_all.each { |w| make_piece_from_part(w.part) }

It won't know what a part is - or how you get one off your widget class. The nasty part is that often you will find this kind of data migration stuffed in the middle of the schema migrations thus:

def self.up
  create_table :pieces do |t|
     #... creates a table here
  end
  add_column :widgets, :piece_id, :integer, :default => nil
  Widget.find_all.each { |w| make_piece_from_part(w.part) }
  remove_column :widgets, :part_id
end
def self.up
  add_column :widgets, :part_id, :integer, :default => nil
  Widget.find_all.each { |w| make_part_from_piece(w.piece) }
  remove_column :widgets, :piece_id
  drop_table :pieces
end

I'm told that migrations are transactional - ie if it fails, then everything rolls back to the state before the migration... this doesn't seem to work when data migrations are involved. If the data part of the migration falls over, it stops halfway through the migration with a nasty backtrace, but doesn't perform any rollback. So at that point it's already added the pieces table and the piece_id column to the widgets table, but it hasn't removed the part_id column and the schema is still pointing at the migration number before this one. So if you try to run the migration again, it will fail on the first line, saying something like:

== MovePartsToPieces: migrating ============================================
-- create_table(:pieces)
rake aborted!
Mysql::Error: Table 'pieces' already exists: CREATE TABLE pieces (<piece-table insert statement here>) ENGINE=InnoDB

(See full trace by running task with --trace)

Unfortunately it also won't migrate you back. The bad data migration failed before it had a chance to update the current migration level - so migrating back gives you entirely unhelpful "finished in 0.000183" seconds message (or similar), without doing anything at all.

Recovering from the stuck state

Recovering is possible, but it takes some small amount of hacking in the migration. Basically you need to force Rails to run an empty migration so that it does nothing except to put the version number up. Then you can force it to run the bits of the down migration that cancel the bits that it did the first time you tried running the up migration. In detail:

1. Comment out every line of code in self.up
2. Comment out the appropriate lines in self.down that correspond with stuff that never got run when the migration fell over the first time - ie leave anything that cancels out actions that were *successfully* done when you did the up migration. in the example above, you'd comment out the downward data migration and the addition of the piece_id column - leaving only the removal of the part_id column and the drop table - which would leave you back in the state you started in.
3. Save the file
4. Now you can run rake db:migrate. This should should leave you with a database that at least has the right version number for you to be able to migrate back down again.
5. Now run the down migration with rake db:migrate VERSION=<one before this one>.
6. Now go fix your migration so this doesn't happen to anybody else.

Fixing this kind of data-migration nightmare is the only time that I recommend you go back and edit old migrations rather than creating a new one.

• [1]Ok, so the real reason I'm writing this post is partly so that I can point said unbelievers at it the next time they swear that nothing's wrong and that I should just quit fussing about.

Securing Rails

Quick post today. Just found a really great Rails Security Cheatsheet here. Has links to useful articles on all sorts of topics about rails security, including (but not limited to):

• Why do security for Rails
• Securing your sessions
• Useful security plugins
• Securing files on your server
• Common web security issues (XSS, SQL injection etc)

Keeping passwords out of your logs

By default, rails will insert all parameters into the logs. This is useful for debugging, but not so grand when the parameters are sensitive eg:
Parameters: {"user"=>{"login => "mylogin", "answer"=>"my answer", "question"=>"my question ", "terms"=>"1", "new_password"=>"mypass123", "new_password_confirmation"=>"mypass123"}, commit => "Activate my account", "_method"=>"put"} ...
OR
Parameters: {"commit"=>"Log in", "action"=>"create", "controller"=>"sessions", "password"=>"mypass123", "login"=>"mylogin"} ...

It's a one-liner for rails to filter this out. Just add this line to the top of the relevant controller(s):

class SessionsController < ApplicationController
  # filter out sensitive fields from the log
  filter_parameter_logging 'password'
  # rest of controller goes here...
end
class UsersController < ApplicationController
  # filter out sensitive fields from the log
  filter_parameter_logging 'password', 'question', 'answer', 'given_answer'
  # rest of controller goes here...
end

This will turn the required log lines into:
Parameters: {"user"=>{"login => "mylogin", "answer"=>"[FILTERED]", "question"=>"[FILTERED] ", "terms"=>"1", "new_password"=>"[FILTERED]", "new_password_confirmation"=>"[FILTERED]"}, commit => "Activate my account", "_method"=>"put"} ...
OR
Parameters: {"commit"=>"Log in", "action"=>"create", "controller"=>"sessions", "password"=>"[FILTERED]", "login"=>"mylogin"} ...

Note that it's even smart enough to automatically filter out the "password_confirmation" field without requiring a specific reference to it.

Extending ActiveRecord::Validations for positive numbers

I noticed I could DRY up a lot of my def validate items by finding a better way to check if a numerical field was a positive number (when provided). I figured this would be a perfect candidate for extending the "validates_numericality_of" method. But then I had a play with extending it and got stuck on "how exactly do you extend a class method?"

I've successfully added new validations by reopening ActiveRecord::Base, but how do you open an exising method and add more bits on?

I tried alising the method... but the question became: how do you alias a method that is defined as self.validates_whatever?

This excellent post describes how to extend class methods by using base.class_eval and putting the alises into class << self

Note: you definitely need to double-alias your function (as in the class extension section below) or you will find yourself instantly spiralling into a "stack level too deep" exception the first time you call it.

Here's how to extend a validation in Rails (includes my extension to validates_numericality_of, and also my preivous validates_percentage method):

module MyNewValidations
  # magic to allow us to override existing validations
  def self.included(base)
    base.extend(ClassMethods)
    base.class_eval do
      class << self
        alias old_numericality_of :validates_numericality_of unless method_defined?(:old_numericality_of)
        alias validates_numericality_of :my_validates_numericality
      end
    end
  end

  module ClassMethods
    # extends the "validates numericality of" validation to allow the option
    # ":positive_only => true" or ":negative_only => true"
    # This will validate to true only if the given number is positive (>= 0)
    # or negative (<= 0) respectively
    # Otherwise is behaves exactly as the standard validation
    def my_validates_numericality(fields, args = {})
      ret = old_numericality_of(fields, args) # first call standard numericality

      pos = args[:positive_only] || false
      neg = args[:negative_only] || false

      if pos || neg
        msg = args[:message] || "should be a #{pos ? 'positive' : 'negative'} number"
        validates_each fields do |model, attr, val|
          if (pos && val.to_f < 0) || (neg && val.to_f > 0)
            model.errors.add attr, msg
            ret = false
          end
        end
      end

      ret
    end

    # validates whether the given object is a percentage
    # Can also take optional args which will get passed verbatim into the
    # validation methods. Thus it's only really safe to use ":allow_nil" and
    # ":message"
    def validates_percentage(fields, args = {})
      msg = args[:message] || "should be a percentage (0-100)"
      validates_each fields do |model, attr, val|
         pre_val = model.send("#{attr}_before_type_cast".to_sym)
         unless val.nil? || !pre_val.is_a?(String) || pre_val =~ /^[-+]?\d+(\.\d*)?%?$/
           model.errors.add(attr, msg)
         end
       end
      args[:message] = msg
      args[:in] = 0..100
      validates_inclusion_of fields, args
    end

  end
end

class ActiveRecord::Base
  # add in the extra validations created above
  include MyNewValidations

  #other stuff I'd defined goes here
end

quarter-master

Continuing my series of "why isn't this in ruby already?", we have some date functions that allow us to add and display the current financial quarter. I have even overridden "strftime" to accept the symbol '%Q' to display the quarter.

class Time
  # save the original strftime so we can call it later
  alias original_strftime :strftime
  # overload strftime to accept '%Q' to display the quarter
  def strftime(format)
    format = format.gsub('%Q', "Q#{self.quarter.to_s}") if format
    self.original_strftime format
  end

  # create a utc time using the year and financial quarter
  def self.utc_fq(year, fq = 1)
    self.utc(year, self.quarter_to_month(fq))
  end
  # create a local time using the year and financial quarter
  def self.local_fq(year, fq = 1)
    self.local(year, self.quarter_to_month(fq))
  end

  # turns a financial quarter (1-4) into the first month of that quarter
  def self.quarter_to_month(fq)
    ((fq-1)  * 3) + 1
  end
  # turns a given month (1-12) into the financial quarter
  # (1=jan-mar, 2=apr-jun, 3=jul-sep, 4=oct-dec)
  def self.month_to_quarter(month)
    ((month - 1) / 3) + 1
  end

  # returns the financial quarter of this date
  # (1=jan-mar, 2=apr-jun, 3=jul-sep, 4=oct-dec)
  def quarter
    self.class.month_to_quarter(self.month)
  end
end

Example of use:

>> order_fq = Time.utc_fq(order.created_at.year, order.created_at.quarter)
=> Sun Jul 01 00:00:00 UTC 2007
>> p "Order's financial quarter: #{order_fq.strftime("%Y-%Q")}"
"Order's financial quarter: 2007-Q3"
=> nil

methods in_time

On the subject of "why isn't this in Ruby already?". I've written up a set of conversion methods that I felt sure were there already, except that I couldn't find them anywhere.

class Numeric
  # assumes i am expressed in seconds - converts me to minutes
  def in_minutes
    self / 60
  end
  # assumes i am expressed in seconds - converts me to hours
  def in_hours
    self / 3600
  end
  # assumes i am expressed in seconds - converts me to days
  def in_days
    self / (3600 * 24)
  end
end

So now I can do things like: 3600.in_hours, but also the more useful: (prevTime - Time.now).in_days

float precision

So, I want to test that some floating-point helper function returns a certain value - but I only want it to check to a certain precision (so I don't get hit with negligible rounding errors).

Add this to config/environment.rb (and why doesn't this already exist in Ruby?)

class Float
  def precision(pre)
    mult = 10 ** pre
    (self * mult).round.to_f / mult
  end
end

Then you can do things like this:

assert_equal -5087.35, order1.profit_loss.precision(2)

[Edit: I've replaced 'truncate' with 'round' - it's the only change I've made in two years and I'm still using this code... maybe I should put it into the Rails core-extensions instead?]

Truth in Fiction

So, I was having dinner with my cousin the other day[1]. Now my cousin and I are both part of an international book-swapping club, so we often swap books with each other, or chat about the books we're currently reading. Anyway, she had a book to lend me, and gave me a brief description of what it was about and why she liked it. What struck me was her use of the word "inoffensive" as a descriptive for the plot.

Now, I like to think I don't really judge a person by their book-taste. I mean everyone's different, and that's just fine. If you want to waste your time reading endless soppy romances, or brain-dead action books with no plot, but lots of sex... that's not my choice and doesn't impinge on my life one jot, so go for your life.

But it got me thinking about what it is that I *do* look for in a book. After all, my taste is, you could say "highly eclectic". I have fiction, non-fiction, fantasy, mysteries, science-fiction, speculative fiction, historical fabrications, and even the odd romance or action book.

With all that diversity, is it possible for there to be an overall theme running through here? Clearly not in genre, but the contrast with the word "inoffensive" really got me thinking.

I don't care if a book is offensive, what I value in a book is its sense of Truth.

Now, clearly I don't mean "it must be a true story" - after all, I read a hell of a lot of fiction (about 40-60 books a year on average). I also don't mean "it must mirror reality" as I read very little mainstream (the realm of "near reality" books) by comparison with my science fiction and fantasy.

After all, "The Lord of the Rings" has elves, and orcs and and magic rings galore, so you couldn't call is a true story, but in one sense it is a True Story. It thoroughly explores the reactions and relationships between the characters, and thereby delves into the Truth by exploring how to hold onto friendship through a struggle against near-overwhelming odds. About the Truth of courage, how it doesn't mean you are unafraid, but that you are prepared to struggle on for a cause that is worth fighting for, even when you are certain that you will not see the end of it.

It is this kind of Truth that I value in (what I consider to be) a good book.

Once I got onto that train of thought, I also realised why some other books really didn't appeal to me. I've recently tried to read my way through a few of the classic "Stainless Steel Rat" stories (by Harry Harrison). Mainly because several SF-fan friends of mine (mainly male) have enthused about how they loved them as kids. When I came to read them I found them to be bog-standard "boy's own adventure" stories... just set in space. Which were *so* not to my taste.

In the light of my new discovery I can see what was lacking in them that turned me off. A boy's own adventure works like a fantasy/day-dream. Everything goes just perfectly. Even when things are going wrong, you know that some Deus ex Machina is waiting in the wings to save the day. I get the same feeling from Traci Harding (though that is fantasy of the female kind).

Some authors bounce between the two ends. Laurell K Hamilton can push too far to the fantasy side of things, her recent books have this side clearly overshadowing the plot. Whereas her earlier books showed a great ability to get to the Truth of the relationships between the characters. Her main character (Anita Blake) is a vampire-hunter, hunting rogue vampires in a world where vampires have been made into "legitimate citizens". Unfortunately, vampires have several "natural" abilities that can cause problems in humans (especially those creating an irresistable "draw" or desire). Laurell writes poignantly about Anita's internal emotional struggle against the desire she feels for a particular vampire while simultaneously having to deal with the physical struggles she goes through in the course of her job.

Of course this also aparrently involves a lot of sex...

So, to get back to the original point, I wonder a bit about what my cousin meant by describing a book as "inoffensive". Inoffensive to what?

I can only guess that she meant inoffensive to her Christian values, and to her sense of well-being. Like many people, she probably doesn't want a provocative book that jolts her out of her current orbit. This is reasonable. She's a mother and definitely has a lot on her plate already... but this kind of thought-provoking, stimulating book is exactly what I crave.

So, I don't hold out a lot of faith that I'll really find her book to be as interesting as she finds it. But I'll definitely give it a go. Who knows? Maybe I'll be pleasantly surprised.

Notes

[1]Surjit's Indian Restaurant: 215 Parramatta Road Annandale (Sydney). I thoroughly recommend this place - they do fantastic Indian. Aparrently the Sri Lankan cricket team visits there when they are over here.

validates percentage

So, we wanted to check that a user could enter both "20" and "20%" and "20.000%" and have them all perfectly valid for a field on our models. I finished up with this validation method (below) to add to ActiveRecord::Base.

  # validates whether the given object is a percentage
  # Can also take optional args which will get passed verbatim into the
  # "validates inclusion" method.
  # It will safely take the usual set of fields for that - but if you pass
  # in a new message - it will get used for both validations.
  # The default message is: "should be a percentage (0-100)"
  def self.validates_percentage(fields, args = {})
    msg = args[:message] || "should be a percentage (0-100)"
    validates_each fields do |model, attr, val|
       pre_val = model.send("#{attr}_before_type_cast".to_sym)
       unless val.nil? || !pre_val.is_a?(String) || pre_val =~ /^[-+]?\d+(\.\d*)?%?$/
         model.errors.add(attr, msg) 
       end
     end
    args[:message] = msg
    args[:in] = 0..100 
    validates_inclusion_of fields, args 
  end

Assert no errors

Small snippet today... I've mainly been working on updating the test-coverage for our app the last couple of weeks - so nothing particularly useful to share. I have, however, found the following tiny test-helper method to be useful.

Many tests require you to check for a particular error on a specific field on an object... but you also tend to check (over, and over, and over) that there aren't any errors on a given object. So I extracted that out.

Put this into "test_helper.rb" for increased DRYness

  # Assert that the handed object (thing) has no errors on it.
  def assert_no_errors(thing)
    fail("should have passed an object") unless thing
    e = thing.errors.full_messages
    assert e.empty?, "Should not have error: #{e.to_sentence}"
  end

Slice and Dice

I've been playing around with sorting and scoping to neatly and easily sort and filter an index page. I'm finally happy with a generic set of scoping/sorting methods I can quickly apply to a new resource. It uses the autoscope plugin I discussed earlier, as well as the smart column sorting I played with.

Scope up

To start with, drop some scoping into your model object - and add the three required methods below (with suitably appropriate modifications for your purposes).

  auto_scope \
       :active => {:find => {:conditions => ['destroyed_at IS NULL']}},
       :archived => {:find => {:conditions => ['destroyed_at IS NOT NULL']}}

  # Available scopes - shouldn't this be available via autoscope?
  def self.scopes
    [:all, :active, :archived]
  end
  # Defaults (put into the model object)
  def self.default_scope
    :active
  end
  def self.default_sort
    '(destroyed_at IS NULL) DESC, login ASC'
  end

Next, drop these methods into your application.rb

  # Generate a quick-and-dirty description of the chosen sort order (for displaying in the template)
  def sort_desc
    "#{params[:dir] == 'down' ? 'descending' : ''} by #{params[:col_name] || params[:col]}"
  end
  # Generates a SQL order-by snippet based on requested sort criteria (or given default). 
  #
  # Adapted from the following blog post:
  # http://garbageburrito.com/blog/entry/447/rails-super-cool-simple-column-sorting
  def sort_order(model, default)
    orderby = "#{params[:col]} #{params[:dir] == 'down' ? 'DESC' : 'ASC'}"
    return sort_desc, orderby
  end

  # Uses model scoping to generate a scoped subset of the required objects
  # for use in the index view.
  # Returns a sorted list of the object .
  # Assumes existance of three methods on the model: 
  # scopes:: returns an array of acceptable scopes for this model
  # default_scope:: returns the scope to use when none has been selected
  # default_sort:: represents an SQL-appropriate string for this model
  #   representing the default way of sorting this model object
  def scoped_search(model, scope)
    scope = model.default_scope unless model.scopes.include?(scope.to_sym)
    sort_desc, orderby = sort_order(model, model.default_sort)
    # a description of the search/sort to display in the view
    filter_desc = "#{scope.to_s} #{model.name.pluralize.downcase} #{sort_desc}"
    return filter_desc, model.find(:all, :order => orderby) if scope.to_sym == :all
    return filter_desc, model.send(scope.to_sym).find(:all, :order => orderby)
  end

Using it is now easy. Drop something like this into your controller and call on it for all your collection-based actions.

  # applies user-specified filters and sorting to the specified collection
  def filter_users
    scope = params[:user_scope].to_sym if params[:user_scope]
    @filter_desc, @users = scoped_search(User,scope)
  end

If you need to paginate, you can always paginate-collection, or add the code into the scoped_search function.

Super Cool Smart Column Sorting

So, I wanted to drop in some basic column sorting without having to rip out the innards of something like streamlined. I googled and came across this blogpost on SCSCS - which is so worth it for super-cool simple column sorting...

But I'm just not satisfied by what it can do. As ever, I want more. In this example, I wanted to be able to display neato little up/down arrow widgety thingies on the column heads by giving the th the appropriate "up/down" class - so the user can see which column it's all sorting by.

Arrowy goodness

We want a way to stuff a CSS class into the table's column-heads so we can show the sorty arrows. We need to indicate two things. Firstly, when the data has been sorted by a particular column, we want to indicate "this is the current sort colum". Secondly, we want to be able to indicate the sorting direction of a column (up, down or indifferent).

So the first step is to create (or appropriate) arrow-images. I'm not going to show an example here (you can figure that out for yourself) but I'll assume you have three images: SortUp.gif, SortDown.gif (to show that the current column is sorted up or down), and SortAny.gif (a double-arrow to indicate that the column could be sorted if they want to).

Stylish stuff

Then you need to put something appropriate in your stylesheet. eg:

/* what an ordinary column-head looks like */
.dataTable th {
   background-color: grey;
   color: white;
   padding-left: 15px;
   padding-right: 4px;
}
/* colour for currently sorted column */
.dataTable th.current {
  background-color: black;
  color: white;
}
/* the sorting link */
.dataTable th a {
  color: white;
  text-decoration: none;
  display: block;
  width: 100%;
}
.dataTable th.current a {
  color: grey;
}
/* pretty colours when hovering */
.dataTable th a:hover {
  color: blue;
  background-color: grey;
}
.dataTable th:hover {
  background-color: grey;
}

/* display of up and down arrows for sortable columns */
.dataTable th.up {
  background-image: url("/images/SortUp.gif");
  background-repeat: no-repeat;
  background-position: center left;
}
.dataTable th.down {
  background-image: url("/images/SortDown.gif");
  background-repeat: no-repeat;
  background-position: center left;
}
/* display for "any" sort - eg up and down arrows */
.dataTable th.any {
  background-image: url("/images/SortAny.gif");
  background-repeat: no-repeat;
  background-position: center left;
}

Stuff to note:

• The "current" column head is a distinctively different colour to a normal column - this makes it stand out.
• The "hover" colours provide good feedback for users - they pick up the idea that clicking here will probably do something.
• The anchor within the column head has display:block; and width:100%; this makes the anchor stretch to the full width of the column-head - which is nicer than having to click just the word itself.
• There's a padding-left on the anchor columns - this gives room for the arrow images. I've specified 15px as it's big enough for the images I use - YMMV.

Classy heads

So now we need to adapt the sort_link method to make it actually use this stuff. But we don't want it just on the link - the class needs to go on the whole column-head. So write a wrapper-function that will generate the whole <th> for you (class and all):

  # generate appropriate class for current sort options
  def sortlink_class(col)
    return "any" unless params[:col] || params[:dir]
    return "current #{params[:dir] == 'up' ? 'up' : 'down'}" if params[:col] == col.to_s
    "any"
  end

  # Generates a column head tag that contains a sort link and is given the
  # appropriate class for the current sorting options.
  def column_sort_link(title, column, options = {})
    content_tag 'th', sort_link(title, column, options), 
                      :class => sortlink_class(column)
  end

  def sort_link(title, column, options = {})
    if options.has_key?(:unless)
      condition = options[:unless] 
      options.delete(:unless)
    end
    new_sort_dir = params[:dir] ==  'down' ? 'up' : 'down'
    link_to_unless condition, title, request.parameters.merge(options.merge(:col => column, :dir => new_sort_dir))
  end

So, the currently sorted column will get something like class="current up", wheras most of the columns will be class="any". You'll also note I updated the badly-named "d" and "c" to "dir" and "col" so that unsuspecting maintenance people might have a clue as to the actual purpose of the options. Self-documenting code being a Good Thing.

Finally, I've modified it to pass through any extra options to the controller by merging the options into the link. This can be used to pass through requests for special sorts, extra parameters etc.

Sliding Door Tabs take 2

So, a while back I wrote a quick widget for making sliding door tabs. But it wasn't enough, I wanted *MORE*. I wanted them to be responsive to conditions.

For example, I have a resource User, and I want the "users" tab to stay open no matter which user page I'm on (index, show, edit etc)... *unless*, of course, it happens also to be the "my account" page (ie I'm viewing myself)... for which I already have a tab. This is a cut above just being "on" if we happen to perfectly match the current url.

So I rewrote the helper methods. Now my tabs come with optional separators (that can be independantly styled), and with the ability to pass in a conditional to override whether or not to show the tab as "on".

  def make_tab(t)
    # use the conditional if one was passed - default to current page 
    cond = t.has_key?(:cond) ? t[:cond] : current_page?(t[:options])
    content_tag "li", link_to(t[:name], url_for(t[:options])),
                             :class => (cond ? 'current' : nil)
  end

  # Builds a tab that is just a separator
  def make_separator
    "<li class='separator'></li>"
  end

  # Make tablist out of a given set of tabs.
  def build_tablist(tabs, do_sep = true)
    list = "<ul>"
    tabs.each_with_index do |t,i|
      list << make_tab(t)
      list << make_separator if do_sep && i != tabs.size - 1
    end
    list << "</ul>"
    list
  end

And an example of use (that assumes existance of restful_auth)

<div id="topnav" class="tabNav">

    <% # standard set of tabs
      tabs = [] 
      if logged_in?
        tabs << {:name => 'dashboard', :options => dashboard_url}
        tabs << {:name => "my account", :options => user_path(current_user)}
        if current_user.is_admin?
          tabs << {:name => "widgets", :options => widgets_path, 
            :cond => (current_controller?(hash_for_widgets_path))}
          tabs << {:name => "users", :options => users_path, 
            :cond => (current_controller?(hash_for_users_path) && 
                      !current_page?(user_path(current_user)))}
        end
        tabs << {:name => 'logout', :options => logout_url}
      else
        tabs << {:name => 'login', :options => login_url}
        tabs << {:name => 'forgot password', :options => forgot_password_url}
      end
-%>
      
  <!-- tabbed browsing of main site areas --> 
  <%= build_tablist tabs, false -%>
</div>

Note that it also uses a convenience function: "current_controller?" This is below and could almost certainly be done better... but it currently serves to check if the given url-options match the current controller.

  # determines if the given set of options contains the current controller
  def current_controller?(options)
    return true if current_page?(options) # trivial case
    if options.respond_to?(:has_key?) && options.has_key?(:controller)
      return options[:controller] == controller.controller_name
    end
    # try matching it - assumes it's a string url
    options =~ /#{controller.controller_name}/
  end

Scope out your models

Just found a nitfy plugin called AutoScope. It lets you define scopes for a model. For example:

class User < ActiveRecord::Base
   auto_scope \
       :fresh => {:find => {:conditions => ['activated_at IS NULL AND destroyed_at IS NULL']},
       :active => {:find => {:conditions => ['activated_at IS NOT NULL AND destroyed_at IS NULL']}},
       :archived => {:find => {:conditions => ['destroyed_at IS NOT NULL']}}
end

These set up some scoped methods

 new_count = User.fresh.count
 old_users = User.archived.find(:all)
 User.fresh.find(:all).each {|u| u.update_attribute(:activated_at, Time.now.to_utc)} 

I've found these great for filtering collection views that group users distinctly, but span across multiple columns.

    def filter_users
      return default_search unless params[:user_scope]
      scope = params[:user_scope].to_sym 
      case scope
      when :fresh, :active, :archived
        # scopes we recognise
        users = User.send(scope).find(:all)
      else
        users = User.find(:all)
      end
      users
    end

Do note, though, to be careful what to name your scopes. I started out by calling my "fresh" scope "new". Unfortunately this overwrote the "new" function on my User model... not a Good Thing.

Don't flash your partials!

Random Rails tip #1: Don't use a partial named "flash" (well: "_flash.rhtml" to be specific) if you don't want to be flooded with deprecation warnings.

Rails auto-magically creates an instance of @flash for you. This triggers an avalanche of warnings for you in your functional tests :P

RubyFit that works...

We're setting up a FITnesse server and intend to use RubyFIT for it. I tried using Cory Foy's tutorial to help get them talking to each other - but found it was out of date. The differences:

• Get your Rubyfit from sudo gem install fit instead of "grabbing ruby.zip" (because ruby.zip no longer exists on the Interweb)
• Instead of !define COMMAND_PATTERN {ruby -I %p ruby/bin/FitServer.rb -v} use !define COMMAND_PATTERN {ruby -I %p <path to your fit gem's bin>/FitServer.rb -v}
• ignore the fact that FITnesse seems not to be as verbose with reporting the details of exceptions as Cory Foy's tutorial suggests - just move on to the "path" step

Exuberant programming

My colleague (Peter Merel) is the sort of person to get enthused at trying new stuff out. He is an Agile-evangelist, and has been trying all different ways to make this process fit into corporate-land. The main issues involved in this tend to be getting buy-in from the usual management-types who have never been exposed to this methodology, and finding ways to interpret it into the sorts of controls and reporting guidelines that they are used to.

Don't blow up the universe

The kind of "No, no! everything you're doing is wrong, get rid of it all and work our way!" approach tends to be frowned-upon as disruptive to standard operating practice. For good reason - it is.

Changing over an entire system of business practice (such as how to develop software) is a Big Thing for any company. Techie types will often scoff and refer to the inertia of corporate behemoths, entrenched dinosaurism and a corresponding lack of corporate flexibility, but the managers at these places actually have a good point. Changing systems involves time, effort and risk of failure (whether total failure of the system or simply setbacks that cause loss of market share).

A bigger company has more systems and people involved - and so more chance of breaking something valuable. They will generally have an entrenched and provably working system of practice. It may not be the best that is out there, but it has gotten them to where they are now. It's up to you to prove to them that what you're offering is not only better, but that it's worth more than the pain and effort involved in changing over.

Managerese

A complete re-write of corporate practice tends only to come onto the books once the proverbial hits the fan. At which point the company is desperately flailing around for any lifeline they can reach. But most companies actually aren't in this position, which means you have to actually, you know, convince them that what you're doing is a good idea (wierd huh?).

This requires an ability sadly lacking in most techie-types... the ability to speak with management in their own language.

There are a number of supporting tools that assist managers to get a handle on a project - tools they are used to and understand. The requirements spec, the gantt chart, todo lists and regular meetings. They not only understand thse, but know how to integrate them into a working whole. They use them to to juggle tasks and developers, to track project progress and momentum and to basically Get Things Done.

If suddenly you arrive on the scene like some animated furry-toothed geek enthusing wildly about "user stories" and index cards and stand-up meetings; sneering at the locals with their endless requirements specs, gantt charts and deliverables; refusing to work with management unless they change all their habits to match your own... you'll undoubtedly gather some resistance to your methodology ideas... even if they would be better off in the long run.

Bridging Mount Learning-curve

So what can you do to bridge the gap? Is there a way to implement all of our agile programming practices, yet still present the incumbents with the tools they are used to seeing? Can we apply the Principle of Least Surprise to our stakeholders too? Can both worlds co-exist in joyful harmony?

This is what we're currently working on. We call it "exuberant programming". It's a set of tools that allows us to be "abundantly fruitful" with our productivity (using the latest in agile methodology), while still giving joy to the more traditional managers.

The project managers are already productive and don't have the time to scale Mount Learning-curve. So let them have their requirements specs, but instruct them how to structure them using user stories, with each sentence a function point that can be fed into the priority planning-game. Let them have their Gantt charts - but use them to show User Stories. Update them at the stand-up-meetings and generate burn-down charts for the managers to let them see the project velocity.

We can work together. We can have peace in our time! We are the world... <waves lighter in air>

er, sorry, got a bit carried away there...

You can see the potential of what we're proposing. We're still working on the details. I'll post more about it as we develop it.

Exploding contracts == dilemma

Two weeks ago I was bemoaning the fact that my cash flow was in the red and my savings were running away in a torrent. I was then approached by a friend for a contract. Shortly after my interview with them I had four other clients approach me. So suddenly I'm flooded with offers!

One of the other clients was a good friend of mine as well. So I had a real dilemma on my hands. I didn't want to disappoint either one.

The first contract came first - but they hesitated on giving me a "Yes definitely" answer until after I'd started to look at the second one. I felt I had to look at each of them in good faith.

The first contract offered sexy video on the web, the second a really big name financial company

The first contract offerred a relaxed, sociable startup feel with some onsite some offsite. The second offered relaxed, sociable academic feel, onsite-only, but I'd have the chance to teach the rest of the team Rails skills.

It was pretty much neck-and-neck. It was a tough decision, from the perspective of preserving friendships. But when I weighed all the pros and cons objectively, the business decision became clear. In the end, for me, it came down to the fact that the first contract could only offer three days a week, while the second offered full-time.

I start on Tuesday.