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.

Prior to Hanami 3.x.x, exposures would be automatically decorated with parts. With 3.x.x and higher, you must specify which exposures you want decorated with parts by passing decorate: true to your exposure.

The following sections detail how you can use exposures.

Every view has a rendering which is especially useful when you want access to the context since the context isn’t directly available by default. Example:

Use of private is important because you don’t want to expose your rendering to your templates as this information should be used to only enhance your exposures. Once you have access to the context, then you can make use of routes, settings, and everything documented in the Contexts section.

The rendering is also useful when testing parts, scopes, and other objects. Here’s how to obtain a rendering:

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

With the above, a custom format and context is supplied. Knowing this can come in handy when needing 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.

All views can be called with the following keyword attributes:

Knowing the above means you can modify default behavior. Example:

The above allows your views to never use a layout when the format is JSON because you don’t need layouts when rendering JSON output. Otherwise, you can fallback to default behavior.

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 by inspecting 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.

When using your own dependencies, contexts are quick to test since you can setup your specs to inject spies as you like. The situation gets more complicated when wanting to simulate an HTTP request for use within your actions. Example:

Alternatively, you can use Rack to create a mock environment object if you need additional support. Example:

If you don’t provide a request object, you’ll get the following error:

This stems from the fact that Hanami will mutate the view layer upon boot via the hanami/extensions/view/context.rb extension. This is hard to simulate when needing isolated specs for testing purposes. This becomes even more complicated when using the view layer outside of Hanami and later wanting to include your custom views, via a gem, into your Hanami app as noted in this issue.

When implementing parts, adhere to 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.

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 to your partial. Example: render "relative/path/to/partial". Also, as mentioned, in the Guidelines, you should avoid rendering partials as they make maintaining your parts much more complicated.

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:

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 implementing scopes, adhere to 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.

When building a scope, you have immediate access to the locals. For example, consider the following keyword arguments that are passed into this demo scope:

Within your scope, you have immediate access to the label and name variables. You can also fetch the values by from the locals object itself:

Use of locals gives you a powerful way in which to provide a fallback value when keys are missing. This also allows the keys passed to your scope to be optional.

Scopes have access to the context via the context object. This means you can access all objects when first discussing Contexts.

There are times, when implementing a scope, when you need access to the current request which. The problem is that Hanami doesn’t make this automatically available to you for testing purposes. Instead, you’ll get the following error in your tests:

Using RSpec, here’s how to setup your scope so it has a request for testing purposes:

The difference with this setup, versus what is described in Tests, is you need to:

This allows you to avoid the Hanami::ComponentLoadError error and test your scope as used by your action.

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 ever need to explicitly render a partial. Example:

In some cases, when you’d like to render a default partial, you can do this by specifying the default path in your render method then sending up to super. Example:

The above will default to templates/shared/_form.html.erb unless you pass 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 also can’t render a partial using HTML helper methods outside of Hanami (i.e. standalone) or you’ll get a dasherize-related stack dump. To avoid this, stick with basic HTML tags.

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 used within a Hanami application:

Implementation

Spec

To simplify spec setup, use the view rendering of your main view. This means if your Hanami application is called Demo, then you can use Demo::View.new.rendering as your rendering which will allow your scope instance to have access to assets, view helpers, and default context.

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

You won’t be able to include helpers directly within your scope due to causing the following exception:

To workaround this issue, you can inject the helpers you need as a dependency instead. See Helpers: Standalone section for details.

When writing specs, you’ll want to provide an anonymous view along with a context (if needed). Example:

The context is optional and can be removed if you are not using the context but the above shows how to wire all of this together if needed.

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:

An important helper to be aware of is the csrf_token helper which is used to prevent Cross-Site Request Forgery (CSRF) attacks when you have sessions enabled for your Hanami Actions. Once enabled, ensure all of your forms are protected by using a hidden input field with the CSRF token being the value. You can use either of the following to protect yourself:

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:

⚠️ 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 added, 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.

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

Scopes can be 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:

Accessing assets via your helpers within views, parts, and scopes will lead to surprising behavior. At the moment, usage is quite buggy, so tread with caution. For example, you might be tempted to use either of the following (both accomplish the same thing):

The problem is this will work in all environments except the test environment due to the following error popping up:

The work around is to use the following solution by importing your assets and using them directly:

This has issues too as you’ll have to write your specs with regular expressions to test the path because, when running locally, you’ll end up with paths without cache busting suffixes (i.e. -6M3WXAC3.svg) but on CI the cache busting suffixes are included which can lead to flakey specs.

There’s another caveat to importing assets like this (i.e. include Deps[:assets]) which is you can’t use asset related helpers in your templates/partials once imported. Example:

You must use HTML tags instead:

The reason is because the asset path won’t be computed when using the tag helpers (image_tag in this case).

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.

The keyword arguments you pass to your template and/or partial are available as a locals hash. For example, let’s say you passed in name and email to your person partial as follows:

This means, within your _person.html.erb partial, you’d have access to the label and name either directly as variables or via the locals hash:

In most cases, you’ll want to directly access the local variables but knowing you have a locals hash means you can provide safe fallbacks when some keywords are missing or optional. Example:

This makes for an elegant way to provide a fallback (default) value when keys are missing.

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.

Errors can be difficult to debug since Hanami doesn’t always have the best error handling. One situation that can pop is when you forget to add a closing quote when rendering a partial. Example:

If you miss a closing (or starting) quote, like this, then you can end up with the following syntax error:

While quite confusing, the stack dump should point you to the line in your code where there error is. So ignore the error message, fix the line, and you’ll be good-to-go.

When using slices, it’s handy for your slice to fallback to your application’s templates when your slice doesn’t have the necessary template. To enable, you only need to configure your slice’s view to add the relative path to the application’s templates like so:

The above will allow you to reference templates and partials in your application which your slice doesn’t have in order to reduce duplication. This isn’t full proof because if your application’s templates use assets, your slice won’t be able to find them so your mileage may vary.