An Introduction to Jade

‘An Introduction to Jade’ is part of my article series ‘Branding SharePoint sites with yeoman’ see the list of all related articles here

  1. Introduction
  2. Yeoman the web development workflow
  3. An Introduction to Jade
  4. An Introduction to CoffeeScript
  5. An Introduction to SASS
  6. Our yeoman generators
  7. Hands  On – Let’s create a custom MasterPage
  8. Hands On – Let’s create a custom PageLayout
  9. A forecast – What are we currently working on

Why Jade?

Well, HTML MasterPages and PageLayouts are great and this is exactly what we’re going to create, but instead of writing the HTML directly we decided to use Jade (which compiles into HTML) in order to build robust HTML sites.

By using Jade we can ensure that our HTML is well-formed and valid. Almost every web-developer ran at least once into the issue of having unclosed tags in his/her HTML site. Jade is preventing us from doing this mistake. Jade is handling closing tags for example depending on the indention of your Jade code. During compilation-time the compiler throws build errors if the indention in your Jade-File isn’t correct. In bottom line I can say that Jade is another quality gate which prevents me from making mistakes in the front-end-layer.

Sample code is available on github

During this post I often reference to several files, you can find all these files within this github repository.

Installing Jade

Jade is a node package that can easily be installed on your system using the

$ npm install jade –g

command. After executing this command, the jade compiler will be installed globally and can easily be invoked by using the jade command from the command-line.

Let’s get started with Jade. Create your first Jade file.

Creating Jade files is easy you need nothing than a text editor in order to create a jade file. As you can imagine are Jade-files using the .jade extension.

So let’s fire-up an editor and put the following lines of Jade into a new file and save the file as 01-getting-started-with-jade.jade

html  
  head
    title My very first jade document
  body
    h1 Welcome
    p This HTML page has been written in Jade  

Let’s talk a little bit about the Jade-Source. You may have noticed that you can save some keystrokes using Jade. Jade don’t need to type the angle brackets and because of the indention-convention you can also ignore the closing tags.

In order to compile the Jade-file into HTML open a command-line and navigate to the folder containing your Jade-file and execute

$ jade 01-getting-started-with-jade.jade

The Jade compiler will translate your source into HTML and create a corresponding .html file within the folder.

<html>  
  <head>
    <title>My very first jade document</title>
  </head>
  <body>
    <h1>Welcome</h1>
    <p>This HTML page has been written in Jade  </p>
  </body>
</html>  

Generating Tags with Attributes

In every HTML document you need to specify attributes on tags. Let’s take a hyperlink for example

<a href='foo.bar' class='my-link' target='_blank'>Foo</a>  

Writing the corresponding Jade is really easy, it’s just

a(href='foo.bar', class='my-link', target='_blank') Foo

//- or
a.my-link(href='foo.bar', target='_blank') Foo  

You can find more examples in the 02-generating-tags-with-attributes.jade file on github

Generating div containers

The div-container is the most frequent used tags in web-sites. Therefor Jade is offering different easy ways to create new divs.

.foo
.foo.bar
#foo.bar
div.foo.bar  
div#foo2.bar  

The corresponding HTML will look like this

<div class="foo"></div>  
<div class="foo bar"></div>  
<div id="foo" class="bar"></div>  
<div class="foo bar"></div>  
<div id="foo2" class="bar"></div>  

You can find more examples in the 03-generating-divs-with-jade.jade file on github

Mixins and Blocks

By using Mixins, you can create reusable blocks of Jade in no-time. In order to keep your project structure clean, you should place your mixins separated files and load them if they are required. In the following picture you can see two mixins, the first one is straight forward. It will just put the source from the mixin at the place where you reference it. But the second one is more powerful by using a block you can inject jade source from the reference location into the mixin.

// file mixins/mixins.jade
mixin icon(name)  
  i(class="fa fa-#{name}")
// file index.jade
include ./mixins/mixins

.contact-info
  .phone
    +icon('phone')
    span 0123456789
  .website
    +icon('globe')
    span www.xplatform.rocks

will become the following HTML

<div class="contact-info">  
  <div class="phone">
    <i class="fa fa-phone"></i>
    <span>0123456789</span>
  </div>
  <div class="website">
    <i class="fa fa-globe"></i>
    <span>www.xplatform.rocks</span>
  </div>
</div>  

Okay, let refactor the mixin and add a block

// file mixins/mixins.jade
mixin contactInfo(name)  
  i(class="fa fa-#{name}")
  block
// file index.jade
include ./mixins/mixins

.contact-info
  .phone
    +contactInfo('phone')
      span 0123456789
  .website
    +contactInfo('globe')
      span www.xplatform.rocks

It will again become the following HTML

<div class="contact-info">  
  <div class="phone">
    <i class="fa fa-phone"></i>
    <span>0123456789</span>
  </div>
  <div class="website">
    <i class="fa fa-globe"></i>
    <span>www.xplatform.rocks</span>
  </div>
</div>  

Referencing mixins is also easy. First you’ve to import the mixin.jade file by using the include command as shown in the upcoming picture. When included you can reference a mixin with the plus-sign (+) followed by the mixins name.

If a mixin contains a single block you can pass the blocks value by nesting the code (one indention).

Inheritance in Jade using the extends mechanism

Inheriting HTML structures has become a required for almost every language that compiles into HTML, in ASP.NET we call it MasterPages and also Jade is offering such a system. Jade offers the extends command which can be used to achieve exactly what MasterPages are offering. Let’s take the following Jade 05-a-simple-jade-layout.jade

// file _layout.jade
html  
  head
    title my Blog
    link(rel='stylesheet', href='/styles/bootstrap.min.js')
  body
    .container
      block content
    script(src='/scripts/angular.min.js')

As you can see within this jade are two blocks defined, the content of these blocks will be defined with the actual page which is extending this layout 05-a-simple-jade-page.jade

extends _layout

block content  
  .row
    .col-md-3
      nav
    .col-md-9
      h1 welcome  

After compile time, you receive a HTML file containing the layout defined from our 05-a-simple-jade-layout.jade mixed up with everything written in 05-a-simple-jade-page.jade. In order to compile this just execute

jade 05-a-simple-jade-page.jade  

and you will receive the following HTML markup

<html>  
  <head>
    <title>my Blog</title>
    <link rel="stylesheet" href="/styles/bootstrap.min.js"/>
  </head>
  <body>
    <div class="container">
      <div class="row"></div>
    </div>
    <div class="col-md-3">
      <nav></nav>
    </div>
    <div class="col-md-9">
      <h1>welcome </h1>
    </div>
    <script src="/scripts/angular.min.js"></script>
  </body>
</html>  

Further Jade Features

With all these features you’re prepared to start with Jade, more features and tricks from Jade can be found on Jade’s github repository at (https://github.com/visionmedia/jade) or on the Jade language site at (http://jade-lang.com/).

Update

See my recent post on more advance Jade language features here.

Comments

comments powered by Disqus