MEAN web development #5: Jade and Express

In the last few weeks it was my time to shine… In absence. Been quite busy with, you know, stuff. But here I am ready to give you a new installment of the MEAN web development series! If you haven’t read my previous posts, or if you’ve forgotten all about them in my absence, you can find them here:

  1. MEAN web development #1: MEAN, the what and why
  2. MEAN web development #2: Node.js in the back
  3. MEAN web development #3: More Node.js
  4. MEAN web development #4: All aboard the Node.js Express!
  5. MEAN web development #5: Jade and Express
  6. MEAN web development #6: AngularJS in the front
  7. MEAN web development #7: MongoDB and Mongoose
  8. MEAN web development #8: Sockets will rock your socks!
  9. MEAN web development #9: Some last remarks

So in my previous blog from a few weeks back I’ve talked about using Express in Node.js. One thing I haven’t discussed yet is the templating option of Express. As that is actually quite simple this blog will be more about the template engine Jade than about Express. Of course we’ll use both to build a few pages.

You can find the examples for this blog on my GitHub page in the mean5-blog repository.

Starting out with Jade

So you can probably guess our first step (assuming you’ve already installed Node.js)… If it included npm somehow you are correct. We need to install Jade using npm. We’ll also want Express, of course, you know how it goes! You can read about npm and how to use it in my first MEAN article, MEAN web development #1: MEAN, the what and why. So create a folder for your project somewhere, optionally create a package.json file (containing at least an opening and closing bracket), open up a command prompt and use the following commands.

cd C:\project-folder
npm install express --save
npm install jade --save

The –save is optional and only makes sense when you created a package.json file.

Finally create your server.js file where your actual JavaScript goes. So now you have everything you need to start using Node.js, Express and Jade.

Let’s not do that yet though. Let’s take a step back. What exactly is Jade and why would you want to use it? Jade is a template engine, which means you can write some pseudo-HTML which the Jade engine can transform into actual HTML. One reason to use Jade is because it saves typing, “h1 Examples” will output “<h1>Example</h1>” for example. So that saves like seven characters, but it adds up.

Less typing is the least good reason to start using Jade though. When using Jade it is possible to pass some JavaScript object to your Jade code and build your page differently depending on your JavaScript. For example you might have an array and you want to iterate over the array to show a table on your page. Or maybe you just want to show the name of the logged in user in the top right corner.
Jade also supports and encourages a more object oriented style of writing your HTML. That’s awesome because you can now write a piece of HTML Jade once and use it everywhere.

Sounds good, right? But isn’t all of this already possible using PHP, Java or C#? Yeah, sure. And you can even do this in Node.js. Simply create a string containing your HTML, do some string concatenation, replaces, etc. No problem at all.
So why would you still want to use Jade? Because Jade makes it easy! All the string concatenation and replaces you’d have to do in PHP or “vanilla” Node.js is done for you. What’s left is a file that’s easier to read than the HTML it ultimately produces! And the good thing about Jade is that it has Node.js and Express support out-of-the-box!

Hello Jade!

I think that title says it all, no? We won’t be using Node.js and Express just yet though. In fact I want you to fire up a command prompt and install Jade again, this time globally so we can use it from the command prompt.

npm install jade -g

Now create a folder in the Node.js project we just created and call it jade-examples. We’re going to use this folder and some of the examples later with Node.js and Express. So in that folder create a file and call it hello-jade.jade. If you got my sources from GitHub you can find the file in jade-examples. Put the following code in the file.

html
  head
    title Hello, Jade!
  body
    h1 Hello, Jade!
    p This is awesome!

So that’s maybe a bit much for a simple Hello World example, but I’m pretty sure you can figure out what HTML this will generate. One thing I’d like to point out is that Jade is whitespace sensitive. More specifically, you must use whitespaces to nest elements. That means that you got to be really careful with your spaces, they’re not just makeup!

I recently spent an evening debugging some Haskell code (which is also whitespace sensitive) because I had used spaces on one line and a tab on another. Try figuring that out, it all looks the same!
I recommend using spaces by the way, if your editor supports it look for the option that converts tabs to spaces and you’ll be safe.

Enter the CMD

So how to get some HTML out of this? With the command prompt, of course. So browse to the folder where you’ve put your file and use the following command.

cd file-folder
jade hello-jade.jade

Now check it out, it generated a hello-jade.html file. It’s not very readable though. Everything is put on a single line! Let’s fix that. You can use some options in the command prompt. We’re going to use -P (that’s a capital P).

jade hello-jade.jade -P

Looks a look better, doesn’t it?

<html>
  <head>
    <title>Hello, Jade!</title>
  </head>
  <body>
    <h1>Hello, Jade!</h1>
    <p>This is awesome!</p>
  </body>
</html>

For multiline text you should use one of the following methods. Use a dot after your element or use pipes | on every single line.

p.
  This is one line.
  This is a second.
p
  |This is one line.
  |This is a second.
p
  This won't work.
  It just won't.

The HTML that is generated looks as follows.

<p>
  This is one line.
  This is a second.
</p>
<p>
  This is one line.
  This is a second.
</p>
<p>
  <This>won't work.</This>
  <It>just won't.</It>
</p>

As you can see Jade will happily generate syntactically correct, yet invalid HTML! Keep in mind that HTML isn’t whitespace sensitive so the above HTML will still render the two lines of text on a single line in your browser. If you need a seperate line you’ll have to insert a <br> element.

Doing more with Jade

So now that we’ve got that out of the way let’s look at some other features of Jade. Of course you can add attributes to your elements.

h1(id="header") Attributes
p(class="text") This is an example using attributes.
p Here's a text input.
input(type="text")

I won’t show you the HTML output as you can generate it yourself or look at the files from my GitHub.

Here’s some other stuff we can do with Jade.

// This comment will be visible in our HTML.
//- This one won't (it's the hyphen!)
//- Ids are so common we have a shorthand!
h1#header Attributes
//- Same goes for classes.
p.text This is an example using attributes.
p.text.second-class.third-class Here's a text input.
input(type="text")
//
  Block comment
  With lots of space
  And lines

p Some text with another <strong>element</strong>.

//-
  Yes, this is possible,
  but we need to put it on a new line
  and prefix it with a pipe.
| Some text without enclosing tags.

Using JavaScript

So that’s all pretty cool, but you probably want more. You’re in luck, because there’s much more! In fact, you can use JavaScript to generate HTML. That means you can have any JavaScript object and use it just like that.

For the next example we’re going to need two files. First is our Jade file. I’ve called it javascript.jade.

h1= title
p= text

The = sign means some code will follow. So “title” and “text” is actually code. More precise they’re properties/variables. Using = will also filter your JavaScript to prevent injection attacks. If you like to disable this feature simply use != instead.

You could generate HTML from the above Jade file, but since title and text are not set you’ll just get an empty header and paragraph. So we’ll need to pass in something to the engine so it knows how to interpret those values. We can do that using a JSON file. So create another file, I’ve called it javascript.json, and put in the following JSON.

{
  "title": "Jade and JavaScript!",
  "text": "You can just insert JavaScript Objects into your templates!"
}

Now we can use the command prompt to generate the HTML using the JSON file. Notice that we’ll use a capital O in the next sample.

jade -O javascript.json javascript.jade

This will generate the HTML and it will have replaced title and text with the values from your JSON file. Awesome!

In the next example I’ve included all JavaScript into the Jade file so we don’t need a seperate JSON file. Try setting the showHeader variable to false and generate the HTML again. Also notice the difference between the escaped and the unescaped code.

//-
  The following code
  will not be shown
  in your HTML.
  We'll use - instead of =

-
  var showHeader = true;
  var header = 'Jade is awesome!'

//- Single line code.
- if (showHeader)
  h1= header

//- Native Jade syntax!
if showHeader
  h1= header

//- Multiline code.
-
  var movies = [];
  movies.push('Star Wars');
  movies.push('Lord of the Rings');
  movies.push('Harry Potter');

ol
  each movie in movies
    li= movie

- var code = 'HTML may look like this: <p>Hello, Jade!</p>';
//- Some escaped code.
p= code
//- Some unescaped code.
p!= code

Inheritance

So how about we look into that inheritance now? Most, if not all, websites have a standard structure that’s the same across the entire page. We have a header at the top, footer at the bottom, a menu on the left, top or right and the content in the middle. And it’s usually the middle part that changes while the rest stays more or less the same. So let’s define that basic layout. I’m going to keep it simple so I’ll just have a page with a fixed footer. For simplicity I’m just going to use embedded CSS in our Jade template. I’ve called the following file base.jade.

html
  head
    style(type="text/css").
      html {
        position: relative;
        min-height: 100%;
      }

      body {
        margin: 0 0 100px;
      }
 
      footer {
        background-color: #41a62a;
        position: absolute;
        left: 0;
        bottom: 0;
        height: 100px;
        width: 100%;
      }
    block head
  body
    div#content
      p This is the content!
      block content
    footer
      p This is the footer!
      block footer

This looks a lot like what we already know. The only weird thing here are those blocks. The block elements aren’t visible in the generated HTML, so it’s completely possible to use a ‘base’ page as a regular page on your site.

Overrides

Now those blocks can be overridden by inheritors. So block content can be replaced with anything you like. Let’s see what that looks like. I’ve created an base-inheritor.jade file which extends base.jade.

extends base.jade

block head
  title Inheritor

block content
  p This is the inheritor page!

block footer
  a(href="#") Some link

The file starts with extending base.jade (that’s actually the relative path to the file, since I have it in the same folder it’s just the file name). After that I’m filling in the content for each block. It’s totally optional to override a block.
Now you can simply generate the HTML for base-inheritor.jade and you’ll see the entire base is generated too!

There’s a little more you can do with those blocks though. Here’s a simple file called blocks.jade.

block header
 h1 Inheritance using Jade!

block content
 p Here is some content.

block footer
 p This is the footer.

As you can see I’ve put some content in each of those blocks. In an inheritor we can replace that content, append to that content or prepend to that content. This is illustrated in blocks-inheritor.jade.

extends blocks.jade

block header
  h1 Another header!

prepend content
  p This is even more content!

append footer
  a(href="#") Some link

You may use “block append” or “block prepend”, but the block keyword is optional. Now generate the HTML and check out the results!

It’s also possible to put blocks in blocks, but I’ll leave that as practice for the reader.

Mixins

Now there is one last feature I’d like to show you, which is mixins. A mixin is a bit like a function, a reusable piece of Jade! Let’s just look at some examples.

//- Here is a mixin.
mixin lorem
  h2 First paragraph of Lorem Ipsum...
  p Lorem ipsum [...]

h1 Mixins
//- Mixin usage is a big plus!
+lorem
+lorem
+lorem

h2 Animals
- var animals = ['Cat', 'Dog', 'Goldfish'];

//- A mixin with a parameter and JavaScript!
mixin isKnownAnimal(animal)
  if animals.indexOf(animal) >= 0
    p= 'The ' + animal + ' is a known animal.'
  else
    p= 'The ' + animal + ' is not a known animal!'

+isKnownAnimal('Cat')
+isKnownAnimal('Dog')
+isKnownAnimal('Parrot')

Pretty awesome, right?

Express

So that’s all the Jade I’ve got for you! You can now create Jade pages and generate HTML through the command prompt. We’d use it within Node.js though! So the time has come to get back to the project we created at the start of this post.

In the server.js you need to do two things. Tell Express where to find its templates and what engine to use when rendering those templates. Then on a request render any template you like.
It’s that easy!

Now we’ve got all these Jade examples we can generate using Express! I picked a few interesting ones. Here’s the code for the entire server.js.

var express = require('express');
var app = express();

app.set('views', './jade-examples')
app.set('view engine', 'jade');

// Use hello-jade as index.
app.get('/', function (req, res) {
    res.render('hello-jade');
});

app.get('/javascript', function (req, res) {
    res.render('javascript', {
        title: 'Jade and JavaScript!',
        text: 'You can just insert JavaScript Objects into your templates!'
    });
});

app.get('/base-inheritor', function (req, res) {
    res.render('base-inheritor');
});

app.get('/mixins', function (req, res) {
    res.render('mixins');
});

var server = app.listen(80, '127.0.0.1');

Is that all? That’s all!

Wrap up

So I usually give you some reading recommendations at the end of a blog, but I really haven’t got anything for Jade. You can get a lot from the language reference on the Jade website, although it’s hardly a good place to start.
Of course you can always check out some books by Manning, like Express.js in Action, which has a chapter on templating in Express and Jade. And keep an eye out for the ebooks by Syncfusion. Node.js Succinctly has a chapter on Express and JavaScript Succinctly is always handy when working with JavaScript.

Hope to see you again next week.
Stay tuned!