Razor-Express (RAZ): a view template engine for NodeJS/ExpressJS

<p align="center"> <a href="https://travis-ci.org/DevelAx/RazorExpress" target="_blank"><img src="https://img.shields.io/travis/DevelAx/RazorExpress.svg?style=plastic" alt="Build Status" /></a> <a href="https://www.npmjs.com/package/raz" target="_blank"><img src="https://img.shields.io/node/v/raz.svg?style=plastic" alt="NodeJS Version" /></a> <a href="https://www.npmjs.com/package/raz" target="_blank"><img src="https://img.shields.io/npm/v/raz.svg?style=plastic" alt="NPM Version" /></a> </p>

<pre>$ npm install <b>raz</b> --save</pre>

^{--> JavaScript (browser) version of this library.}

• Intro
  • A brief comparison of syntax of Node.JS template engines
• Quick Start
  • Node.js example
  • Express web-server example
• Razor-Express API
• The overview of Razor-Express view template engine
  • Views and View Template Engine
  • Rendering layout system
• Razor-Express syntax
  • A simple example
  • Escaping @ character
  • Expressions
  • Code blocks
  • Control structures
  • Functions
  • More examples
  • Reserved keywords
    • @section
  • Reserved View objects
    • debug
    • @Model
    • @ViewData
    • @Html
  • Syntax highlighting in code editors
• Common pitfalls & remarks
  • Missing semicolon
  • Expressions & code blocks confusion
• Debugging & Errors handling in Razor-Express
• Misc
  • The source code examples
  • TODO list

---

Intro

When I just started to dive into the world of Node.js after years of working with ASP.NET MVC I couldn't find any view template engine that was as convenient, elegant, concise, and syntactically close to native HTML as ASP.NET MVC Razor syntax was. And when it comes to code it's also syntactically close to the original C# language. Actually, ASP.NET MVC Razor markup is a hybrid of HTML markup and C# programming language. This is exactly what I expected to see in the NodeJS world - a hybrid of HTML and JavaScript.

The closest to Razor currently supported library for NodeJs & Express I could find was Vash. But in some points, it was quite different from ASP.NET MVC Razor syntax which I was used to and it just looked much less concise and convenient to me (the syntax for rendering layouts and partial blocks, for example). In short, it did not suit me completely and what's more important I couldn't see its current development.

A brief comparison of syntax of Node.JS template engines

I may be exaggerating the merits of ASP.NET MVC Razor and maybe it's all just a matter of habit, but let's look at a few examples that I found on the web (the question on Quora):

This is our data model represented via a JavaScript object:

var model = {
    subject: "Template Engines",
    items: [
        {name: "Mustache"},
        {name: "HandleBar"},
        {name: "Dust"},
        {name: "Jade"},
        {name: "EJS"},
        {name: "Razor"},
    ]
};

Mustache / HandleBar

<h1>{{subject}}</h1>
<ul>
  {{#items}}
    <li>{{name}}</li>
  {{/items}}
</ul>

^{^ mustache live example}

---

Pug (Jade)

h1=model.subject  
ul
  each item in model.items
      li=item.name 

^{^ pug live example}

---

EJS

<h1><%= model.subject %></h1>
<ul>
  <% for(var i = 0; i < model.items.length; i++) {%>
     <li><%= model.items[i].name %></li>
  <% } %>
</ul>

^{^ ejs live example}

---

Razor

<h1>@Model.subject</h1>
<ul>
  @for(var i = 0; i < Model.items.length; i++) {
     <li>@Model.items[i].name</li>
  }
</ul>

^{^ razor live example}

Haml

Or let's consider an example from http://haml.info/tutorial.html

.item{:id => "item#{item.id}"}= item.body

Maybe I'm wrong and this kind of markup really simplifies the development and perception of the code, but to me it doesn't seem to be so. Let's just compare it to the equivalent Razor markup:

<div class='item' id='item@item.id'>
  @item.body
</div>

I won't go much into all the aspects I don't like in other engines syntax just say that "Mustache / HandleBar", "Pug", and Haml look like I have to learn a new syntax while with Razor I virtually know it if I'm already familiar with HTML and JavaScript languages. EJS is very close to Razor but it is too verbose that makes it difficult to write and read the code.

In these examples I don't compare logic constructions because some of the view engines have logic-less templating syntax. With Razor you can implement amost any logic that is available with normal JavaScript without learning a new syntax.

Given all the mentioned and unmentioned pros and cons, I decided not to part with Razor-syntax and create something similar for using with ExpressJS library (it can work with other frameworks as well). This library works quite fast since it does not use third-party HTML parsers and regular expressions.

---

Quick Start

Assuming that you are already familiar with the basic idea let's look at a simple example.

Our first component is a model:

{
    title: "Names of the Days of the Week",
    days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
};

which is just a JavaScript object. And we want to get some HTML displaying the data of this model in some simple way. Later we might want to change the model data and still get the same HTML structure to display it. So, we need our second component which is called view-template:

<h3>@Model.title</h3>
<ul>
@for(var i = 0; i < Model.days.length; i++){
    var day = Model.days[i];
    <li>@day</li>
}
</ul>

As you can see the view-template (or just view) is nothing more than HTML markup mixed with JavaScript syntax. This is exactly what Razor-Express syntax is.

Now we are going to take these two components and "compile" them into pure HTML.

Node.js example

First, we'll be doing this "compilation" without creating any web-server to keep things as simple as possible. It can be done either in Node.js environment or in just the browser JavaScript. To do this we will declare two variables model and template:

const model = {
    title: "Names of the Days of the Week",
    days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
};

const template = `
<h3>@Model.title</h3>
<ul>
@for(var i = 0; i < Model.days.length; i++){
    var day = Model.days[i];
    <li>@day</li>
}
</ul>`;

...which are pretty much self-explained as we remember what our two components are. Next, we have to render them together using Razor-Express library to get the expected HTML.

// This code is meant for Node.js 
const razor = require("raz");
var html = razor.render({ model, template });

Now let's display it in the console to make sure our expectations are fully met.

console.log(html);

Here's what we can see in the conso