` 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 `attrs` attribute allows attributes to be dynamically added to an element at runtime. The value of the 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!
```
## Comments
Standard HTML comments can be used to add comments to your template. The HTML comments will not show up in the rendered HTML.
Example comments:
```html
Hello
```
If you would like for your HTML comment to show up in the final output then you can use the custom `html-comment` tag:
```html
This is a comment that *will* be rendered
Hello
```
Output:
```html
Hello
```
## Helpers
Since Marko 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.marko_:
```html
${util.reverse('reverse test')}
```
## Custom Tags and Attributes
Marko supports extending the language with custom tags and attributes. A custom tag or a custom attribute __must have at least one dash__ to indicate that is not part of the standard HTML grammar.
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 [Custom Taglibs](#custom-taglibs) section below.
## Async Taglib
The async taglib allows portions of your template to be rendere asynchronously. An asynchronous fragment can be bound to a function that accepts an "args" objects and callback argument. When the data provider function completes and invokes the callback with the resulting data, the body of the async fragment is then rendered with the asynchronous data assigned to the specified variable. Asynchronous fragments allow parts of your page to render out-of-order while still providing the final HTML in the correct order.
Example:
```javascript
template.render({
userProfileDataProvider: function(arg, callback) {
var userId = arg.userId;
userProfileService.getUserProfile(userId, callback);
}
}, ...);
```
```html
-
First name: ${userProfile.firstName}
-
Last name: ${userProfile.lastName}
-
Email address: ${userProfile.email}
```
For more details, please see [https://github.com/raptorjs/marko-async](https://github.com/raptorjs/marko-async).
## Layout Taglib
Marko provides a `layout` taglib to support separating out layout from content. The usage of of the `layout` taglib is shown in the sample code below:
_default-layout.marko:_
```html
<layout-placeholder name="title"/>
Default Footer
```
_Usage of `default-layout.marko`:_
```html
My Page
BODY CONTENT
```
For more details, please see [https://github.com/raptorjs/marko-layout](https://github.com/raptorjs/marko-layout).
# Custom Taglibs
## Tag Renderer
Every tag should be mapped to a "renderer". A renderer is just a function that takes two arguments (`data` and `out`). The `data` argument is an arbitrary object that contains the data for the renderer. The `out` argument is an [asynchronous rendering out](https://github.com/raptorjs/async-writer) that wraps an output stream. Output can be produced using `out.write(someString)` There is no class hierarchy or tie-ins to Marko when implementing a tag renderer. A simple tag renderer is shown below:
```javascript
module.exports = function(data, out) {
out.write('Hello ' + data.name + '!');
}
```
If, and only if, a tag has nested content, then a special `invokeBody` method will be added to the `data` object. If a renderer wants to render the nested body content then it must call the `invokeBody` method. For example:
```javascript
module.exports = function(data, out) {
out.write('BEFORE BODY');
if (data.invokeBody) {
data.invokeBody();
}
out.write('AFTER BODY');
}
```
A tag renderer should be mapped to a custom tag by creating a `marko-taglib.json` as shown in the next few sections.
## marko-taglib.json
### Sample Taglib
```json
{
"tags": {
"my-hello": {
"renderer": "./hello-renderer",
"attributes": {
"name": "string"
}
}
}
}
```
### Defining Tags
Tags can be defined by adding a `"tags"` property to your `marko-taglib.json`:
```json
{
"tags": {
"my-hello": {
"renderer": "./hello-renderer",
"attributes": {
"name": "string"
}
},
"my-foo": {
"renderer": "./foo-renderer",
"attributes": {
"*": "string"
}
}
}
}
```
Every tag should be associated with a renderer. When a custom tag is used in a template, the renderer will be invoked at render time to produce the HTML/output.
#### Defining Attributes
If you provide attributes then the Marko compiler will do validation to make sure only the supported attributes are provided. A wildcard attribute (`"*"`) allows any attribute to be passed in. Below are sample attribute definitions:
_Multiple attributes:_
```javascript
"attributes": {
"message": "string", // String
"my-data": "expression", // JavaScript expression
"*": "string" // Everything else will be added to a special "*" property
}
```
### Scanning for Tags
Marko supports a directory scanner to make it easier to maintain a taglib by introducing a few conventions:
* The name of the tag directory will be the name of the tag
* One tag per directory
* All tag directories should be direct children of a parent directory
* Every tag directory must contain a `renderer.js` that is used as the tag renderer or, alternatively, a `template.marko`
* Each tag directory may contain a `marko-tag.json` file or the tag definition can be embedded into `renderer.js`
With this approach, `marko-taglib.json` will be much simpler:
```json
{
"tags-dir": "./components"
}
```
Given the following directory structure:
* __components/__
* __my-hello/__
* renderer.js
* __my-foo/__
* template.marko
* __my-bar/__
* renderer.js
* marko-tag.json
* marko-taglib.json
The following three tags will be exported:
* ``
* ``
* ``
Directory scanning only supports one tag per directory and it will only look at directories one level deep. The tag definition can be embedded into the `renderer.js` file or it can be put into a separate `marko-tag.json`. For example:
_In `renderer.js`:_
```javascript
exports.tag = {
"attributes": {
"name": "string"
}
}
```
_In `marko-tag.json`:_
```javascript
{
"attributes": {
"name": "string"
}
}
```
_NOTE: It is not necessary to declare the `renderer` since the scanner will automatically use `renderer.js` as the renderer._
### Nested Tags
It is often necessary for tags to have a parent/child or ancestor/descendent relationship. For example:
```html
```
Marko supports this by leveraging JavaScript closures in the compiled output. A tag can introduce scoped variables that are available to nested tags. This is shown in the sample `marko-taglib.json` below:
```json
{
"tags": {
"ui-tabs": {
"renderer": "./tabs-tag",
"var": "tabs"
},
"ui-tab": {
"renderer": "./tab-tag",
"import-var": {
"tabs": "tabs"
},
"attributes": {
"title": "string"
}
}
}
}
```
In the above example, the `` tag will introduce a scoped variable named `tabs` that is then automatically imported by the nested `` tags. When the nested `` tags render they can use the scoped variable to communicate with the renderer for the `` tag.
The complete code for this example is shown below:
_components/tabs/renderer.js:_
```javascript
var templatePath = require.resolve('./template.marko');
var template = require('marko').load(templatePath);
module.exports = function render(data, out) {
var nestedTabs = [];
// Invoke the body function to discover nested tags
data.invokeBody({ // Invoke the body with the scoped "tabs" variable
addTab: function(tab) {
tab.id = tab.id || ("tab" + tabs.length);
nestedTabs.push(tab);
}
});
// Now render the markup for the tabs:
template.render({
tabs: nestedTabs
}, out);
};
```
_components/tab/renderer.js:_
```javascript
module.exports = function render(data, out) {
// Register with parent but don't render anything
data.tabs.addTab(data);
};
```
_components/tabs/template.marko:_
```html
```
## Taglib Discovery
Given a template file, the `marko` module will automatically discover all taglibs by searching relative to the template file. The taglib discoverer will search up and also look into `node_modules` to discover applicable taglibs.
As an example, given a template at path `/my-project/src/pages/login/template.marko`, the search path will be the following:
1. `/my-project/src/pages/login/marko-taglib.json`
2. `/my-project/src/pages/login/node_modules/*/marko-taglib.json`
3. `/my-project/src/pages/marko-taglib.json`
4. `/my-project/src/pages/node_modules/*/marko-taglib.json`
5. `/my-project/src/marko-taglib.json`
6. `/my-project/src/node_modules/*/marko-taglib.json`
7. `/my-project/marko-taglib.json`
8. `/my-project/node_modules/*/marko-taglib.json`
# FAQ
__Question:__ _Is Marko ready for production use?_
__Answer__: Yes, Marko has been battle-tested at [eBay](http://www.ebay.com/) and other companies for well over a year and has been designed with high performance, scalability, security and stability in mind.
__Question:__ _Can templates be compiled on the client?_
__Answer__: Possibly, but it is not recommended and it will likely not work in older browsers. The compiler is optimized to produce small, high performance compiled templates, but the compiler itself is not small and it comes bundled with some heavyweight modules such as a [JavaScript HTML parser](https://github.com/fb55/htmlparser2). In short, always compile your templates on the server. The [RaptorJS Optimizer](https://github.com/raptorjs/optimizer) is recommended for including compiled templates as part of a web page.
__Question:__ _Which web browsers are supported?_
__Answer__: The runtime for template rendering is supported in all web browsers. If you find an issue please report a bug.
__Question:__ _How can Marko be used with Express?_
__Answer__: The recommended way to use Marko with Express is to bypass the Express view engine and instead have Marko render directly to the response stream as shown in the following code:
```javascript
var template = require('marko').load(require.resolve('./template.marko'));
app.get('/profile', function(req, res) {
template
.render({
name: 'Frank'
}, res);
});
```
With this approach, you can benefit from streaming and there is no middleman (less complexity).
Alternatively, you can use the streaming API to produce an intermediate stream that can then be piped to the response stream as shown below:
```javascript
var template = require('view-engine').load(require.resolve('./template.marko'));
app.get('/profile', function(req, res) {
template.stream({
name: 'Frank'
})
.pipe(res);
});
```
__Question:__ _What is the recommended directory structure for templates and "partials"_
__Answer__: Your templates should be organized just like all other JavaScript modules. You should put your templates right next to the code that refers to them. That is, do not create a separate "templates" directory. For a sample Express app that uses Marko, please see [marko-express](https://github.com/raptorjs/raptor-samples/tree/master/marko-express).
__Question:__ _How is Marko related to [RaptorJS](http://raptorjs.org)?_
__Answer__: Marko is one of the modules that is part of the RaptorJS toolkit. It used to be a submodule, but now it has been split out into its own top-level Node.js module (for history, please see the [RaptorJS 3 Plan](https://github.com/raptorjs/raptorjs/wiki/RaptorJS-3-Plan) page).
# Further Reading
* [Marko versus Dust](http://psteeleidem.com/marko-versus-dust/)
* [The JavaScript Templating Landscape](http://psteeleidem.com/the-javascript-templating-landscape/)
# Discuss
Please post questions or comments on the [RaptorJS Google Groups Discussion Forum](http://groups.google.com/group/raptorjs).
# Contributors
* [Patrick Steele-Idem](https://github.com/patrick-steele-idem) (Twitter: [@psteeleidem](http://twitter.com/psteeleidem))
* [Phillip Gates-Idem](https://github.com/philidem/) (Twitter: [@philidem](https://twitter.com/philidem))
# Contribute
Pull Requests welcome. Please submit Github issues for any feature enhancements, bugs or documentation problems.
# License
Apache License v2.0