Blade - HTML Template Compiler ============================== Blade is a HTML Template Compiler, inspired by Jade & Haml, implemented in JavaScript, so it will run on your microwave oven. It works like this... 1. Write up your template in Blade (which is a Jade-like language) 2. Use the Blade compiler to generate a Blade template (which is a JavaScript function) 3. Pass variables into your generated template to produce HTML or XML [View a simple example](#simple-example) Never write HTML again. Please. Blade

"Blade's blood is the key" :P Sorry... I had to... This is *NOT* the Blade templating engine developed by [Laravel](http://laravel.com/). Laravel Blade was added in Sept, 2011; whereas, I did not begin development on Blade until May, 2012. Nevertheless, I still blame Laravel for choosing the same name and for creating any confusion. :) Table of Contents ----------------- - [Why use Blade instead of Jade?](#why-use-blade-instead-of-jade) - [Features](#features) - [Project Status](#project-status) - [Installation](#installation) - [Language Syntax](#syntax) - [The Basics](#syntax) - [Functions](#functions) - [Dynamic File Includes](#dynamic-file-includes) - [Blocks](#blocks) - [API](#api) - [Browser Usage](#browser-usage) - [A Simple Example](#simple-example) - [Syntax Highlighting](#syntax-highlighting) for your favorite text editor - [Plugins](#plugins) - [Meteor Support](#meteor-support) - [Implementation Details](#implementation-details) - [Benchmarks](#benchmarks) - [License](#license) Why use Blade instead of Jade? ----------------------- - Jade is an ornamental stone. Blade is a badass vampire hunter. - **Client-side templates** can be served to the browser, no problem. See [Browser Usage](#browser-usage) and [Blade Middleware] (#blademiddlewaresourcepath-options) for more info. - **Meteor support** - Blade works with [Meteor](http://meteor.com/) 0.6.4 and Spark. See the [documentation below](#meteor-support). - **Compatibility** - The language syntax of Blade is very similar to Jade's. Jade is an awesome templating language, and if you are already familiar with it, getting started with Blade should take you very little time. - **[Smarter](#fileIncludeDetails) file includes** - Files compiled in Blade can be much smaller than Jade files when you are using file includes because file includes happen at runtime instead of at compile-time. If you re-use the same included file across multiple views, the included file does not need to be reloaded multiple times. - **[Blocks](#blocks) are more flexible.** We removed features from Jade like explicit template inheritance and then added features like blocks and parameterized blocks. You might find our idea of a block to be similar to Jade's, but just wait until you realize how much more flexible they are. - **Just [Functions](#functions), not mixins or partials.** In Blade, there are no "mixins" or partial templates. There are only functions, and they work just like regular JavaScript functions that you've come to know and love. You can put your functions into separate files and include them into other templates, you can take advantage of the `arguments` Array-like Object, or whatever you want! - **Other cool [features](#features)** For example, Blade provides built-in syntax to capture content rendered by a function and store it into a variable within your view template. This allows you to pass rendered HTML content to another function. Checkout the [list of features](#features) below for a more complete list of features ``` Jade vs. Blade ``` Jade

OK... it's admittedly not as funny as I thought it would be. But, I tried. Features -------- - Write extremely readable [short-hand HTML](#syntax) - Insert escaped and unescaped text and vanilla JavaScript code - Code and text are escaped by default for security/convenience - [Functions](#functions) (like Jade mixins) - [Dynamic file includes](#dynamic-file-includes) - [Regular blocks](#blocks) and [Parameterized blocks](#parameterized-blocks) (aids in supporting template inheritance) - [True client-side template support](##browser-usage) with caching, etc. - Supports Express.JS - just write `app.set("view engine", "blade");` - [HTML Comments and block comments](#comments) - [Text filters](#text-filters) - [String interpolation](#string-interpolation) - Nice error reporting to help you debug your broken templates - Command-line tool to compile/render templates (try `blade --help`) - [Meteor smart package](#meteor-support) - Write DOM [event handlers right into your views](#event-handlers) - Cool plugins (including [Live UI](https://github.com/bminer/node-blade/wiki/Live-UI-Blade-Plugin)) Project Status -------------- I'd say that Blade itself is **stable**. There are very few (if any) [known issues](https://github.com/bminer/node-blade/issues), and I think that Blade is ready for production environments. I use Blade for many of my projects. [Meteor support for Blade](#meteor-support) is a **work-in-progress**. The Meteor team has been changing the Templating API for Meteor significantly, and it is quite likely that any code that has been written for Blade + Meteor support will be very broken in the near future. If you use Blade with Meteor, please hang in there. Once Meteor 1.0 is released and the APIs are well-documented, I will work to integrate Blade with Meteor. If you find a bug, please [report it here] (https://github.com/bminer/node-blade/issues). If you include the Blade code that failed along with the expected HTML output, that is always splendid. Full stack traces for Errors are quite nice, too. By all means, please feel free to submit pull requests for new features, new tests, or whatever! For big changes, say ~100 lines of code, you might want to contact me first or submit an issue before getting started. Installation ------------ for Node (via npm): `sudo npm install -g blade` Runtime for Browsers: `wget https://raw.github.com/bminer/node-blade/master/lib/runtime.js` Minified runtime is about 7-8 KB, uncompressed. Using Blade in a Meteor project? Check out [Meteor support](#meteor-support). Syntax ------ ### Tags Like Jade, a tag is simply a word. For example, the string `html` will render to ``. You can have 'id's: ``` div#awesome ``` which renders as `

`. Any number of classes work, separated by a dot (`.`) ``` div.task-details.container ``` which renders as `

`. Tag attributes? Yep, they work pretty much like Jade, too. Even string [interpolation] (#interpolation) works. Put attributes in parenthesis, separate attributes with a comma, space, newline, or whatever. `a(href="/homepage", onclick="return false;")` renders as: ```html ``` You can also have line feeds or weird whitespace between attributes, just like in Jade. Whatever. This works, for example: ``` input( type="text" name="email" value="Your email here" ) ``` You can also put substitute an attribute value with vanilla JS code like this: `input(type="text" name="contact-"+name value=value)`. For example, if you passed the object `{name: "fred", value: "testing"}` to your view, the above would render to: `` You cannot put whitespace, commas, newlines, or parentheses in the vanilla JavaScript code, though. Blade uses these characters to separate each attribute or to end the tag definition. And, yes... the `class` attribute is handled with extra special care. Pass an array or string. Classes (delimited by ".") from before will be merged with the value of the `class` attribute. For example: `div#foo.bar.dummy(class="another dude")` renders as: `

` Boolean attributes are allowed, as well. If the attribute value is boolean `true`, then the attribute is set; if the attribute value is boolean `false`, then the attribute is ignored entirely. For example: `input(type="text" checked=true)` renders as: ``. Or... you can write it [HTML 5 style](http://dev.w3.org/html5/html-author/#empty-attr) like this: `input(type="text" checked)` which renders as: ``. div, div, div can get annoying... so, we can omit the tag specifier if we specify an id or some classes: ``` #foo .bar #this.is.cool ``` renders as: ```html

``` Blade just assumes anything without a tag name specifier is a `

` tag. Also, tags without matching ending tags like `` render properly. #### Escaping Blade keywords Finally, you can start a tag name with a backslash to escape Blade keywords. Normally, `include test` would include a file, but `\include test` renders as: ```xml test ``` This allows you to be flexible with tag names, so you are not restricted to rendering HTML, for example. You can render any XML document with Blade. ### Indenting Simply intent to put content inside of a tag. You can indent with any number of spaces or with a single tab character. The only rule is to be consistent within a given file. Jade gives you a lot of weird indent flexibility. Blade, by design, does not. ``` html head title Welcome body #content ``` renders as: ```html Welcome

``` ### Text Simply place content after the tag like this: ``` p This text is "escaped" by default. Kinda neat. ``` renders as: ```html

This text is "escaped" by default. Kinda neat.

``` Want unescaped text? Large blocks of text? Done. Start a line of text with a `|`. ``` p! This will be unescaped text. | How about a block? (this is "escaped", btw) Yep. It just works! Neato. ``` renders as: ```html

This will be unescaped text. How about a block? (this is "escaped", btw) Yep. It just works! Neato.

``` Rules are: - Text is escaped by default. - Want unescaped text? Precede with a `!` - Precede with a `=` to evaluate and output some JavaScript. - Large text block? Use `|` and indent properly. - Unescaped text block? Use `|!` or even just `!` works. - JavaScript code block? Use `|=` or even just `=` works. - Unescaped JavaScript code block? Yep. Use `|!=` or `!=`. - Newlines in text blocks are preserved. #### String Interpolation String interpolation is supported for text blocks (and text attributes and text filters). Use `#{var_name}` notation, and anything between the curly braces is treated as vanilla JavaScript code. For example, you can write: (caution: indents are **required** on line 4 even though it is blank) ``` p | I am just testing #{whatever + ", alright?"} Relax... ``` instead of writing the equivalent, but arguably less awesome... ``` p |= "I am just testing " + whatever + ", alright?" + "\n\n" + "Relax..." ``` Assuming a local variable `whatever` is passed to the template with value "Blade", both of the examples above will render to this: ```html

I am just testing Blade, alright? Relax...

``` Interpolation comes in two forms: escaped and unescaped. If you want escaped (i.e. the resulting string has `>`, `<`, `"`, and other HTML characters escaped), use `#{foo}`; if you want unescaped, use `!{foo}`. If you literally want to insert "#{foo}" in your text, just prepend with a backslash like this: `\#{foo}`. #### Whitespace between tags In Blade, whitespace is only added when it's explicitly needed. For example: ```blade input(type="text") input(type="text") ``` renders as: `` If you need something like... ` ` (notice the space between the elements), then you have some options... One way is to use a text block: ```blade input(type="text") | input(type="text") ``` Notice on line 2 that the `|` is followed by **two** spaces. Another way is to prepend a tag with a `<`: ```blade input(type="text") `: ```blade input>(type="text") input(type="text") ``` Whatever you like! ### Text filters Need `
` tags inserted? Use a built-in filter, perhaps? ``` p :nl2br How about some text with some breaks? Yep! It works! ``` renders as: ```html

How about some text with some breaks?

Yep! It works!

``` Built-in text filters include: - :nl2br - Escapes the content and converts newline characters to `
` - :cdata - Surrounds text like this: `` Text should not contain `]]>`. - :markdown (must have [markdown-js](https://github.com/evilstreak/markdown-js) installed) - :md (alias for :markdown) - :javascript - Generates a ` Page Title

Hello

``` Obviously, the example above is rather contrived, but it shows how blocks work. A more [realistic example of using blocks](#template-inheritance) is below. #### What happens if I define the same block more than once? You can re-define a block that has already been defined with another "block" statement. This completely destroys the previously defined block. Previously executed "append", "prepend", "replace", and "render" blocks do not affect the re-defined block. In summary... - Use the `block` keyword to mark where the block will go (block definition). - Use the `render` keyword to render the matching "parameterized" block. Do not use this on a regular block. - Use the `append` keyword to append to the matching block. - Use the `prepend` keyword to prepend to the matching block. - Use the `replace` keyword to replace the matching block. You may not render, append to, prepend to, or replace undefined blocks. If you do so, an error message will occur. When you define a block within a function, and you output the function's rendered content to a variable, the defined block will be destroyed immediately after the function call. ### Template Inheritance There is no `extends` keyword. Just use blocks and includes: layout.blade: ``` !!! 5 html head block title(pageTitle) title=pageTitle block scripts script(type="text/javascript" src="/js/jquery.min.js") script(type="text/javascript" src="/js/jquery-ui.min.js") block stylesheets body block body ``` homepage.blade: ``` include "layout.blade" render title("Homepage") replace block body h1 Hello, World ``` If you render layout.blade, you get: ```html ``` but if you render homepage.blade, you get: ```html Homepage

Hello, World

``` The idea here is that you can derive many pages in a website from a basic template. In this case, `layout.blade` provides the generic template for each page in your website. `homepage.blade` simply uses the layout and modifies some blocks to generate the actual page. ### Preserve and constant regions Preserve and constant regions are only useful when using a live page update engine. Anything in a "constant" region is marked by the live page update engine as a region that is not subject to re-rendering. Example of constant region (using Meteor): ``` - console.log("Rendering header") h1 This is a header constant - console.log("Rendering constant...") p The current user is: #{Session.get("user")} ``` In the above example, "Rendering constant..." will only be printed once to the console, even if the Session variable changes. "Preserve" regions can be used to preserve certain DOM elements during re-rendering, leaving the existing element in place in the document while replacing the surrounding DOM nodes. This means that re-rendering a template need not disturb text fields, iframes, and other sensitive elements it contains. Example of preserve region (using Meteor): ``` form preserve {"input[id]": function (node) {return node.id;}} label First Name input#firstName(type="text") label Last Name input#lastName(type="text") ``` The example above will preserve the `` DOM elements when the template is re-rendered. Notice that the code following the "preserve" keyword `{"input[id]": function (node) {return node.id;}}` is passed directly to the Landmark's "preserve" option (see [the Meteor documentation] (http://docs.meteor.com/#template_preserve) for more info). You must specify how elements in a preserve region are to be preserved. To do this, you need to tell Blade how to uniquely identify each element that you want to preserve in the block. In the example above, `` fields with `id` attributes are preserved, and their `id` is used to uniquely identify them. The following is an example of preserving a single element. Since there is only one element in this preserve block, identifying it with the `*` selector is acceptable. ``` preserve ["*"] input(type="text") ``` If the "preserve" keyword is not followed by any code, then nothing is preserved. ### Isolates Isolates are only useful when using a live page update engine. Creating an isolate ensures that if data dependencies relating only to that isolate are updated, then only the part of the template within isolate will be re-rendered. All other parts of the Blade template will *not* be re-rendered. Example (using Meteor): ``` - console.log("Rendering header...") h1 This is a header isolate p The current user is: #{Session.get("user")} ``` In the example above, "Rendering header..." will be printed to the console when the whole template is rendered, but if the reactive variable is updated using `Session.set("user", ...)`, only the isolate will be re-rendered. In this case, nothing will print to the console. Note: As with Blade functions, any [blocks](#blocks) defined within an isolate will be deleted and unaccessible outside the isolate block. See [Reactivity isolation](http://docs.meteor.com/#isolate) on the Meteor documentation for more details. ### Chunks Chunks are *no longer supported* as of Blade 3.0.0beta. You should use [isolates](#isolates) instead. API --- `var blade = require('blade');` ### blade.compile(string, [options,] cb) Compiles a Blade template from a string. - `string` is a string of Blade - `options` include: - `filename` - the filename being compiled (required when using [includes] (#dynamic-file-includes) or the `cache` option) - `cache` - if true, the compiled template will be cached (defaults to false) - `debug` - outputs debugging information to the console (defaults to false) - `minify` - if true, Blade generates a minified template without debugging information (defaults to true if `cache` option is set; false, otherwise) If [UglifyJS](https://github.com/mishoo/UglifyJS) is installed, Blade may automatically compress or prettify the template depending on whether `minify` is true or false. - `includeSource` - if true, Blade inserts the Blade source file directly into the compiled template, which can further improve error reporting, although the size of the template is increased significantly. (defaults to true if and only if `process.env.NODE_ENV` is "development" and minify is false; defaults to false, otherwise) - `doctypes` - an Object to specify additional doctypes or overwrite any built-in ones. This object is merged with `blade.Compiler.doctypes` - `selfClosingTags` - Array of self-closing tags to be used instead of `blade.Compiler.selfClosingTags` - `filters` - an Object to specify additional filters or overwrite any built-in ones. This object is merged with `blade.Compiler.filters` - `templateNamespace` - the name of the reserved variable in the view (defaults to two underscores: __). Other reserved names are [listed here](#variable-names-to-avoid) - `basedir` - the base directory where Blade templates are located. This option is primarily used by the Blade middleware to allow the Blade runtime to properly load file includes. - `middleware` - option reserved for the Blade middleware. Passing `true` tells the compiler that the template to be compiled is for client-side use, allowing it to mask the basedir (see issue #112 for details). - `cb` is a function of the form: `cb(err, tmpl)` where `err` contains any parse or compile errors and `tmpl` is the compiled template. If an error occurs, `err` may contain the following properties: - `message` - The error message - `expected` - If the error is a 'SyntaxError', this is an array of expected tokens - `found` - If the error is a 'SyntaxError', this is the token that was found - `filename` - The filename where the error occurred - `offset` - The offset in the string where the error occurred - `line` - The line # where the error occurred - `column` - The column # where the error occurred Note: if there is a problem with the Blade compiler, or more likely, if there is a syntax error with the JavaScript code in your template, Node.js will not provide any line number or other information about the error. See issue #40 for more details. You can render a compiled template by calling the function: `tmpl(locals, cb)` - `locals` are the local variables to be passed to the view template - `cb` is a function of the form `function(err, html)` where `err` contains any runtime errors and `html` contains the rendered HTML. In addition, a compiled template has these properties and methods: - `template` - a function that also renders the template but accepts 3 parameters: `tmpl.template(locals, runtime, cb)`. This simply allows you to use a custom runtime environment, if you choose to do so. - `filename` - the filename of the compiled template (if provided) - `dependencies` - an array of files that might be included by this template at runtime, relative to the path of this template - `unknownDependencies` - if true, this template uses *dynamic filename includes* and may include any file at any time. - `reldir` - the path to this template, relative to the base/root path - `toString()` - a function that converts the view template function into a string of JavaScript code. If you need a client-side template for example, you can use this function. [UglifyJS](https://github.com/mishoo/UglifyJS) is now used if you have it installed. ### blade.compileFile(filename, [options,] cb) Asynchronously compile a Blade template from a filename on the filesystem. - `filename` is the filename - `options` - same as `blade.compile` above, except `filename` option is always overwritten with the `filename` specified. There is also a `synchronous` option that will tell Blade to read and compile the file synchronously instead of asynchronously. - `cb` - same as `blade.compile` above ### blade.renderFile(filename, options, cb) Convenience function to compile a template and render it. - `filename` is the filename - `options` - same as `blade.compileFile` above. This object is also passed to the view, so it should also contain your view's local variables. A few [reserved local variables](#variable-names-to-avoid) are removed before passing the locals to the view. - `cb` - a function of the form `function(err, html)` ### blade.middleware(sourcePath, options) Express middleware for serving compiled client-side templates to the browser. For example, if you visit the URL "/views/homepage.blade" on your server, you can compile the view stored at `sourcePath + "/homepage.blade"` - `sourcePath` - the path on the server where your views are stored - `options` include: - `mount` - the URL path where you can request compiled views (defaults to "/views/") - `runtimeMount` - the URL path where the minified Blade runtime is served to the browser (defaults to "/blade/blade.js"). Use `null` to disable this functionality. - `pluginsMount` - the URL path where Blade plugins will be served to the browser (defaults to "/blade/plugins/"). Use `null` to disable this functionality. - `returnErrors` - if true, compilation errors are exposed to the client (i.e. passed to the callback function that was passed to `blade.Runtime.loadTemplate`); if false, compilation errors are passed to the [error-handling middleware] (http://expressjs.com/guide.html#error-handling). Defaults to `process.env.NODE_ENV == "development"` if unspecified. - `compileOptions` - options passed to `blade.compile()`. Defaults to: ```javascript { 'cache': process.env.NODE_ENV == "production", 'minify': process.env.NODE_ENV == "production", 'includeSource': process.env.NODE_ENV == "development" }; ```` ### blade.Compiler The compiler itself. It has some useful methods and properties. ### blade.Compiler.parse(string) Just generates the parse tree for the string. For debugging purposes only. Example using the API: ```javascript var blade = require('blade'); blade.compile("string of blade", options, function(err, tmpl) { tmpl(locals, function(err, html) { console.log(html); }); }); ``` Here is a sample Express application that uses Blade for server-side and client-side templates: ```javascript var express = require('express'), blade = require('blade'); var app = express.createServer(); app.use(blade.middleware(__dirname + '/views') ); //for client-side templates app.use(express.static(__dirname + "/public") ); //maybe we have some static files app.set('views', __dirname + '/views'); //tells Express where our views are stored app.set('view engine', 'blade'); //Yes! Blade works with Express out of the box! app.get('/', function(req, res, next) { res.render('homepage'); }); app.listen(8000); ``` Browser Usage ------------- The Blade runtime should work on every browser, and since Blade provides an Express middleware for serving compiled templates to the browser ([see above] (#blademiddlewaresourcepath-options)), rendering Blade templates in the browser is a breeze. Once you have the middleware setup, you can now serve your compiled Blade views to the client. Simply include the /blade/blade.js file in your `

			Stars	Issues	Version	Updated	Created	Size
	blade				3.3.1	7 years ago	12 years ago
	react				18.2.0	2 years ago	12 years ago

blade vs react

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past