First, If you have not already done so, configure your project to use GTM. This is a bit of a no-brainer as it currently stands. Until Apple comes up with something better, GTM is the way to go. It works as advertised, and is a credit to the folks at Google for providing this toolkit.

Now then, many tutorials on the web seem to imply that one should test somewhere in the middle by suggesting to add a few outlets to your controller, fire up IB and wire up your view to your view controller before you even start to think about testing any of it.

Testing controller logic means working under the assumption that you have wired up your view components correctly to match the controller's actions and outlets. Wire up an element to the wrong action (or worse, forget to wire it up at all) and you can easily learn to rely too heavily on manual testing. While this might be acceptable for small one-off applications, within a team of developers practicing collective code ownership, this kind of error can cost real money over time. "Thanks for caring, but I'd rather have a unit test."

Now then, let's take a look at some code!

I have been taking an alternate approach to creating my views and view controllers by writing the test first and then wiring up my components to pass the test. As a result, I'm starting to see other cool ways of tackling the problem while minimizing the amount of code required to get the system under test.

The following is a short method from one of my controller tests which allows me to assert that a UIButton is properly wired up to the right action on a controller (sorry for the screenshots, I'm having problem with syntax highlighting today):

The controller in the above code snippet is an instance variable referencing the controller under test. While it's possible to move this logic into a macro, I liked keeping it as a method. See "actionsForTarget:forControlEvent:" for more information on the second assertion-- this should work with any UIControl as long as you understand which UIControlEvents to accept. Here's a sample unit test which uses the helper method above:

This varies from other examples I have seen on the web in that I don't actually 'fire' an event through the UIButton at all. Technically that approach exercises more of the system, but in this case, if I am confident that the button is wired up to the correct action, that's good enough for me. I would rather invoke the controller logic directly within the test than make the test code longer than it needs to be.

This approach to unit testing avoids mocking, or creating custom categories to get at, say, the internals of UIEvent. Surely there is a time and place for mocks, but so far I have found the SDK to allow me just enough in most cases without requiring me to be too clever. And while I think other approaches are worthwhile in their own way, in a team environment I am less apt to mock out the internals of a system if it means making the tests harder for others to read or follow along. Clean tests are their own reward!

Let me know if you find this approach useful, or how you go about testing that your view and view controllers play nicely. I'm still looking for better ways, and plan to talk a lot more about iPhone SDK testing in the future.

Survey the software you use for yourself, both browser- and desktop-based. Think about which applications provide the most invisible, effortless interfaces. I doubt it will be the ones that hide commands in complex menus and dropdown systems.

For some negative examples, let's look at Firefox and its more social cousin, Flock. Each app offers an advanced bookmark management mechanism, but the usability of that mechanism suffers in each due to over-reliance on cryptic menus.

Here's Firefox:

Can you guess which bookmark management options are going to appear under each menu? Where, for example, would the command for adding a separator live? What about sorting your bookmarks? Can't figure it out? Welcome to the world of evil icons.

For comparison, here's Flock, the social browser derived from Firefox:

Clearly, Flock provides friendlier menus; at least they've got text labels. With enough trial-and-error training, you'll probably be able to teach yourself which command lives under which menu.

Here's another example, this time from the webapp world: Confluence, the popular enterprise wiki package. Older versions of Confluence offered the by-now-familiar star icon. Click it, and a page would be added to your favorites. More recent versions, however, hide the "add favorite" option in one of several dropdown menus. Can you guess which?

If you guessed the "Add" menu, for "add to favorites," you're wrong. It's under the "Tools" menu. Welcome to the world of evil menus.

So where does that leave us? Must every single command available in an interface exist as an always-visible text link within the browser viewport? Of course not. But there are some best practices in choosing how to build our menus:

• Icons are great, but they should either be universally recognizable (such as a star or trash can) or paired with a text label.
• Menu groupings should be intuitive. Use care in choosing the top-level labels and don't group disparate items under the same menu.
• For frequently accessed functionality, consider leaving it as a dedicated clickable item on the page. There's nothing wrong with a mixture of icons and menus, the former for the most popular features and the latter for everything else.

And all too often, dysfunctional organizations create dysfunctional security requirements.

It is common knowledge then that a failure to account for security from the start can prove much more costly in the end.  However, over-engineering security needs can require so much effort that your team may not have enough time left over to actually build the very features you are trying to secure.

I find the following two points very useful to keep in mind when participating in discussions concerning security regardless of the application, but especially when working under the assumption that a new application needs the same kind of security model as the old application:

• All security models are idiosyncratic
• Never underestimate the cost of being flexible

These two items work as polar opposites of each other:  a flexible system can accommodate many types of organizations, but not without the added cost of training, installation, documentation or maintenance. On the other hand, a static model is cheap to build, but rarely captures the nuances of an organization's structure, particularly as business needs evolve over time.

Years ago I worked on a small part of the security infrastructure for a public-facing site.  The security model included a fairly complex, "lattice-based" authorization scheme:  User roles were arranged in hierarchies.  Access to resources could only be determined by understanding both the hierarchy and the security level at each step in the hierarchy.  Resources were configured with different "security levels" along the way.  Half of the information needed to answer the question of access control was stored in a database, and the other half in code.  Because of this, user management was left in the hands of development, and only after that proved to be a clear bottleneck were we given the opportunity to build a front-end management interface for non-developers to manage user access rights.

The system was flexible, but a coordinated mess.  Several developers spent a significant effort to keep things going, and it still took a few hours with a whiteboard to explain problems or inconsistencies in the model.  A simpler, role-based authorization would have sufficed.  In retrospect, the idea of role hierarchies was never justified, and could have been done away completely if just a little bit of the front-end interface had been designed in tandem with the original security specification.

I wish this were an isolated case, but we hear these types of stories time and again.  The lesson I take from it is that, in trying to be flexible, an organization can overshoot its needs.  In this case, the security model covered the nuances of the organization, but at an ever-widening cost measured in development time, maintenance, training, documentation, review, etc.

While developing OpenSocial applications can be a bit tricky, getting set up to develop can be a real pain in the neck. For this installment of OpenSocial and GWT, I'm going to go through the basics of setting up a simple Hello World gadget with iGoogle. We'll get into the details of signing up for other OpenSocial containers, testing, and so on, later. Right now we're just going to do the basics.

So, what do you need to build a Google Gadget with GWT for iGoogle? You need the following:

1. The Google Web Toolkit
2. The GWT Google Gadget API
3. An account on iGoogle
4. Access to the iGoogle sandbox
5. Some public server space so you can serve up your gadget to iGoogle

Pretty much everything else is self explanatory, but the sandbox can be a little bit confusing. Let's talk a little bit about the iGoogle sandbox. It's an experimental space where you can test things out without polluting your regular iGoogle account. Eventually you'll want several accounts in order to test. But every journey starts with a single step.

First, you need to sign up for iGoogle. I'll assume this isn't your first rodeo and you've done this before. Once you've got your iGoogle access, you'll want to go over to this page to sign up for the developer sandbox and add the developer tools to your space.

When developing, make sure that there's a message towards the top left of the page that says "Welcome to the iGoogle Developer sandbox." If you don't see that message, you're not in the sandbox. If you have to, navigate to http://www.google.com/ig/sandbox. You may have to "sign up" again to drop into the sandbox.

Once there, you can add those developer tools. Just clicking this link will get you started.

The developer widgets are:

• My Gadgets: let's you set inlining and caching on the Gadgets on your page from a handy interface
• Sandbox Profile Editor: let's you modify your profile in the sandbox so you can test a few things out.
• Sadbox Friends: lets you view and edit who your friends are. Important for OpenSocial applications.
• Updates:shows activities posted to your friends while interacting with the gadget.

The Hello World Gadget

In this part we're not doing anything OpenSocial related. We're just setting up a Google Gadget. That's a necessary first step for the OpenSocial stuff.

Let's get started. In my example I'll be working in ~/src/HelloGadget. Create a lib directory and put the gwt-gadgets.jar library file from the GWT Gadgets API project in it. Next, we run the GWT projectCreator to create our ant and Eclipse files:

./projectCreator -ant HelloGadget -eclipse HelloGadget -out ~/src/HelloGadget/ -addToClassPath ~/src/HelloGadget/lib/gwt-gadgets.jar
Created directory /Users/dkappe/src/HelloGadget/src
Created directory /Users/dkappe/src/HelloGadget/test
Created file /Users/dkappe/src/HelloGadget/HelloGadget.ant.xml
Created file /Users/dkappe/src/HelloGadget/.project
Created file /Users/dkappe/src/HelloGadget/.classpath

Now we create a simple sample application using the applicationCreator tool:

./applicationCreator -eclipse HelloGadget -out ~/src/HelloGadget/ -addToClassPath ~/src/HelloGadget/lib/gwt-gadgets.jar com.pathf.demo.app.gwt.client.HelloGadget
Created directory /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt
Created directory /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/client
Created directory /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/public
Created file /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/HelloGadget.gwt.xml
Created file /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/public/HelloGadget.html
Created file /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/public/HelloGadget.css
Created file /Users/dkappe/src/HelloGadget/src/com/pathf/demo/app/gwt/client/HelloGadget.java
Created file /Users/dkappe/src/HelloGadget/HelloGadget.launch
Created file /Users/dkappe/src/HelloGadget/HelloGadget-shell
Created file /Users/dkappe/src/HelloGadget/HelloGadget-compile

You now have a nice little application that you can run using the hosted mode script HelloGadget-shell in the src/HelloGadget directory. Congratulations, you have a sample GWT application.

But we want a Google Gadget. In order to make it a gadget, we have to change the code a bit. First, import the project into Eclipse. Then open the HelloGadget.gwt.xml and add the following inherit statement.

<!-- Other module inherits                                      -->
	  <!-- Inherit Google Gadgets API -->
	  <inherits name="com.google.gwt.gadgets.Gadgets" />

Now let's open up the HelloGadget.java file. We're going to change it around a bit so it can be a gadget. The critical part of the original looks like this.

public class HelloGadget implements EntryPoint {
 
  /**
   * This is the entry point method.
   */
  public void onModuleLoad() {

We change our class to extend Gadget and change the onModuleLoad method to init.

@ModulePrefs(title = "HelloGadget", author = "Dietrich Kappe", author_email = "dkappe@gmail.com", height = 300, description = "A simple gadget.")
public class HelloGadget extends Gadget<UserPreferences> {
 
	/**
	 * This is the entry point method.
	 */
	@Override
	protected void init(UserPreferences preferences) {

You have to also import the following three classes:

import com.google.gwt.gadgets.client.Gadget;
import com.google.gwt.gadgets.client.UserPreferences;
import com.google.gwt.gadgets.client.Gadget.ModulePrefs;

Running the Darned Thing

Done! Well, not quite. While changing the EntryPoint to a Gadget was pretty straightforward, we now need a container to run the thing. Mind you, it will still run in it's current form in hosted mode, but all of those things it's expecting from iGoogle are not going to happen. So it's time to inject it into iGoogle.

Go ahead and compile the code using the shell command HelloGadget-compile. The resulting compiled JavaScript and sundries is under the www directory in your projects home. If you take a look, you'll see a new file that you likely haven't seen before, namely com.pathf.demo.app.gwt.client.HelloGadget.gadget.xml. This is the gadget manifest. Essentially, this is what your gadget container needs to load to display the app. Many of the parameters are set by the parameters to the @ModulePrefs annotation.

Bundle this app up and upload it to your publicly available server. In my case, I've uploaded the app here. This is the link to the XML file. You can now go to the sandbox and, using the My Gadgets gadget, add it to your sandbox.

You can tweak some of the settings having to do with caching of he Gadget resources with the MyGadgets gadgets, but more on that later. Next time we'll set up our simple Gadget in various other containers and perform something a little bit more useful with it (but only a little).

As always, comments and questions are welcome.

Lately I've been working on a revision of one of my first Pathfinder projects, an internal agile management tool. Along with adding and rearranging some features, I'm also taking the opportunity to modernize some of the Rails 1.2 era code up to new Rails 2.1 and 2.2 features.

Note 1: I don't always (or often) recommend a wholesale update of working code when updating features. But this was a large enough feature change that cleaning up the code is worth the effort.

Note 2: When the time comes for you to perform a major refactoring like this remember that your tests have all the institutional memory about how the application should work. What I actually did was create a new blank project, and copy test files one by one. For each file, I commented all the tests, then uncomment them one at a time, rearranging the test as needed to match the new data model. Sometimes I take the new code directly from the previous version, sometimes I rewrite using a newer or better idiom. This gives me the benefits of test-driven design in my big refactor, while still preserving all the functional specification in my tests. (This seems to work better on models than controller/views, I'll probably have a fuller report next week).

There was one particular design decision in the original code that had always bothered me, but I could never think of a better solution.

In this system, the basic unit is the story. A story can belong to several other different entities in the system -- one or more users, an application, a specific iteration, and so on. Each of those entities, obviously has a has_many relationship with stories, and each one has a mostly-common set of functionality needed from that relationship -- how many stories have been done, how many are left, how many stories were done last week, and so on.

My original design placed all those common methods in a StoryGroup module. Each class that used stories had a declaration like this:

class Application < ActiveRecord::Base
  include StoryGroup
  has_many :stories
  ## and so on
end

Within the story group, there were a lot of methods that performed calculations and called back to class methods of Story, in part, that might look like this...

Module StoryGroup
  def remaining_expected_hours
    Story.expected_hour_total(remaining_stories)
  end 

  def remaining_tasks
    stories.select{ |each| !each.complete? }
  end
end

Class Story
  def self.expected_hour_total(story_list)
    if story_list.blank? then return 0 end
    story_list.to_a.sum(&:expected_hours)
  end
end

Honestly, I can't quite recreate the rationale for having the expected_hour_total method as a class method of Story. I think it's because there was a usage within the Story class before there was a need for it among the StoryGroup classes.

I have two main problems with the structure of the old code. First, having to include the module and declare the has_many relationship always struck me as kind of dodgy. Second, calling back to a class method of Story that takes a list of stories as an argument is really ugly looking, and the class methods kind of gunk up the Story class with a lot of calculations that don't necessarily belong there.

Everything works in the old version, but I was pretty sure there was a cleaner way. In the new version I solve both problems (I think). The first problem is solved by taking a page from your basic acts_as plugin. The second problem is solved with named scopes. Named scopes are particularly helpful here, since they apply to both Story as a class and to any has_many :stories associations. As a result, all the common story functionality is easier and clearer to describe.

The new StoryGroup functionality is a module, now placed in the config/initializers directory. This seems a bit verbose, but most of it is the standard boilerplate for an ActiveRecord plugin -- the main functionality will be in the InstanceMethods submodule

module ActiveRecord
  module HasManyStories

    def self.included(base)
      base.extend(ClassMethods)
    end

    module ClassMethods
      def has_many_stories
        has_many :stories
        include ActiveRecord::HasManyStories::InstanceMethods
      end
    end

    module InstanceMethods
      def remaining_expected_hours
        stories.uncompleted.sum(:expected_hours)
      end
    end

  end
end
ActiveRecord::Base.send(:include, ActiveRecord::HasManyStories)

On initialization, the has_many_stories method is added to ActiveRecord::Base. Any ActiveRecord class that calls the method, then gets all the instance methods included within it (I've left out common class methods, because they are not needed for this example)

Adding the story relationship and the common methods is now down to a single line within the class:

class Application < ActiveRecord::Base
  has_many_stories
end

In the new module, the remaining_expected_hours method has changed, now calling the named scope stories.uncompleted rather than a class method. The scope definition itself is straightforward.

class Stories
  named_scope :uncompleted,
      :conditions => {:state => ["new", "in_progress", "blocked"]}
end

As an added bonus, using the scope and appending sum to the scope now does the calculation in the database, which should be faster than the earlier version, which was calculating the sum in Ruby.

I like this cleanup. The individual methods within StoryGroup are now significantly simpler. The named scopes they depend on are also simpler and less distracting in the class then the previous class methods. Because the scopes are compossible, it's much easier to add calculations to the various slices of stories that the system needs.

What do you think? Have you had a similar problem? Is there a better way to solve it?

At times that can seem like a cop out, an admission of defeat in the face of the Flash arsenal of graphic effects. Somtimes, like today, it seems more like a visionary declaration of the power of Canvas. Check out Steven Wittens' use of Canvas for projective texturing. Maybe there is a little bit more coolness left in these Ajax bones.

At first I didn't like the fact that I needed to explicitly create the data for what I was working on, but then I realized that (especially for unit tests)  you don't need much dependent data; usually it's one or two records. For functional tests, I found that the data setup methods rocked, as I could quickly get the data set up that I needed.I could quickly assert the content of the response, based on the data in my setup. I missed fixtures at first, but now realize that over time, they are a pain.

My unit tests used to take about 5 seconds, now it's around a minute. I am not really happy about this, as I like to run rake before each commit, and I am apparently very impatient. The luxury of fixtures is that it loads the data directly in the database, and skips the model validations and what-not. The transaction is started, each test is run, and then the transaction is rolled back. Now, all of my data setup occurs in the transaction rather than before it.

So, I think I am definitely using the plugin, but need to make sure not to create any more data than necessary for the tests I'm writing. I guess I miss the speed of fixtures, but the benefits from the plugin seem to outweigh my impatience.  At first it seemed that fixtures were the way to go, but the more I use fixture replacement, the more I realize that I don't miss them at all.

As I blogged a few weeks ago, I ported the Java chess library ChessPresso into GWT, which was a blast and an example of how you can leverage existing Java libraries to write browser-based apps.

In the example, I've pulled the eleven games of the recently completed world championship between Anand and Kramnik in a single page. The GWT app identifies all of the relevant tags, reads the PGN (Portable Game Notation) in those tags, then inserts a game viewer widget into the page.

What isn't working yet:

• Doesn't look so good in IE (a little CSS work)
• The notation pane isn't hooked in so you can click on a move and jump to the position

Anyhow, have a look and let me know what you think.

Update: OK, the notation panel is hooked up to allow clicking on moves to navigate aroung the game. Still looks like crap in IE, though.

Update: for those interested in some of my very few games that make me look good, see here.

Update: Another set of tweaks to display a collection of games, one 41 games PGN chunk and a 250 or so chunk. See here.

Code organization

If I'm filling a front-end role on a Rails project, most of the files I need are in /app/views and /public. I dig that. Likewise, I appreciate the underscore naming conventions for partials. However, I wish /layouts weren't just another subdirectory of /app/views. Layouts are inherently different from standard view templates. A better hierarchy within /app/views would help drive this home. Likewise, I wish partials and full templates each had their own directory within a specific controller's view folder. That would help keep directories manageable on big projects. The /public directory, on the other hand, offers just the right amount of organization.

Markup and styles

Scaffolds are awesome for rapid prototyping, but the markup and styles they spit out reflect a standard of front-end coding that's several years out of date. Plenty of plugins tackle this very problem, but I'm disappointed to find so little attention to view-layer code from the core version of such a respected application platform.

In an ideal world, a platform famed for its convention-over-configuration approach would ship with a decent reset.css and a solid baseline stylesheet with reusable utility styles that rely on class rather than id attributes to work their magic. I'm not talking about layout so much as simple problems that have long been solved in the web standards world: pure CSS pipe-delimited lists, table-free form layouts and the like.

So much Rails development is about tweaking the defaults just enough to achieve the results you need. That means lots of crappy auto-generated markup ends up in production. Rails can't be all things to all people, but it would be cool if it didn't pump out antiquated UI code by default.

Macros and view-logic encapsulation

Tab-based templating systems make it easy to separate view logic from application logic. Whether you're using JSTL or a custom tag library, JSP 2.0 offers a specific syntax for templating that's different from the syntax used for model and controller logic. Sure, JSP tags compile down to Java, but they look different from regular Java. And sure, you can use scriptlets in JSP, but you don't have to.

In Rails, however, ERB looks like plain old Ruby code. It's hard to tell at a glance whether the Ruby contained in a template is doing view stuff or jumping the shark to tackle controller and model stuff. This makes it very difficult for either humans or automated tools to do sniff tests on Rails code for separation of concerns at the view layer.

Helpers exacerbate the problem. In JSP, if you need to create a view-layer macro, you do it as a tag. In Rails, you do it as a helper. But those helpers live in the same place as other, unrelated helpers from the controller. The result is a mixture of view code and controller code within the same directories and even the same files.

If experience has taught me anything, it's that controller logic and even model logic like to leak into the view. Without strong conventions to prevent this, it's too easy to compromise your MVC architecture and hinder the maintainability of your application. JSP offers better encapsulation of the view layer - a clear advantage.

JavaScript

I've posted before about my experiences dropping jQuery into Rails and making it work. I'm not a huge fan of the tight coupling between a specific JavaScript framework and the core server-side framework. Nor do I love the lack of built-in progressive enhancement on many of the Rails Ajax helpers. I get why it's attractive to people without dedicated front-end resources. But for anybody who wants to do a really sophisticated behavior layer, Rails Ajax helpers are more of a hindrance than a help. jRails and other projects offer a way to drop jQuery into a project and still access the Rails Ajax helpers, but I'd love to see a different approach to sophisticated Rails Ajax, one that doesn't create apps that break when JavaScript is unavailable.

Conclusions

Of course, I'm still a Rails noob and have probably missed all sorts of best practices that could help ameliorate the bad and accentuate the good. Let me know in the comments!

Everybody sing! (to the tune of "Love and Marriage")

Helpers and Partials

Helpers and Partials

Go together like a

Fire and a Marshal.

Okay, that was silly. In my defense, the tune has been going through my head all day since I decided this would be my topic today.

Yes, we're back in Chapter One Zillion And Three in the ongoing epic: How Do You Write View Code Anyway?

Previously, I had tried to move as much view code as possible to helper methods. This produced some interesting code, as well as a threatened revolt on the part of the non-Ruby programming HTML designers and architects who had to look at it. Pitchforks and torches were mentioned, and there was muttering about know-it-all code monkeys. The primary complaint was that non-Rubyists couldn't easily modify the code buried in tangled Ruby gunk in helpers. At the same time, everybody agrees that ERb code running all over the place is a total mess.

What to do, what to do?

Listen to me, of course. Here are my thoughts about managing view code. This week.

Keep the view code as close to HTML as you can

This is something of a change for me -- I've always been a big fan of generating HTML from code, dating back to my first web apps. And I still think that generating HTML has a place. Still, working close to HTML has some advantages -- non-Ruby designers can tweak the view directly, which is much more efficient. It's easier for new people to join the team. ERb is, in my experience, close enough to HTML for people to be able to tweak. To give one other example, Haml is not.

Treat ERb with the respect that you treat your code

A slight attitude adjustment toward the ERb can help a lot. I see a lot of legacy Rails code that we get where the ERb files have been allowed to get out of hand in a way that a professional developer would never let plain Ruby code get out of hand. ERb is part of your code, and the same design principles that inform your code structure still apply.

• Don't Repeat Yourself in ERb
• Indentation and layout still help readability in HTML and ERb
• Refactoring ERb files is a valuable way to clean them up
• View code should be tested to ensure correct results

And so on. Replacing ERb with Ruby in the preceding list would make it seem like complete newbie advice, but not everybody treats their ERb the same way.

An individual ERb file is a method. Not a class.

The biggest problem in ERb files is that they get long and raggedy, which makes it increasingly difficult to find what's going on and make changes -- in exactly the same way that long methods make Ruby code hard to manage.

Luckily this is reasonably easy to manage by aggressively breaking ERb code off into partial methods, in much the same way that a long method is best refactored into a series of smaller methods. I like to break off code inside loops into a partial, headers, footers, and sidebars of various types are obvious candidates. Really, any coherent block of the page should be in it's own partial.

Doing this has several advantages.

• Keeping the ERb files smaller makes them easier to follow. I start to get nervous when they go longer then a screen, which is a mere 35 lines or so on my monitor. Obviously, sometimes you need an ERb chunk to be longer, but a long ERb file should at least trigger a "can I split this" thought.
• Your main page ERb will likely then largely consist of calling several partials. If you give the partials meaningful names, it's very easy to follow what the page is doing, you get some self-commenting code.
• It's almost inevitable that you'll find reuse opportunities for some of your small partials, especially in an Ajax-heavy site.

The main disadvantage is that it can get tricky to find a specific piece of page if you need to follow the code through nested partials. I find that clear naming tends to make this a minor problem.

Helpers are best used to help

Helpers are most useful, I think, for small, boilerplate pieces of code that are used frequently and which are unlikely to be messed with by designers. Basically, you're using them to improve the API to make it more specific to your application. Looking at recent projects, I see things like:

• Wrappers around commonly used link_to and link_to_remote patterns
• Wrappers around common HTML patterns -- such as header_row or label_block. Most of these are very short.
• Block guards along the lines of if_logged_in?
• Rarely, global data access methods along the lines of current_user, where it makes more sense to have a method rather than assign the data in some weird set of controller actions that might need it.
• As presenters, generating display-specific data based on a model, where you don't want to put the code in the model because it's view specific. The display-specific formatting of an address, for example.

Going much beyond that, I find from somewhat painful experience, and you run the risk of having some opaque view code in your helpers.

Your turn. How are you structuring view code these days?

In my current Ruby on Rails project, I am checking all roles and ensuring those who should be able to do certain things are able to, and those that shouldn't are unable to. What I have found, is that usually, the Admin and one other role can usually do a set of things, and every other role can't. So, I find that I set up my tests the following manner:

['root','hr'].each do |role_name|
    context "logged in as #{role_name}" do
      setup do
        login_as_user(role_name)
      end
 
      should 'index' do
         get :index
         assert_response :success
         # other assertions
      end
  end
end

This is for the roles who cannot do the actions:

['user','manager'].each do |role_name|
    context "logged in as #{role_name}" do
      setup do
        login_as_user(role_name)
      end
 
      should 'index' do
         get :index
         assert_redirected_to root_url
         # or logged out - or whatever you do with a violation of this type
      end
  end
end

You can now see that we have automated tests that assert the expected functionality for all roles in the system. As a developer who deploys and supports applications in production, it is very reassuring to me that our code has this level of tests. I know that when I deploy, there won't be that many bugs, and I don't have to fear production deployments; just schedule them and perform them.

What usually needs to happen on a project is a combination of some or all of the above. Not having a single point of reference for skinning creates quite a bottleneck.

From different approaches, two surfaced as having the best pipeline: Illustrator CS3 and Degrafa. If we are talking speed and ease of graphic design, I would now default to Illustrator CS3. For advanced skinning and interactions Degrafa holds first place.

Speed, of course, is a major factor. A lot of projects do not need advanced skinning, but just a step forward from useful but many times seen default Flex skins. By that I mean applying the brand guidelines of the company or product/service.

After a long time I gave Illustrator another chance and the CS3 version proved remarkably useful. Illustrator with Flex CSS that is.

My goal was to create the fore mentioned single point of reference for skins and I did it in Flex CSS. Good people of Adobe even made a script for Illustrator to speed things up which I gladly use. Process works fine without the script too (maybe even faster, but you have more skins to track yourself), and you can find a tutorial for that version here.

For the streamlined version you can find Illustrator scripts here (together with scripts for other apps) and you need to have a free Adobe account to download.

STEPS:

1. Download the Illustrator scripts from here. You can find the installation instructions in the downloaded archive.

2. Create your skins for various states of the component in Illustrator as you would do usually using all the wonderful features of Illustrator.

3. Convert your skins to Symbols.

      a. Open the Symbols panel in Illustrator (Window -> Symbols).

      b. Select a particular skin graphic that you have made.

      c. Click the "New Symbol" icon in the bottom right corner of the Symbol panel.

      d. Naming the symbol is important. For example, if you want to automate creating an "up" state skin for a button, you would name it myButton_upSkin. For "down" state you would select an appropriate graphic to create a symbol from and name it myButton_downSkin. So for every state you want, you would add an underscore and state name after the symbol name that needs to be camelCase.

      e. I would highly recommend setting the "Flash Registration" point to upper left corner to be in sync with standard flex registration point.

      f. If you want to have the symbol to scale using 9-slice approach, check the box labeled "Enable guides for 9-slice scaling". You can later go back to your symbol and adjust the slices position.

4. Now that you have made the symbol (and adjusted slicing if need be), you can export it by choosing:

File -> Scripts -> Flex Skin -> Export Flex Skin.

A SWF file will be created by name of your choice.

5. Go to Flex Builder and choose:

File -> Import -> Skin Artwork

6. Set up parameters in the dialog box like this:

      a. Select "SWC of SWF file" and point to the file you've just created in Illustrator.

      b. Select the folder you want to import it in.

      c. Click "Next".

7. At this window you will be prompted to select the skins that you want to import. No reason not to "Check All" here. For the selected skins you will now see the states of the particular skin in the "Skin Part" Column.

8. Click "Finish" and a Flex CSS file will be made with all the skins appropriately declared.

9. All you have to do now is to apply the name of a particular skin to your components Style name.

This skining approach has proven very fast and error free for me.

I'm enjoying the 9-slice scaling, vector graphic crisp scaling and mouse interaction only with visible pixels.

I have worked on projects that have used Use Cases and Functional Specifications, but these never seem to convey all the necessary information for all involved. They tend to be very verbose, and they are really not fun to write, read or manage. A good requirement should tell each audience member exactly what the expected functionality is, and never generate a myriad of questions from all involved. It's often difficult to solicit information from a client, but documenting for developers should never be that hard. Here is a recap of what a good requirement is:

Good Requirements:

• User Stories
• User Acceptance Tests
• Workflow
• Requirements (Details)
• Wireframes

Without any one of the aforementioned sections, the requirements start to lose value. Each section brings a lot to the table, and too often they are judged as a "waste of time." Much like pair programming, having each of the sections for your requirements actually creates a synergy, as the development process is sped up. (Sorry for the consultant buzzword, but it does)

• User Stories

This states all of the scenarios of the users involved. These should read:

As a SOME ROLE,
I want to DO SOMETHING,
So that I CAN GET SOME BENEFIT

The user stories are critical to lay out exactly who is going to do what, and for what reason(s).

• User Acceptance Tests

These should include all scenarios outlined in the user stories. These should not be too detailed (they don't need to mention specific screens or a complete list of actions to execute the steps). These should read:

GIVEN that condition 1 and condition 2....
WHEN I do step 1, and step 2...
THEN, desired result 1, desired result 2....

These define a set of actual scenarios a tester could walk through to assert that the feature is complete. These are not detailed test scripts that you find in UAT. They are meant to convey a set of tests that all involved can walk through to understand how the feature will work.

• Workflow

This should include a picture of the screens involved. Error states and view changes based on role should be documented. This picture is worth a thousand words, as the details of the flow through the feature can be quite complex, and this is hard to spell out the details in the next section. We have been using Gliffy, a confluence plugin, and it rocks. It is a flash app that allows us to create and edit the workflows with eases.

• Requirements (Details)

These are the details of the feature. Document all screen(s) and every field, label, validation, message, and action. This is essentially the functional specification of the details of the screen(s) involved. Because it is in the context of the wireframe (next section), it is more concise. You can simply reference the field name, rather than verbosely state everything about the field. You can keep the details to field length, required, etc.

• Wireframes

A picture is required for each screen involved. Wireframes can be simple drawings on a whiteboard that are photographed, or a set of boxes created in Visio or OmniGraffle (or anything really). Some are photoshop-ed, and others are HTML. We have found that the best approach is HTML if that's your end result. Recreating HTML that looks the exact same as a picture can be quite painful. Usually, a visual designer is involved in creating the mock ups, and can easily do this work in HTML. The developers can therefore take the exact HTML that is requested, and fill in their code as needed.

See Alice's post about wireframes, and Noel's post about how you can allow a designer to write the HTML within a rails application.

Smooth Project

If each iteration begins with all features fully documented in this format, it runs smoothly, and often finishes early, leaving time for those TODOs we all keep a list of. I have found that when writing requirements in this format, many of my questions for the client comes from writing the very first two sections. Coming up with the user stories and acceptance tests often find huge oversights of the feature, as you start to detail who will use it and in what ways.

Given that I am a user who clicks on a link.... well - what if that user doesn't have access to view the link? Details like this help generate a list of questions for the client, who often can't think that far ahead with respect to the complexities of the system. Writing the requirements to this level of details, ensures that oversights are found early, and before any code is written. Unfortunately, all too often, some project managers don't see the value in ensuring requirements are complete before they get the developers involved. This always leads to chaos during the iterations and is a recipe for disaster.  I have found that projects that have finished requirements before iterations are often under-budget, and the team members are quite happy to be on the project.

If you do a gem install ferret, you will be getting 0.11.6. The latest stable version of acts_as_ferret is 0.4.3. Both of these versions were released nearly a year ago in November 2007. Since then, there have been various performance improvements and bug fixes which you'll be missing out on. In order to get the latest versions, you'll need to do a little bit of work but I would recommend it if an update is feasible for you.

Since it will be the easiest, let's begin with acts_as_ferret.

acts_as_ferret

Installing the latest version of acts_as_ferret is pretty straight forward, as the documentation for it is pretty clear.

If you are starting a new project:

script/plugin install svn://projects.jkraemer.net/acts_as_ferret/trunk/plugin/acts_as_ferret

If you are updating an existing project:

script/plugin install svn://projects.jkraemer.net/acts_as_ferret/trunk/plugin/acts_as_ferret --force

The --force option will force a re-install.

Ferret

Ferret is a bit more involved. The gem on RubyForge is version 0.11.6. Ferret has been moved to github, but sadly the github gem source does not include ferret. In order to install an updated ferret gem, we will need to compile it and install it by hand. Thankfully, this process is not difficult.

Unfortunately, the ferret project site has been down for a few days now. Google cache does have a copy of the instructions from the site for installing edge as a gem on your machine; however, the instructions are old and a little inaccurate for the latest version. Despair not! I went through this process yesterday and this is what worked for me.

Checkout and Compile

First, we need to checkout the latest ferret code. This will require git.

$ cd /tmp
$ git clone git://github.com/dbalmain/ferret.git

Next, let's run the tests to make sure everything is working right. This step will compile the code, which will take a little bit of time before the tests are run.

$ cd ferret/ruby
$ rake

If this fails, you will need to make a slight change to the rake task. I got the following error message while running this on a mac: rake aborted! WIN32 has been removed, use CURRENT instead.

Do the following step only if you get this error and you are not on a windows machine.
Change the following lines in ferret/ruby/Rakefile

windows = (RUBY_PLATFORM =~ /win/) rescue nil
SUDO = windows ? "" : "sudo "

to

windows = false

Then, run rake again.

Now, we need to build the ferret gem.

$ rake package

Simple, right?

Installation

Installing the gem is simple as well.

$ cd pkg/
$ sudo gem install ferret-0.11.8.gem

Of course, if there is a different version number you should use that instead. Feel free to uninstall the old gem if you want.

If you unpacked the ferret gem in your rails app, you will need to remove it and unpack this new version. Navigate to your rails app directory.

$ rm -rf vendor/gems/ferret-0.11.6
$ rake gems:unpack ferret

You will probably need to rebuild your index, as I do not believe a 0.11.6 index is compatible with 0.11.8 (I needed to rebuild it).

$ rake ferret:rebuild

I would highly recommend that you run your tests for your app, to make sure nothing was broken. Assuming everything went well, you should now be using the latest versions of ferret and acts_as_ferret.

Those of you using ferret 0.11.6 (the latest released gem) and acts_as_ferret 0.4.3 (the latest stable version) may have noticed that rebuilding an index can be painfully slow when working with a large number of documents. Even if each document contains a relatively small amount of text, indexing crawls with a large set of documents. The problem is a result of how bulk update works; "bulk indexing" processes a single document at a time! Fortunately, there is a simple patch which will provide a significant speed boost.

There is a fairly old trac ticket where Francois Lagunas posted a clever patch which will make bulk indexing process documents as a group. Here is a monkey patch based on what he submitted as a patch (in Rails, just drop this as a file into config/initializers).

class Ferret::Index::Index

  def update_batch(docs)
    @dir.synchrolock do
      ensure_writer_open()
      commit = false
      docs.each do |id, value|
        delete(id)
        commit = true if id.is_a?(String) or id.is_a?(Symbol)
      end
      if commit
        @writer.commit
      end
      ensure_writer_open()
      docs.each do |id, new_doc|
        @writer << new_doc
      end
      flush() if @auto_flush
    end
  end

end

class ActsAsFerret::BulkIndexer

  def index_records(records, offset)
    docs = {}
    batch_time = measure_time {
      records.each { |rec| docs[rec.id] = rec.to_doc if rec.ferret_enabled?(true) }
      @index.update_batch(docs)
    }.to_f
    @work_done = offset.to_f / @model_count * 100.0 if @model_count > 0
    remaining_time = ( batch_time / @batch_size ) * ( @model_count - offset + @batch_size )
    @logger.info "#{@reindex ? 're' : 'bulk '}index model #{@model.name} : #{'%.2f' % @work_done}% complete : #{'%.2f' % remaining_time} secs to finish"

  end

end

If you are using a newer version of ferret by building the gem yourself, the ferret side of this patch is already included (although, you do need to make a slight change on the acts_as_ferret side). Stay tuned for another post about how to do this.

Lots of big-name, highly successful sites eventually reach a state of paralysis in which they're too scared of alienating their customers to examine their interaction design and information architecture from a fresh perspective.

The cautionary tale of Amazon.com

Look at Amazon: The online retailer adopted DHTML navigation just last year - at least 5 years after most other big sites - because its tab interface had grown so comically large. Nevertheless, huge chunks of the Amazon user experience are still massively broken:

• Once you've started down the checkout process, the site tries to keep you from getting back to your shopping cart to add or remove additional items. If you use your back button to do so, you've got to start the checkout process all over again.
• Wish lists offer perhaps the most confusing, error-prone user interface I've ever had the displeasure to experience.
• Link targets on a wide variety of UI controls are tiny and persnickety enough to elicit involuntary profanity.

Why does Amazon let its design blunders live on in perpetuity? It's simple: Redesigns confuse users, and confused users don't spend money. Your current customers have invested so much effort in learning to work around your site's shortcomings that a new interface stops them in their tracks. Even the most humane and usable UI refresh takes acclimation - and that may cost your site conversions and revenue in the meantime.

The agony and the ecstasy of the redesign

I learned this lesson the hard way during my days at Reflect.com and Orbitz, where A/B testing constantly shocked us by revealing that change, any change, causes key metrics to dip, at least temporarily. Redesign an unusable feature and test the old and new versions with your current customer base on the live site. Chances are, the old version will win in the short term. That's why it takes guts to even consider a top-to-tails redesign. If small changes can have a negative impact, big changes could be deadly.

To me, however, it seems as if the bigger danger lies in allowing your site's information architecture to become ossified. Eventually, new UI paradigms will offer your younger competitors an avenue for feature differentiation. I was at Orbitz when Kayak.com launched, and I was sick with envy that a site could push the user experience of online travel into such new and compelling directions. I knew a company as large as mine could never rock the boat by switching to such an off-the-wall UI.

Sure, budget aggregator Kayak wasn't a direct competitor to an online travel agent like Orbitz. But if somebody had launched a full-service OTA with an interface as fresh as Kayak's, then Expedia, Orbitz and Travelocity would have been forced to play catch-up. After all, it was UI differentiation that had originally allowed Orbitz to woo customers from other, more established competitors: Its matrix-based results pages provided a compelling new way to find cheap seats. Eventually, though, other sites copied that feature. Now, all the big OTAs match each other feature for feature.

Beta sites: Hope for the future

That's what's so impressive about today's crop of Web 2.0 upstarts. A young service such as FriendFeed can offer an entirely separate, opt-in beta site and tinker away at it without annoying current users. Then, once the geekier end of the user base has helped work out the kinks, the service can flip the switch and roll out its new features to everyone. That's exactly what Facebook did with its new interface, but at far greater risk than FriendFeed. Facebook may be obscenely overvalued, but it does function as a business. A redesign is far less scary for the relatively unmonetized FriendFeed.

Regardless of whether you're a social networking giant or a microblogging upstart, this kind of usability and design lab has become de rigueur. By acclimating your users to frequent change early on, you can help ensure that future refreshes don't send them packing. Amazon may be in a design coma, but your site shouldn't have to be. Have the courage to redesign early and often.

One of the annoying things about the highlight visual effect in Scriptaculous is that it will break your :hover background-color CSS definitions. The occurs because scriptaculous sets the background-color style property of the element to whatever it was set to before the effect began. This behavior would be desirable if you're using inline styles or setting the style property through javascript, but you will run into issues if you're doing it The Right Way™ and using CSS classes and Element.add/removeClassName. Fortunately, there is an easy solution to this problem.

To fix this on a case-by-case basis, you will need to use the afterFinish callback.

First, we'll define the function in some javascript so we can reuse it.

Object.extend(Effect.Highlight, {
  clearBackgroundStyle: function(effect) {
    effect.element.style.background = "";
  }
});

Unfortunately, we cannot use Element.setStyle to do this, as the blank style definition is ignored when going through prototype.

Now, we just need to set the callback. If you're in rails and doing RJS, it will look something like this:

page.visual_effect(:highlight, dom_id(@smurf),
  :afterFinish => 'Effect.Highlight.clearBackgroundStyle'
)

Which will produce the following javascript:

new Effect.Highlight("smurf_7",{
  afterFinish: Effect.Highlight.clearBackgroundStyle
});

If you would prefer to just patch scriptaculous instead, just include the following javascript after effect.js from scriptaculous is loaded (a default rails app can drop it into application.js).

Object.extend(Effect.Highlight.prototype, {
  finish: function() {
    this.element.style.background = "";
  }
});

The Rails 2.2 release contains a number of big features that are going to be commented on endlessly, especially thread safety, internationalization, and ETag support. Going through the various release notes and what's new documents, I found a lot of smaller features that I'm looking forward to using in future projects, or would have made past projects easier, or are just cool in a framework-geek kind of way.

The concat method no longer needs a block binding

This may be the most subtle change I've ever been this excited about. Let's go back to the bad old days -- last week -- and say that you wanted to write a block helper method like this:

  def label_block(caption, &block)
    content = content_tag("span", caption) + capture(&block)
    concat(content_tag("label", content), block.binding)
  end

It's the block.binding part that was crazy-making. It was an implementation detail that was unfortunately exposed to the programmer (Since the ERb output stream was a private attribute, the method needed direct access to a binding frame to push text into the stream. I think.) Plus, it was off-putting to explain to new Rails programmers, and as an added bonus, made block helpers a total pain to test.

Well, now the ERb output stream is more accessible, and you can now do without the block.binding argument -- in fact, you'll get a DepricationWarning if you use it. You can just remove the argument from the helper, or since you no longer need the explicit block, the helper can now be written in a more Rubyish style:

  def label_block(caption)
    concat("<label>")
    concat("<span>#{caption}</span>")
    yield
    concat("</label>")
  end

I'm also interested to see how this works with my Html generator mini-library

While On The Subject of Blocks

There are two nice additions of things that now take blocks. The first is link_to, as in:

    <% link_to(@project) do %>
      "Caption"
      <%= image_tag(@project.image_url) %>
    <% end %>

Also, partials now take blocks, meaning they can act somewhat like layouts.

The partial itself can contain a yield:

   <table>
     <tr><td>
       <%= yield %>
     </td></tr>
   </table>

Then the call to the partial can include a block:

<% render :partial => "table_partial" do %>
  <%= @project.name %>
<% end %>

And the yield command invokes the block, as you would expect

Rails Guides

For this release, Rails has added a number of in-depth guides to various and sundry rails features, accessible at http://guides.rubyonrails.org/ or by rake doc:guides from your command line.

Better error message for assert_difference

Speaking of minor changes that make me happy, the error message for an assert_difference failure now actually contains the text of the failing expression, as in "<projects.count> was the expression that failed". I actually saw this one in my testing before I saw it in the release notes. Since it's pretty common for me to nest assert_difference calls when multiple objects are being created at one time, this made me smile.

Performance Tests

And.... another chapter of my book gets further out of date with the inclusion of performance tests that are essentially wrappers around the ruby-prof profiling module. A new generator, performance_test, places tests in a test/performance directory. Inside each test you can do integration test style calls to controllers, and you get nice ruby-prof profiling reports on the results.

This feature, at least in, release candidate, does not seem totally polished. Couple of notes -- it requires ruby-prof 0.6.1, which is not the version available via regular gem methods, it seems like you need to get it at github, and install via the directions here.

There also isn't a rake task to run the performance tests, you need to run them as individual Ruby scripts, which means, if you are like me, then you will be scrambling a bit to make sure the Rails environment loads properly.

second through tenth

This is the sort of nearly pointless syntactic sugar that I love. I mean, nearly pointless in the best and most respectful way, because I plan to use this all over the place. It's actually very Lisp-like...

>> players = %w(who what i_dont_know today tomorrow why because i_dont_care)
=> ["who", "what", "i_dont_know", "today", "tomorrow", "why", "because", "i_dont_care"]
>> players.second
=> "what"
>> players.fifth
=> "tomorrow"

I would love to see a knock-down drag-out argument about the merits of players.second versus players[1]...

assert_sql

This may seem a little esoteric, but I have a reporting feature where I would have used this test extensively. Probably good for searches too. It checks for a match between the argument to the method and SQL generated inside the block.

should "produce correct sql" do
  assert_sql(/LIKE \'me\'/) do
    Product.report(params)
  end
end

StringInquirer

I like this because it's such a nice Rails metaprogramming thing.

>> role = ActiveSupport::StringInquirer.new("admin")
=> "admin"
>> role.admin?
=> true
>> role.user?
=> false

I like it. Here's the entire implementation of the class

  class StringInquirer < String
    def method_missing(method_name, *arguments)
      if method_name.to_s[-1,1] == "?"
        self == method_name.to_s[0..-2]
      else
        super
      end
    end
  end

That's pretty.

Rails scaffolds now generate belong_to links

And finally...

script/generate scaffold task name:string project:references

Will now generate

class Task < ActiveRecord::Base
  belongs_to :project
end

A small thing, but useful.

• Amazon EC2 is offering Windows on EC2, with the pricing at $0.125 per hour for a small instance running Windows Server (as compared to $0.10 for a Linux instance). You can run SQL Server Express at no extra charge. The SQL Server Standard smallest instance (Stadard Large) rings in at $1.10 per hour, however, which ain't such a good deal.
• Microsoft's Azure Services Platform. It's still in community evaluation mode, but there is one thing that is already clear about it: it's as confusing as all git out. One of the advantages of Amazon's services like S3 and EC2 is that they are simple and can form the building blocks for other applications and services.

If I'm provisioning a web application, I'm pretty comfortable thinking in terms of virtual servers or instances. Not sure how to think about scaling and cost with Azure. I think MS would have done better to start out with a KISS approach to drive adoption. Time will tell if their "it can cure cancer" approach will work out.

This week, Rails 2.2 Release Candidate one was loosed on an unsuspecting public. Friday, I'll post about the Rails 2.2 features that I'm most excited about working with. Today, I'm going to review Gregg Pollack and Jason Seifer's screencast on new Rails features (and the associated PDF document by Carlos Brando and Carl Youngblood.)

In the interests of full disclosure, I should mention that we received a review copy of the screencast. In the interest of fuller disclosure, I'll add that had the email from them come even 10 minutes later than it did, I would have already bought it myself (I really was just about to go to their site and buy when I got the email) -- I really liked their first screencast on ActiveRecord. And I really liked this one, as well.

Like their first EnvyCast, the Rails 2.2 cast consists primarily of Gregg and Jason talking directly to the audience while code samples and diagrams appear in greenscreen behind them, with a lot of Keynote-style effects. They've raised the bar in terms of the visual presentation of screencast code. It's a lot more engaging then the typical screencast (including my own). We showed the video in a meeting for all our developers, which I don't think we could have done with a more traditional screencast. Gregg and Jason use the visuals to make the changes between Rails 2.1 and Rails 2.2 code extremely clear. The visual effects don't feel gimmicky or overdone, but nicely focus attention at the important parts of the new code and features.

In particular, the section on the new ETag features is outstanding, clearly explaining what the feature does and how you might use it. This is potentially one of the most important features in the new release. I knew very little about it going into watching the video, and now I am ready to start using the ETag feature in some of our projects.

The video is split into different sections for the different Rails sections with updates -- ActiveRecord, ActiveSupport, ActionPack, ActionController, etc, and covers a lot of ground in 45 minutes. The PDF is even more detailed. I've just started working in Rails 2.2 and I learned about several features that I can't wait to try out.

Overall the two make an excellent guide to the latest and greatest in Rails 2.2. The screencast and PDF are well worth your time and money if and when you are planning on working in Rails 2.2.

Quick notes:

• I would have liked to have gotten more detail on the internationalization features, and to a slightly lesser extent more detail on the costs and benefits of thread safety.
• My favorite of the cheesy jokes was the one about the rejected method eighthiest, returning true if the object doesn't believe in the existence of Enumerable.
• I would have liked a little more acknowledgement that some of the changes were big and some were just little tweaks. I realize that you don't want to put all the big changes up front and then end with twenty minutes of little tweaky things. Still, the video feels a little scattershot at times, and a couple of "here are a few new little code-cleanup features" kind of would have minimized that.