Taming Hobo with Tyler Lesmann

Headers and Footers in Hobo

Tyler Lesmann

It’s really easy to override the header and footer in hobo. There are two ways to do this. I use both in aura-site.

First, look at the pages definition in rapid_pages.dryml. Everything with a param attribute can be redefined.

Note the main-nav element. By default, Hobo will magically generate a menu for you, based on your project. On aura-site, we override this in application.dryml to build our menus the way the admin wants.

Now you can also redefine the page as a whole. We do this in the aura theme to add a bit of css and javascript to the head of the html.

The easiest way to make a header or footer is to use this second method. Just use a <header:> to replace the header or <append-header:> to add to the end of it. Same deal with footer, just use the <footer:>, <append-footer:>, <prepend-footer:>.

Make a Blog with Hobo: Theming

Tyler Lesmann

It took me awhile to figure out how Hobo’s theming engine works. It’s not hard to create and use a new theme if you know the caveats.

We’ll start by using hobo’s default theme, clean, as a template. Go into RAILS_ROOT/app/views/taglibs/themes. You will see a directory called clean. Inside this directory is a single file called clean.dryml. You’ll want to pick a name for your theme. For this example, my new theme will be called red. Create a new directory called red and copy clean/clean.dryml to red/red.dryml.

We do not need to make changes to red.dryml for it to work properly. This file is where you will define tags, cards, and forms specific to your theme. If you need to pull in some more javascript and css, this would be the place to do it.

Next, we need go to RAILS_ROOT/public/hobothemes. Again you will see a clean directory. Copy this directory to a new one, red. Go to stylesheets within the red directory. Rename clean.css to red.css. Now we have the media assets for our new theme all set up. So how do we use this new theme?

Open RAILS_ROOT/app/views/taglibs/application.dryml. You’ll see a tag early on called set-theme. Just change that to point to red.

<set-theme name="red"/>

If you are running your server, then restart now. Hobo will not load the new theme correctly otherwise. Now your blog its own theme!

Make a Blog with Hobo: Lifecycles

Tyler Lesmann

Sometimes we may want to not publish our blog entries to the world. They might need a little work, which we plan on doing later. So our entries need two states: published and drafted. Hobo’s lifecycles make this not too much of a chore.

First, let’s open app/models/entry.rb and define our lifecycle. These lines can go right after where we’ve defined our relations.

lifecycle do
  state :drafted, :default => true
  state :published

  transition :publish, {:drafted => :published}, :available_to => :user
  transition :unpublish, {:published => :drafted}, :available_to => :user
end

We’ve defined our two states. Our entries will default to the drafted state. There are also two transitions. Transitions define how our entry can change states. A entry can become drafted only when it is in the published state. The opposite is also true. Only the user, or author in this case, can change states. Now let’s migrate!

$ script/generate hobo_migration

States are now engaged, but we cannot change between them. We need to add some buttons. Hobo provides the extremely helpful <transition-buttons/> tag to accomplish this. Open app/views/taglibs/application.dryml and add this tag to our entry-info tag like so.

<def tag="entry-info">
  <div>
    Posted on <view:created-at/>
  </div>
  <div>
    Tags: <view:tags/>
  </div>
  <transition-buttons/>
</def>

You now have Publish and Unpublish buttons. The assortment of buttons depends on the transitions available to your current user. So we have our states and we can change between them. Now we just need to do something with those states. Let’s change the view permissions in app/models/entry.rb.

def view_permitted?(field)
  acting_user.administrator? or state == 'published'
end

Now an entry is viewable if the user is an adminstrator or if the entry is in a published state.

Make a Blog with Hobo: Commenting

Tyler Lesmann

It would be nice to allow our readers to leave a little feedback, so in this edition we’ll do just that. This should give you insight into how Hobo can present one-to-many relationships. Create a very simple model with the following:

$ script/generate hobo_model_resource comment body:text

Nothing you haven’t seen. Open app/models/comment.rb and alter it to be like this:

class Comment < ActiveRecord::Base

  hobo_model # Don't put anything above this

  fields do
    body :text
    timestamps
  end

  belongs_to :user, :creator => true
  belongs_to :entry

  # --- Permissions --- #

  def create_permitted?
    acting_user.signed_up?
  end

  def update_permitted?
    acting_user.administrator?
  end

  def destroy_permitted?
    acting_user.administrator?
  end

  def view_permitted?(field)
    true
  end

end

A few changes to note here. We’ve added two relations, one to the User model and another to the Entry model. The :creator flag automatically sets the user if one is not given. You should also note the change to the permissions. Any user that has signed up will be able to create new comments. Let’s add the relations to the Entry model. Put these lines after the fields in app/models/entry.rb:

belongs_to :user, :creator => true
has_many :comments, :dependent => :destroy

The relation to comments has been made and now each entry will have an author. Now for the User model. Add these lines to app/models/user.rb after the fields:

has_many :entries
has_many :comments

Go ahead and run a hobo_migration to apply the changes to the database.

$ script/generate hobo_migration

If you take a look at the blog now, you’ll find a very awkward setup. Comments can only be created from the Comments tab. Comments aren’t connected to entries in an obvious way. Let’s change that. First, open up app/viewhints/entry_hints.rb and add this before the final end:

children :comments

Comments related to an entry are now shown on the entry’s show page. Let’s make it so users can add comments from there as well. Open app/controllers/comments_controller.rb and change it to be like this:

class CommentsController < ApplicationController

  hobo_model_controller

  auto_actions :destroy
  auto_actions_for :entry, [:create]

end

The auto_actions are now limited to destroy, which will allow the administrators to easily remove comments. The auto_actions_for is very convenient. That one line allows users to make comments from the show page of an entry. Take a look. One problem you should notice is that the user relation is accessible. Users would be able to leave comments as anyone on the site. That’s no good. Open app/views/taglibs/application.dryml and append this to the end of it:

<extend tag="card" for="Comment">
  <old-card merge>
    <body:>
      <div>
        On <view:created_at/>, <a:user/> said:
      </div>
      <view:body/>
    </body:>
  </old-card>
</extend>

<extend tag="form" for="Comment">
  <old-form merge>
    <field-list: fields="body" without-body-label/>
  </old-form>
</extend>

We’ve made a prettier card for comments and the form has been trimmed to only display a field for body. Of course, that’s not enough to stop users from spoofing comments. Open app/controllers/comments_controller.rb and add this before the final end:

def create_for_entry
  # Remove user spoofing
  # Hobo should make this easier
  params["comment"].delete("user_id")
  hobo_create
end

Yep. Hobo allows you customize how controllers on related pages work. All that we’ve done is removed user_id from the params. Hobo will instead relate the comment to the creator as we defined earlier. You might consider doing something similar to this for entries as well. Since comments are related to users and entries are now related to users, let’s make the user show page more interesting. Create a new file at app/viewhints/user_hints.rb and add this content:

class UserHints < Hobo::ViewHints
  children :entries, :comments
end

The user show page now features entries and comments authored by the user. Your extra credit on this lesson is to make the card for Entry more presentable.

Make a Blog with Hobo: Tagging

Tyler Lesmann

In this episode, we’ll add tagging support to our blog. Features of this lesson will be applicable to any many-to-many relationship in Hobo. Before I go any further, at the time of this writing, Hobo does not support has_and_belongs_to_many :models. A many-to-many relationship will only be blessed with the Hobo magic when implemented using has_many :models, :through => :join_model.

We need two tables, one for tags and a join table. We create these with the following commands:

$ script/generate hobo_model_resource tag name:string
$ script/generate hobo_model tag_assignment

Only thing you haven’t seen before is the hobo_model. It’s like hobo_model_resource less the controllers, which a join table doesn’t need. Let’s add the relationship code to the models. Add these lines to their indicated files before the # — Permissions — # line.

app/models/entry.rb

has_many :tags, :through => :tag_assignments, :accessible => true
has_many :tag_assignments, :dependent => :destroy

app/models/tag.rb

# Let's change the ordering while we're in here.  It defaults to created_at.
# This will affect how cards are ordered as well as when tags are viewed as
# a whole.
set_default_order "name" 

has_many :entries, :through => :tag_assignments
has_many :tag_assignments, :dependent => :destroy

app/models/tag_assignment.rb

belongs_to :entry
belongs_to :tag

Most of this is pure rails, except for the :accessible. This tells Hobo to build tag assignment into the form for Entry. Whenever a user accesses a tag’s show page, Hobo will display any child objects the coder describes. To describe children, we edit the viewhints, which in this case is app/viewhints/tag_hints.rb. Add this line:

children :entries

Time to apply the changes to the database!

$ script/generate hobo_migration

Note that if you’ve been following along to this tutorial, you will need to add tags to the fields of field-list for the Entry form, if you want to see how regular many-to-many relationships work in Hobo. You’ll remember that the form is described in app/views/taglibs/application.dryml. The way Hobo does these relationships is clumsy as you’ll see, for tagging anyway. It would be better for the blogger to just enter a bunch of words and phrases separated by commas. Let’s make it work that way. Add the following line to the list of fields in app/models/entry.rb:

tagstring     :string

This will hold the input string for the user. Now there are a few ways to handle the actual assignment of the tags to the blog entry. We could implement it like we did markdown formatting for posts earlier. Since I haven’t shown how to go outside the box in controllers yet, we’ll do it that way. Open app/controllers/entries_controller.rb and add the following lines before the last end.

def assign_tags
  params["entry"]["tags"] = params["entry"]["tagstring"].split(',').collect{
    |tag|
    '@' + Tag.find_or_create_by_name(tag.strip).id.to_s
  }
end

def create
  assign_tags
  hobo_create
end

def update
  assign_tags
  hobo_update
end

The meat of the changes is in the assign_tags method. Here we take the tagstring field and split it by commas. Then, we create or get a Tag instance for each tag, pull the id, and add @ to the front of the id. All of these ids are put into the tags param where Hobo will look at them later. We add two other methods: create and update. These will override the default Hobo/rails actions. We first call assign_tags to parse the tags. After this we use hobo_create or hobo_update, which invokes the usual Hobo handling.

Make sure you have the tagstring in the fields of the Entry form and apply the changes to the database.

$ script/generate hobo_migration

Look at that! Easy tagging! One last thing. Let’s make the tags a bit more visible by having them appear on the show page and card for Entry. Since we will need the same code in both places, we will make a new DRYML tag. In app/views/taglibs/application.dryml, remove the existing <extend tag="card" for="Entry"/> and add this:

<extend tag="card" for="Entry">
  <old-card merge>
    <prepend-body:>
      <entry-info/>
    </prepend-body:>
  </old-card>
</extend>

<def tag="entry-info">
  <div>
    Posted on <view:created-at/>
  </div>
  <div>
    Tags: <view:tags/>
  </div>
</def>

Alter app/views/entries/show.dryml to be like this:

<show-page>
  <append-content-header:>
   <entry-info/>
  </append-content-header:>
  <field-list: replace>
    <view:body_html/>
  </field-list:>
</show-page>

In DRYML, tags are includes with a bit of extra magic. For instance, in this entry-info tag, we are using <view:created-at/> and <view:tags/>. Hobo knows how to handle these depending on the context. If used out of context, Hobo gracefully outputs Not Available. To use a tag, we simply use it by name, like <entry-info/>.

Take a look at the results. Hobo made the entry’s tags each link to the tag’s show page. The tags are more visible and users can easily navigate to similarly tagged blog posts.

Make a Blog with Hobo: Customizing Cards, Forms, and Pages

Tyler Lesmann

In this part of the tutorial, we’ll make it so the interface and presentation of the blog are not so clumsy.

First thing to do is remove the body_html field from the Entry form. Open app/views/taglibs/application.dryml and add the following:

<extend tag="form" for="Entry">
  <old-form merge>
    <field-list: fields="name, body_markdown"/>
  </old-form>
</extend>

DRYML is powerful, but very complex. It takes a bit of time to understand it. The part that makes the changes is the <field-list: fields="name, body_markdown"/>. The <old-form merge> tells Hobo to only merge the changes I describe into the existing form. So how do I know what the existing form looks like? It took me a while to figure this out because it isn’t in Hobo’s documentation at the time of this post. If you look near the top of app/views/taglibs/application.dryml, you’ll see these lines:

<include src="taglibs/auto/rapid/cards"/>
<include src="taglibs/auto/rapid/pages"/>
<include src="taglibs/auto/rapid/forms"/>

Every time the server is booted, Hobo automatically creates three files for us, based on our model and controller. These are located in app/views/taglibs/auto/rapid/. If you open up the forms.dryml in this directory, then you’ll see the form automatically created for Entry. It looks something like this:

<def tag="form" for="Entry">
  <form merge param="default">
    <error-messages param/>
    <field-list fields="name, body_markdown, body_html" param/>
    <div param="actions">
      <submit label="#{ht 'entries.actions.save', :default=>['Save']}" param/>
      <or-cancel param="cancel"/>
    </div>
  </form>
</def>

Notice the <field-list>? Any element with a param attribute can be accessed later by appending a colon to the tag name, like we did with field-list:. Pretty slick, right? Let’s add some helpful text to the form for those who don’t know markdown by heart. Let’s also change the label of the name field to be Title and body_markdown to be Body. We do this in a file called app/viewhints/entry_hints.rb. Make the file resemble this:

class EntryHints < Hobo::ViewHints
  field_names :name => "Title", :body_markdown => "Body"
  field_help  :body_markdown => '
    Supports markdown formatting<br/>
    *emphasized* = <em>emphasized</em><br />
    **strong** = <strong>strong</strong><br />
    [Developer\'s Blog](http://hobo.tylerlesmann.com/) =
    <a href="http://hobo.tylerlesmann.com/">Developer\'s Blog</a><br />
    Go <a href="http://daringfireball.net/projects/markdown/syntax">here</a>
    for more information.'
end

Pretty easy when you know where to put it. Let’s alter how our posts are displayed in a list. The abbreviated version of any model instance, like an Entry, is known as a card in Hobo. Let’s have the card for Entry display the created_at date. Open up app/views/taglibs/application.dryml again and append this content:

<extend tag="card" for="Entry">
  <old-card merge>
    <body:>
      Posted on <view:created-at/>
    </body:>
  </old-card>
</extend>

Looks a bit similar to the form we changed earlier. Here we are replacing the body of the card. The <view:created-at/> element will do a few things for us. Depending on the field type, the content will be escaped. It also will format the field for us, like here with the created_at datetime field. Also, make note that all underscores in fields become hyphens in DRYML. You might notice a lot of content in ending up in this application.dryml. You should consider using includes to organize it, like those used by the automatically generated tags, cards, and forms. One last thing to do. Let’s change the way the Entry is viewed. Readers don’t need to see the body_markdown field or the field labels. They only need the HTML version of the post. Create a new file at app/views/entries/show.dryml with the following content:

<show-page>
  <append-content-header:>
    Posted on <view:created-at/>
  </append-content-header:>
  <field-list: replace>
    <view:body_html/>
  </field-list:>
</show-page>

Getting an idea of how DRYML works? Since body_html is an html field, it will not be escaped. See the <append-content-header:>? Hobo, like Rails and Ruby, has loads of magic. By slapping append- or prepend- in front of the tag, we can add content within that element. You can replace a tag and its content by adding the replace attribute, like here with the <field-list: replace>. It’s starting to come together.

Next up is tagging support.

Making a Blog with Hobo: Posting

Tyler Lesmann

Welcome to the first part of the tutorial. We will start a new hobo project, set up a model to hold blog entries, and add markdown formatting.

To create our new hobo project, we use this command:

$ hobo blog

You will see a load of output. This is the scripts of hobo and rails setting up everything we need to get started. We will now create a model to hold our posts with this command:

$ cd blog
$ script/generate hobo_model_resource entry name:string body_markdown:text body_html:html

You’ll be presented with more output. Hobo’s scripts have created several things for us. The most important at the moment is a new model, entry, which has three fields: A string field called name, a text field called body_markdown, and a html field called body_html. What’s the difference between text and html fields? Text fields are escaped when viewed. They are the same otherwise. Let’s make it so our posts are can be written in markdown. This is our first bit of coding! Open a new file in the project directory called app/models/markdown_wrapper.rb and insert the following ruby:

require 'rubygems'
require 'maruku'

class MarkdownWrapper
  def before_save(record)
    record.body_html = Maruku.new(record.body_markdown).to_html
  end
end

What this little piece of code does is every time our model is about to be saved, the text in body_text will be compiled into HTML by maruku and placed in body_html. There is one more thing to do to start to use it. Open app/models/entry.rb and add a line of before_save MarkdownWrapper.new after the line that reads hobo_model. Your code should look something like this:

class Entry < ActiveRecord::Base

  hobo_model # Don't put anything above this

  before_save MarkdownWrapper.new

  fields do
    name          :string
    body_markdown :text
    body_html     :html
    timestamps
  end


  # --- Permissions --- #

  def create_permitted?
    acting_user.administrator?
  end

  def update_permitted?
    acting_user.administrator?
  end

  def destroy_permitted?
    acting_user.administrator?
  end

  def view_permitted?(field)
    true
  end

end

See our fields in the fields do block? The timestamps are created_at and updated_at datetime fields, which are added by hobo. Now all we have to do is apply the changes to the database. We do that with this command:

$ script/generate hobo_migration

Hobo will generate the database migration for us. You will see that it is creating a users table in addition to our entries table. Enter m to save the migration and apply it to our database. It will ask you to name the migration. This can be whatever you want. I like to use initial on the first one. Let’s fire up the development server and take a look!

$ script/server

Navigate to http://localhost:3000/ and you’ll see the new hobo app! It will have you create a new administrator user. Then, you can create your blog posts! A lot of functionality has been accomplished with a few lines, but the interface is awkward. We will fix this in the next portion of the tutorial.

Make a Blog with Hobo

Tyler Lesmann

If you follow this tutorial, you will end up with a fully functional blog, with markdown formatting, tagging, commenting. You will also get a walkthrough of the many of hobos features. If you just want the code for this blog, then you can get it from Google Code. This tutorial only assumes one thing, which is that you have ruby and the hobo, maruku, and syntax gems installed.