V1.3: Basic Usage


In the previous section we generated a view. Let’s use it.

Default Rendering

First, we edit the corresponding template:

# apps/web/templates/dashboard/index.html.erb
<h1>Dashboard</h1>

By visiting /dashboard, we should see <h1>Dashboard</h1> in our browser.

Again we should look at the naming convention. Our view is Web::Views::Dashboard::Index, while the file name of the template is web/templates/dashboard/index.

For a given view Web::Views::Dashboard::Index, the corresponding template MUST be available at apps/web/templates/dashboard/index.html.erb.

Context

While rendering a template, variable lookups requested by the template go to a view context.

# apps/web/templates/dashboard/index.html.erb
<h1><%= title %></h1>

If we amend our template by adding an interpolated variable, the view is responsible for providing it.

# apps/web/views/dashboard/index.rb
module Web
  module Views
    module Dashboard
      class Index
        include Web::View

        def title
          'Dashboard'
        end
      end
    end
  end
end

The view now responds to #title by implementing it as a concrete method. We still see <h1>Dashboard</h1> when we visit /dashboard.

Exposures

There is another source for our context: exposures. They are a payload that comes from the action.

# apps/web/controllers/dashboard/index.rb
module Web
  module Controllers
    module Dashboard
      class Index
        include Web::Action
        expose :title

        def call(params)
          @title = 'Dashboard'
        end
      end
    end
  end
end

We can remove #title from our view, to get the same output when accessing /dashboard.

# apps/web/views/dashboard/index.rb
module Web
  module Views
    module Dashboard
      class Index
        include Web::View
      end
    end
  end
end

Rendering context for a template is made of view methods and exposures.

The objects exposed in the controller action are available in the corresponding view. So the values can also be modified, wrapped or reused in some other way. Assuming that the title is exposed in the action, it can be accessed as follows:

# apps/web/views/dashboard/index.rb
module Web
  module Views
    module Dashboard
      class Index
        include Web::View

        def full_title
          "The title: " + title
         end
      end
    end
  end
end

Custom Rendering

Hanami performs rendering by calling #render on a view and it expects a string in return. The benefit of an object-oriented approach is the ability to easily diverge from default behavior.

We can override that method to define a custom rendering policy.

# apps/web/views/dashboard/index.rb
module Web
  module Views
    module Dashboard
      class Index
        include Web::View

        def render
          raw %(<h1>Dashboard</h1>)
        end
      end
    end
  end
end

Once again our output is still the same, but the template isn’t used at all.

If a view overrides #render the output MUST be a string that will be the body of the response. The template isn't used and it can be deleted.

Bypass Rendering

If an action assigns the body of the response with #body=, the rendering of the view is bypassed.