jaded

Port of the excellent Pug, formerly Jade view engine in Dart.

Now feature complete with the original jade view engine, begin by taking the comprehensive tour on learnjade.com and refer to jade's detailed documentation
to learn about Jade's features and syntax.

Although the aim was to have a high-fidelity port, the major syntactical difference compared with the original Jade (in JavaScript) is that the compiler only emits and executes Dart code, so any embedded code in views must be valid Dart (i.e. instead of JavaScript).

Installing via Pub

Add this to your package's pubspec.yaml file:

dependencies:
  jaded: 0.3.0

Public API

Compile a Directory

Add a pre-build step and use renderDirectory to statically compile all views into a single jade.views.dart file containing a Map of all compiled Jade views, e.g:

import "dart:io";
import "package:jaded/jaded.dart" as jade;

var jadeTemplates = jade.renderDirectory('.');
new File('jade.views.dart').writeAsString(jadeTemplates);

Writes to jade.views.dart snippet:

Map<String,Function> JADE_TEMPLATES = {
  './index.jade': ([Map locals]){
     ...
  },
  './dir/page.jade': ([Map locals]){
    ...
  },
}

Usage:

import "jade.views.dart";

var render = JADE_TEMPLATES['./index.jade'];
var html = render({'title': 'Hello Jade!'});

Compile a jade view at runtime

import "package:jaded/jaded.dart" as jade;

var renderAsync = jade.compile('string of jade', { //Optional Compiler Defaults:
  Map locals,
  String filename,
  String basedir,
  String doctype,
  bool pretty:false,
  bool compileDebug:false,
  bool debug:false,
  bool colons:false,
  bool autoSemicolons:true  
});

renderAsync(locals)
  .then((html) => print(html));

Options

locals Local variable object
filename Used in exceptions, and required when using includes
basedir The basedir where views start from
doctype What doctype to use
pretty Add pretty-indentation whitespace to output (false by default)
debug Outputs tokens and function body generated
compileDebug When false no debug instrumentation is compiled
autoSemicolons Auto add missing semicolons at the end of new lines (true by default)

Web Frameworks

jaded is the de-facto HTML View Engine in Dart express web framework.

Current Status

All tests in jade.test.dart are now passing.

All integration test cases in /test/cases that doesn't make use of an external DSL library are passing. Specifically, the following filters are NOT supported:

filters.coffeescript.jade
filters.less.jade
filters.stylus.jade
include-filter-stylus.jade

When they become available support for external Web DSL's can be added to transformers.dart in the same way as done inside Jade's feature-rich transformers.js.

Markdown filter

We've added the markdown filter which lets you include markdown inline:

html
  body
    :markdown
      This is _some_ awesome **markdown**

Or as an external include:

html
  body
    include some.md

Pre-compilation of .jade templates

The recommended way to execute .jade templates is to pre-compile all views with renderDirectory() out to a static file at design time. This can be automated using the Dart Editor build system /build.dart file, which can be used to trigger the background compilation of .jade views when it detects a .jade file was saved or deleted.

This is the approach the Dart Express Web Framework takes with its express_build.dart helper that gets triggered when a '.jade' file is touched will scan all directories for an empty jade.yaml marker and recursively pre-compiles all .jade views in that directory into a single jade.views.dart file.

Compile and execute at runtime - Missing eval

Jade relies on eval'ing code-gen to work which is a limitation in Dart that lacks eval. To get around this when compiling on the fly, we're currently wrapping the code-gen Dart inside an Isolate and writing it out to a file then immediately reading it back in with spawnUri and invoking the new code asynchronously in the runCompiledDartInIsolate() method.

Although this works, it forces us to have an async API to convert jade to html at runtime. When Dart offers a sync API for evaluating Dart code we'll convert it back to a sync API.

Contributors

mythz (Demis Bellot)
MaxHorstmann (Max Horstmann)
Cheney-Enterprises (Eric Cheney)

dartist/jaded