# HoboFields

## Introduction

Welcome to HoboFields -- a spin-off from the Hobo project (Hobo not required!).

**HoboFields writes your Rails migrations for you! Your migration writing days are over!**

All we ask is that you declare your fields in the model. It's still perfectly DRY because you're not having to repeat that in the migration -- HoboFields does that for you. In fact, you'll come to love having them there.

It still has all the benefits of writing your own migrations, for example if you want to add some special code to migrate your old data, you can just edit the generated migration.

## Example

First off, if you're using the migration generator outside of Hobo, do remember the `--skip-migration` option when generating your models:

        $ rails generate model blog_post --skip-migration

If you're using Hobo:

        $ rails generate hobo:model blog_post

Now edit your model as follows:

    class BlogPost < ActiveRecord::Base
      fields do
        title :string
        body  :text
        timestamps
      end
    end
{: .ruby}


Then, simply run

        $ rails generate hobo:migration

And voila

        ---------- Up Migration ----------
        create_table :blog_posts do |t|
          t.string   :title
          t.text     :body
          t.datetime :created_at
          t.datetime :updated_at
        end
        ----------------------------------

        ---------- Down Migration --------
        drop_table :blog_posts
        ----------------------------------
{: .ruby}

The migration generator has created a migration to change from the schema that is currently in your database, to the schema that your models need. That's really all there is to it. You are now free to simply hack away on your app and run the migration generator every time the database needs to play catch-up.

Note that the migration generator is interactive -- it can't tell the difference between renaming something vs. adding one thing and removing another, so sometimes it will ask you to clarify. It's a bit picky about what it makes you type in response, because we really don't want you to lose data when someone's amazing twitter distracts you at the wrong moment.

## Installing

The simplest and recommended way to install HoboFields is as a gem:

        $ gem install hobo_fields

The source lives on GitHub as part of the main Hobo repo:

 - [http://github.com/Hobo/hobo](http://github.com/Hobo/hobo)

## Rich Types

In addition to the migration generator, HoboFields provides a Rich-Type mechanism that allows you to declare your fields using higher level concepts like "email-address" or "markdown text". This can give you both automatic validations, and automatic rendering of those values in the UI (this works particularly well if you use the rest of Hobo).

Read more:

 - [HoboFields Rich Types](/manual/hobo_fields/rich_types)

## API

HoboFields provides various API methods. Read more:

 - [HoboFields API](/manual/hobo_fields/api)

## Migration Generator Details

The migration generator doctests provide a lot more detail. They're not really that great as documentation because doctests run in a single irb session, and that doesn't fit well with the concept of a generator. Skip these unless you're really keen to see the details of the migration generator in action

 - [Migration Generator Details](/manual/hobo_fields/migration_generator)

## About Doctests

HoboFields is documented and tested using *doctests*. This is an idea that comes from Python that we've been experimenting with for Hobo. Whenever you see code-blocks that start "`>>`", read them as IRB sessions. The `rdoctest` tool extracts these and runs them to verify they behave as advertised.

Doctests are a great way to get both documentation and tests from the same source. We're still experimenting with exactly how this all works though, so if the docs seem strange in places, please bear with us!

You may download rubydoctest via [github](http://www.github.com/tablatom/rubydoctest)