react-templates

[![NPM version][npm-image]][npm-url] [![build status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url] # React Templates Lightweight templates for [React](http://facebook.github.io/react/index.html). * No runtime libraries. No magic. Simply precompile your way to clear React code. * Easy syntax that's similar to HTML, supported by most IDEs. * Clear separation of presentation and logic - almost zero HTML in component files. * Declarative coding ensures that the HTML that you write and the HTML you inspect look nearly identical. * Supports AMD, CommonJS, ES6, Typescript and globals. ## How does it work React Templates compiles an *.rt file (react template file - an extended HTML format) into a JavaScript file. This file, which uses AMD syntax, returns a function. When invoked, this function returns a virtual React DOM based on React.DOM elements and custom user components.

A common use case would be that a regular React component would require a JavaScript file generated from a template, and then perform `func.apply(this)`, causing the template to have that component as its context. ## Playground http://wix.github.io/react-templates/ ## Yeoman generator https://github.com/wix/generator-react-templates ## Hello react-templates Here's a sample Hello project:
https://github.com/wix/hello-react-templates Here's a sample Hello project with webpack, es6 and hot reload:
https://github.com/wix/react-templates-transform-boilerplate ## IntelliJ / WebStorm plugin http://plugins.jetbrains.com/plugin/7648 ## Basic concepts for React templates * Any valid HTML (including comments) is a template * {} to identify JS expression * Built-in directives: * [rt-if](#rt-if) * [rt-repeat](#rt-repeat) * [rt-scope](#rt-scope) * [rt-props](#rt-props) * [rt-class](#rt-class) * [rt-import](#rt-import) * ~~rt-require~~ (deprecated, use rt-import) * [rt-template](#rt-template) * [rt-include](#rt-include) * [rt-pre](#rt-pre) * [rt-virtual](#rt-virtual) * [styles](#styles) * [event handlers](#event-handlers) ## Why not use JSX? Some love JSX, some don't. We don't. More specifically, it seems to us that JSX is only a good fit for components with very little HTML inside. And this can be accomplished by creating DOM elements in code. Also, we like to separate code and HTML because it just feels right. ## Installation You can install react-templates using npm: ```shell npm install react-templates -g ``` ## Usage ```shell rt [file.rt|dir]* [options] ``` See more on CLI usage [here](https://github.com/wix/react-templates/blob/gh-pages/docs/cli.md). In most cases, this package will be wrapped in a build task, so CLI will not be used explicitly: * Grunt: [grunt-react-templates](https://github.com/wix/grunt-react-templates) * Gulp: [gulp-react-templates](https://github.com/wix/gulp-react-templates) * Broccoli: [broccoli-react-templates](https://github.com/kraftwer1/broccoli-react-templates) * Browserify plugin: [react-templatify](https://www.npmjs.com/package/react-templatify) * Webpack loader : [react-templates-loader](https://github.com/AlexanderPavlenko/react-templates-loader) ### Use React Templates for Native Apps? You can get all the react templates functionality and more. [Click here for more info](https://github.com/wix/react-templates/blob/gh-pages/docs/native.md) # Template directives and syntax ## Any valid HTML is a template Any HTML that you write is a valid template, except for inline event handlers ("on" attributes). See the "event handlers" section below for more information. ## {} to identify JavaScript expressions To embed JavaScript expressions in both attribute values and tag content, encapsulate them in {}. If this is done inside an attribute value, the value still needs to be wrapped in quotes. For directives (see below), {} are not used. ###### Sample: ```html {this.state.linkText} ``` ###### Compiled: ```javascript define([ 'react', 'lodash' ], function (React, _) { 'use strict'; return function () { return React.DOM.a({ 'href': this.state.linkRef }, this.state.linkText); }; }); ``` ## rt-if This lets you add conditions to a subtree of HTML. If the condition evaluates to true, the subtree will be returned; otherwise, it will not be calculated. It is implemented as a ternary expression. ###### Sample: ```html ``` ###### Compiled: ```javascript define([ 'react', 'lodash' ], function (React, _) { 'use strict'; return function () { return this.state.resultCode === 200 ? React.DOM.div({}, 'Success!') : null; }; }); ``` ## rt-repeat Repeats a DOM node with its subtree for each item in an array. The syntax is `rt-repeat="itemVar, indexVar in arrayExpr"`, where the element, `itemVar`, will be available in JavaScript context, and an `itemVarIndex` will be created to represent the index of the item. By using this naming scheme, repeated expressions have access to all levels of nesting. It is also possible to declare a custom index variable using the syntax `rt-repeat="itemVar, indexVar in arrayExpr"`, in which case the index variable will be `indexVar`. ###### Sample: ```html ``` ###### Compiled: ```javascript define([ 'react', 'lodash' ], function (React, _) { 'use strict'; function repeatMyNum1(myNum, myNumIndex) { return React.DOM.div({}, myNumIndex + '. ' + myNum); } return function () { return _.map(this.getMyNumbers(), repeatMyNum1.bind(this)); }; }); ``` ## rt-virtual This directive creates as a virtual node, which will not be rendered to the DOM, but can still be used as a root for directives, e.g. `rt-if` and `rt-repeat`. ###### Sample: For instance, to repeat several nodes at once without a shared root for each instance: ```html

• {n}
• {n*2}

``` ##### Compiled: ```javascript define([ 'react/addons', 'lodash' ], function (React, _) { 'use strict'; function repeatN1(n, nIndex) { return [ React.createElement('li', {}, n), React.createElement('li', {}, n * 2) ]; } return function () { return React.createElement.apply(this, [ 'ul', {}, _.map([ 1, 2, 3 ], repeatN1.bind(this)) ]); }; }); ``` ## rt-scope This directive creates a new JavaScript scope by creating a new method and invoking it with its current context. The syntax is `rt-scope="expr1 as var1; expr2 as var2`. This allows for a convenient shorthand to make the code more readable. It also helps to execute an expression only once per scope. ###### Sample: ```html ``` ###### Compiled: ``` … ``` Subsequent expressions may reference preceding variables, since generated code declares each alias as a `var` (as opposed to a function parameter, which get bound to formal parameter names only after evaluation), so you can do stuff like ```html ``` ###### Compiled: ``` … ``` ## rt-include Optionally choose to extract static contents out of rt files.
rt-include is a "macro" that takes a text file (e.g svg/html/xml) and injects it into the file as if it was part of the original markup. ###### Sample: given `main.rt`: ```html ``` and `my-icon.svg`: ```html ``` is equivalent to: ```html ``` ## rt-pre When using the option `--normalize-html-whitespace` it allows to override the whitespace removal behaviour on a specific tag. ###### Sample: given `main.rt`: ```html here repeating whitespaces are preserved even if --normalize-html-whitespace is on here repeating whitespaces are removed if --normalize-html-whitespace is on ``` `rt-pre` is applied automatically on `

` and `