haml--haml/REFERENCE.md

Hamlit

Basically Hamlit is the same as Haml. See Haml's tutorial if you are not familiar with Haml's syntax.

REFERENCE - Haml Documentation

Supported features

See Haml's reference for full features in original implementation.

• Using Haml
  • Rails XSS Protection
  • Ruby Module
  • Options
  • Encodings
• Plain Text
  • Escaping: \
• HTML Elements
  • Element Name: %
  • Attributes: `
    • :class and :id Attributes
    • HTML-style Attributes: ()
    • Ruby 1.9-style Hashes
    • Attribute Methods
    • Boolean Attributes
    • HTML5 Custom Data Attributes
  • Class and ID: . and #
    • Implicit Div Elements
  • Empty (void) Tags: /
  • Whitespace Removal: > and <
  • Object Reference: []
• Doctype: !!!
• Comments
  • HTML Comments: /
    • Conditional Comments: /[]
  • Haml Comments: -#
• Ruby Evaluation
  • Inserting Ruby: =
  • Running Ruby: -
    • Ruby Blocks
  • Whitespace Preservation: ~
  • Ruby Interpolation: #{}
  • Escaping HTML: &=
  • Unescaping HTML: !=
• Filters
  • :cdata
  • :coffee
  • :css
  • :erb
  • :escaped
  • :javascript
  • :less
  • :markdown
  • :maruku
  • :plain
  • :preserve
  • :ruby
    • haml_io API is not supported. Use hamlit-haml_io.gem if you need.
  • :sass
  • :scss
  • :textile
  • Custom Filters
• Helper Methods
  • preserve
  • surround
  • precede
  • succeed
• Multiline: |
• Whitespace Preservation
• Helpers

Limitations

No Haml buffer

Hamlit uses Array as buffer for performance. So you can't touch Haml::Buffer from template when using Hamlit.

Haml helpers are still in development

At the same time, because some methods in Haml::Helpers require Haml::Buffer, they are not supported now. But some helpers are supported on Rails. Some of not-implemented methods are planned to be supported.

Limited attributes hyphenation

In Haml, %a{ foo: { bar: 'baz' } } is rendered as <a foo-bar='baz'></a>, whatever foo is. In Hamlit, this feature is supported only for aria and data attribute. Hamlit renders %a{ data: { foo: 'bar' } } as <a data-foo='bar'></a> because it's data attribute. This design allows us to reduce work on runtime and the idea is originally in Faml.

Limited boolean attributes

In Haml, %a{ foo: false } is rendered as <a></a>, whatever foo is. In Hamlit, this feature is supported for only boolean attributes, which are defined by http://www.w3.org/TR/xhtml1/guidelines.html or https://html.spec.whatwg.org/. The list is the same as ActionView::Helpers::TagHelper::BOOLEAN_ATTRIBUTES. In addition, aria-* and data-* is also regarded as boolean.

Since foo is not boolean attribute, %a{ foo: false } is rendered as <a foo='false'></a> This is the same behavior as Rails helpers. Also for %a{ foo: nil }, Hamlit does not remove non-boolean attributes and render <a foo=''></a> (foo is not removed). This design allows us to reduce string concatenation and is the only difference between Faml and Hamlit.

You may be also interested in hamlit/hamlit-boolean_attributes.

5 Types of Attributes

Haml has 3 types of attributes: id, class and others. In addition, Hamlit treats aria/data and boolean attributes specially. So there are 5 types of attributes in Hamlit.

id attribute

Almost the same behavior as Haml, except no hyphenation and boolean support. Arrays are flattened, falsey values are removed (but attribute itself is not removed) and merging multiple ids results in concatenation by "_".

# Input
#foo{ id: 'bar' }
%div{ id: %w[foo bar] }
%div{ id: ['foo', false, ['bar', nil]] }
%div{ id: false }

# Output
<div id='foo_bar'></div>
<div id='foo_bar'></div>
<div id='foo_bar'></div>
<div id=''></div>

class attribute

Almost the same behavior as Haml, except no hyphenation and boolean support. Arrays are flattened, falsey values are removed (but attribute itself is not removed) and merging multiple classes results in unique alphabetical sort.

# Input
.d.a(class='b c'){ class: 'c a' }
%div{ class: 'd c b a' }
%div{ class: ['d', nil, 'c', [false, 'b', 'a']] }
%div{ class: false }

# Output
<div class='a b c d'></div>
<div class='d c b a'></div>
<div class='d c b a'></div>
<div class=''></div>

aria / data attribute

Completely compatible with Haml, hyphenation and boolean are supported.

# Input
%div{ data: { disabled: true } }
%div{ data: { foo: 'bar' } }

# Output
<div data-disabled></div>
<div data-foo='bar'></div>

aria attribute works in the same way as data attribute.

boolean attributes

No hyphenation but complete boolean support.

# Input
%div{ disabled: 'foo' }
%div{ disabled: true }
%div{ disabled: false }

# Output
<div disabled='foo'></div>
<div disabled></div>
<div></div>

List of boolean attributes is:

disabled readonly multiple checked autobuffer autoplay controls loop selected hidden scoped async
defer reversed ismap seamless muted required autofocus novalidate formnovalidate open pubdate
itemscope allowfullscreen default inert sortable truespeed typemustmatch

If you want to customize the list of boolean attributes, you can use hamlit/hamlit-boolean_attributes.

"aria-*" and "data-*" are also regarded as boolean.

other attributes

No hyphenation and boolean support. false is rendered as "false" (like Rails helpers).

# Input
%input{ value: true }
%input{ value: false }

# Output
<input value='true'>
<input value='false'>

Engine options

Option	Default	Feature
escape_html	true	HTML-escape for Ruby script and interpolation. This is false in Haml.
escape_attrs	true	HTML-escape for Html attributes.
format	:html	You can set :xhtml to change boolean attribute's format.
attr_quote	'	You can change attribute's wrapper to " or something.

Set options for Rails

# config/initializers/hamlit.rb or somewhere
Hamlit::RailsTemplate.set_options attr_quote: '"'

Set options for Sinatra

set :haml, { attr_quote: '"' }

Ruby module

Hamlit::Template is a module registered to Tilt. You can use it like:

Hamlit::Template.new { "%strong Yay for HAML!" }.render

Creating a custom filter

Currently it doesn't have filter registering interface compatible with Haml. But you can easily define and register a filter using Tilt like this.

module Hamlit
  class Filters
    class Es6 < TiltBase
      def compile(node)
        # branch with `@format` here if you want
        compile_html(node)
      end

      private

      def compile_html(node)
        temple = [:multi]
        temple << [:static, "<script>\n"]
        temple << compile_with_tilt(node, 'es6', indent_width: 2)
        temple << [:static, "\n</script>"]
        temple
      end
    end

    register :es6, Es6
  end
end

After requiring the script, you can do:

:es6
  const a = 1;

and it's rendered as:

<script>
  "use strict";

  var a = 1;
</script>