So I threw together some simple experiments, and turned on logging in the console. It’s a bit rough and certainly not exhaustive, but I formatted it in markdown out of habit and then though hey, I should post this, so here it is.

Is this stuff documented somewhere? I never found it if it is. I wonder if most Rails devs know about all this already.

This is all in Rail 2.0.2 BTW.

Some simple models

class Post < ActiveRecord::Base
  has_many :comments
  has_many :categorisations
  has_many :categories, :through => :categorisations
end

class Comment < ActiveRecord::Base
  belongs_to :post
end

class Category < ActiveRecord::Base
  has_many :categorisations
end

class Categorisation < ActiveRecord::Base
  belongs_to :post
  belongs_to :category
end

has_many (not through)

Assigning to the array on a new record

New comments are created along with a new post:

>> p = Post.new
=> #<Post id: nil>
>> p.comments = [Comment.new]
=> [#<Comment id: nil, post_id: nil>]
>> p.save
  Post Create (0.000601)   INSERT INTO posts VALUES(NULL)
  Comment Create (0.000195)   INSERT INTO comments ("post_id") VALUES(1)
=> true

Appending to the array

For a post that exists, the appended comments are created immediately:

>> p
=> #<Post id: 1>
>> p.comments << Comment.new
  Comment Create (0.000481)   INSERT INTO comments ("post_id") VALUES(1)
=> [#<Comment id: 1, post_id: 1>, #<Comment id: 2, post_id: 1>]

Assigning to the array on an existing record

Comments no longer in the array have their foreign_key set to NULL. (I’d guess this changes if you declare :dependent => :destroy, but I didn’t try it)

>> p.comments
=> [#<Comment id: 1, post_id: 1>, #<Comment id: 2, post_id: 1>]
>> p.comments = []
  Comment Update (0.001335)   UPDATE comments SET post_id = NULL WHERE (post_id = 1 AND id IN (1,2))
=> []

New comments in the array are created immediately:

>> p.comments = [Comment.new]
  Comment Create (0.000504)   INSERT INTO comments ("post_id") VALUES(1)
=> [#<Comment id: 3, post_id: 1>]

Existing comments have their foreign key set

>> p2 = Post.create
  Post Create (0.000820)   INSERT INTO posts VALUES(NULL)
=> #<Post id: 2>
>> c = p.comments.first
=> #<Comment id: 3, post_id: 1>
>> p2.comments = [c]
  Comment Load (0.000292)   SELECT * FROM comments WHERE (comments.post_id = 2) 
  Comment Update (0.000684)   UPDATE comments SET "post_id" = 2 WHERE "id" = 3
=> [#<Comment id: 3, post_id: 2>]

belongs_to

When assigning c.post on an existing comment, the change is saved when the comment is saved:

>> c.post == p2
=> true
>> c.post = p
=> #<Post id: 1>
>> c.save
  Comment Update (0.000778)   UPDATE comments SET "post_id" = 1 WHERE "id" = 3
=> true

When assigning a c.post to a new post, the post is created when the comment is saved:

>> c
=> #<Comment id: 3, post_id: 1>
>> c.post = Post.new
=> #<Post id: nil>
>> c.save
  Post Create (0.000464)   INSERT INTO posts VALUES(NULL)
  Comment Update (0.000148)   UPDATE comments SET "post_id" = 3 WHERE "id" = 3
=> true

This happens the same way when the comment is new — both are created together:

>> c = Comment.new
=> #<Comment id: nil, post_id: nil>
>> c.post = Post.new
=> #<Post id: nil>
>> c.save
  Post Create (0.000499)   INSERT INTO posts VALUES(NULL)
  Comment Create (0.000161)   INSERT INTO comments ("post_id") VALUES(4)
=> true

has_many :through

Assigning to the array has no effect:

Assignment to p.categories where p is an existing post:

>> p
=> #<Post id: 1>
>> cat = Category.create
  Category Create (0.000427)   INSERT INTO categories VALUES(NULL)
=> #<Category id: 1>
>> p.categories = [cat]
  Category Load (0.000289)   SELECT categories.* FROM categories INNER JOIN categorisations ON categories.id = categorisations.category_id WHERE ((categorisations.post_id = 1)) 
=> [#<Category id: 1>]
>> p.save
=> true

Note there were no changes to the categories table.

Assignment to p.categories where p is a new post:

>> p = Post.new
=> #<Post id: nil>
>> p.categories = [cat]
=> [#<Category id: 1>]
>> p.save
  Post Create (0.000513)   INSERT INTO posts VALUES(NULL)
=> true

Again, nothing happens to the categories table

Appending to the array does have an effect

Can’t append to a has-many-through on a new record:

>> p = Post.new
=> #<Post id: nil>
>> p.categories << cat
ActiveRecord::HasManyThroughCantAssociateNewRecords: Cannot associate new records through 'Post#categorisations' on '#'. Both records must have an id in order to create the has_many :through record associating them.

Can append to a has-many-through on an existing record. The joining record is created immediately:

>> p = Post.find(:first)
  Post Load (0.000365)   SELECT * FROM posts LIMIT 1
=> #<Post id: 1>
>> p.categories
  Category Load (0.000294)   SELECT categories.* FROM categories INNER JOIN categorisations ON categories.id = categorisations.category_id WHERE ((categorisations.post_id = 1)) 
=> []
>> p.categories << cat
  Categorisation Create (0.000479)   INSERT INTO categorisations ("post_id", "category_id") VALUES(1, 1)
=> [#<Category id: 1>]

But this is not allowed if the category is new:

>> p.categories << Category.new
ActiveRecord::HasManyThroughCantAssociateNewRecords: Cannot associate new records through 'Post#categorisations' on '#'. Both records must have an id in order to create the has_many :through record associating them.

Did you learn something?

To upgrade simply

gem update hobo

or grab the files from github or the svn repo and update your plugin directories.

A highlight of some of the changes.

• Autocompleters and in-place-editors have been broken for a while. They’re working again now
• Some incompatibilities with older REXML versions have been addressed. DRYML should now work with REXML versions 3.1.4 to 3.1.7.3
• The “permission denied” page should be working again.
• The Clean theme works much better in IE6 now.
• We’ve squished a pagination bug that was messing a few people up

There’s a bunch more little changes — see the changelog for the full low-down.

Then on the tidying up side, there are two major changes. First, we’ve moved to gems for the whole of hobo. Installing the hobo gem should get you hobosupport, hobofields and will_paginate. As a result of this the hobo command no longer tries to fetch anything with subversion.

And we’ve made a change to the structure of the git repo. Because Hobo is really one project, with some sub-components available as spin-offs, it is really much better to have the whole thing in a single repo. So github.com/tablatom/hobo now also contains hobosupport and hobofields in sub-directories. The separate repos on github for HoboSupport and HoboFields will be deleted soon. The one downside is that you can no longer follow “edge Hobo” by using git sub-modules, because git doesn’t support partial exports. We’ll provide some rake tasks to make that easier at some point.

And then there’s the docs.

We’ve got the very beginnings of a complete reference to the Rapid tag libraries. At the moment it’s just generated from the source-code but all we need to do now is start adding in-line documentation comments. The format is probably not ideal either - it doesn’t lend itself to easily searching the whole library. We’ll improve that too in time.

The manual has been extended to include a fairly comprehensive guide to customising Hobo’s RESTful model controller.

James has added some great insights into working with DRYML in the third part of the POD tutorial and with some additions to the DRYML guide.

And finally there’s our first HOW-TO: adding an admin sub-site to a Hobo app. We’ve got a bunch more of these planned which should be very useful.

So! We’re making good on our promise to concentrate less on features and more on making Hobo accessible to others. Mind you, having said that, there’s a cracking new feature in the pipeline…

If you wanted to use Hobo not so long ago, pretty much your only option was reading the source and asking questions. If you want to use Hobo now, you’ve got some reasonable docs to get you going, but you’ll still need to read some source (especially the DRYML libraries in vendor/plugins/hobo/taglibs). Eventually, you’ll be able to get by on the docs alone and everyone will be happy :-)

There’s all sorts of details that we haven’t documented at all, but there’s two really big gaps: customising your controllers and the Rapid tag library. What I really wanted to talk about in this post is Rapid.

Rapid, in my opinion, is the best part of Hobo. You could say (and in fact I think I did somewhere or other) that everything else in Hobo exists to make Rapid possible. The combination of development speed and flexibility that Rapid brings is something I can’t say I’ve seen anywhere else.

But there’s a catch. You have to know it. And there’s a lot to know: layers and layers of tags calling tags calling tags. If you know your way around it from top to bottom, you’re singing. If you don’t, you’re probably writing way more view code than you need to.

You should get a good sense of this from the Agility tutorial. Towards the end you’re asked to code up bits and pieces of DRYML. These snippets seem to add functionality that far outweighs their size, but you must be thinking “how was I supposed to know that?!”

Some folk seem perfectly happy to read the DRYML taglibs and find their way around that way, but we really, really need docs for this stuff.

This is not meant as an apology, and it’s not going to be a promise to deliver X by Y. It’s just to let you know that those docs are very much on the to do list (and near the top), and please don’t think that you’re expected to just know what to do.

An idea that came out of that IRC chat was to create a tutorial that starts with a full app, in “normal Rails” style, and goes through how to gradually Hoboize it. In the view layer we could explain how to factor out all the HTML into layers of DRYML tags. That would not only show how to use bits and pieces from Rapid, but would also illustrate why Rapid is like it is. It would throw a lot of light on the whole of Hobo in fact. Could be a lot of work though, so don’t hold your breath until it’s ready :-)

p.s. On the subject of docs I just noticed that the HoboSupport docs are messed up — there’s a whole bunch of pages that aren’t linked to. like this one for example. Will fix!

First up, two new Enumerable methods that HoboSupport adds: * and where. Attentive readers might be thinking — hang on, Array already defined *. Don’t worry, it still works.

* is some syntactic sugar for map. The idea is that we use ‘dot’ to call a method on one object, and we use ‘dot star’ to call a method on a whole collection of objects, returning all the results in a new array.

Say users is an array of user objects, and we want all the names:

users.*.name

Nice eh? You can pass arguments too:

users.*.to_json(:only => [:first_name, :surname])

Note that you can’t do

users.*.name.upcase

That would try to upcase the array. You’d have to do:

users.*.name.*.upcase # Not very efficient though

Of course, as a good functional programmer, I wouldn’t dream of giving map some love while neglecting filter (better known in Ruby-land as find_all or select). So you can also do:

users.where.active? # same as users.find_all {|u| u.active? }

There’s also where_not

Given that the result is just an array, we can chain them. Want the names of all the inactive users?

users.where_not.active?.*.name

Very handy in the console.

Hobo 0.7.4 is out. Please see the changes. Note that rubyforge seems to be having a very bad day. Downloading the gem files directy from http://rubyforge.org/projects/hobo seems like a good option. You’ll need both hobo and hobosupport.

There are two, count them, two tutorials on the docs page, as well as guides to the basics of DRYML and the Hobo generators.

The big breakup has begun. The HoboSupport gem, and HoboFields plugin (with the migration-generator) are now available without the rest Hobo. Let the whole world be freed from the drudgery of writing migrations! As you’ll see, HoboSupport and HoboFields are tested and well documented. We’ve achieved both in one go using Python-style DocTests. More on those in a later post.

The source code now lives on GitHub at http://github.com/tablatom. This is a really fantastic step forward giving us:

• A super easy way for people to contribute code
• A nice online browser for both the source code and commit trail
• RSS feeds for commits
• And even a wiki

And of course, if you do the GitHub thing, you’ve got to do the Lighthouse thing too. Lighthouse is now the new Hobo issue tracker.

BUT. More importantly than all that. This all marks the start of a new chapter in the life of Hobo. The documentation that’s available now is just the start. We’re now moving on to extracting DRYML as a separate plugin, which also means doctests for every last DRYML feature. Then it’ll be on to docs for the Rapid tag library.

The one thing that’s missing right now is screencasts. The old ones are still online but they’re so out of date that we’re not linking to them any more. A new series of screencasts based around the Agility tutorial will be created soon.

We will continue to add new features and functionality, and we will sill make breaking changes right up until 1.0, but the focus now is on stability, tests and documentation. Oh, and building a community of contributors. That means you!

First off though, I better deflate your expectations a bit. I don’t know if this was my fault for wording the last blog post badly, but a few people seem to have gained some pretty wild expectations about what’s coming. Terms like “fully documented” and even (gasp) “version 1.0″ have been bouncing around. Sorry folks, there’s good stuff coming but I never meant to give you that idea. Apologies for any confusion.

What is coming is this — we are turning the corner and focussing our energy on making Hobo into something everyone can use. That means breaking it up into parts, and writing more documentation and tests. The process has begun, and the first installment is on the way. Here’s what we’re about to put out. (If you know where to look you’ll know that some of these things are in fact available already. We’re just holding off from the ‘official’ release so we can promote the new stuff properly in a few places).

• Hobo 0.7.4
• HoboSupport as a separate gem (core Ruby extensions). With full docs!
• HoboFields plugin. This is something a lot of people have asked for — the migration generator as a separate plugin. HoboFields will be well documented too :-)
• Significant improvements to the current Hobo tutorial (the POD classified ads application)
• An entirely new tutorial — this is the one I delivered today at the conference. It goes through the full development of an app for tracking an agile development process (sort of a mini Mingle). Runs to 13 pages when printed.
• A DRYML guide covering all of the basic facilities that DRYML provides.
• A revamped hobocentral.net
• Very nice online access to the source-code and commit log (from a service you may have heard of)
• A very nice ticketing system that won’t drown in spam like the last one (also from a service you may know)
• Possibly some other stuff I’ve forgotten because this is all off the top of my head and it’s kinda late.

So it’s not 1.0 and it’s not fully documented but I hope it’s enough to demonstrate that we’re serious about moving Hobo in the right direction now. And like I said, it’s nearly ready. Watch this space.

As promised, Hobo is being broken down into smaller sub-projects such as DRYML, the migration generator, the security system etc. etc. You’ll still be able to use Hobo as a whole but people will be able to try out just the bits that interest them much more easily.

As promised, Hobo is going to be properly tested and documented. This is being done at the same time as the break-up into sub-projects. Each sub-project will be released complete with a decent test suite and documentation.

And finally, the current hobocentral.net website does a pretty poor job of expressing what the project is all about. We’ll be making some changes there too.

The break-up / test / document work is already well underway, but we’re holding off from any releasing anything until we’re a bit more prepared. The goal is to have our new face ready in time for the Ruby Fools conference in Denmark. That’s 31st March, so you don’t have to hold on for too long. In the mean time there probably won’t be any releases and the blog will be a bit quiet. We haven’t gone anywhere so you can still say hi in the forums and the #hobo channel. A new and much more mature chapter in the Hobo story is just around the corner - please hold tight :-)

We are very excited to be presenting a three hour hands-on Hobo tutorial at RailsConf in Portland, Oregon!

Three hours should be enough time to build a complete Facebook clone and still have time for a relaxed chat about Danish history. Well, um, it should be enough time to build a decent demo app and get some experience with all of the main features of Hobo. Excellent! The tutorial is scheduled for March 31st, which I believe is the day before the presentations start. The tutorial is in addition to the one hour presentation which is on the 2nd.

Would be great to meet some more of you Hobo people face-to-face.

If you’re coming, say so in the comments :-)

Should be fun!

p.s. As I’m writing this the details they have for me on the conference website are kinda broken, and my face is that of a white fuzzy blob. Should all be fixed up shortly :-)

• CHANGELOG