machty / emblem.js

Emblem.js - Ember-friendly, indented syntax alternative for Handlebars.js

Emblem.js

Emblem.js is an indentation-based templating language that prints Handlebars.js templates. Specifically, it targets Ember.js templates.

Emblem's syntax most closely resembles that of the Slim templating language. Please see the Emblem docs site for a full explanation of the syntax.

Also check out the Embercast on Emblem.js

Installation with Ember-CLI

To use Emblem with Ember-CLI, use the ember-cli-emblem addon.

Handlebars Version Dependencies

As of Emblem 0.5.0, the compiler is really a template printer. Previous versions compiled to Handlebars AST nodes and were forced to target specific versions of Handlebars. The move to printing has eliminated that restriction, and Emblem 0.5.0 should be compatible with any version of Handlebars.

For posterity, here is a history of Emblem and Handelbars compatibility across revisions.

• HTMLBars: Emblem 0.5.0+
• Handlebars 2.0.0: Use Emblem ~0.4.0, or 0.5.0+
• Handlebars 1.0.0: Use Emblem ~0.3.0, or 0.5.0+
• Handlebars <= 1.0.0.rc4: Use Emblem <= 0.2.9, or 0.5.0+

Using Emblem in your application

Previous versions of Emblem have supported a "vanilla" Handlebars mode. The intent was that Ember-specific helpers could be avoided.

Emblem 0.5.0 dropped support for vanilla template compilation, but we would like to bring it back. Please refer to VANILLA_HANDLEBARS.md for more context.

Building Emblem.js

Clone the repo, then run:

yarn install
ember build

To run tests in the browser, run:

ember test --serve

The tests will be available at http://localhost:4200/tests/.

To run tests in Headless Chrome and Node (which is how CI runs), use:

ember test

Reporting Bugs

If you find a bug in Emblem syntax, please try to reproduce it in its simplest form with this JSBin before reporting an issue, which will help me nail down the source of the issue.

Emblem was authored and released by Alex Matchneer (@machty).

The Emblem 0.5.0 release was generously funded by Vestorly. Vestorly is a technology company solving the content marketing problem for individual professionals, small businesses, and the enterprises that support them. Vestorly's user interface is built entirely with Ember.js and modern web technologies. Vestorly is hiring!

emblem.js's Issues

%tagName syntax

App.FunView%ul
li woot

Better yet

each%ul things... Or each things %ul ?

Perhaps allow generalized shorthand for all HTML/CSS attributes in mustaches, eg

App.FunView #someId .woot1 %span

Translates to

view App.FunView elementId="someId" classes="woot1" tagName="span"

Also valid without spaces, though initial space needed for class shorthand else indecipherable from hb path

Rework tagName detection

right now known tagName detect is built into the grammar, but this produces ugly ass inefficient parsing code. Rework into predicate function

Create Grunt plugin

Instructions are at https://github.com/gruntjs/grunt/wiki/Creating-plugins

Support #{} syntax

#{} should act like {{ }} in text nodes

.class#id doesn't work, but #id.class does

http://jsbin.com/egakay/1/edit

Expected BeginStatement or DEDENT but "\uEFEF" found.

I seem to get this error alot? Does it have something to do with how I am tabbing my haml.

Sample haml

.container-fluid.hero.team-banner
  %i.icon-cheer
  %h1 Fan a Team
  %span Choose one or more teams from the list below to get started.

.container
  .row-fluid.team-tab
    %ul.row-fluid.nav.nav-tabs
      %li.active
        %a{"data-toggle" => "tab", :href => "#3a"} 3A
      %li
        %a{"data-toggle" => "tab", :href => "#2a"} 2A
      %li
        %a{"data-toggle" => "tab", :href => "#1a"} 1A
      %li.title Conference:

  .tab-content

    #1a.row-fluid.tab-pane.active
      .row-fluid.division
        .row-fluid.division-header
          Olympic Division
        .row-fluid.division-content
          %table.table.table-bordered
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                = link_to "fan team", "#", :class => "fan-team", :'data-team-id' => 109
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}


    #2a.row-fluid.tab-pane
      .row-fluid.division
        .row-fluid.division-header
          Another Division
        .row-fluid.division-content
          %table.table.table-bordered
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                -#%input{:type => "checkbox", :class => "ez-checkbox"}
                = link_to "fan team", "#", :class => "fan-team", :'data-team-id' => 109
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}
            %tr
              %td.team-logo
                .img-wrapper= image_tag "team-logo.png"
              %td.name Golden St. Elites, Golden Eagles
              %td.location San Mateo, CA
              %td.options
                %input{:type => "checkbox", :class => "ez-checkbox"}
    .text-centered
      %a.btn.btn-large.btn-success{:href => "#"} Start Spinning

. Compiler said: Error: Emblem syntax error, line 7: Expected BeginStatement or DEDENT but "\uEFEF" found.
.row-fluid.team-tab
^

Partials Support

I tossed this together: https://github.com/dbashford/emblem-test

I was expecting the handlebars partial syntax {{>partial}} to compile ok and it seems not to. I can see some tests that make me think this is the right syntax.

Let me know if I've screwed anything up. =)

allow/ignore closing tags

Slim-esque syntax:

<p>
  span This be some text
</p>

produces <p><span>This be some text</span></p>

text blocks break when indenting after newlines

Expects else but gets end of input:

  div
    p
      span Butts
        em fpokasd
        iunw
          paosdk

fix for this will likely fix #9 too

underscore not considered valid hash value

This is raising an error:

div style=tagline_bg_color_style

Integrate with Barber

need a way to precompile, seems like Barber (originally for handlebars) is the way to go.

Syntax enhancement: line-starting % in text block should force element syntax

So should =

Idea:

p Here is some multiline nonsense and a 
  %a href="asd" Link
  to some page. Here is some
  = mustache_content
  and now we're back to text content.

Presently, the cleanest way to write the above-proposed syntax is:

p 
  | Here is some multiline nonsense and a 
  a href="asd" Link
  | to some page. Here is some
  = mustache_content
  | and now we're back to text content.

Thoughts?

How to use this in Yeoman?

syntax for bindAttr class

Since the syntax for {{bindAttr class="foo:bar"}} is class=foo:bar (without quotes), it is not possible to do {{bindAttr class="foo:bar :baz"}}

The current workaround for this is span{bindAttr class="foo:bar :baz"}

Proposal: We could just do class="foo:bar :baz", because the only reason why you want to use class is bindings. There is no reason to write span class="bar" when you can just do span.bar.

Which means if we force static classes to always use the . dot notation, we can always use class=".." as a binding.

Weird comment skipover nesting bug

button wraps label and field

http://jsbin.com/ulegec/15/edit

Support angle bracket html starting a line

p
  <span>Should be able to do this</span>

Text refinements

Inspired by markdown. Need some sugar to help the medicine go down.

p Check out this syntax. 
  Multiple lines, _and then at_ any point you
  can *add an* inline-link via
  markdown notation, e.g.
  [I'm an inline-style link](https://www.google.com)
  perhaps support for linkTo? actions?
  hell yeah [I am a link]{action doTheThing hash="Fudge"}.

class binding syntax

Let's say I want

<div {{bindAttr class="isActive::hidden :content"}}>

the current syntax is to have class=foo:bar:baz for a binding, but that doesn't really scale with multiple classes, no?

If I specify this as

.content class=isActive::hidden

the binding won't be used at all, and I will just have .content class.

Compilation always fails on top level element without a helpful error message

The code in the gist will fail with

Pre compilation failed for: .row.user-profile
  .span3
    .avatar
      img src={image}

while the actual error is on line 36, which should instead be

= linkTo .help-inline "users.index" | back to users

the only way to debug this is randomly removing segments of the code to see which part breaks it.

In-text block mustache shorthand

Posted this before, but got sidetracked by more important issues. We should support

p This is a text block with #{ aBlockHelper | with this text content }. 
p No reason not to support #{ aBlockHelper: span with colon syntax }

@ghempton: look alright?

need a filter for rake pipeline

perhaps the best way to do this is just for rake pipeline web filters. someone wanna help me out with this?

Comments following html/mustache

Presently, comments are only supported on a single line. Should support

.container / This comment doesn't show up
  .row / Nor does this
    p Hello

div.nested: span: em / Comment
  | Hello

per Mike Aski's request

`=` before `else` doesn't work

Boolean `view` arguments seem to get set as strings…

I'm trying to pass boolean arguments to a View, but it seems Emblem is passing them as strings?

App.BackgroundView isStretched=false isDarkened=true

App.BackgroundView = Ember.View.extend
  classNameBindings: ['isStretched', 'isDarkened']

  isStretched: true
  isDarkened: false

<div id="ember335" class="ember-view background-view false true">...</div>

I expected…

<div id="ember335" class="ember-view background-view is-darkened">...</div>

Perhaps I'm missing something?

Slim-esque inline tags

Will there be support for a compact inline tag shortcut denoted by the colon (:)?

In slim,

ul
  li.first
    a href="/a" A link
  li
    a href="/b" B link

can be written more succintly as

ul
  li.first: a href="/a" A link
  li: a href="/b" B link

A lot of common patterns fit into this syntax: li: a, nav: ul, a: img, etc. They all belong to the family of items having multiple semantics: a link that is a list item, a list that is a navigation, an image that is a link, etc.

multi-line text line limited to 2

Remove dependency on github project

Unfortunately if attempting to install Emblem on a machine (at least Windows) that does not have git results in a failed installation.

  "dependencies": {
    "handlebars": "git://github.com/machty/handlebars.js.git#397149429d81dbfc73a4ded9d89bd89d6983dee5",
    "optimist": "~0.3",
    "uglify-js": "~1.2",
    "StringScanner": "~0.0.3"
  },

CLI for hbs -> emblem and emblem -> hbs

This would make it really easy to start with Emblem, especially for complex very complex templates, or even just to demo to people how awesome it really is :)

When are quotes optional?

Both of these work, which makes me wonder when do I really want to ommit the "?

Ember.TextField placeholder="foo" valueBinding=bar
Ember.TextField placeholder="foo" valueBinding="bar"

Segregate vanilla/Emberized Handlebars

Emblem was quickly rolled out to generate Emberized templates, but we need better support for vanilla Handlebars. I'll be adding more to this list now, but here's some things that need to happen:

1. Throw UnsupportedFeature if trying to use an Ember-specific syntax with vanilla handlebars, e.g. p class={asd:dfg:gh}, which invokes vanilla-HB-nonexistent bindAttr.
2. p class=foo should yield <p class="{{foo}}"> for vanilla and <p {{bindAttr class="foo"}}> in Ember

Also need to refine the test suite so that both variants/syntaxes can be easily tested.

see: #20

need a package for Meteor

a few things missing in documentation

There are many ways to write bindAttr in emblem

li class=isIndex:active
li class={isIndex:active}
li{bindAttr class="isIndex:active"}

Same goes for the action handler, how do we write

<form {{action foo on="submit"}}>

Allow single-quoted attributes

a href="foo" compiles, but a href='foo' doesn't.

Is there any specific reason for this? Otherwise, I suggest that we allow single-quotes because:

• Slim does
• HTML-wise, both are allowed
• Saves on hitting the Shift key :-)
• It is not semantically distinctive (quoted vs unquoted is distinctive, but not single vs double quotes)

I have read through how you implemented some of the previously closed issues, and I think this should be easy to fix, just use a regex of ["']. This would allow mismatched quotes like a href='foo", but, well, no harm done? Otherwise, a regex of (["']) followed by the capture group should do the trick.

Thanks again for making emblem, I had previously used hamlbars as a rather ugly compromise, but emblem beats it handsdown.

Add syntax to not strip out newlines, e.g. for pre / code

e.g.

pre
  ` Newlines will make it into rendered code
      This line will be indented
     Normal indentation rules don't need to be followed
  span But you should still be able to use other elements in pre tags

Will require a change to the preprocessor, which would currently gobble the preceding space on the next line and convert to INDENT token

Reconsider EOL whitespace usage

Presently Emblem doesn't automatically insert whitespace between lines in a block of text and relies on EOL whitespace. This is at odds with a lot of editors out there which strip trailing whitespace when a file is saved. It's probably safe to just inject a space to connect blocks of text.

Use ruby coffeescript lib rather than invoking coffee through the shell

see https://github.com/josh/ruby-coffee-script

Use apostrophe instead of backtick for trailing space

In slim you'd use ' to specify that you want a trailing whitespace to be added to a block of text, such as

p
  ' foo
  a href="#" bar

Since Emblem is based on slim, it should use the same conventions whenever possible.

bower package

Hello! Would you provide a bower package?

self-closing tags

br yields <br></br>

Support same-line multi-line syntax

The following should be valid

p This is a paragraph tag that goes on and on and on
   and on and on and on and on. Woot woot.

   Still in the same paragraph tag.

blockquote This is a long ass quote
     wherever I start on the second line sets the baseline
     for the next lines of indentation

no good way to do prop="{{unbound whatever}}"

Not just unbound, but any strings properties with potential mustaches in them.

Should be able to do

a href="http://www.google.com/{{unbound hello}}" 
a href="{{unbound hello}}"
a href=hello!  -> yields href="{{unbound hello}}" in Ember or just href="hello" in vanilla
a href="{{{whatever hello}}}"

Note that the single bracket {} notation is taken up by bindAttr

`=` as blockstache helper

linkTo "home" = foo translates to {{#linkTo "home"}}{{foo}}{{/linkTo}}

Also, we should allow for this:

| Here is a line of text #{ linkTo "borf" | Shit }
| Here is another #{ linkTo "borf" = foo } 

This would generate

Here is a line of text {{#linkTo "borf"}}Shit{{/linkTo}}
Here is a line of text {{#linkTo "borf"}}{{foo}}{{/linkTo}}

can't handle dashes in class={ :asasd-asd } syntax

allow HAML-style % to force interpretation as html element

%each App.things

should produce <each>App.things</each>

shouldn't require space before equal sign

Apparently this is erroring. it shouldn't

h1= title

Disable 'view' capitalization helper if suffix modifiers are in place

= App.foo?
    p It was <strong>TRUE</strong>

The above presently causes both view and if helpers to be invoked. Also need to make sure this works for

App.foo!

Using a fork of ember-rails is a pain. I made a gem that can be used independantly.

In your Gemfile:

gem 'emblemjs-rails'

I called it emblem-rails but it seemed you already have reserved that.

The code is available here: https://github.com/alexspeller/emblem-rails

The "renamed" branch is what is pushed to rubygems, I don't know if this is helpful to you or not or if you're already working on the same thing.

The only horrible bit is the monkeypatch of barber:

Comments don't work with inconsistent indentation

/ <a class="header-link" href="test/">App tests</a>
  <a class="header-link" href="http://brunch.readthedocs.org/">Docs</a>
  <a class="header-link" href="https://github.com/brunch/brunch/issues">
    GitHub issues
  </a>
  <a class="header-link" href="https://github.com/paulmillr/ostio">
    Ost.io example app
  </a>

this was giving me errors in brunch

Need separate attribute mustache behavior b/w non/Emberized Handlebars

Presently.

p class=asd Hello

will generate {{bindAttr class="asd"}}, which obviously assumes Ember handlebars. Need to branch on this behavior and for vanilla HB produce something like class="{{asd}}"

Need better syntax for block mustaches

Need something better than just always forcing two lines and indentation. e.g.

linkTo 'faq' | To the FAQ! 

Alternatives

linkTo 'faq' | <span>To the FAQ!</span>
linkTo 'faq' <span>To the FAQ!</span>
linkTo 'faq'
  span To the FAQ

So basically, the | would trigger a text line