danwebb.net - Rails

Writing a new library? Sketch it out first

2011-02-10T05:51:00Z

So you’re embarking on writing a new library. You might dive right in to the code and work straight on solving the problem or you might take a more considered approach and start thinking about how to model the problem, what classes and methods you need to create, how they interact and so on. However, rather than doing that why not start with sketching out not how the library works but how you would like it to be used. I think you’ll see pretty positive results if you try it.

Usability isn’t just for designers. If you want your co-workers or other developers to use and be productive with this code your creating its got to be as simple and fun to use as your user interfaces. Your library’s API is a user interface. History has shown that libraries and open source projects that put their API design up front are far more successful than their competitors. Take jQuery for instance, you can bet that when John sat down to create jQuery he wasn’t thinking “How do I animate CSS style?” or “How do I create and event system?” his main concern was how he wanted jQuery to be used. At least initially, the internals of jQuery were a mish mash of various libraries that came before it. What actually powered the explose growth of jQuery was the revolutionary API concepts it introduced: Method chaining, Selector-focussed API, simple plug in interface and so on. Other success stories like Ruby on Rails shared a similar focus on API design.

So, how do you write your code in such a way that it will make programmers happy and propell you into internet stardom? When you start out writing a new library or feature, start with a sketch. Cast aside any ideas that you might have already have about the implementation details and try to also cast aside any technical constraints and just start writing how you’d like your code to be used. Let’s take a DOM builder, for example. Mashing strings (or indeed using the terribly designed W3C DOM API) is no fun in JavaScript. If you were taking an implementation first approach you might start with an JSON-style data structure describing your DOM fragment or maybe even consider a set of objects that map to the various types of elements and this may well be how you implement it under the hood but put that aside for now. How would your code look when using the library? Here’s my first pass:

var fragment = build(
  div({ id: 'contact' },
    ul(
      li('Email: whatever@thing.com'),
      li('Twitter: ', a({ href: 'http://twitter.com/danwrong' }, '@danwrong')) 
    ) 
  )
);

Come up with the simplest, most aesthetically pleasing API you can and keep itterating on it until you’ve weeded out all the complexity you can. If certain arguments are optional or have a sensible defaults then make sure that the developer doesn’t have to worry about them unless they need to, is your library similar to any other library? If it is maybe its worth adopting the conventions of that library so it acts in a way that other developers expect it to. Developers dislike like reading documentation as much as your site’s users dislike read help pages. Strive for an API so simple that you can describe it in a few sentences.

Once you are happy with your sketch start building it out. You might need a little meta programming magic to realise the UI you are going for and that’s fine but use with caution. You need to weigh up whether the magic you are adding is going to make your code act in a way that is unpredictable to developers used to working with the language in question or if it will prevent developers from using their existing knowledge of the language to solve problems with your code. If you smell badness then leave the magic behind. In our example above we need to do quite a bit of work with the function arguments in order to support variable amounts of child nodes and to allow optional attribute hashes. In this case I’d make the call that this doesn’t add any extra confusion to the code so I’m happy to go with that.

Also, at this point consider how the API you are trying to design will impact real world pratical issues. For instance, in the example above it I would need to create functions for all HTML tags on the global namespace. Am I happy with my library a defining a global function called a()? No. Time to scale back on that idea a little.

Finally, when it comes to the implementation ensure that the architecture is sound and don’t try to couple the under the hood implementation with the API design to a degree that it’ll make the quality of the library suffer. I often view the API as a simple, pretty veneer over the top of a well crafted solution. Don’t hide the raw internals, make them accessable alongside the simple API. That way if the developer is on the beaten track they get a simple API but if they have specific needs they can delve right in and get stuff done.

So yeah, next time you write some code. Think about sketching out the API first rather than leaving it as an after thought. Your colleagues will thank you.

I’d love to speak more about this at JSConf. The competition is very hot but here’s my proposal if your interested. If it’s picked I’ll go in to detail on some great and poor examples of API design and also show off some nice techniques for bringing your API sketches to life.

Added OEmbed and Embeddable Player to twaud.io

2010-05-26T06:37:00Z

I’ve just added OEmbed to twaud.io for fun and profit. I’d not really looked into it until Dustin and Russ pointed out and I really like the idea although it seems a bit under done at the moment (You can only have ‘image’, ‘video’ or ‘rich’ as media types. What about audio?). I’ve been meaning to implement an embeddable player for twaud.io for a long time so I decided to add them in.

The OEmbed endpoint is:

http://twaud.io/oembed.{format}

It supports JSON, XML and JSON-P (if you provide a callback parameter to a json request). For example:

http://twaud.io/oembed.json?url=http%3A%2F%2Ftwaud.io%2FYf&callback=myCallback

Returns this:

myCallback({
  "height":"65",
  "provider_url":"http://twaud.io",
  "title":"Little mix of all the dubstep tunes I've been listening to lately: WRONG BEAT",
  "type":"rich",
  "html":"<iframe allowtransparency='true' frameborder='0' scrolling='no' src='http://twaud.io/embed/Yf' style='width: 395px;  height: 65px; border: none;'></iframe>\n",
  "audio_type":"audio/mpeg",
  "audio_url":"http://twaud.io/audio/Yf",
  "width":"395",
  "author_name":"danwrong",
  "version":"1.0",
  "author_url":"http://twitter.com/danwrong",
  "provider_name":"twaud.io" 
});

The HTML property contains a snippet of HTML that renders the player:

All very beta at the moment but give it a try. Also, check the short dubstep mix I did a while back. Will post a longer one soon.

Massive Robot launches twaud.io

2009-05-20T13:29:00Z

Well, it’s been a bloody long while again since I’ve posted here and I suppose you’ve all unsubscribed me now. To be honest, I wouldn’t blame you.

However, silence here does not mean that I’ve been sitting on my arse doing nothing. In fact, the reality is very much to the contrary. Loads of stuff has been going on but there are two new pieces of news. Firstly, I’ve renamed and rebranded my company. We are now Massive Robot and we are available for consultancy and development work so if you have anything in mind then please contact us. Joe has done the branding and it’s something I’m really pleased with.

Check the business cards…

Along with those is a new site and a T-shirt. The final and most important Massive Robot branding will be the kicks. I’m working on those at the moment.

This week launched twaud.io, Massive Robot’s new service. The idea is simple – it’s like twitpic but for audio. Go to the site or use the API to upload your audio and you get a page with a short URL and a player for your followers to listen to it. This is just the start and we are working on a whole load of new features for it so follow @twaudio to keep up to date.

The build of twaud.io has been an interesting and fun experience. I was able to use Twitter’s new OAuth based login process via twitter_auth which I’d recommend wholeheartedly for as a foundation for Twitter applications, although I have hacked to allow for both OAuth (for the site) and username/password based (for the API) authentication where normally you must choose one or the other. It also uses S3’s direct uploading facility via SWFUpload which was not easy to get going but has provided a really scalable system as the application stays completely out of the loop of the bulky upload process. I love the direction web development is moving in at the moment.

It's Been A Long Time...

2008-06-23T22:56:00Z

But I’ve not just been sitting on my arse playing GTA IV, oh no. Well, not all the time anyway. The reason I’ve not posted anything (or been particularly active on the web in general) is that I’ve been damn busy. Most importantly, Catherine kindly gave birth to our first son, Max, back in March which has been quite a change and sapped a lot of my hacking time. I have to say though, despite the horror stories that many veteran parents like to feed you, our experience has only been good. In fact, not good, great. I recommend this reproducing lark.

Secondly, I’ve been hacking away nearly full time on one of my favourite projects to date, Peoples Music Store with LRUG stalwart and renowned anarchist, James ‘Bringing London To Its Very Knees’ Darling which is maturing nicely under private beta as we speak. Peoples Music Store is a great idea from some of the guys behind bleep.com whereby users can construct and customise their very own download store from the music they love then get free music themselves if people buy from their store. It’s a great way to both promote and show off you’re own music taste or in depth genre knowledge and find new music from stores you trust while getting some free digital swag along the way. I’m probably not explaining it well so just drop me a line if you want and invite and the site will explain itself. Public launch is coming in a month or so.

Building Peoples Music Store has been a great learning experience. We run the site on a cloud computing platform and from content ingestion to audio preview delivery to application servers to download packaging and delivery everything has been designed to scale horizontally – and I’m pretty proud of it. Thin, Rack, Sphinx, God, Starling and a whole load more cool open source gear is all running in there. I really need to get to blogging some of what I’ve discovered about working with Rack. It simply is the dog’s bollocks.

So, enough of the excuses. What’s on the horizon?

Speaking and Conferences

I’ve taken some time of speaking and conferencing in general so as to spend lots of time with Catherine and Max but come September I’m restarting the conference trail. Firstly, I’m doing a presentation and a tutorial (with Jarkko Laine) at RailsConf Europe all about JavaScript related Rails stuff and I’m likely to have a slot at @media Ajax as well. Also, I’ll be heading to dConstruct as is the tradition.

Hacking and Open Source Business

Although I’ve not commited to Low Pro or Low Pro JQ for a good while now they are both very much alive. I’ve simply not come across anything that I’ve felt the need to add for a while. If you have any suggestions or patches do let me know. I’ve actually got time to commit them at the moment. Another little project that I’m hoping to get off the ground is called Evil which is going to contain lots of Merb/Rack goodness. The first by-product of which is the merb_openid gem for consuming OpenID in Merb apps (it’s still not quite production ready though so don’t go using it just yet). I’ll let you know what Evil actually does when (or if) I actually get something working.

So, that’s all for now. Just a bit of a status report. I promise I’ll get some useful content written that you actually care about very soon.

How Good Is This?

2008-01-02T12:35:00Z

>> a = 79.99 * 100
=> 7999.0
>> a.floor
=> 7998
>> b = 7999.0
=> 7999.0
>> b.floor
=> 7999

I’ll tell you. It’s not good. I hate floating point calculations. Happy new year!

The State (And Future) Of The UJS Plugin

2007-06-16T15:19:00Z

Over the past few weeks loads of people have been asking me about what’s going on the UJS plugin. It’s obviously fallen in to disrepair so people, understandably, have been concerned. There has been a reason for this aside from the fact that I am a lazy barsteward (which of course I am, but that’s beside the point). Here is a letter I’ve just written to the UJS mailing list that I’d thought I’d post here to try to get a little more feedback. It’s a little bit long but bear with me…

I’ve been chatting to Luke and users of UJS about what to do with it and still haven’t quiet decided hence the lack of news but below is a rundown of where we are at on the whole thing. However, this is definitely personal opinion and doesn’t necessarily represent Luke’s opinion on the matter.

Essentially, the status is that, of late, I personally have not used UJS at all and have found a much better process by using Low Pro on its own without all the Ruby scaffolding of the UJS plugin. Secondarily, after talking to lots of developers at RailsConf it seems that the UJS plugin has failed to truly achieve it’s main goal which is to get Rails developers to write JavaScript using progressive enhancement. Many people seem to mainly use the plugin to get their JavaScript in to a separate file which is actually not even essential to progressive enhancement and I think this is a failing in the design of UJS itself. To achieve progressive enhancement you really need to think of JavaScript as a separate layer on top of a working HTML application but UJS lets you get away with keeping behavior in your views and hence leads many developers to think in the same way as they did before but think they are unobtrusive because they don’t see any JavaScript in their HTML – which is obviously not what we wanted to achieve. While many people can and do successfully use UJS for progressive enhancement even more seem not to – UJS has not been the ‘angel on your shoulder’ that I originally wanted it to be.

On top of this, the method by which the generated JavaScript is kept in the session has many limitations which myself and Luke have been aware of from the start. It’s not generally a good idea to keep this much information in the session (in fact, normally I never store more than a user ID if I can help it) and while acceptable for light to medium use it does have an upper limit depending on the type of session storage you are using. Rails edge now uses cookies to store session info by default which have a very very low limit which will cripple UJS completely. We have considered other alternatives such as some kind of file based storage but every time it just strikes me as too much scaffolding just to allow developers to put behavior in their view files which, as a said above, I’ve come to believe is a really bad idea anyway.

One of the things that I do personally like and something that has received the most positive feedback are the behavior helpers (the make_*) stuff which essentially encapsulate common tasks with sensible defaults in a very Rails like way. It’s a real time saver and the conventions provided mean that the best path (such as using this.href for the Ajax url) is the easiest. Recently, I’ve come to do this in my own projects via Low Pro and it’s behavior ‘classes’ (although they need a better name!). Now via Low Pro I can write stuff like:

Event.addBehavior({
  '.product a.description' : Remote.Link({ update : 'product_description' }),
  '.product' : Draggable({ revert : true }),
  '#basket' : Droppable
});

I really like this and am slowly building up a library (which you can see if you look at the Low Pro trunk) of common behaviors. There’s a date picker, a drag/drop implementation and the remote stuff I’ve illustrated above. I’m planning on writing autocompleters and in-place editors as behaviors as well. But behaviors have proven really easy to write and I love them as a tool for building site specific components. In fact, as I’ve worked with Low Pro it’s become apparent to me that behaviors are by far the killer feature which is interesting as they were just an experiment I hacked together one day without much thought.

So what to do? Well, there’s two ways to go as far as I can see. The first is to shut down development on UJS completely (or hand it over to another party if anyone is interested) and go on to promote the techniques of implementing progressive enhancement using Low Pro that I’ve found to be so successful recently. This could possibly be via the UJS4Rails site or through my own site – I’m not sure which would be a better platform right now.

The other would be to re-think the UJS plugin totally and go for some kind of 2.0 release that would take a completely different tack. However, all of the ideas for this I’ve thought of or heard so far don’t really compel me to write them. I think to work on this myself I’d need to be sure that I’d want to use it and so far this is not the case but any ideas and feedback are very welcome so please do drop me a mail or feedback on this list.

Either way, we need to make fixes to the current plugin to make it work with Rails 1.2.3 which I’ve been working on recently but I’d love patches if you’ve already solved these issues yourself (which it appears many of you have).

So yes, that’s it. Let me know what you think, I’d appreciate any feedback you have.

RailsConf Is Over: One Down, One To Go

2007-05-21T18:14:00Z

UPDATE: The RailsConf version of the slides are over at SlideShare. The versions of the presentation I’ll be doing at @media San Fancisco and @media London will be considerably different but the kung-fu foolishness will remain intact.

RailsConf 2007 is over and I have to say it was considerably better than the previous year. Rather than last year’s overwhelmingly self-congratulatory tone (“Aren’t we clever! We use Rails!” Accompanied by much clapping, standing ovations and general whooping) it was a much more down to business affair and although it was really big (1600 people) it was friendly.

So what was the big news this year? Firstly, I got the feeling that everyone was bracing themselves for “the enterprise” with JRuby going strong and Sun looming over the proceedings. It seems that everyone’s got a new Rails IDE on the way out and the exhibition hall was full of people hawking their wares and pretty much everyone I met was a full time Rails professional. I suppose the up side of this injection of big money into Rails is the free beer but aside from that I think the transition is going to be uneasy. Java and J2EE are great for getting huge amounts of programmers to write huge things because inevitably some of those programmers are going to be shit and Java and J2EE provide a strict framework by which you can’t go too wrong. However, Ruby on Rails is great for getting small amounts of really good programmers to churn out software quickly but doesn’t provide a rigid safety net which means a bad (or even not really good programmer) can basically bring an application to it’s knees. In fact, I’ve seen some terrible code in Rails apps recently…stuff that would make Koz and Jamis turn white. Rails dev shops really need to watch for this. Quality control, people!

Secondly, there was lots of buzz about Merb which is really promising and in my opinion is starting to feel more like Rails 2.0 that Rails 2.0 is shaping up to be. It’s got all the really useful stuff that I use day to day in Rails and none of the stuff I don’t use. Better still all of the core features are really well implemented and feel really cruft-free (I read and understood the Merb source in about 2 hours). This makes it fast as well. Ezra seems committed to keeping the core pretty lean and providing most extra functionality as gems rather than plugins which seems extremely sensible. Plugins are simple are now suffering from a lot of the problems that gems have already solved (load order, dependencies, version control etc).

Finally, I was impressed with DHH’s keynote. He must be under large amounts of pressure to deliver the next new big feature but regardless his keynote was low-key and considered. There’s no big stuff on the way but what is coming is consolidating the core ideas of Rails, providing more sensible defaults, more support for REST and it sounds like some of the JavaScript helpers are being pulled to plugins (or at least some of them)....nice one!

On the social side it was great. Portland is a cool place and of course we had Robby and the Planet Argon crew to show us around and they did a great job. I think I managed to meet up with nearly everyone I wanted to, the highlight being lunch with Sam, Thomas and Seth and some chat about Prototype which has got me pretty enthused about contributing again. I even met the Rails Envy guy who is Ruby On Rails…rock on. There was a mad burlesque breakbeat marching band in the conference center at one point as well….got to like that. It was quite a Ruby moment when a guy in hot pants with a huge flag tried to dry hump Rich Kilmer. Poor dude.

My presentation, The Mysteries Of JavaScript-Fu, went down reasonably well from what I could tell (apparently, I was not slagged off on IRC…miracle!) and I’ll be putting the slides up as soon as I get a vaguely working wireless connection (I’ll update this post with the link). But Dr James’ presentation on plugins was a work of art. While my presentation involved me talking in a fake kung-fu voice, James had a gothic horror thing going on. Stupid voices from the Brits!

My only regret is that Zed Shaw won the Rails Pimp Cup ....that was main to be in my possession, damn it!

Now to get on a plane to San Francisco for @media America and a lot of footwear purchases.

Off To RailsConf and @media America

2007-05-15T23:10:00Z

Just breaking radio silence briefly to say that I’m off to the states (again) to speak at RailsConf in Portland 17th-20th then on to @media America in San Francisco for the 21st-28th. I’m going to be doing presentations both called ‘The Mysteries Of JavaScript-Fu’, both with an old skool kung fu theme but quite different aside from that. If you are around in either of these places or have any tips on good skate and sneaker stores then drop me a line….I’m always up for a couple of cold ones or/and sneaker shopping missions.

When I get I’ll be working a load more on Low Pro and blogging more about it. It’s developing quickly at the moment as Prototype picks up momentum and it’s getting some damn good features. In the meantime, you could always check out the trunk and see the new features that have already gone in. Build the trunk release then try as a sneak preview:

$('an_element').wrap('<strong>');

Also, look out for a major new set of features for Event Wax scheduled for release round about the time of @media London.

Low Pro 0.4 Released

2007-04-16T10:08:00Z

I’m back from India and just dropping a quick note to say that Low Pro 0.4 is out. There are a few new features (which I’ll go into later) but essentially this is a bug fix / optimisation release and has many changes that help it work well with the latest version of Prototype. Most of this has been backing out parts of Low Pro that have been implemented or otherwise bettered in Prototype now which is great and I expect to see more of this happening soon. There’s some good work going on with events at the moment and DOM ready support is planned to go in soon.

One feature of Low Pro I have been using heavily myself are Behaviour classes. Behaviour classes allow you to attach behaviour to elements in an object orientated way. Each element gets it’s own instance of the behaviour which means that it can retain state through its lifetime without using expandos or creating nasty circular references that cause memory leaks (well, of course, you still can but it lessens the chances). I intend to write a lot more about behaviour classes shortly but in the meantime have a peek at the Draggable behaviour in SVN it turns out that it’s a really neat way to write components.

Download Low Pro 0.4

The No Shit Guide To Supporting OpenID In Your Applications

2007-02-27T01:37:00Z

OpenID, with the superhuman effort of Mr Willison is taking the world by storm and I am amoungst the masses leaping onto the bandwagon. Simon has done an excellent post and screencast detailing the whys and what-fors of OpenID so I thought I’d have a bash at applying the same no-bullshit approach to the other side of the coin, supporting (or as the official terminology puts it consuming) OpenID in your applications. With this post I’m going to blast through the absolute essentials you need to get started so if you need more general background on OpenID check out Simon’s stuff first. The examples, as you might except will be using Ruby on Rails but all of the concepts are applicable across platforms. So, without further ado, grab yourself a beer and we’ll begin…

Overview of the authentication process

When consuming OpenID what you are trying to do is ask the user for their OpenID (which is a URL) then ascertain from their OpenID server that they actually own this OpenID. Once you know that they own the OpenID you can then wack it in the session (and use it as a really lightweight means of identifying users between visits) or key it in with your own application specific account data if you need more power. This article is going to take you up to and including verifying the user’s OpenID. What you do with it is left to your imagination.

On a more granular level the verification process breaks down into these steps:

Get the user to give you their OpenID URL.
‘Begin’ the verification process whereby your OpenID library of choice will work out the users OpenID server and, if successful, provide you with a redirect URL.
Redirect the user to the given redirect URL. You specify a return URL within this URL.
The user goes to their OpenID server, logs in and authorises your site’s verification request and is then redirected back to your return URL.
Your server ‘completes’ the verification request and, if successful, confirms that this user owns this OpenID. The end.

So that’s essentially it. Some of the details of the transactions between your server, the user’s delegates and the OpenID are pretty complex but fortunately for us there are lots of good libraries for most platforms that mean you don’t need to bugger about with the crypotography and stuff. Woo hoo. For these examples we are going to use the ruby-openid gem but you can choose your own. Also note that East Media have a OpenID Consumer plugin for Rails that wraps even more detail with some generators but it’s good to understand the concepts before you let something write your code for you.

Get your library sorted

That’s easy. For us Rubyists its:

$ sudo gem install ruby-openid -y

Create your OpenID consuming controller

We are going to try to be as RESTy as possible here so we’ll create a singleton resource called openid. In routes.rb:

map.resource :openid, :member => { :complete => :get }

Then we’ll set up a simple controller. Firstly, we’ll need to require the ruby-openid gem here. We are also going to need a method that gives us an OpenID consumer object which is the single most complex part of this whole thing (and it isn’t complex). First, here’s the skeleton:

require_gem 'ruby-openid'

class OpenidController < ApplicationController

  def new
    # TODO: show a form requesting the user's OpenID
  end

  def create
    # TODO: begin the OpenID verification process
  end

  def complete
    # TODO: omplete the OpenID verification process
  end

  protected

    def openid_consumer
      @openid_consumer ||= OpenID::Consumer.new(session,      
        OpenID::FilesystemStore.new("#{RAILS_ROOT}/tmp/openid"))
    end

end

The OpenID::Consumer constructor takes two arguments, the first one should be a hash like object that holds session data. That’s always going to be session for Rails. The second one takes a file store object which is used to store state information for the verification process. There’s lots (including an ActiveRecord store) but for many apps the filesystem store is fine.

Getting the user’s OpenID

The new action just needs to show a simple form posting the OpenID to the create action:

<% form_tag openid_path do %>
  <%= text_field_tag 'openid_url' %> <%= submit_tag 'Login' %>
<% end %>

Note that it’s convention to call the field openid_url so browsers will autocomplete nicely. They also recommend that you embed the OpenID logo in the form field. Get the logo then try some CSS like this:

#openid_url {
  background: url(/images/login-bg.gif) no-repeat #FFF 5px;
  padding-left: 25px;
}

Beginning the verification

The create action is going to be responsible for kicking off the process:

def create
  openid_url = params[:openid_url]
  response = openid_consumer.begin openid_url

  if response.status == OpenID::SUCCESS
    redirect_url = response.redirect_url(home_url, complete_openid_url)
    redirect_to redirect_url
    return
  end

  flash[:error] = "Couldn't find an OpenID for that URL"
  render :action => :new
end

We simply get the OpenID and pass it to the begin method of our consumer object to get a response. We then handle the status of the response which can have a number of states. For this super simple example we are just going to look for success but in a production app you’ll need to handle error states more usefully.

If the response was successful we call redirect_url passing the trust root and the return URL. The return URL is simply our complete action. The trust root is normally the homepage URL of your site. We then redirect the user to the resulting URL where the user logs in to their OpenID server, authorises your verification request and is (normally) redirected to return URL you provided.

Completing the verification

When the user is redirected back to your application the server will append information about the response in the query string which the OpenID library will unpack:

def complete
  response = openid_consumer.complete params

  if response.status == OpenID::SUCCESS
    session[:openid] = response.identity_url
    # the user is now logged in with OpenID!
    redirect_to home_url
    return
  end

  flash[:error] = 'Could not log on with your OpenID'
  redirect_to new_openid_url
end

After passing the params hash containing all the info that the OpenID server sent us to the complete method we are given a response status to handle. Again for production apps more states should be handled but here, if the complete was successful we have completed the process. Here we just store the identity_url given in the session but at this point we could also do something like:

session[:user] = User.find_by_openid_url(response.identity_url)

Which would grab the users local account data based on the OpenID. Easy as pasty. However, there’s a few more bits and bobs you might want to know about.

Simple Registration Extension (SReg)

SReg is a basic means by which you can request additional information about the user from their OpenID server which you might normally use to prefill account details or other form fields. The information you can request access to is in the spec but there’s not much there at the moment. It’s still kind of useful. To request this information you need to add parameters to the redirect URL which is of course handled for you by your library. Revisiting the create action, we just add a call to add_extension_arg:

def create
  openid_url = params[:openid_url]
  response = openid_consumer.begin openid_url

  if response.status == OpenID::SUCCESS
   response.add_extension_arg('sreg','required','email') # <== here...
   response.add_extension_arg('sreg','optional','nickname,gender') # <== ...and here
   redirect_url = response.redirect_url(home_url, complete_openid_url)
   redirect_to redirect_url
   return
  end

  flash[:error] = "Couldn't find an OpenID for that URL"
  render :action => :new
end

Then in the complete action, extract the returned information:

def complete
  response = openid_consumer.complete params

  if response.status == OpenID::SUCCESS
   session[:openid] = response.identity_url
   # the user is now logged in with OpenID!
   @registration_info = response.extension_response('sreg') # <= { 'name' => 'Dan Webb', etc... }
   redirect_to home_url
   return
  end

  flash[:error] = 'Could not log on with your OpenID'
  redirect_to new_openid_url
end

Immediate mode

Immediate mode allows you to attempt to verify the user without them leaving your site at all. This is normally possible if, during the first time you attempt to verify a user, they choose to always allow you to verify them and offers a slightly more streamlined login experience.

To implement this we first pass an extra argument to redirect_url:

def create
  openid_url = params[:openid_url]
  response = openid_consumer.begin openid_url

  if response.status == OpenID::SUCCESS
   redirect_url = response.redirect_url(home_url, complete_openid_url, true) # <== here
   redirect_to redirect_url
   return
  end

  flash[:error] = "Couldn't find an OpenID for that URL"
  render :action => :new
end

Then ensure that our complete action handles the OpenID::SETUP_NEEDED status by redirecting them to the OpenID server’s setup page:

def complete
  response = openid_consumer.complete params

  case response.status
  when OpenID::SUCCESS
    session[:openid] = response.identity_url
    redirect_to home_url
    return
  when OpenID::SETUP_NEEDED
    redirect_to response.setup_url # <== here!
    return
  end

  flash[:error] = 'Could not log on with your OpenID'
  redirect_to new_openid_url
end

Fin

So that’s it. All you need to know to start getting OpenID going in your web applications. You’ve got no excuse now. In fact, neither have I…

Any corrections, questions or further wisdom are very welcome. I’m no expert on OpenID, I’ve literally just picked all this up from reading API docs, specs and source code and thought it would be good to share. let me know what you think.

Coding Like A Bitch: Mephisto Plugins Upgraded and Fridaycities/EventWax Beta Biznizz

2007-01-31T16:57:00Z

Just a quick note to say that I’ve just upgraded to the newest version of Mephisto which has forced me to update my Mephisto plugins to work with the new updates to Liquid. Sorry for being slack on that. I’ve had a ton of email about it but hadn’t had the chance to fix these since my new venture into the freelance world has started.

In unrelated news, most of my coding effort has been going into a site called Fridaycities which is a cool site where Londoners ask questions and get insider info about all things London-ish. It’s great to browse around…Apparently there’s an Elvis Chinese restaurant on Old Kent Rd and a naked disco in Vauxhall. Who’d a thunk it? It’s still in very early stages at the moment but the FC people have got big plans and myself and Mr Tanner are beavering away on it as we speak. It’s invite only but you can check out the posts without registering so go have a squizz.

Finally, EventWax has been going great guns. It’s great to see a load of events running on there including @media2007 and BarCampLondon2. We been collecting lots of feedback and slowly introducing features but there’s going to be some cool changes in the near future so keep an eye out there.

Finally, I’m stacking up a few patches for Prototype and Rails that I need to finish up. Hopefully I’ll get chance to do that soon. Writing patches for Rails is weird. I tend to find myself spending 20 seconds on getting the patch done and 3 hours trying to bash tests together. Does anyone else find writing tests for the Rails core a bit of a pain in the arse?

MinusMOR Released!

2006-11-24T16:32:00Z

Okay then you bunch of wusses. Here’s your goddamn liberal, namby-pamby, let’s sit on the fence version of MinusR that doesn’t override anything and provides your JavaScript with embedded Ruby templates as the .ejs extension so it works alongside the normal .rjs templates. Live and let live. Let’s all hold hands and be nice to each other….

Damn you, you hippies!

It’s in my SVN repos but you can still get at MinusR if you are feeling hardcore. I must admit that the whole thing does smell better than the original version. It turns out that changing the default behaviour of respond_to for different types has got easier since last time I looked as well. Go core team! It was also easier to test which normally indicates a sweeter smell of code. In the end it required more monkey patching that MinusR to get it to work correctly. It turns out that .rjs templates trigger a few hardcoded special cases to template handling and to get .ejs files to act the same required patching these hardcoded bits which is a shame. It looked like it was going to be nice and clean.

Now I’ve gone out of the way to make this version especially for you people you MUST use it. I’ll be checking…

RJS Minus R

2006-11-17T11:39:00Z

UPDATE: I’ve released a happy-clappy, touch feely version that doesn’t override .rjs and instead gives you the .ejs extension. It’s called MinusMOR.

I like RJS and it’s approach of sending executable JavaScript responses back to Ajax requests. It seems ugly but it’s actually a life saver for making really complex UI updates easily and once I got to using it in real projects it definitely saved me vast amounts of time for anything more than trivial. The thing is that if I did want to do anything more than trivial (as in a simple conditional statement) the whole ‘write Ruby generate JavaScript’ thing fell down and I ended up writing these nasty Ruby-JavaScript Frankenstein’s monsters as I’m sure many of you have:

page << 'if (someClientSideVariable) {'
page['a'].replace_html :partial => 'thing'
page << '} else {'
page['b'].replace_html :partial => 'thong'
page << '}'

Why do I need to write the RJS templates in this ugly style? When RJS first came out I was quite impressed with the Ruby to JavaScript translation stuff but it’s limitations (and that of lots of other similar attempts at ‘compiling down to JavaScript’ like Google Web Toolkit) shine through after the lightest of uses. Now, in that example above, I know I could make it cleaner so it’s not quite fair but still for me (or anyone else that can write JS) it’s just another hurdle to jump through and, in my experience, it’s never been long before I’ve needed to resort to the old page << business. Also, why bother learning another API when you already know Prototype? Or, for that matter, what if you don’t want to use Prototype but do want to use RJS….

With this in mind, I’ve written a tiny weeny plugin to help out. It’s called MinusR and it simply changes .rjs templates so you can write JavaScript and use ERB in them:

if (someClientSideVariable) {
  $('a').update(<%=js render(:partial => 'thing') %>);
} else {
  $('b').update(<%=js render(:partial => 'thong') %>);
}

MinusR gives you the js helper that calls to_json on any value passed to it so you can drop nicely escaped and formatted data into your script as before. Everyone’s a winner. Well, not quite, I could be going out on a limb here but I really think this is the better way. Go on, give it a go. A bit of javaScript won’t hurt you….

The only problem to solve now is to get it highlighting nicely in Textmate….anyone?

UPDATE: Luke has written a little bit about Minus R.

Event Wax Is The First Production UJS Application

2006-11-09T11:05:00Z

UPDATE: It appears that Zaadz event section beat us to it as the first production UJS app. Damn! Excellent work though.

Last week we quietly snuck Event Wax into production but now, at last, we are ready to shout about it. It’s the result of several months work and a whole load of experience running @media and is something we’re pretty proud of. Event Wax is a web-based application that allows event organisers to easily provide registration, payment and management facilities for attendees. An early prototype of the application was used to manage the 800 delegates for @media 2006 to great success but since then we’ve been refining and improving it and its turned into a pretty nifty application. So now it’s out in the open I thought I’d speak a little bit about some of its technical aspects.

One of the biggest highlights for me is that it’s, to my knowledge, the first production application using the UJS Plugin. Much of the development of the plugin has grown up alongside this and some of Agile Evolved’s applications and it’s come a long way in a few months from a fairly simple plugin to something very capable of handling pretty intensive Ajax stuff. In this post I’ll take one of those features and talk about some of the thinking behind its implementation. That feature is…

The In-Line Help System

One of my favourite features in Event Wax is the help sidebar in the admin area. The interface itself is kept pretty clean but if you need help on a particular page you can just open the help which shows the relevant help page. This way we avoid filling the screen with prompts and help content that will get in the way of experienced users but still give new users plenty of help if they need it.

The help content is in fact taken from the help site which resides at eventwax.com/help but is re-purposed and pulled into the help sidebar via Ajax. This way we have a searchable, printable plain HTML version of the documentation for users to refer to if needed but are able to provide context sensitive help to users as they use the application. Of course, this is all implemented unobtrusively and still provides users with a decent experience if for some reason JavaScript isn’t behaving. Here’s how:

Firstly, we define the inline help link and a div to hold the help content:

<a href="/help/your_account/your_event/the_attendees_tab" id="hlink"><span>Help</span></a>

<!-- code omitted for clarity -->

<div id="help"></div>

Notice that the href of the link is pointing to the location of that particular help page in the regular site so as it stands now our help link will just send us through to the correct documentation. In order to pop up the content in a side bar I’ve implemented a help script that’s responsible for opening and closing the sidebar by applying a class to the help div and triggering an Ajax.Updater request to fill it with content. I’m not going to show that here but you can check it out if you like. Essentially this gives us Help.show(url), Help.hide() and Help.toggle(url) to play with.

Now we can use UJS to apply some behaviour and make our sidebar come alive:

<% apply_behaviour '#hlink:click', 'Help.toggle(this.href); return false;' %>

This catches the help links click event and instead triggers the sidebar to open and close. We call Help.toggle() to open the sidebar passing in the href of the link as the content to get to place in the help div. At this point, it’s all pretty much working but there’s one snag: there are links inside the help content and we want them to change the sidebar rather than link normally. Time for some more UJS:

<% apply_behaviour '#help a:click', 'Help.open(this.href); return false;' %>

We hijack the click events of all the links inside the help div and make them call Help.open() with their href instead of their default behaviour which causes them to open within the sidebar. Sorted.

There’s a final problem to solve. The normal help content is going to need to be inside a full HTML document with a header and footer while the help content in the sidebar doesn’t need any of that. We solve this with a bit of Rails magic. The Help controller that displays the help pages looks like this:

class HelpController < ApplicationController

  # displays a page of help given the path
  def page
    # page finding code ommitted for clarity
    respond_to do |type|
      type.html { render :file => page, :layout => :help }
      type.js { render :file => page, :layout => false }
    end
  end

end

This means that requests for help pages via Ajax get no layout and just get the html content and normal requests get the whole page, doctype, html tag and all. As you can see it would be easy to dispense these pages in lots of other formats if we need to.

So that’s that…As you can see, it’s really quite simple to get some impressive features working unobtrusively, especially with Rails and UJS. In coming posts I’ll highlight how I went about implementing some of the other features of Event Wax but in the meantime register and check out the application and plan an event while you’re at it. Get it while it’s free!

RailsConf Presentation Slides and Example Code

2006-09-18T09:50:00Z

As promised, here are the slides and example code from my RailsConf presentation.

Presentation Slides (PDF)
Example Application (ZIP)