Skip to content

Commit

Permalink
Docs: readme updated (#390 fixed)
Browse files Browse the repository at this point in the history
  • Loading branch information
@miripiruni
miripiruni committed Dec 5, 2016
1 parent 79b3e4e commit 3e76fc1
Showing 1 changed file with 111 additions and 103 deletions.
214 changes: 111 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# BEM-XJST
# bem-xjst

Declarative template engine for the browser and server.

Expand All @@ -8,152 +8,160 @@ Declarative template engine for the browser and server.
[![devDependency Status](https://david-dm.org/bem/bem-xjst/dev-status.svg)](https://david-dm.org/bem/bem-xjst#info=devDependencies)
[![Coverage Status](https://coveralls.io/repos/github/bem/bem-xjst/badge.svg?branch=coverage-badge)](https://coveralls.io/github/bem/bem-xjst?branch=coverage-badge)

[Online demo](https://bem.github.io/bem-xjst/). Twitter account: [@bemxjst](https://twitter.com/bemxjst)
## Features

## Installation
### Templates are extensible: they can be redefined or extended

Install it by [npm](https://npmjs.org): `npm install bem-xjst`.

## Usage

### As a node.js module
Not only by simple redefined via new templates, but using ‘modes’ you can redefine or extend only paticular part of output. For example only tag name or tag content.

```js
var bemxjst = require('bem-xjst');
var bemhtml = bemxjst.bemhtml;

// Add templates
var templates = bemhtml.compile(function() {
block('b').content()('yay');
});
block('link').tag()('span');
// The template set tag to `span` for all `link` blocks.
// And ‘mode’ tag() can be redefined if any condition passed.

// Apply templates to data context in BEMJSON format and get result as HTML string
var html = templates.apply({ block: 'b' });
// Result in html: <div class="b">yay</div>
block('link').match(function(node, ctx) { return ctx.url; }).tag()('a');
// The template set tag to ‘a’ only if block ‘link’ have `url` field.
// Otherwise tag will be ‘span’ as previous template says.
```

### Templates are written using [pattern matching](/docs/en/7-runtime.md#how-templates-are-selected-and-applied) for the values and structure of input data

```js
var bemxjst = require('bem-xjst');
var bemtree = bemxjst.bemtree;
block('list').tag()('ul');
block('item').tag()('li');
```

// Add templates
var templates = bemtree.compile(function() {
block('b').content()('yay');
});
For these two declarative-style templates we can apply data:
```js
{
block: 'list',
content: [
{
block: 'item',
content: {
block: 'list',
content: [
{ block: 'item', content: 'CSS' },
{ block: 'item', content: 'HTML' }
]
}
},
{
block: 'item',
content: {
block: 'list',
content: [
{ block: 'item', content: 'JS' }
]
}
}
]
}
```

// Apply templates to data context in BEMJSON format and get result as BEMJSON
var bemjson = templates.apply({ block: 'b' });
// Result in bemjson: { block: 'b1', content: 'yay' }
The result is:

```html
<ul class="list">
<li class="item">
<ul class="list">
<li class="item">CSS</li>
<li class="item">HTML</li>
</ul>
</li>
<li class="item">
<ul class="list">
<li class="item">JS</li>
</ul>
</li>
</ul>
```

### As a CLI tool
As you can see templates as simple as CSS.

CLI can be used for creation bundles. See [Compiler generate](#generatestring-or-function).
### Traverses input data by default

```bash
$ bem-xjst --help
In example above you may have noticed that bem-xjst automaticaly Traverses input data by `content` fields. This behaviour is default feature of bem-xjst.

Usage:
bem-xjst [OPTIONS] [ARGS]
### Built-in rendering behavior is used by default, even if the user didn’t add templates

You probably already guessed that bem-xjst will give you result, even if no template has been added. For example from above it will be:

Options:
-h, --help : Help
-v, --version : Version
-e, --engine : Engine name (default: bemhtml, supported: bemhtml | bemtree)
-i INPUT, --input=INPUT : File with user templates (default: stdin)
-o OUTPUT, --output=OUTPUT : Output bundle file (default: stdout)
```html
<div class="list">
<div class="item">
<div class="list">
<div class="item">CSS</div>
<div class="item">HTML</div>
</div>
</div>
<div class="item">
<div class="list">
<div class="item">JS</div>
</div>
</div>
</div>
```

## API
That is more than half the work ;) You will add the salt (couple of templates for tags) and the HTML-soup is very tasty!

### Compiler

#### `.compile(string or function)`
### Written in JavaScript, so the entire JavaScript infrastructure is available for checking code quality and conforming to best practices

Compile input templates and return `templates` object.
(See documentation below for its methods)
Since templates is just JS-code you can use precommit hooks, automatic syntax validator from your editor and tools like jshint/eslint.

#### `.generate(string or function)`
### Runs on a server and client

Generate output JavaScript code that might be transferred and executed in
browser to get the `templates` object.
In any browser (with JS) you can use bem-xjst as well as in any JavaScript VM. We support Node.JS v0.10 and higher.

### templates

#### `.apply(context)`
## Tell me more

Run compiled templates on specified input context. Return resulting HTML output.
See documentation:

#### `.compile(string or function)`
1. [About](/blob/master/docs/en/1-about.md)
2. [Quick Start](/blob/master/docs/en/2-quick-start.md)
3. [API: usage, methods, signatures and etc](/blob/master/docs/en/3-api.md)
4. [Input data format](/blob/master/docs/en/4-data.md): BEMJSON
5. [Templates syntax](/blob/master/docs/en/5-templates-syntax.md)
6. [Templates context](/blob/master/docs/en/6-templates-context.md)
7. [Runtime](/blob/master/docs/en/7-runtime.md): processes for selecting and applying templates

Add more BEM templates to the `templates` instance. Might be called in runtime
to deliver more blocks declarations to the client.

```js
var bemxjst = require('bem-xjst');
var templates = bemxjst.bemhtml.compile(function() {
block('b').tag()('a');
});
## Try it

templates.apply({ block: 'b' });
// Return '<a class="b"></a>'
To use bem-xjst, you need [Node.js](https://nodejs.org/) v0.10 or later, and [npm](https://www.npmjs.com/).

templates.compile(function() {
block('b').content()('Hi, folks!');
});
Install:

templates.apply({ block: 'b' });
// Return '<a class="b">Hi, folks!</a>'
```bash
npm install bem-xjst
```

#### `.BEMContext`
Copy-paste [example from quick start](https://github.com/bem/bem-xjst/blob/master/docs/en/2-quick-start.md#basic-example) or see [simple example](https://github.com/bem/bem-xjst/tree/master/examples/simple-page) from repository.

Constructor of the `this` object available in template bodies. Might be amended
to expose some functionality to the templates, or to add [_flush][1] method.

```js
var bemxjst = require('bem-xjst');
var templates = bemxjst.bemhtml.compile('');

templates.BEMContext.prototype.myField = 'opa';
# Is bem-xjst used in production?

templates.compile(function() {
block('b').content()(function() {
return this.myField;
});
});

templates.apply({ block: 'b' });
// Return '<div class="b">opa</div>'
```
Yes. A lot of projects in Yandex and Alfa-Bank, also in opensource projects based on [bem-core](https://github.com/bem/bem-core) and [bem-components](https://github.com/bem/bem-components).

## Benchmarks

To run benchmarks:
See [readme](https://github.com/bem/bem-xjst/tree/master/bench).

```bash
cd bench/
npm install
node run.js -h
node run.js
```

Benchmarks could be run in `--compare` mode to verify absence of regression
in comparison to previous bem-xjst version. Make sure that the
`benchmarks/package.json` has the right git hash of `bem-xjst` before running!
## Runtime linter

## Documentation
See [readme](https://github.com/bem/bem-xjst/tree/master/runtime-lint).

* [Documentation](https://en.bem.info/platform/bem-xjst/)
* [Releases notes](https://github.com/bem/bem-xjst/releases)
* [Migration guide from 4.x to 5.x](https://github.com/bem/bem-xjst/wiki/Migration-guide-from-4.x-to-5.x)
* [Changes from v1.x version](https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x)
## Static linter and migration tool for templates

## License
See [readme](https://github.com/bem/bem-xjst/tree/static-analyze/migration).

Code and documentation copyright 2016 YANDEX LLC. Code released under the
[Mozilla Public License 2.0](LICENSE.txt).
## Links

[0]: https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x
[1]: https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x#this_str-is-gone
* [Documentation](https://en.bem.info/platform/bem-xjst/)
* [Changelog](CHANGELOG.md) and [releases notes](https://github.com/bem/bem-xjst/releases)
* [Contributing guide](https://github.com/bem/bem-xjst/blob/master/CONTRIBUTING.md)
* [Online demo](https://bem.github.io/bem-xjst/) (you can share code snippets)
* Twitter account: [@bemxjst](https://twitter.com/bemxjst)
* [Migration guides](https://github.com/bem/bem-xjst/wiki/Migration-guides) for all major versions

0 comments on commit 3e76fc1

Please sign in to comment.