diff --git a/README.md b/README.md index f2ccb9af7..0edb0e2a6 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,10 @@ raptor-templates +**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* + - [Overview](#overview) -- [Sample Templates](#sample-templates) +- [Sample Template](#sample-template) - [Installation](#installation) - [Usage](#usage) - [Template Rendering](#template-rendering) @@ -14,6 +16,28 @@ raptor-templates - [Using the RaptorJS Optimizer](#using-the-raptorjs-optimizer) - [Using Browserify](#using-browserify) - [Template Compilation](#template-compilation) +- [Language Guide](#language-guide) + - [Template Directives Overview](#template-directives-overview) + - [Text Replacement](#text-replacement) + - [Expressions](#expressions) + - [Variables](#variables) + - [Conditionals](#conditionals) + - [if...else-if...else](#ifelse-ifelse) + - [choose…when…otherwise](#choose…when…otherwise) + - [Shorthand conditionals](#shorthand-conditionals) + - [Looping](#looping) + - [for](#for) + - [Macros](#macros) + - [def](#def) + - [invoke](#invoke) + - [Structure Manipulation](#structure-manipulation) + - [attrs](#attrs) + - [content](#content) + - [replace](#replace) + - [strip](#strip) + - [Helpers](#helpers) + - [Custom Tags and Attributes](#custom-tags-and-attributes) + - [Taglibs](#taglibs) @@ -21,7 +45,7 @@ raptor-templates # Overview Raptor Templates is an asynchronous, high performance, _HTML-based_ templating language that can be used in Node.js or in the browser. The directives in Raptor Template files are less obtrusive and more powerful because the templating language understands the structure of the HTML document. -# Sample Templates +# Sample Template A basic template with text replacement, looping and conditionals is shown below: ```html Hello ${data.name}! @@ -36,6 +60,32 @@ Hello ${data.name}! ``` +If rendering using the following input data: +```javascript +{ + colors: ["red", "green", "blue"] +} +``` + +The output of rendering the above sample template would be the following: +```html + +``` + +For comparison, given the following input data consisting of an empty array of colors: + +```javascript +{ + colors: [] +} +``` + +The output would be the following: + +```html +
No colors!
+``` + Raptor Templates also supports custom tags so you can easily extend the HTML grammar to support things like the following: ```html @@ -113,7 +163,7 @@ You can then bundle up the above program for running in the browser using either ### Using the RaptorJS Optimizer -The `raptor-optimizer` CLI can be used to generate a browser bundle that includes all application modules and all referenced Raptor Template files using a command similar to the following: +The `raptor-optimizer` CLI can be used to generate resource bundles that includes all application modules and all referenced Raptor Template files using a command similar to the following: ```bash # First install the raptor-optimizer npm install raptor-optimizer --global @@ -121,6 +171,15 @@ npm install raptor-optimizer --global raptor-optimizer --main run.js --name my-page ``` +This will produce a JSON file named `build/my-page.html.json` that contains the HTML markup that should be used to include the required JavaScript and CSS resources that resulted from the page optimization. + +Alternatively, you can inject the HTML markup into a static HTML file using the following command: + +```bash +raptor-optimizer --main run.js --name my-page --inject-into my-page.html +``` + + ### Using Browserify The `rhtmlify` transform for browserify must be enabled in order to automatically compile and include referenced Raptor Template files. @@ -164,6 +223,450 @@ require('raptor-templates/compiler').compileFile(path, function(err, src) { }); ``` +# Language Guide + +## Template Directives Overview + +Almost all of the Raptor templating directives can be used as either an attribute or as an element. For example: + +_Applying directives using attributes:_ +```html + + + + +
+ No colors! +
+``` + +_Applying directives using elements:_ +```html + + + + + + + +
+ No colors! +
+ +``` + +The disadvantage of using elements to control structural logic is that they change the nesting of the elements which can impact readability. For this reason it is often more suitable to use attributes. + +## Text Replacement + +Dynamic text is supported using either `$` or `${ +``` + +## Expressions + +Wherever expressions are allowed, they are treated as JavaScript expressions copied out to the compiled template verbatim. However, you can choose to use alternate versions of the following JavaScript operators: + +JavaScript Operator | Raptor Equivalent +------------------- | ----------------- +`&&` | `and` +`||` | `or` +`===` | `eq` +`!==` | `ne` +`<` | `lt` +`>` | `gt` +`<=` | `le` +`>=` | `ge` + +## Variables + +Input data passed to a template is made available using a special `data` variable. It's possible to declare your own variables as shown in the following sample code: + +```html + +``` + +## Conditionals + +### if...else-if...else + +Any element or fragment of HTML can be made conditional using the c:if, c:else-if or c:else directive. + +_Applied as an attribute:_ +```html + +
+ Hello World +
+ + +
+ A +
+
+ B +
+
+ C +
+
+ Something else +
+``` + +_Applied as an element:_ +```html + + + +
+ Hello World +
+ + + + +
+ A +
+ + +
+ B +
+ + +
+ C +
+ + +
+ Something else +
+ +``` + +### choose…when…otherwise + +The `c:choose` directive, in combination with the directives `c:when` and `c:otherwise` provides advanced conditional processing for rendering one of several alternatives. The first matching `c:when` branch is rendered, or, if no `c:when` branch matches, the `c:otherwise` branch is rendered. + +_Applied as an attribute:_ +```html + + +
A
+ + +
B
+ + +
Something else
+ + +``` + +_Applied as an element:_ +```html + +
+ A +
+
+ B +
+
+ Something else +
+ +``` + +### Shorthand conditionals + +Shorthand conditionals allow for conditional values inside attributes or wherever expressions are allowed. Shorthand conditionals are of the following form: +`{?;[;]}` + +For example: + +```html +
Hello
+``` +With a value of `true` for `active`, the output would be the following: + +```html +
Hello
+``` + +With a value of `false` for `active`, the output would be the following: + +```html +
Hello
+``` + +_NOTE: If the expression inside an attribute evaluates to `null` or an empty string then the attribute is not included in the output._ + +As shown in the previous example, the "else" block for shorthand conditionals is optional. The usage of an else block is shown below: + +```html +
Hello
+``` + +With a value of `false` for `active`, the output would be the following: + +```html +
Hello
+``` + +## Looping + +### for + +Any element can be repeated for every item in an array using the `c:for` directive. The directive can be applied as an element or as an attribute. + +_Applied as an attribute:_ +```html +
    +
  • ${item}
    • +
+``` + +_Applied as an element:_ +```html +
    + +
  • ${item}
    • +     +
+``` +Given the following value for items: +```javascript +["red", "green", "blue"] +``` +The output would be the following: +```html +
    +
  • red
    • +
  • green
    • +
  • blue
    • +
+``` + +## Macros + +Macros allow for reusable fragments within an HTML template. Macros can also be parameterized. A macro can be defined using the `` directive and a macro when defining a macro. + +### def + +The `` directive can be used to define a reusable function within a template. + +```html + + Hello $name! You have $count new messages. + +``` + +The above macro can then be invoked as part of any expression. Alternatively, the [``](#invoke) directive can be used invoke a macro function using named attributes. The following sample template shows how to use macro functions inside expressions: + +```html + + Hello $name! You have $count new messages. + + +

+ ${greeting("John", 10)} +

+

+ ${greeting("Frank", 20)} +

+``` + +### invoke + +The `` directive can be used to invoke a function defined using the `` directive or a function that is part of the input to a template. The `` directive allows arguments to be passed using element attributes, but that format is only supported for functions that were previously defined using the `` directive. + +```html + + Hello ${name}! You have ${count} new messages. + + + + +``` + +The output for the above template would be the following: + +```html +

+ Hello John! You have 10 new messages. +

+

+ Hello Frank! You have 20 new messages. +

+``` + +_NOTE: By default, the arguments will be of type "string" when using `.` However, argument attributes support JavaScript expressions which allow for other types of arguments. Example: +```html +count="10" +count="${10}" +``` + + +## Structure Manipulation + +### attrs + +The `c:attrs` attribute allows attributes to be dynamically added to an element at runtime. The value of the c:attrs attribute should be an expression that resolves to an object with properties that correspond to the dynamic attributes. For example: + +```html +
+ Hello World! +
+``` + +Given the following value for the `myAttrs` variable: + +```javascript +{style: "background-color: #FF0000;", "class": "my-div"} +``` + +The output would then be the following: + +```html +
+ Hello World! +
+``` + +### content + +This directive replaces any nested content with the result of evaluating the expression: + +```html +
    +
  • Hello
    • +
+``` + +Given a value of `"Bye!"` for the value of `myExpr`, the output of the above template would be the following: + +```html +
    +
  • Bye!
    • +
+``` + +### replace + +This directive replaces the element itself with the result of evaluating the expression: + +```html +
+ Hello +
+``` + +Given a value of "Bye!" for the value of "myExpr", the output of the above template would be the following: + +```html +
+ Bye! +
+``` + +### strip + +This directive conditionally strips the top-level element from the output. If the expression provided as the attribute value evaluates to true then the element is stripped from the output: + +```html +
+ Hello +
+``` + +_Output:_ + +```html +
+ Hello +
+``` + +## Helpers + +Since Raptor Template files compile into CommonJS modules, any Node.js module can be "imported" into a template for use as a helper module. For example, given the following helper module: + +_src/util.js_: +```javascript +exports.reverse = function(str) { + var out = ""; + for (var i=str.length-1; i>=0; i--) { + out += str.charAt(i); + } + return out; +}; +``` + +The above module can then be imported into a template as shown in the following sample template: + +_src/template.rhtml_: +```html + + +
${util.reverse('reverse test')}
+``` + +The `c:require` directive is just short-hand for the following: +```html + +
${util.reverse('reverse test')}
+``` + +## Custom Tags and Attributes + +Raptor Templates supports extending the language with custom tags and attributes. A custom tag or a custom attribute should be prefixed with a namespace that matches a module name that exports the custom tag or custom attribute. Alternatively, the namespace can be a shorter alias defined by the taglib. + +Below illustrates how to use a simple custom tag: + +```html +
+ +
+``` + +The output of the above template might be the following: + +```html +
+ Hello World! +
+``` + +For information on how to use and create taglibs, please see the [Taglibs](#taglibs) section below. + +## Taglibs + +TODO \ No newline at end of file