reference.haml

%h1#reference
  Reference

%h2#base
  Base

%h3#base-compile
  %code Handlebars.compile(template, options)

.contents
  .bullet
    .description
      Compiles a template so it can be executed immediately.

    :javascript
      var template = Handlebars.compile('{{foo}}');
      template({});

    .notes
      Supports a variety of options that alter how the template executes.
      %UL
        %li
          <code>data</code>: Set to false to disable <code>@data</code> tracking.
        %li
          <code>compat</code>: Set to true to enable recursive field lookup.
        %li
          <code>knownHelpers</code>: Hash containing list of helpers that are known to
          exist (truthy) at template execution time. Passing this allows
          the compiler to optimize a number of cases.
          Builtin helpers are automatically included in this list and may be omitted by setting
          that value to <code>false</code>.
        %li
          <code>knownHelpersOnly</code>: Set to true to allow further optimzations
          based on the known helpers list.
        %li
          <code>noEscape</code>: Set to true to not HTML escape any content.
        %li
          <code>strict</code>: Run in strict mode. In this mode, templates will throw rather than silently ignore missing fields. This has the side effect of disabling inverse operations such as <code>{{^foo}}{{/foo}}</code> unless fields are explicitly included in the source object.
        %li
          <code>assumeObjects</code>: Removes object existence checks when traversing paths. This is a subset of <code>strict</code> mode that generates optimized templates when the data inputs are known to be safe.
        %li
          <code>preventIndent</code>: By default, an indented partial-call causes the output of the
          whole partial being indented by the same amount. This can lead to unexpected behavior when the
          partial writes <code>pre</code>-tags.
          Setting this option to <code>true</code> will disable the auto-indent feature.
        %li
          <code>ignoreStandalone</code>: Disables standalone tag removal when set to <code>true</code>. When set, blocks and partials that are on their own line will not remove the whitespace on that line.
        %li
          <code>explicitPartialContext</code>: Disables implicit context for partials. When enabled, partials that are not passed a context value will execute against an empty object.

%h3#base-precompile
  %code Handlebars.precompile(template, options)

.contents
  .bullet
    .description
      Precompiles a given template so it can be sent to the client and executed without
      compilation.

    :javascript
      var templateSpec = Handlebars.precompile('{{foo}}');

    .notes
      Supports all of the same options parameters as the <code>Handlebars.compile</code> method. Additionally may pass:
      %ul
        %li
          <code>srcName</code>: Passed to generate the source map for the input file. When run in this manner, the return structure is <code>{code, map}</code> with <code>code</code> containing the template definition and <code>map</code> containing the source map.
        %li
          <code>destName</code>: Optional parameter used in conjunction with <code>srcName</code> to provide a destination file name when generating source maps.

%h3#base-template
  %code Handlebars.template(templateSpec)

.contents
  .bullet
    .description
      Sets up a template that was precompiled with <code>Handlebars.precompile</code>.

    :javascript
      var template = Handlebars.template(templateSpec);
      template({});


%h3#base-registerPartial
  %code Handlebars.registerPartial(name, partial)

.contents
  .bullet
    .description
      Registers partials accessible by any template in the environment.

    :javascript
      Handlebars.registerPartial('foo', partial);

    .notes
      Also supports registering multiple partials at once.

    :javascript
      Handlebars.registerPartial({
        foo: partial,
        bar: partial
      });

    .notes
      If loading the whole library, the partials may be string values which will be
      compiled on demand. If only loading the runtime, the partials must be a precompiled
      template that has been set up properly using the <code>Handlebars.template</code> method.


%h3#base-unregisterPartial
  %code Handlebars.unregisterPartial(name)

.contents
  .bullet
    .description
      Unregisters a previously registered partial.

    :javascript
      Handlebars.unregisterPartial('foo');


%h3#base-registerHelper
  %code Handlebars.registerHelper(name, helper)

.contents
  .bullet
    .description
      Registers helpers accessible by any template in the environment.

    :javascript
      Handlebars.registerHelper('foo', function() {
      });

    .notes
      Also supports registering multiple helpers at once.

    :javascript
      Handlebars.registerHelper({
        foo: function() {
        },
        bar: function() {
        }
      });


%h3#base-unregisterHelper
  %code Handlebars.unregisterHelper(name)

.contents
  .bullet
    .description
      Unregisters a previously registered helper.

    :javascript
      Handlebars.unregisterHelper('foo');


%h3#base-registerDecorator
  %code Handlebars.registerDecorator(name, helper)

.contents
  .bullet
    .description
      Registers a decorator accessible by any template in the environment.

    :javascript
      Handlebars.registerDecorator('foo', function() {
      });

    .notes
      Also supports registering multiple decorators at once.

    :javascript
      Handlebars.registerDecorator({
        foo: function() {
        },
        bar: function() {
        }
      });


%h3#base-unregisterDecorator
  %code Handlebars.unregisterDecorator(name)

.contents
  .bullet
    .description
      Unregisters a previously registered decorator.

    :javascript
      Handlebars.unregisterDecorator('foo');


%h3#base-SafeString
  %code Handlebars.SafeString(string)

.contents
  .bullet
    .description
      Prevents <code>string</code> from being escaped when the template is rendered.

    :javascript
      new Handlebars.SafeString('<div>HTML Content!</div>')

    .notes
      When constructing the string that will be marked as safe, any external content should be
      properly escaped using the <code>Handlebars.escapeExpression</code> method to avoid potential
      security concerns.


%h3#base-escapeExpression
  %code Handlebars.escapeExpression(string)

.contents
  .bullet
    .description
      HTML escapes the passed string, making it safe for rendering as text within HTML content.

    :javascript
      Handlebars.Utils.escapeExpression(string)

    .notes
      Replaces <code>&</code>, <code><</code>, <code>></code>, <code>"</code>, <code>'</code>,
      <code>`</code>, <code>=</code> with the HTML entity equivalent value for string values. <code>SafeString</code>
      values are left untouched.
    .notes
      The output of all expressions except for triple-braced expressions are passed through this
      method. Helpers should also use this method when returning HTML content via a
      <code>SafeString</code> instance, to prevent possible code injection.
    .notes
      This method is aliased at <code>Handlebars.Utils.escapeExpression</code>.


%h3#base-createFrame
  %code Handlebars.createFrame(data)

.contents
  .bullet
    .description
      Used by block helpers to create child data objects.

    :javascript
      if (options.data) {
        var data = Handlebars.createFrame(options.data);
        data.foo = 'bar';
        options.data = data;
      }

    .notes
      Helpers that modify the data state should create a new frame when doing so, to isolate
      themselves and avoid corrupting the state of any parents. Generally, only one frame needs
      to be created per helper execution. For example, the <code>each</code> iterator creates a single frame
      which is reused for all child execution.


%h3#base-create
  %code Handlebars.create()

.contents
  .bullet
    .description
      Creates an isolated Handlebars environment.

    :javascript
      var OtherHandlebars = Handlebars.create();

    .notes
      Each environment has its own helpers and partials. This is only necessary for use cases
      that demand distinct helpers or partials. Most use cases can use the root
      <code>Handlebars</code> environment directly.
    .notes
      Templates created for a given environment are bound to that environment. This means that
      templates that need to run in multiple environments will need to be recompiled or
      reconstructed via <code>Handlebars.template</code> for each environment. This applies to
      partials as well.


%h3#base-noConflict
  %code Handlebars.noConflict()

.contents
  .bullet
    .description
      Removes this Handlebars instance from the global namespace, restoring the global `Handlebars` variable to its
      previous value.

    :javascript
      var myHandlebars = Handlebars.noConflict();

    .notes
      This allows for distinct versions of the library to be used simultaneously without
      concern for version conflicts.


%h3#base-log
  %code Handlebars.log(level, message)

.contents
  .bullet
    .description
      Logger used by the <code>log</code> helper.
    .notes
      May be overriden if desired.

%h2#hutils
  Utilities

.contents
  .bullet
    .description
      Handlebars offers a variety of utility methods that are exposed through
      the <code>Handlebars.Utils</code> object.

%h3#utils-isEmpty
  %code Handlebars.Utils.isEmpty(value)

.contents
  .bullet
    .description
      Determines if a given value is empty.

    :javascript
      Handlebars.Utils.isEmpty(value)

    .notes
      This is used by the built-in <code>if</code> and <code>with</code> helpers to control their
      execution flow. The Handlebars definition of empty is any of:

      %ul
        %li
          Array with length 0
        %li
          falsy values other than 0

      This is intended to match the <a href="http://mustache.github.io/mustache.5.html#Sections">Mustache behavior</a>.

%h3#utils-extend
  %code Handlebars.Utils.extend(obj, value)

.contents
  .bullet
    .description
      Simple utility method to augment <code>obj</code> with all keys defined on <code>value</code>.

    :javascript
      Handlebars.Utils.extend(foo, {bar: true})
    .notes
      Will set the key <code>bar</code> on object <code>foo</code> with the value <code>true</code>.

%h3#utils-toString
  %code Handlebars.Utils.toString(obj)

.contents
  .bullet
    .description
      Generic <code>toString</code> method.

%h3#utils-isArray
  %code Handlebars.Utils.isArray(obj)

.contents
  .bullet
    .description
      Determines if an object is an array.

%h3#utils-isFunction
  %code Handlebars.Utils.isFunction(obj)

.contents
  .bullet
    .description
      Determines if an object is a function.

%h2#data
  @data Variables

.contents
  .bullet
    .description
      The following <code>@data</code> variables are implemented by Handlebars and its builtin
      helpers.

%h3#data-root
  %code
    @root

.contents
  .bullet
    .description
      Initial context with which the template was executed.

    :html
      {{#each array}}
        {{@root.foo}}
      {{/each}}

    .notes
      Unless explicitly modified, this value is consistent across all portions of the page rendering,
      meaning it can be used within partials where depthed parameters are unable to reference their
      parent templates.

%h3#data-first
  %code
    @first

.contents
  .bullet
    .description
      Set to true by the <code>each</code> helper for the first step of iteration.

    :html
      {{#each array}}
        {{#if @first}}
          First!
        {{/if}}
      {{/each}}

%h3#data-index
  %code
    @index

.contents
  .bullet
    .description
      Zero-based index for the current iteration step. Set by the <code>each</code> helper.

    :html
      {{#each array}}
        {{@index}}
      {{/each}}

%h3#data-key
  %code
    @key

.contents
  .bullet
    .description
      Key name for the current iteration step. Set by the <code>each</code> helper when iterating over objects.

    :html
      {{#each array}}
        {{@key}}
      {{/each}}

%h3#data-last
  %code
    @last

.contents
  .bullet
    .description
      Set to true by the <code>each</code> helper for the last step of iteration.

    :html
      {{#each array}}
        {{#if @last}}
          Last :(
        {{/if}}
      {{/each}}

%h3#data-level
  %code
    @level

.contents
  .bullet
    .description
      Assigned log level.

    :javascript
      template({}, {data: {level: Handlebars.logger.WARN}})
    .notes
      May be set to one of
      %code Handlebars.logger.DEBUG
      ,
      %code Handlebars.logger.INFO
      ,
      %code Handlebars.logger.WARN
      , or
      %code Handlebars.logger.ERROR

    .notes
      When set, the logger will include in its output only messages with a log level of
      <code>Handlebars.logger.level</code> or higher. The default value is <code>Handlebars.logger.ERROR</code>.