haml-rails

To use Haml as your templating engine in a Rails application, add the haml-rails gem to your Gemfile. This automatically configures Rails to use Haml for generated resources, views, and mailers, and ensures Haml templates are respected by the view template cache digestor.

gem "haml-rails"

You can convert your existing ERB application layout (typically app/views/layouts/application.html.erb) to Haml using the haml:application_layout generator.

Prerequisite: This command requires the html2haml gem. You must install it locally before running the generator:

gem install html2haml

Steps:

1. Run the conversion command: rails generate haml:application_layout convert
2. After successful conversion, manually delete the original app/views/layouts/application.html.erb file to ensure Rails uses the new .haml version.

$ rails generate haml:application_layout convert

To bulk-convert all .erb views in your application to .haml, use the rails haml:erb2haml command.

Behavior:

• If .haml files already exist for certain .erb files, the task will prompt you to either replace them or leave them in place.
• After conversion, the task will ask if you want to delete the original .erb files.

Automation: If you are running this in a script and want to avoid interactive prompts, use the HAML_RAILS_DELETE_ERB environment variable:

• HAML_RAILS_DELETE_ERB=true: Deletes the original .erb files automatically.
• HAML_RAILS_DELETE_ERB=false: Keeps the .erb files and skips the prompt.

$ rails haml:erb2haml

# To automate deletion of ERB files:
$ HAML_RAILS_DELETE_ERB=true rails haml:erb2haml

For Rails versions 4.2 and newer, haml-rails enables source annotations. This allows you to use special comments in your Haml files that Rails can track to provide better error reporting and source mapping.

To use source annotations, follow the pattern of using a comment tag that the extension recognizes. The extension is configured to look for the following pattern:

-# tag: message

When using haml-rails, the standard Rails controller generator is overridden to use Haml templates instead of ERB. When you run the Rails controller generator, the resulting view files will be created with the .haml extension and use Haml syntax.

rails generate controller MyController

When haml-rails is installed in a Rails application, it overrides the default Rails scaffold generator to use Haml templates instead of ERB. This allows you to generate resource controllers, models, and views (index, edit, show, new, and the _form partial) directly in .html.haml format.

The generator supports standard Rails scaffold arguments (field:type) and respects the current Rails version to select appropriate template structures (e.g., handling Rails 7+ specific partial patterns).

rails generate scaffold User name:string email:string

The ApplicationLayoutGenerator is a Rails generator designed to automate the conversion of your Rails application's main layout file from ERB to Haml.

It performs the following steps:

1. Locates the existing app/views/layouts/application.html.erb file.
2. Uses the html2haml command-line tool to convert the content.
3. Creates a new app/views/layouts/application.html.haml file.

Requirements:

• The html2haml executable must be available in your system's PATH.

Note: After a successful conversion, you must manually remove the original ERB file (app/views/layouts/application.html.erb) to prevent Rails from potentially using the wrong template.

# Run the generator via the Rails CLI
rails generate haml:application_layout

When using haml-rails, the standard Rails mailer generator is overridden to use Haml instead of ERB for mailer templates. When you run the Rails mailer generator, it will automatically create .haml files for your mailer views instead of .erb files.

rails generate mailer UserMailer

The current version of haml-rails requires Rails 5.1 or later. If you are working on a legacy application, use the following version constraints in your Gemfile:

• Rails 4: Use haml-rails version ~> 1.0.0.
• Rails 3: Use haml-rails version ~> 0.4.0.

# For Rails 4
gem "haml-rails", "~> 1.0.0"

# For Rails 3
gem "haml-rails", "~> 0.4.0"

The Haml::Generators::AuthenticationGenerator is a Rails generator that creates authentication-related view templates using Haml instead of ERB. It generates the following files:

• app/views/passwords/new.html.haml
• app/views/passwords/edit.html.haml
• app/views/sessions/new.html.haml

This generator inherits from the standard Rails Erb::Generators::AuthenticationGenerator, meaning it is intended to be used within a Rails application context where authentication scaffolding is being generated.

# Usage within a Rails environment
rails generate haml:authentication