Getting Started with Hanami

Hanami is one of the newer Ruby frameworks. It has gained some popularity of late, for its cleaner separation of code and being a light weight framework.

Why Hanami?

Hanami allows cleaner separation of code and follows clean architecture or atleast makes it easier for an app to follow the clean architecture. The framework also emphasizes on explicitly calling code and functions rather than leaving it to “magic”. This allows the programmer to be in full control of what is being written.

Layered architecture in Hanami

Hanami is lightweight, with 60% less memory than other full-featured Ruby frameworks(as quoted from hanamirb.org), and the core framework is thread safe.

Creating a New Hanami Application

Lets create a blog application in the Hanami framework and compare the steps when creating a blog with Rails.

1

hanami new hanami_blog --database=postgres --test=rspec

Note the apps folder that got created, and web is just one of the channel of delivery for the application.

Model (aka Entity) and Migration

Lets create the Post entity.

1

bundle exec hanami generate model Post

Hanami follows Repository Pattern, where the database access details are in a separate file called Repository, which is different from the entity. The generator will create a PostRepository to connect the Post entity to the Postgres database. The Entity will hold the domain logic.

Also note that the entities and the repositories are in the lib folder and can be accessesed across multiple ‘apps’ of which web is just one.

Add the fields title and body to the migration, and migrate the database

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# File: db/migrations/20180529115153_create_posts.rb

 Hanami::Model.migration do
   change do
     create_table :posts do
       primary_key :id
+
+      column :title, String, null: false
+      column :body, String

       column :created_at, DateTime, null: false
       column :updated_at, DateTime, null: false
     end
   end
 end

Create the database and run the migrations.

1

bundle exec hanami db prepare

The database is configured in the .env.development file, refer config/environment.rb for the database and other configurations.

Controller

Lets create controller actions for creating a new blog post.

1
2

bundle exec hanami generate action web posts#new
bundle exec hanami generate action web posts#create

Note that the controller actions are separate plain Ruby classes(and files) which includes Web::Action module, with a call function. The views are also separate Ruby classes. The erb to be rendered is in the templates folder.

New Post Form

Hanami has a dsl for forms, lets add a form to the templates/posts/new.html.erb file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<h2>New Blog Post</h2>

<%=
  form_for :post, routes.posts_path do
    div class: 'input' do
      label      :title
      text_field :title
    end

    div class: 'textarea' do
      label      :body
      text_area :body
    end

    div class: 'controls' do
      submit 'Create Post'
    end
  end
%>

Create Action

Hanami allows param validation with its own dsl. You don’t need the view and the template for create(as we are using a redirect), so you can delete them.

1
2
3
4
5
6

params do
  required(:post).schema do
    required(:title).filled(:str?)
    required(:body).filled(:str?)
  end
end

And you can persist the Post by passing the validated params to the create method of the PostRepository (it gets this from the parent class Hanami::Repository).

The call method in the Create class will be as follows:

1
2
3
4
5
6
7
8
9

def call(params)
  if params.valid?
    post = PostRepository.new.create(params[:post])

    redirect_to routes.posts_path
  else
    status 422, 'Post is not valid!'
  end
end

Index Action

Similarly create the index action for showing the list of blog posts.

1

bundle exec hanami generate action web posts#index

Hanami provides exposures which can be passed on to the view. In our case expose the posts array to the index view.

Also add a boilerplate index template which iterates through the posts and lists them.

Modify routes to point the root action to posts#index in the config/routes.rb file with the following:

1
2
3
4
5

# File: apps/web/config/routes.rb

resources :posts
root to: 'posts#index'

Up and Running

Migrate the database, and run the development server.

1
2

bundle exec hanami db prepare
bundle exec hanami server

Viola! Your blog application is running at http://localhost:2300. You can refer the source code in the Github Repo - https://github.com/awinabi/hanami_blog.

This is in no way complete; edit, update, show and destory actions for blog posts needs to be implemented, but you get the hang of it.

Checkout the documentation for the latest Hanami version 1.2. For a complete tutorial, checkout the official bookshelf application in the Getting Started guide.