The main point here is this – Hobo is nothing but extensions to Rails! There’s nothing that Rails can do that Hobo can’t. I’m not saying that Hobo will be to everyone’s taste – of course you may prefer Rails as it is. I’m just making the point that Hobo only adds to Rails, it doesn’t take anything away. Perhaps it’s the slightly “magic” feel to the POD screencast — I can see that the screencast might leave some people thinking they’d rather build the app themselves and have control over everything. So I guess I’m really just making the point that you do have control over everything, in just as direct a manner as you do in Rails without Hobo.

Hobo does do more than your average plugin though — it’s kind of like several plugins rolled into one. Inevitably people are going to be interested in having those features as separate plugins — a few people have asked for DRYML by itself already. But there are a bunch of dependencies between the different features, and to be honest I won’t know exactly where things can be separated until Hobo matures a bit.

So, for now at least, I’ve taken a different approach – you install all these features at once by installing Hobo, but you use only those features you want to. If you want the whole “web app builder” thing, then you’ll end up using most or all of them, but if you just want DRYML? Not a problem, the rest of Hobo won’t get in your way. If you later see that you could also benefit from, say, the ajax-mechanism, fine — just start using it.

So perhaps a quick tour of what these features are would be in order :-)

DRYML

This is really the heart of Hobo — it all started with DRYML. There’s a few posts on this already of course – have a look in the documentation category. DRYML consists of the templating mechanism itself, as well as a “core” tag library, with the basic things like loops and conditionals.

Ajax Rendering

Building on DRYML, this is the ability to mark a section of your page as a “part”. Having done this, Hobo will track the object that was in context when the part was rendered, and can re-render the part using the new state of that object when requested. This mechanism can be used by itself, but works best in combination with the Hobo Rapid tag library, which lets you write very simple stuff like

<delete_button update="number_of_users"/>

and the number of users will automatically change to reflect the deletion.

Right now using the Ajax mechanism without also buying into Hobo Rapid is kind of a pain. Some extra work to smooth that out is in order. Perhaps some regular Rails helpers.

Hobo Rapid Tag Library

This is where things get groovy. A tag library is basically just like a load of Rails helpers, but as DRYML tags instead of methods. Hobo Rapid contains the Hobo equivalent of link helpers, form helpers, ajax helpers, and pagination helpers. There’s also some “scaffold-like” tags for default pages, and support for navigation bars.

This library is expected to grow!

ActiveRecord Permission System

This appears prominently in the POD screencast. At it’s heart it’s just a simple convention for declaring who’s allowed to do what to your models (create, update, delete and view). The permissions come into effect in two places: in customising the views, and in validating http requests.

View customisation is provided in the tag library. The output of various tags is dependent on permissions. For example the <edit> tag will automatically become a read-only view if the current user does not have edit permission.

Validation of web requests is done in Hobo’s generic model controller (see below). If the request, be it a view, a create, an update or a delete (http get/post/put/delete) is not permitted for the current user, it will be rejected.

Cross-Model Search

Fairly simple but useful. Models can declare which columns are searchable (there are sensible defaults of course!) and Hobo provides both server and client-side support for a nice ajaxified search that finds many types of model from a single search page.

Switchable Themes

A Hobo theme consists of public assets such as a stylesheet and images, and some tag definitions. The tags define the basic HTML structure of the various theme elements – the overall page, header and footer, navigation bar, sidebars, panels (boxed sections within the page) etc. Themes are switchable by changing a configuration variable. All the variable does is determine the paths used to find the tag definitions (app/views/hobolib/themes/theme-name) and the public assets (public/hobothemes/theme-name).

User Management (Acts As Authenticated)

In order for the permission system to work, a user model must be present. For that reason we decided to go ahead and include AAA in Hobo. It’s been tweaked a bit — the controller has been merged with Hobo’s “front” controller (so called because it gives you your front page and related pages like search, login and signup). The user model methods that are not commonly changed have been moved out into a module to keep your user model clean.

Hobo also adds the concept of a guest user, this is a pseudo model that is not stored in the database. It’s just a place to define the permissions for someone who has not logged in. One implication of this change this is that instead of testing if current_user is nil, you test for current_user.guest?.

ActiveRecord Composable Query Mechanism

It’s common practice with ActiveRecord to write query methods to capture standard queries your application needs beyond the magic find_by_thingumybob methods. A problem I ran into was that I wanted to be able to compose queries: find everything that matches this query or that one; find the first record that matches some query and some other one.

I found I needed such a feature in Hobo so I implemented the following:

Post.find(:all) { (title_contains("Hobo") | content_contains("Hobo")) &
                   is_in(news_category.posts) }
User.find(:first) { name_is("Tom") | email_is("foo@bar.com") }

Note that in the first example, the collection my_category.posts doesn’t need to be loaded – the query generates SQL and runs entirely on the database.

The query operations in those examples — *_contains, *_is and in_collection — are all built in. If you write class methods on your model that return SQL expressions you can use those in the query too.

Generic Model Controller (CRUD Support)

Hmmm – this does a fair few things. Maybe I need another cup of tea… Slurp, ahhh. Sorry where was I? Oh yeah – the model controller. To get this functionality, add this to your controller

hobo_model_controller

It’s just a short-hand for including Hobo::ModelController. You can also generate a controller which already contains this declaration (hey – every little helps!) with:

$ ./script/generate hobo_model_controller <model-name>

CRUD support

Hobo derives the model class from the controller class name, so you should follow the Rails convention of PostsController for model Post (the generator will do this for you of course). You then get the basic CRUD methods familiar from scaffolding: index, show, new, create, edit and update.

The controller also has support for your has_many and belongs_to associations. Firstly, your has_many associations get published automatically, so for example the URL

/posts/12/comments

Would map to the action show_comments, which is implemented for you. Also

/posts/12/comments/new

Will invoke the new_comment action – again it’s implemented for you. Note that the form on that page doesn’t post to /posts/12/comments but to /comments as usual. I decided it was best to have a single URL for creating a given model.

There’s also support for your associations when creating / updating models. Without going into too much detail in this overview, when you post (create) or put (update), you can set both has_many associations and belongs_to associations. You can either pass the id of an existing record, or pass entirely new records in nested parameter hashes. There’s support for all this in DRYML and Hobo Rapid, so for example if a person has an address as a separate, associated model, you can easily build a single form with fields for both the person and the associated address.

Data filters

The composable query mechanism for ActiveRecord has been described above. Data filters allow you to expose these queries to the web. This is easiest to explain with an example. Say we have people that are members of groups, and we want a page with all the people not in a particular group. Inside the people controller we define a data filter:

def_data_filter :not_in do |collection|
  not_in(collection)
end

A page with all the people not in the group with id 7 would then be available at

/people?where_not_in=group_17

Enhanced autocomplete

Rails already has support for working with the Scriptaculous auto-completer through the helper auto_complete_for (although that’s on its way out in 2.0). Hobo’s version is enhanced to work with the data filter mechanism. Say for example you wanted an auto-completer to allow you to add people to a list – you don’t want the people already in the list to be included in the completions. You would add the following to your controller:

def_data_filter :not_in do |collection|
  not_in(collection)
end

autocomplete_for :name

You would then point your auto-completer at (e.g.) /people/completions?for=name&where_not_in=list_12

Hobo Rapid has an auto-completer tag so the client side is nice and easy too.

Remote procedure calls

When DHH introduced the Simply Restful stuff, he described CRUD as an aspiration rather than a hard rule (IIRC). In other words, you shouldn’t go crazy trying to model absolutely everything as resources — there will still be “remote procedure calls” (RPC) that we post to. I hit this recently with a need for a “reset password” service on an app I’m building. (BTW – this is basically how Hobo moves forward – if I hit a need for a feature that I feel will crop up again and again, I build it into Hobo, not the app. In this case I didn’t want to build password reset into Hobo, but I did build the RPC mechanism).

The basic procedure is: write an action in your controller as normal. Add web_method <method-name>. Hobo will add a route for your method, and apply a before filter so the object in question is already available in @this. Hobo’s ajax mechanism supports updating the page with results from your method, and there’s integration into the permission system too.

Let’s see an example – the reset password method. In the controller we add:

web_method :reset_password
def reset_password
  new_password = @this.reset_password
  hobo_ajax_response(@this, :password => new_password)
end

On the model we can add a method can_call_reset_password?(user). In my case I only wanted the super-user to have access to this method so I didn’t need can_call_reset_password?.

The method will be available to HTTP posts at, e.g.

/users/21/reset_password

For the client side there’s a <remote_method_button> tag (note to self: should be called <web_method_button>?)

Alternative show methods

Simply Restful introduced the semicolon in the URL to access alternate views of the same object. So

/posts/12

Would be a ‘normal’ view of the post, while

/post/12;edit

Would give you a form to edit the post — still a view of the post, just a different one. You’ll probably find the need for additional “alternative views”, e.g. you might have a main view of a user, plus a separate “My Profile” page where users can edit details that don’t change so often, like their email address. Hobo allows you to simply say

show_method :profile

In your controller. You then create app/views/users/profile.dryml. You also get a named route person_profile so you can call person_profile_url(fred) and get the URL back.

Migration Enhancements

This is a little one, but very useful. In create_table calls, you can add columns like this

t.string :name, :subject, :limit => 50

instead of

t.column :name, :string, :limit => 50
t.column :subject, :string, :limit => 50

There’s also t.auto_dates that gives you updated_at and created_at, and

t.fkey :zip, :zap

That will give you integer columns zipid and zapid.

ID Names

In ActiveRecord everything has a numeric ID. It’s common however, that models also have an identifying name (e.g. a name column where every row is unique). If a model has an ID name like this, it’s nice to be able to sometimes use it instead of the numeric ID, for example in readable URLs. If your model declares hobo_model, you can also declare

id_name <column-name>

If you don’t specify a column it defaults to name. This gives you a read/write attribute id_name which is just an alias for the column in question. You also get find_by_id_name on the class.

If you are using Hobo’s model_controller you can then use names instead of IDs in your URLs, e.g. (using ID names in combination with the associations support):

/categories/News/posts

The helper object_url will generate this kind of URL too – if the object you pass supports ID names.

That’s All Folks!

That’s pretty much everything, although of course lots of detail is lacking. Oh and there’s a ton of great new stuff just around the corner of course!

So to keep you going, I thought I’d better rattle off a few quick tips on customising a page, seeing as it’s a total mystery at the moment. We’ll customise the view of a category page in the POD demo.

If you wanted to customise the front page, that would be a relatively familiar process – look in app/views/front and you’ll find index.dryml, as well as a few others. But app/views/categories is empty — so where is the current page coming from?

Hobo’s model controller (i.e. any controller that declares hobo_model_controller) provides the following pages (actions) just like a regular Rails scaffold:

• index – A list of all the records

• show – A view of a single record

• edit – an editable view of a single record (the default UI doesn’t use this, as the show page supports in-place editing)

• new – A blank form for a new record

If Hobo doesn’t find a template for a given page, it will use a tag instead – these are defined by the theme:

• <index_page>
• <show_page>
• <edit_page>
• <new_page>

So there are two ways to override the look of a page. If you override one of these tags, say by defining <show_page> in app/views/hobolib/application.dryml, all the show pages will change. If you create a file, say app/views/categories/show.dryml, then just that page will change.

Try creating this file:

app/views/categories/show.dryml

My category page

If you browse to a category page, you should see just that text – all trace of the theme is gone. To get the theme back, we need to use the <page> tag which gives us a generic page (this tag is used in turn by <index_page>, <show_page> etc.). E.g.:

app/views/categories/show.dryml

<page>
  <h1>My category page</h1>
</page>

Now lets start to build out the page

app/views/categories/show.dryml

<page>
  <h1><show attr="name"/></h1>

  <panel>
    <h1>Adverts</h1>
    <repeat attr="adverts">
      <section>
        <h2><show attr="title"/></h2>
      </section>
    </repeat>
  </panel>
</page>

Note the use of <panel> and <section> tags. These are theme tags and will be rendered differently by each theme.

One problem with this page is that we’ve lost the ability to edit in-place. If we change those <show> tags to <edit> tags, Hobo will provide an in-place editor to any user with the right permissions. Lets include the advert body while we’re at it:

app/views/categories/show.dryml

<page>
  <h1><edit attr="name"/></h1>

  <panel>
    <h1>Adverts</h1>
    <repeat attr="adverts">
      <section>
        <h2><edit attr="title"/></h2>
        <p><edit attr="body"/></p>
      </section>
    </repeat>
  </panel>
</page>

And there you have it. An obvious feature we’re missing is the ability to paginate. What’s needed I think is something like <paginated_repeat> which would only be allowed once on a page. Hobo doesn’t have this yet. There’s no shortage of things on the to-do list!

We’re going to build on the todo-list demo app from an earlier post, so if you want to follow along you should start with that post. Just to recap, the app is trivially simple, consisting of a TodoList model which has_many :tasks and a Task model which belongs_to :todo_list. We created a controller for to-do lists with just a show action, and we implemented a DRYML view for that action.

We’re going to add an ajaxified “New Task” form on that same page. Let’s do the back-end first, so that it’s possible to create tasks. We’ll start by being good modern Rails citizens, and switch to RESTful routing. Add this line to routes.rb:

map.resources :todo_lists, :tasks

Now create our controller

$ ./script/generate controller tasks

app/controllers/tasks_controller.rb

class TasksController < ApplicationController

  def create
    Task.create(params[:task])
  end

end

Now we’ll add a simple ajax form to todo_lists/show.dryml. We’ll use the familiar remote_form_tag helper. We’ll use raw HTML for the form controls, just to be clear about exactly what’s going on, What we won’t do, for now, is deal with refreshing the page.

app/views/todo_lists/show.dryml

<head>
  <%= javascript_include_tag :defaults %>
</head>
<body>
  <h1>Todo List: <name/></h1>

  <ul_for attr="tasks"><name_link/></ul_for>

  <% form_remote_tag :url => "/tasks", :method => :post do %>
    <input type="hidden" name="task[todo_list_id]"
                         value="<%= this.id %>"/>
    <input type="text" name="task[name]"/>
    <input type="submit" value="New Task"/>
  <% end %>
</body>

That should work as is, although you’ll have to manually reload the page to see any new tasks. Let’s fix that, Hobo style.

With DRYML, any fragment of the page can be marked as a part. A part can be rendered separately from the rest of the page, just like a partial. To create a part, just give any element a part_id. For this demo we’ll add it to the ul_for tag.

app/views/todo_lists/show.dryml

<head>
  <%= javascript_include_tag :defaults %>
</head>
<body>
  <h1>Todo List: <name/></h1>

  <ul_for attr="tasks" part_id="task_list"><name_link/></ul_for>

  <% form_remote_tag :url => "/tasks", :method => :post do %>
    <input type="hidden" name="task[todo_list_id]"
                         value="<%= this.id %>"/>
    <input type="text" name="task[name]"/>
    <input type="submit" value="New Task"/>
  <% end %>
</body>

Having done that, reload the page in the browser and have a look at the source. You should see something like (with bits cut out for the sake of clarity):

Generated HTML Source

<head>
  <!-- A BUNCH OF JAVASCRIPT INCLUDES -->
</head>
<body>
  <h1>Todo List: Launch Hobo!</h1>

  <span id='task_list'>
  <ul>
    <!-- A BUNCH OF LIST ITEMS -->
  </ul>
  </span>

<!-- THE FORM HERE -->
</body>

<script>
var hoboParts = {}
hoboParts.task_list = 'todo_list_1'
</script>

The important bits to note are the <span> with the same ID as our part, and the JavaScript snippet at the end. The JavaScript was generated by Hobo to keep track of which model objects are displayed in which parts.

We can ask for a part to be updated, simply by adding a few parameters to the request. Hobo provides tags to make this blissfully easy, and we’ll have a look at those shortly. For now though, just to show there’s no magic going on, we’ll add them by hand using hidden fields.

The parameters we need are:

• part_page: The path of the current page template, e.g. “todo_lists/show”. (Future development: maybe we can do away with this and use the HTTP referrer instead)

• render[][part]: The name of the part we’d like to refresh. e.g. task_list

• render[][object]: The “DOM ID” of the “context object” for that part. e.g. todo_list_1

Update the form as follows:

app/views/todo_lists/show.dryml (fragment)

<% form_remote_tag :url => "/tasks", :method => :post do %>
  <input type="hidden" name="task[todo_list_id]"
                       value="<%= this.id %>"/>
  <input type="text" name="task[name]"/>
  <input type="submit" value="New Task"/>

  <input type="hidden" name="part_page" value="todo_lists/show"/>
  <input type="hidden" name="render[][part]" value="task_list"/>
  <input type="hidden" name="render[][object]"
                       value="todo_list_<% this.id %>"/>
<% end %>

We now need to upgrade our controller to recognize this “render request”. That just requires including a module, and calling one method:

app/controllers/tasks_controller.rb

class TasksController < ApplicationController

  include Hobo::AjaxController

  def create
    this = Task.create(params[:task])
    hobo_ajax_response(this)
  end

end

The hobo_ajax_response method needs a page context. As you can see we’re passing in the object just created.

You should now have a working ajax “New Task” feature.

The code might work but it’s pretty ugly (heh). Let’s clean it up using the appropriate Hobo tags. The tags we need come from a tag library that’s provided with Hobo — Hobo Rapid. Hobo Rapid is a very general purpose tag library that makes it extremely quick and easy to do the bread-and-butter stuff: links, forms, ajax…

We’ll look at Hobo Rapid in more detail in another post. For now we’ll see how to pretty-up our ajax demo.

To include Hobo Rapid in your application:

$ ./script/generate hobo_rapid

Then edit your view to look as follows:

app/views/todo_lists/show.dryml

<head>
  <%= javascript_include_tag :defaults %>
  <hobo_rapid_javascripts/>
</head>
<body>
  <h1>Todo List: <name/></h1>

  <ul_for attr="tasks" part_id="task_list"><name_link/></ul_for>

  <create_form attr="tasks" update="task_list">
    <edit attr="name"/>
    <submit label="New Task"/>
  </create_form>
</body>

Yep – that’s it :-) Try it — it should be working.

The <create_form> tag can be read as: Include a form which will first create an object in the collection “tasks” of the current context (the TodoList), and then update the “task_list” part. Note that you don’t need to say anything about how to update that part. Hobo knows.

<booming-voice>AND NOW [drum-roll] THE GRAND FINALE…</booming-voice>

How easy is it to update multiple parts in one go? For example, suppose the page had a count of the number of tasks — that would need updating too. We’ll use another handy little tag from Hobo Rapid: <count/> (Note this tag doesn’t have any special ajax support. We could have used a regular ERB scriptlet and the ajax would still work). And for bonus marks, we’ll DRY up all those attr='tasks' using a <with> tag, which just changes the context.

app/views/todo_lists/show.dryml

<head>
  <%= javascript_include_tag :defaults %>
  <hobo_rapid_javascripts/>
</head>
<body>
  <h1>Todo List: <name/></h1>

  <with attr="tasks">
    <ul_for part_id="task_list"><name_link/></ul_for>
    <p><count part_id="task_count"/></p>

    <create_form update="task_list, task_count">
      <edit attr="name"/>
      <submit label="New Task"/>
    </create_form>
  </with>
</body>

To update multiple parts, just list the part names in the update attribute.

What more could you ask for? :-)

For those that want all the details, we’ll do the whole thing from scratch: create the Rails app, install Hobo, create some models… For those who don’t, you can skip the stuff between the two rules

<skippable>

Let’s get started with a fresh Rails app and get Hobo installed:

$ rails hobo_demo
$ mysqladmin create hobo_demo_development
$ cd hobo_demo
$ ./script/plugin install svn://hobocentral.net/hobo/trunk
$ ./script/generate hobo

…then create some models, populate with some data. Hmm, I guess we need to pick some kind of domain to model. How about a simple to-do list app? [Groan] OK but it’s a cliché for a reason – simple, familiar… Let’s move on :-)

To start we’ll just have TodoLists and Tasks, where a TodoList has many Tasks.

$ ./script/generate model todo_list
$ ./script/generate model task

Now let’s get those tables created — edit the two migrations so the create tables look like these:

create_table :todo_lists do |t|
  t.column :name, :string
end

create_table :tasks do |t|
  t.column :name, :string
  t.column :todo_list_id, :integer
end

Declare the relationships in the models:

app/models/task.rb

class Task < ActiveRecord::Base
  belongs_to :todo_list
end

app/models/todo_list.rb

class TodoList < ActiveRecord::Base
  has_many :tasks
end

Then just a quick

$ rake migrate

…and we’re good to go. Gotta love Rails eh?

If you’re following along you might want to pause here to get some data in there. Personally I’d use ./script/console but you might prefer scaffolding, your MySQL GUI…

</skippable>

(Welcome back to the skimmers :-) What you missed: we’re working with a skeleton app with a TodoList model that has a name and has_many :tasks and a Task model that has a name and belongs_to :todo_list)

OK lets create a view of a single list

$ ./script/generate controller todo_lists

app/controllers/todo_lists_controller.rb

class TodoListsController < ApplicationController

  def show
    @this = TodoList.find(params[:id])
  end

end

@this?? That’s kind of unconventional isn’t it? The implicit context in a DRYML template is held in a variable this (actually it’s not a variable, it’s a method, but don’t worry about it). To set the context for the whole page, we assign to @this in the controller.

Now the view. We can access the context as this in a regular ERB scriptlet.

app/views/todo_lists/show.dryml

<h1>Todo List: <%= this.name %></h1>

<ul>
  <% this.tasks.each do |task| %>
    <li><%= task.name %></li>
  <% end %>
</ul>

Now lets clean that up with some DRYML goodness. First we’ll use <repeat>, which is part of the core taglib (available everywhere) instead of that loop. Let’s see the code first, and then go through how it works

app/views/todo_lists/show.dryml

<h1>Todo List: <%= this.name %></h1>

<ul>
  <repeat attr="tasks">
    <li><%= this.name %></li>
  </repeat>
</ul>

Starting to look cleaner! Two things to notice. First: we gave repeat just the name of the attribute we were interested in (tasks). It implicitly found that collection in the current context (the current value of this). We are therefore iterating over this.tasks. In other words, you just say “how to get there from here”: the page is displaying a TodoList, so iterate over the tasks. Nice and easy.

(Aside: We use the term ‘attribute’ here in the Ruby sense, as in, say, attr_reader. Unfortunately, in a mark-up setting that term conflicts confusingly with XML attributes. We might change this name. What else could you call the attributes of a model object? Properties? Fields?)

The second thing to notice is that inside the repeat, we’re using this again, only now it refers to the individual task. repeat sets the context to each item in the collection in turn. If you’ve ever worked with XSL-T, this idea may be familiar.

Notice now that both the scriptlets that display the name are identical. Bad programmer! Don’t repeat yourself! No problemo:

app/views/todo_lists/show.dryml

<def tag="name"><%= this.name %></def>

<h1>Todo List: <name/></h1>

<ul>
  <repeat attr="tasks">
    <li><name/></li>
  </repeat>
</ul>

Note that the name tag declares this as an attribute. Any tag that’s going to use this should declare so in this way, even though we never actually give this as an attribute when we use the tag.

Next we should move that <def> to the global taglib (application.dryml, which lives in app/views/hobolib). While we’re at it, <ul>/<li> lists tend to crop up all over the place, right? Bad programmer! Don’t repeat yourself! Let’s make a tag for those lists.

app/views/hobolib/application.dryml

<def tag="name"><%= this.name %></def>

<def tag="ul_for">
  <ul>
    <repeat>
      <li><tagbody/></li>
    </repeat>
  </ul>
</def>

The ul_for tag expects the context to be a collection. Here’s how we use it:

app/views/todo_lists/show.dryml

<h1>Todo List: <name/></h1>

<ul_for attr="tasks"><name/></ul_for>

You can’t ask for much more concise than that! Let’s now improve things a bit. Suppose the individual tasks were each going to have their own page in this app, perhaps displaying notes and such-like. In that case, we’d like that list to be a list of links. Here’s a handy tag that makes it easy to create a link to anything with a name:

app/views/hobolib/application.dryml (fragment)

<def tag="name_link">
  <%= link_to this.name,
              :controller => this.class.name.underscore.pluralize,
              :action => 'show',
              :id => this %>
</def>

There’s a little reflective name-mangling magic going there, but the beauty is that we can forget about that and just use the name_link tag. The change to our page to add our links is trivial:

app/views/todo_lists/show.dryml

<h1>Todo List: <name/></h1>

<ul_for attr="tasks"><name_link/></ul_for>

And we’re done. For today at least. Now — bearing in mind that this page is dramatically simpler than a typical page in a production app — let’s just compare:

Traditional ERB

<h1>Todo List: <%= @todo_list.name %></h1>

<ul>
  <% @todo_list.tasks.each do |task| %>
    <li>
      <%= link_to task.name, :controller => "tasks",
                             :action => "show",
                             :id => task %>
    </li>
  <% end %>
</ul>

…to…

DRYML

<h1>Todo List: <name/></h1>

<ul_for attr="tasks"><name_link/></ul_for>

I don’t know about you but to me that’s like a breath of fresh air. Now imagine that clarity in the context of a vastly more complex production app, and you might see what Hobo is all about.

(And we still haven’t shown you the best bit…)

UPDATE: This stuff is very out of date now, you might prefer to look here

Gosh – there’s quite a lot in here – where to start? Guess I’ll just dive right in.

To follow along, create yourself a new app, install Hobo, and throw in a demo controller. (for help with that, see Hello World)

Tags can be defined inside your views, making them local to that view. Useful for quick prototyping:

app/views/demo/my_page.dryml

<def tag="time"><%= Time.now %></def>

<p>The time is <time/></p>

More commonly you’d define tags in app/views/hobolib/application.dryml, making them available to your whole app, but for the purposes of exploring we’ll stick with local definitions.

Tags can have attributes. They are available as local variables inside the definition:

<def tag="time" attrs='format'>
  <%= Time.now.strftime(format) %>
</def>

<p>Today is <time format='%A'/></p>

Tags can call other tags, as you’d expect:

<def tag="time" attrs='format'>
  <%= Time.now.strftime(format) %>
</def>

<def tag='today'><time format='%A'/></def>

<p>Today is <today/></p>

Tags can have a body. Use DRYML’s <tagbody/> to insert the body where you need it:

<def tag="flower_box">
  <div class='flower_box'>
    <img src='flower.gif'/><tagbody/>
  </div>
</def>

<flower_box>Nice flower eh?</flower_box>

(Aside: yes, you could have done something similar with CSS, but there plenty you can’t do with CSS, like adding drop shadows in a way that copes with resizing. The drop-shadow technique I prefer needs 8 nested DIVs. Boy was I ever glad to wrap that in a tag)

Watch out for the XHTML compliant image tag (<img ... />). DRYML templates must be valid XML, except for two relaxations: they may contain ERB scriplets (in content or attribute values), and they need not have a single root tag.

OK let’s define a tag that lays out a whole page — yes you can use DRYML tags instead of layouts. This has the advantage of letting the choice of page-layout be made in the view, where it belongs (regular Rails layouts are selected in the controller). It also makes it easier for the page to pass bits-and pieces to the layout, such as a title and an onload event.

Here’s a simple page layout that separates the header and footer with a horizontal rule no less! Notice how we define multiple attributes using commas in attrs attribute.

<def tag='page' attrs='title,onload,header,footer'>
  <html>
    <head><title><%= title %></title></head>
    <body onload="<%= onload %>">

      <div class='header'>
        <%= header %>
      </div>
      <hr/>

      <tagbody/>

      <hr/>
      <div class='footer'>
        <%= footer %>
      </div>

    </body> 
  </html>
</def>


<page title="My Page"
      onload="alert('NO PLEASE! Not an onload alert!')">
  My wonderful page
</page>

Note the absence of a header and footer in that case. We’d rather not define those in attributes, as they’ll probably contain mark-up. So we’ll use an alternate syntax for supplying parameters to tags. Lets quickly get rid of that horrible alert too – if we don’t supply the onload, the result in the rendered page will simply be a blank onload on the <body> tag.

<def tag='page' attrs='title,onload,header,footer'>
  <html>
    <head><title><%= title %></title></head>
    <body onload="<%= onload %>">

      <div class='header'>
        <%= header %>
      </div>
      <hr/>

      <tagbody/>

      <hr/>
      <div class='footer'>
        <%= footer %>
      </div>

    </body> 
  </html>
</def>


<page title="My Page">
  <:header>
    Welcome to my site
  </:header>

  My wonderful page

  <:footer>
    My site. &copy; Me. Some Rights Reserved
  </:footer>
</page>

Those tags that start with a colon, e.g. <:footer>, are not defined tags. They are simply parameters to the <page> tag. They can appear anywhere directly inside the call (i.e. the <page> tag in this case). They could even have been given the other way around, the result would be the same.

Obviously the <page> tag isn’t much use unless it’s defined somewhere where it can be used by multiple pages. The simplest thing is to move it into app/views/hobolib/application.dryml. That library — or taglib as we call them — is implicitly imported by every page in your app. Alternatively here’s how you could put it into your own taglib instead. Move just the <def> into a new file e.g.:

app/views/shared/my_tags.dryml

<def tag='page' attrs='title,onload,header,footer'>
  <html>
    <head><title><%= title %></title></head>
    <body onload="<%= onload %>">

      <div class='header'>
        <%= header %>
      </div>
      <hr/>

      <tagbody/>

      <hr/>
      <div class='footer'>
        <%= footer %>
      </div>

    </body> 
  </html>
</def>

In the page, instead of the full definition of <page>, you now just need to import that taglib using, um, <taglib>. Like this:

<taglib src="shared/my_tags"/>

<page title="My Page">
  <:header>
    <h1>Welcome to my site</h1>
  </:header>
  <:footer>
    <i>My site. &copy; Me. Some Rights Reserved</i>
  </:footer>

  My wonderful page

</page>

If you define your tags in app/views/hobolib/application.dryml, you don’t need to use <taglib> — this is the global taglib and is always imported. Convention over configuration, man!

Where was I?

Oh yes. One of the main features of Hobo is DRYML – an new template engine that extends ERB with user-defined tags. Thats right: extends. DRYML templates can use erb scriptlets just like regular RHTML templates.

We’re going to create a custom tag <hello> which will render – you guessed it – “Hello World” on the page. Obviously, the real goal here is to get Hobo installed and verify that it’s running.

To run Hobo you need Rails 1.2, which at the time of writing is available as release-candidate 1. Install it like this:

gem install rails --source http://gems.rubyonrails.org -y

To install Hobo into a new Rails app, simply:

$ rails hobo_hello_world
$ cd hobo_hello_world
$ ./script/plugin install svn://hobocentral.net/hobo/trunk

Next, there are one or two directories and files that Hobo expects to find. Create these with the handy generator:

$ ./script/generate hobo
  create  app/views/hobolib
  create  app/views/hobolib/themes
  create  app/views/hobolib/application.dryml

OK, Hobo is now at your service! Before we can have a Hello World view, of course, we’ll need a controller:

$ ./script/generate controller hello

No need to edit that. We’ll just go straight for the view.

File: app/views/hello/hello_world.dryml

<def tag="hello">Hello World!</def>

<p>Here it comes... Can you stand it??!</p>

<p style="font-size: 500%"> <hello/> </p>

That’s it. Start your engines:

$ ./script/server

And browse yourself over to localhost:3000/hello/hello_world

Outstanding work people. If that has whet your appetite and you want more, I suggest you haul your digital assets over to either Why DRYML? or A Quick Guide to DRYML.