#2183 [ANN] afEfan v1.3.0 - Embedded Fantom Templates

Collapse AllExpand All

SlimerDude Wed 14 Aug 2013

Alien-Factory efan

afEfan is a library for rendering Embedded Fantom (efan) templates.

Much like EJS for Javascript, ERB for Ruby and JSP for Java, efan lets you embed snippets of Fantom code inside textual templates.

afEfan aims to hit the middle ground between programmatically rendering markup with web::WebOutStream and rendering logicless templates such as Mustache.

ALIEN-AID: If rendering HTML, use afSlim !!! The concise and lightweight template syntax makes generating HTML easy!

Pod doc follows - always see Status302 for the latest and most up to date documentation.

Quick Start

xmas.efan:

<% ctx.times |i| { %>
  Ho!
<% } %>
Merry Christmas!

Fantom code:

template := `xmas.efan`.toFile.readAllStr

Efan().renderFromFile(template, 3)   // --> Ho! Ho! Ho! Merry Christmas!

Tags

ALIEN-AID: efan believes templates are sacred! It preserves all formatting and all whitespace not contained in <% ... %> tags. Even DOS / UNIX line-endings are preserved!

Efan supports the following tags:

Eval Tags

Any tag with the prefix <%= will evaluate the fantom expression and write it out as a Str.

Hello, <%= "Emma".upper %>!

Comment Tags

Any tag with the prefix <%# is a comment and will be left out of the resulting template.

<%# This is just a comment %>

Code Tags

Any tag with the prefix <% will be converted into Fantom code.

<% echo("Hello!") %>

ALIEN-AID: When casting or using static methods in efan templates, be sure to use the fully qualified class name (FQCN) including the pod. Example:

<% concurrent::Actor.sleep(2sec) %>

Template Context

Each template render method takes an argument called ctx which you can reference in your template. ctx is typed to whatever Obj you pass in, so you don't need to cast it. Examples:

Using maps:

ctx := ["name":"Emma"]  // ctx is a map

template := "Hello <%= ctx["name"] %>!"

Efan().renderFromStr(template, ctx)

Using objs:

class Entity {
  Str name
  new make(Str name) { this.name = name }
}

...

ctx      := Entity("Emma")  // ctx is an Entity

template := "Hello <%= ctx.name %>!"

Efan().renderFromStr(template, ctx)

View Helpers

Efan lets you provide view helpers for common tasks. View helpers are mixins that your efan template will extend, giving your templates access to commonly used methods. Example, for escaping XML:

mixin XmlViewHelper {
  Str xml(Str str) {
    str.toXml()
  }
}

Set view helpers when calling efan:

Efan().renderFromStr(template, ctx, [XmlViewHelper#])

Template usage would then be:

<p>
  Hello <%= xml(ctx.name) %>!
</p>

Layout Pattern / Nesting Templates

Efan templates may be nested inside one another, effectively allowing you to componentise your templates. This is accomplished by passing body functions in to the efan render() method and calling renderBody() to invoke it.

This is best explained in an example. Here we will use the layout pattern to place some common HTML into a layout.efan file:

layout.efan:

<head>
  <title><%= ctx %></title>
</head>
<body>
  <%= renderBody() %>
</body>

index.efan:

<html>
<%= ctx.layout.render("Cranberry Whips") { %>
    ...my cool page content...
<% } %>
</html>

Code to run the above example:

Index.fan:

using afEfan

class Index {
  Str renderIndex() {
    index     := efan().compileFromFile(`index.efan` .toFile, EfanRenderer#)
    layout    := efan().compileFromFile(`layout.efan`.toFile, Str#)

    return index.render(layout)
  }
}

This produces an amalgamation of the two templates:

<html>
<head>
  <title>Cranberry Whips</title>
</head>
<body>
    ...my cool page content...
</body>
</html>

Err Reporting

Efan compilation and runtime Errs report snippets of code showing which line in the efan template the error occurred. Example:

Efan Compilation Err:
  file:/projects/fantom/Efan/test/app/compilationErr.efan : Line 17
    - Unknown variable 'dude'

    12: Five space-worthy orbiters were built; two were destroyed in mission accidents. The Space...
    13: </textarea><br/>
    14:         <input id="submitButton" type="button" value="Submit">
    15:     </form>
    16:
==> 17: <% dude %>
    18: <script type="text/javascript">
    19:     <%# the host domain where the scanner is located %>
    20:
    21:     var plagueHost = "http://fan.home.com:8069";
    22:     console.debug(plagueHost);

This really helps you see where typos occurred.

Renderers

Efan works by dynamically generating Fantom source code and compiling it into a Fantom type. Because types can not be unloaded, if you were compile 1000s of efan templates, it could be considered a memory leak.

Each invocation of EfanCompiler.compile creates a new Fantom type, so use it judiciously. Caching the returned EfanRenderer classes is highly recommended. Example:

template := "<% ctx.times |i| { %>Ho! <% } %>"
renderer := EfanCompiler().compile(template, Int#)  // <-- cache this class!

ho       := renderer.render(1)
hoho     := renderer.render(2)
hohoho   := renderer.render(3)

SlimerDude Tue 3 Sep 2013

Hiya,

Just to say that the new version of efan is essentially a standalone version and doesn't have any dependencies on afIoc or afBedSheet.

All afBedSheet integration is now via afBedSheetEfan.

Steve.

Login or Signup to reply.