Differences

This shows you the differences between two versions of the page.

--- javascript:jade [2014/03/17 22:28] – created mithat
+++ javascript:jade [2014/03/18 03:36] – [Creating web pages] mithat
@@ Line 1: / Line 1: @@
 ====== Jade ======
-[[http://jade-lang.com|Jade]] is billed as a template engine for Node.js, but I think it's better thought of as a language that makes HTML easier to write and also lets you do templating.
+[[http://jade-lang.com|Jade]] is billed as a template engine for [[http://nodejs.org/|Node.js]], but it could be thought of as a language that makes writing HTML easier that also lets you do templating.
 ===== Getting started =====
 ==== Installing Jade ====
-To use Jade, you must have Node.js installed on your system. That's better convered elsewhere, so I will not cover that here.
+To use Jade, you must first have Node.js installed on your system. On Windows and MacOS, you can use an [[http://nodejs.org/download/|installer]]; on Linux, you should be able to [[https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager|use your package manager]]((See http://lovingthepenguin.blogspot.com/2013/10/node-no-such-file-or-directory.html for a potential gotcha on Debian-based systems.)).
-Once you have Node.js installed, you have the choice of installing it so it available system-wide or only for a particular project. To make it available system-wide, open a terminal and enter <code>npm install jade -g</code>
+Once you have Node.js installed, you have the choice of installing the Jade module so it's available system-wide or only for a particular project. To make it available system-wide, open a terminal and enter: <code>npm install jade -g</code>
-Until I get a good grasp of using Jade, I want to install it on a per-project basis. To do this, open a terminal in your project directory (or navigate to the directory) and enter <code>npm install jade</code>
+When I am learning new Node.js modules, I prefer to install them on a per-project basis. To do this, open a terminal in your project directory (or navigate to the directory) and enter: <code>npm install jade</code>
-When this is done you should see a ''node_modules'' subdirectory. Inside that directory will be the Jade modules as well as any other modules Jade depends on.
+When this is done you should see a ''node_modules'' subdirectory inside your project directory. Inside ''node_modules'' will be the Jade modules as well as any other modules Jade depends on.
+==== Creating an HTML fragment ====
+=== Rendering strings in Jade to HTML ===
+The first thing we are going to do is use Jade to produce an HTML fragment from a string literal. This is done with the ''jade.render'' method.
+<file javascript renderFragment.js >
+var jade = require('jade');
+// Render an HTML fragment from a string literal written in Jade.
+var htmlFrag = jade.render('p Hello, world');
+console.log(htmlFrag);
+</file>
+output: <code><p>Hello, world</p></code>
+=== Compiling strings in Jade into functions ===
+You can use the ''jade.compile'' method to create a function that when called will return the converted Jade.
+<file javascript compileFragment.js>
+var jade = require('jade');
+// Compile a function that produces an HTML fragment from a string
+// literal written in Jade.
+var frag = jade.compile('p Hello, world');
+// Render stuff.
+var htmlFrag = frag();
+console.log(htmlFrag);
+</file>
+output: <code><p>Hello, world</p></code>
+=== jade.renderFile ===
+In a lot of cases, you will want to render code that is stored in a file rather than in a string literal or variable. You can do that with the ''jade.renderFile'' method.
+<file jade myFrag.jade>
+h1 Hello, there!
+p Nice to meet you.
+</file>
+<file javascript renderFragmentFile_1.js>
+var jade = require('jade');
+// Render an HTML fragment from a file written in Jade.
+var htmlFrag = jade.renderFile('myFrag.jade');
+console.log(htmlFrag);
+</file>
+output: <code><h1>Hello, there!</h1><p>Nice to meet you.</p></code>
+The above produces valid HTML, but it's hard to read. To make the output human-readable, we can pass ''jade.renderFile'' an options object with its ''pretty'' property set to true. (The options argument can be provided to the ''jade.render'' and ''jade.compile'' methods as well.)
+<file javascript renderFragmentFile_2.js>
+var jade = require('jade');
+options = {
+    pretty: true
+};
+// Render an HTML fragment from a file written in Jade.
+var htmlFrag = jade.renderFile('myFrag.jade', options);
+console.log(htmlFrag);
+</file>
+output: <code><h1>Hello, there!</h1>
+<p>Nice to meet you.</p></code>
+You can (and should) also take anvantage of the callback that you can pass to ''jade.renderFile'' to handle errors:
+<file javascript renderFragmentFile_3.js>
+var jade = require('jade');
+options = {
+    pretty: true
+};
+// Render an HTML fragment from a file written in Jade.
+// Use callback to trap errors.
+var htmlFrag = jade.renderFile('myFrag.jade', options, function (err, html) {
+        if (err) {
+           throw(err);
+        }
+        return html;
+    });
+console.log(htmlFrag);
+</file>
+=== Writing output to file ===
+To write the output created to a file, you'll need to use Node.js' ''fs'' module.
+<file javascript convertFragment.js>
+var jade = require('jade');
+var fs = require('fs');
+options = {
+    pretty: true
+};
+// Render an HTML fragment from a file written in Jade.
+var htmlFrag = jade.renderFile('myFrag.jade', options, function(err, html) {
+        if (err) {
+           throw(err);
+        }
+        return html;
+    });
+// Write HTML fragment to a file.
+fs.writeFile('myFrag.html', htmlFrag, function(err) {
+    if (err) {
+        throw(err);
+    }
+});
+</file>
+output:<code bash>
+$ cat myFrag.html
+<h1>Hello, there!</h1>
+<p>Nice to meet you.</p>
+</code>
+==== Creating web pages ====
+In this section, we will use Jade to build a simple but complete web page. It will serve as an introduction to some fundamental Jade language concepts.
+<file jade myPage.jade>
+doctype html
+html
+    head
+        title A Simple Site
+    body
+        h1 Hello there!
+        p Nice to meet you.
+</file>
+<file javascript buildMyPage.js>
+var jade = require('jade');
+var fs = require('fs');
+options = {
+    pretty: true
+};
+// Render an HTML page from a file written in Jade.
+var html = jade.renderFile('myPage.jade', options, function(err, html) {
+        if (err) {
+           throw(err);
+        }
+        return html;
+    });
+// Write HTML to a file.
+fs.writeFile('myPage.html', html, function(err) {
+    if (err) {
+        throw(err);
+    }
+});
+</file>
+output:<code>
+$ cat myPage.html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>A Simple Site</title>
+  </head>
+  <body>
+    <h1>Hello there!</h1>
+    <p>Nice to meet you.</p>
+  </body>
+</html>
+</code>
+The basic idea is that Jade uses a shorthand HTML syntax where indentation is used to nest elements.
+This should be enough to make you comfortable reading the [[http://jade-lang.com/reference/|Jade Language Reference]], after which you should be able to compose entire web pages in Jade.