Skip to content

Latest commit

 

History

History
268 lines (196 loc) · 5.07 KB

README.md

File metadata and controls

268 lines (196 loc) · 5.07 KB
Raw

Himl

Himl is an HTML-based Indented Markup Language for Ruby.

What's This?

Himl is a yet another template engine for Haml-lovers and non Haml-lovers, deriving HTML validity from Haml and syntax intuitiveness from ERB.

Motivation

Haml is a great template engine that liberates us from annoying HTML bugs. By automatically closing the HTML tags, Haml always produces perfectly structured 100% valid HTML responses. Actually, I've never experienced the HTML closing tag mismatch error over the past 10 years or so, thanks to Haml.

However, the Haml (or Slim or whatever equivalent) syntax is very much different from that of HTML. And to be honest, I still rarely can complete my template markup works without consulting the Haml online reference manual.

Oh, why do we have to learn another markup language syntax where we just want to generate HTML documents? HTML has tags. HTML has indentations. Why can't we just use them?

Syntax

Himl syntax is a hybrid of ERB and Haml. Himl is basically just a kind of ERB. Indeed, Himl documents are compiled to ERB internally, then rendered by the ERB handler.

So, the following Himl template opening and closing a tag will be compiled to exactly the same ERB template.

Himl

<div>
</div>

ERB

<div>
</div>

You can omit closing tags. Then Himl auto-closes them, just like Haml does.

Himl

<div>

ERB

<div>
</div>

For nesting tags, use whitespaces just like you do in the Haml templates.

Himl

<section>
  <div>

ERB

<section>
  <div>
  </div>
</section>

Of course you can include dynamic Ruby code in the ERB way.

Himl

<section>
  <div>
    <%= post.content %>

ERB

<section>
  <div>
    <%= post.content %>
  </div>
</section>

Ruby blocks in the ERB tag can also automatically be closed.

Himl

<ul>
  <%= @users.each do |user| %>
    <li>
      <%= user.name %>

ERB

<ul>
  <%= @users.each do |user| %>
    <li>
      <%= user.name %>
    </li>
  <% end %>
</ul>

Or manually be closed.

Himl

<ul>
  <%= @users.each do |user| %>
    <li>
      <%= user.name %>
  <% end %>

ERB

<ul>
  <%= @users.each do |user| %>
    <li>
      <%= user.name %>
    </li>
  <% end %>
</ul>

You can open and close tags in the same line.

Himl

<section>
  <h1><%= post.title %></h1>

ERB

<section>
  <h1><%= post.title %></h1>
</section>

There's no special syntax for adding HTML attributes to the tags. You see, it's just ERB.

Himl

<section class="container">
  <div class="content">

ERB

<section class="container">
  <div class="content">
  </div>
</section>

More detailed syntax may be covered in the tests.

Document Validations

Himl's strongest advantage is not that you just can reduce the template LOC, but the engine validates the structure of the document and detects some syntax errors. For example, Himl raises SyntaxError while parsing these templates.

Mismatched closing tag

<div>
  hello?
  </div>

Mismatched ERB end expression

  <% if @current_user.admin? %>
    TOP SECRET
<% end %>

Extra ERB end expression

<% @books.each do |book| %>
  <% book.read %>
<% end %>
<% end %>

Example

Following is a comparison of ERB, Haml, and Himl templates that renders similar HTML results (the Haml example is taken from the Haml documentation). You'll notice that Himl consumes the same LOC with the Haml version for expressing the structure of this document, without introducing any new syntax from the ERB version.

ERB Template

<section class="container">
  <h1><%= post.title %></h1>
  <h2><%= post.subtitle %></h2>
  <div class="content">
    <%= post.content %>
  </div>
</section>

Haml Template

%section.container
  %h1= post.title
  %h2= post.subtitle
  .content
    = post.content

Himl Template

<section class="container">
  <h1><%= post.title %></h1>
  <h2><%= post.subtitle %></h2>
  <div class="content">
    <%= post.content %>

Installation

Bundle 'himl' gem to your project.

Usage

The gem contains the Himl template handler for Rails. You need no extra configurations for your Rails app to render *.himl templates.

Runtime Performance

Since every Himl template is converted to ERB, then cached as a Ruby method inside the view frameworks (such as Action View in Rails), Himl runtime performance in production is exactly the same with that of ERB.

Contributing

Pull requests are welcome on GitHub at https://github.com/amatsuda/himl.

Other Template Engines That I Maintain

jb

A faster and simpler and stronger alternative to Jbuilder.

string_template

The ultimate fastest template engine for Rails in the world.

Haml

The one that you may be currently using everyday.

License

The gem is available as open source under the terms of the MIT License.