elm-mustache

Mustache templates in Elm.

There are two parts to this package:

• The Elm package with which you can parse and render mustache templates in the browser.
• The NPM package with which you can parse a mustache template in advance and generate a typesafe™ rendering function for use in the browser.

Should I use the Elm package or the NPM package?

If you have .mustache templates already that you'd want to render with different hashes in the browser then you should probably use the NPM package. If you have a use-case where you can't know in advance what the template will be, then you should use the Elm package. If you don't already have .mustache templates ready and have found this package because you're looking for a nice templating experience in Elm, then you are probably better off writing some rendering functions in Elm directly with the help of multiline strings, the ++ operator.

The Elm package

See https://package.elm-lang.org/packages/emmabastas/elm-mustache/latest/

The NPM package

There are two types of rendering functions that can be created: A typesafe but more limited version (It can't iterate a section), and a full version.

Let's say you have a file mytemplate.mustache

{{#section}}
Hello {{world}}!
{{/section}}

Then you can generate a typesafe rendering function with elm-mustache ./mytemplate.mustache ./src/Mustache/MyTemplate.elm Mustache.MyTemplate, which will give you the Elm module:

module Mustache.MyTemplate exposing (..)

render : Context a -> String
render c =
    (if c.section then ("""Hello """ ++ htmlEscape c.world ++ """!
""") else "")

type alias Context a =
    { a
        | section : Bool
        , world : String
    }

One the other hand, if you run elm-mustache again but with the --full flag you'd get the "full" version:

module Mustache.MyTemplate exposing (..)

import Json.Decode exposing (Value)
import Mustache exposing (htmlEscape, lookup, interpolate, section, invertedSection)

render : Value -> String
render json = (\context0 ->
    (section context0 ["section"] (\context1 ->"""Hello """ ++ htmlEscape (interpolate (lookup context1 ["world"])) ++ """!
"""))) [json]

While the typesafe version is better in the sense that you can never forget to supply some variable, and typos will be caught by at compile time, it is worse in the sense that it can't iterate a section. With the full version you can call it with:

import Json.Encode exposing (list, string)
render (object
    [ ("world", string "Earth")
    , ("world", string "Venus")
    , ("world", string "Pluto")
    ])

which will produce the string

Hello Earth!
Hello Venus!
Hello Pluto!

This is not possible with the typesafe version

Why is can't the typesafe version deal with lists?

When presented with the template

{{#section}}
{{foo}}?
{{bar}}!!
{{/section}}

I can't tell if the foo and bar variables are supposed to change for every iteration of the section, or if they should remain the same, in other words I don't know if the Context type should be

{ section :
    List { foo : String
         , bar : String
         }
}

or

{ section : Bool
, foo : String
, bar : String
}

or something in between.

Summary of capabilities and spec compliance

| | elm-mustache | elm-mustache --full | Elm package | |-------------------------------------|----------------|-----------------------|-------------| | variables | ✅ | ✅ | ✅ | | boolean section | ✅ | ✅ | ✅ | | list section | ❌ | ✅ | ✅ | | inverted section | ✅ | ✅ | ✅ | | set delimiters | ✅ | ✅ | ✅ | | lambdas | ❌ | ❌ | ❌ | | partials | ❌ | ❌ | ❌ | | inheritance | ❌ | ❌ | ❌ | | dynamic names | ❌ | ❌ | ❌ | | respects \r\n-style line endings? | ✅ | ✅ | ❌ |

Testing

npx elm-test to run all unit tests. All unit tests are generated from ./tests/specs/*.json which have been fetched from the mustache test suite over at https://github.com/mustache/spec

Contributing

Yes please :-) Feel free to email me or open an issue.

TODOs

This package isn't immensely high-quality, hopefully it can get the job done for you. Some things that could be nice:

• Integration tests for the CLI tool
• Make a elm-codegen generator to replace the CLI tool
• Use Parser.Advanced to provide useful error messages and fault-tolerant parsing.
• Unit tests pertaining to weird variable names

License

GPLv3