Exposures allow the passing of values — either via injected dependencies or inputs upon construction — from the view to the templates. Exposures are meant for exposing data only, not behavior. For example, routes can be exposed as follows (using a block as default):

Exposures can have explicit defaults (but use a block if you need dynamic content):

Defaults can be taken a step further by defining keyword parameters:

Exposures can use a specific part via the :as keyword:

Exposures can be used within your actions so you can supply custom data as keyword arguments to your view when rendered by the action:

An exposure can depend on another by making the dependent exposure a positional argument:

Exposures can be private which is handy when you need building blocks — not needed by the template — which are great for use in complex exposures:

By default, exposures are only available to the template but can be made available to the layout as well by using layout: true:

Exposures are decorated by parts but this can be disabled, via decorate: false, since this allows you to use a primitive which has no extra behavior:

Every view has a rendering, which is not something you’d use much in your application, but very useful when used for testing purposes especially when testing parts, scopes, and other objects. Here’s how to obtain a rendering:

A rendering can take additional arguments which, when supplied, override the defaults as provided via your view:

With the above, I supplied a custom format and context. Knowing this can come in handy when needing to supply different formats and contexts when testing your parts, scopes, and other objects. Keep this in mind when learning more about renderings later in this article.

Views are convenient to use outside of HTTP requests/responses which simplifies debugging and testing. For example — since every view is a registered dependency — you can access a view instance via the application container as follows:

The above would render the following output (truncated for brevity):

You can take this a step further. In this case, I inspect the view’s locals:

Use of config.paths, for the moment, has set and forget behavior because you can’t append paths without extra effort. To do this, you need to create a Hanami::View::Path object which can be appended to your path. Like so:

The above is necessary because only view paths are allowed at the moment. I point this out because knowing how to append to an existing path — especially when using a slice — allows you to provide fallback behavior for missing templates, parts, etc.

Template engine detection happens automatically based on format (i.e. .erb, etc.) so you only need to change this if you need a custom engine. That said, if you don’t customize config.renderer_engine_mapping, you’ll end up with Hanami::View::ERB::Template as your engine which provides the following functionality:

Should Hanami::View::ERB::Template not be desired, you could use config.renderer_engine_mapping = {erb: ::Tilt::ERBTemplate} which gives you basic Tilt ERB functionality.

Lastly, multiple custom engines can be defined depending on your needs. In the original configuration example, I use {liquid: ::Tilt::LiquidTemplate} where Liquid is the format and Tilt::LiquidTemplate is the engine. All custom engines can be mapped using Tilt Template documentation.

By default, the renderer options are: {default_encoding: "utf-8"}. Anything you define, in addition to the defaults, will be merged with the defaults.

For more on the above, I’ll refer you to the Dry View Configuration documentation.

You can inject dependencies, like you would with any Ruby object, by using a custom constructor. Example:

The double splats (**) are important because you need to pass all keyword arguments up to the superclass to complete initialization. Otherwise, you are free to define additional parameters for your method signature as needed.

You can render partials within a part by using the #render method but, unlike when working within a template, you can’t use symbols to identify your partial. This means you must pass the full relative path of the template. Example: render "my/relative/path/to/partial".

Use the decorate macro to memoize expensive operations and ensure they only run once when rendered. This is because a part instance only lives for the duration of a single rendering. For example, the following decorates a collection of commits associated with a tag:

Use of decorate serves another purpose as it also allows you to decorate associations. In the above example, the Tag has a collection of Commit objects. Due to using decorate :commits, this means you can use the following in your templates/partials:

⚠️ Decorations are only automatically applied for your templates and partials. When writing specs, you’ll need to manually decorate any/all records you need for testing purposes. This is as simple as mapping over your records and turning them into a collection of parts you can test. Example:

Using the Hemo application, for example, here is a task part which provides additional information when rendered by the view:

The corresponding spec is:

Other than a tiny bit of setup where I use a user and task in-memory ROM factory, I then pass the task record as a value to the part and that’s it.

While the above is straightforward, you’ll need to pass in your view as the rendering argument to your part when using helpers. Here’s a simplified example of the above with implementation and spec:

Notice two important changes are applied in the above:

There are a couple of ways to setup your RSpec specs when testing parts. As shown above, when testing parts within a Hanami application, this is as simple as defining your subject and supplying the value (in this case a task) that your part wraps:

If working within a slice, you’ll need a few lines of extra code to setup your view. Example:

All the above is doing is defining an anonymous view, for testing purposes, so we can create our part with the view’s rendering.

When working with parts outside of a Hanami application, like in a pure Ruby project or a gem, you’ll need a similar setup when working in slices. Here’s an example from the Milestoner gem:

The above isn’t much different than working in a Hanami application, only that we need to construct our own view for testing purposes that uses a valid path to where your templates are located. Then, when creating an instance of our part, we pass in the view’s rendering like when working in a slice.

When using parts, be conscious of the following:

You can inject dependencies, like you would with any Ruby object, by using a custom constructor. Example:

The double splats (**) are important because you need to pass all keyword arguments up to the superclass to complete initialization. Otherwise, you are free to define additional parameters for your method signature as needed.

Scopes have access to the context via the context object. This means you can access objects like the inflector: context.inflector.humanize "A demo".

Rendering a scope has a lot of uses. By default, whenever your message #render, the scope will look for the partial of the same name. Example (assuming ERB is configured as your template engine):

Even better, your scope will dynamically load the partial of the same name relative to where the scope is used. For example, let’s say you have the following structure:

If you message scope(:form).render within the show template of both books and authors, the corresponding _form partial relative to the show template will used. This gives you a lot of reusability since the same scope can be used with different partials of the same name.

The #render method takes a path argument should you never need to explicitly render a partial. Example:

In some cases, when you’d like a custom default, you can do this by specifying the default path in your render method and send to super. Example:

The above will always default to templates/shared/_form.html.erb unless you pass as an argument to #render. Super handy for shared partials or default behavior in general.

Blocks are supported which means you can pass a block of content to #render when wanting to yield the result via your partial. Example:

The above allows you to wrap your scope around a chunk of content that might have helpers or other dynamic content you wish to yield to your partial.

⚠️ You might be tempted to message your scope’s methods while inside the block of your scope when used within a template but this isn’t possible and will result in a method error.

You can render partials within your scopes via the #render method but, in general, you should shy away from heavy use by preferring to be explicit instead. Example:

Being explicit improves readability because you can see the scope being used and the corresponding partial being scoped. That said, there is an interesting use case where rendering within your scope is valuable by using the #call method to deal with logic that requires you to render a partial based on whether you have or don’t have content. Here’s an example pulled from the Milestoner gem:

What’s nice about the above is the logic for determining if you have an array of users or none at all is nicely encapsulated in the scope so you don’t have to deal with any logic in your partial. Instead, you can use the scope as follows:

This simple one-liner will render a list of users or a paragraph stating there are no users. Now you can reuse this logic across multiple partials that need to render different kinds of users. Finally, this allows you to encapsulate and easily test this logic in one place.

Here’s an example of an implementation and corresponding spec:

Implementation

Spec

When used outside of Hanami, the default folder structure is not auto-detected so you must be explicit which namespace to use when configuring your view:

You won’t be able to include helpers directly within your scope. Example:

As you can see, the above will result in an exception. To workaround this bug, you can inject the helpers you need as dependency instead. See Helpers: Standalone section for details.

Hanami comes with several default helpers but documentation is spotty. Some documentation can be found via the official guides and others can be found in the repository. Here’s the full list:

⚠️ Due to helpers being available everywhere — and this includes built-in Hanami helpers like the asset helpers — you’ll need to be careful to not define a helper which is the same name as a reserved word within the Hanami View ecosystem. You can workaround this limitation by using locals[:key] to pluck out the value you need but will make your code tedious to maintain.

Example:

While helpers are available everywhere, including them within your views, parts, scopes, etc is not a good idea because mixing helpers within your views and parts prevents them from being reused in different formats (i.e. html, rss, json, etc.) — as emphasized earlier — and you don’t want to miss out on that flexibility.

By default, any slices/<name>/views/helper.rb will be automatically included for use. Example:

To add additional helpers, you could use this structure within your slice:

For each new helper module you add, you’ll need to manually include them as you would any Ruby module. There is nothing special about helpers, they are normal Ruby modules so, once included, ensure you don’t have method name conflicts with other modules.

⚠️ Helpers have access to the routes method so ensure you don’t override this.

Use of content_for is is not a helper but deserves attention because it acts like a helper by allowing you to define content in a template for use in another template later. This is powerful when combined with your layout which allows your template to reach up into the layout and customize as necessary. This behavior is very similar to behavior found in other frameworks. Example:

The context can be accessed via context. For example, you could obtain the flash by asking for it: context.flash.

Scopes can used via the scope method. For example, the following builds and renders a scope:

With the above, we are able to use the Shared::Flash scope, provide a custom message and kind, in order to render the _flash partial.

Helpers have the ability to render partials via the render method. Example:

When used outside of Hanami, you’ll not have automatic access to any of the helpers. One way to get around this is to create the following module for injection within any object that needs them. Example:

The above allows you to inject the default helpers while also providing a namespace for them. Example:

Now, when using the above, you can access all helpers via the helpers object which is similar in nature to how you would use helpers within a native Hanami application. This also gives you a convenient way in which to add custom helpers to the Demo::Views::Helpers object if desired.

You can escape multiple ways:

None of the above are recommended because of security vulnerabilities and general Ruby Antipatterns. Instead, you should use the Sanitize and/or Loofah gems to ensure all output is properly sanitized.