Config options

[svallory]

The haml options

:format

Determines the output format. Normally the default is :xhtml, although under Rails 3 it’s :html5, since that’s the Rails 3’s default format. Other options are :html4 and :html5, which are identical to :xhtml except there are no self-closing tags, the XML prolog is ignored and correct DOCTYPEs are generated.

:escape_html

Sets whether or not to escape HTML-sensitive characters in script. If this is true, = behaves like &=; otherwise, it behaves like !=. Note that if this is set, != should be used for yielding to subtemplates and rendering partials. See also Escaping HTML and Unescaping HTML Defaults to false.

:escape_attrs

Sets whether or not to escape HTML-sensitive characters in attributes. If this is true, all HTML-sensitive characters in attributes are escaped. If it’s set to false, no HTML-sensitive characters in attributes are escaped. If it’s set to :once, existing HTML escape sequences are preserved, but other HTML-sensitive characters are escaped. Defaults to :once.

:ugly

If set to true, Haml makes no attempt to properly indent or format the HTML output. This significantly improves rendering performance but makes viewing the source unpleasant. Defaults to true in Rails production mode, and false everywhere else.

:suppress_eval

Whether or not attribute hashes and Ruby scripts designated by = or ~ should be evaluated. If this is true, said scripts are rendered as empty strings. Defaults to false.

:attr_wrapper

The character that should wrap element attributes. This defaults to ' (an apostrophe). Characters of this type within the attributes will be escaped (e.g. by replacing them with ') if the character is an apostrophe or a quotation mark.

:filename

The name of the Haml file being parsed. This is only used as information when exceptions are raised. This is automatically assigned when working through ActionView, so it’s really only useful for the user to assign when dealing with Haml programatically.

:line

The line offset of the Haml template being parsed. This is useful for inline templates, similar to the last argument to Kernel#eval.

:autoclose

A list of tag names that should be automatically self-closed if they have no content. This can also contain regular expressions that match tag names (or any object which responds to #===). Defaults to ['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base'].

:preserve

A list of tag names that should automatically have their newlines preserved using the Haml::Helpers#preserve helper. This means that any content given on the same line as the tag will be preserved. For example, %textarea= "Foo\nBar" compiles to <textarea>Foo Bar</textarea>. Defaults to ['textarea', 'pre']. See also Whitespace Preservation.

:encoding

The encoding to use for the HTML output. Only available in Ruby 1.9 or higher. This can be a string or an Encoding Object. Note that Haml does not automatically re-encode Ruby values; any strings coming from outside the application should be converted before being passed into the Haml template. Defaults to Encoding.default_internal; if that’s not set, defaults to the encoding of the Haml template; if that’s us-ascii, defaults to "utf-8".

Many Ruby database drivers are not yet Ruby 1.9 compatible; in particular, they return strings marked as ASCII-encoded even when those strings contain non-ASCII characters (such as UTF-8). This will cause encoding errors if the Haml encoding isn’t set to "ascii-8bit". To solve this, either call #force_encoding on all the strings returned from the database, set :encoding to "ascii-8bit", or try to get the authors of the database drivers to make them Ruby 1.9 compatible.

HamlPHP Options

For the Avant (1.0) release the proposed options are divided in groups as follows

Must implement

• encoding
• format

Should implement

• escape_html
• escape_attrs
• attr_wrapper
• autoclose
• preserve

Needs discussion

• ugly and supress_eval

The indentation of output in HamlPHP doesn't really seems expensive, but no benchmarks have been made to confirm that. To benchmark this we would have to modify a lot of code.

I don't really see how supress_eval could be useful. If you see where it is handy, please, enlighten me!

• filename and line

These are already used internally, and aren't really configuration options. the filename is required for processing, ahm... the file! And line only makes sense if we add some way to inline templates.

Thoughts? Please, share them!