grunt-tt2-bem

grunt-tt2-bem
=============

> Template Toolkit 2 to BEM bridge.


Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

``shell
npm install grunt-tt2-bem --save-dev
`

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

`js
grunt.loadNpmTasks('grunt-tt2-bem');
`

The "bemdecl" task

$3

In your project's Gruntfile, add a section named bemdecl to the data object passed into grunt.initConfig().

`js
grunt.initConfig({
bemdecl: {
someTarget: {
options: {
// Target-specific options go here.
root: 'path/to/root',
includes: [ 'includes', 'inc' ] // relative to $root
},
src: [ 'templates/*/.html' ],
dest: 'bem/bundles.generated'
}
}
})
`

Each target defines a specific task that can be run.

$3

#### options.root

Type: String
Default: Gruntfile.* directory

Templates root directory.

#### options.includes

Type: Array
Default: [ '.' ] (root directory)

List of directories contains include files.

#### options.prefixes

Type: Array
Default: [ 'b', 'i', 'l' ]

Valid BEM prefixes.

> Will catch all BEM-blocks started with (like b-foo__bar, i-rel) and skip others (like d-quux__foo).

#### options.allowed

Type: Array | Function
Default: [ ]

Allowed BEM-blocks. Not allowed blocks will be filtered out from *.bemdecl.js files.

> An empty list means that all BEM-blocks considered valid. If Function used it should return an Array of allowed blocks.

`js
options: {
allowed: function () {
var blocks = [];
// build Array of allowed blocks
...
return blocks;
}
}
`

#### options.extSrc

Type: String
Default: .html

Source files (templates) extension.

#### options.extDst

Type: String
Default: .bemdecl.js

Destination files (declarations) extension.

#### options.sep

Type: String
Default: -

Separator for flattened files and directories.

>Suppose we have source template called choose/domain/index.html the bemdecl file for it would be like choose-domain-index.bemdecl.js. So path parts will be joined with options.sep value.

#### options.cut

Type: Number
Default: 0

The numbers of levels in source file path which should be skipped.

>Used to get flatten path for a template. For the templates/choose/domain/index.html and value of 1 the part templates/ would be skipped.

#### options.indentSize

Type: Number
Default: 4

The indentation levels for bemdecl structure.

$3

The Gruntfile.js of this distribution contains the task bemdecl:all

`js
bemdecl: {
all: {
src: [ 'templates/*/.html' ],
dest: 'test/fixtures/bem/bundles.generated',
options: {
root: 'test/fixtures',
includes: [ 'includes', 'templates' ],
cut: 1
}
}
}
`

A few templates utilized by this task located in directory test/fixtures/templates. If we run this task by issuing a command grunt bemdecl:all we will see the following:

`
$ grunt bemdecl:all

Running "bemdecl:all" (bemdecl) task
Processing test/fixtures/templates/choose/index.html...
Processing test/fixtures/templates/choose/new.html...
Processing test/fixtures/templates/web-sites/wix/index.html...

Done, without errors.
`

The directory test/fixtures/bem/bundles.generated will be created and will contains declarations for each processed template:

`
$ tree test/fixtures/bem/bundles.generated

test/fixtures/bem/bundles.generated
├── choose-index
│   └── choose-index.bemdecl.js
├── choose-new
│   └── choose-new.bemdecl.js
└── web-sites-wix-index
└── web-sites-wix-index.bemdecl.js

3 directories, 3 files
`

The .bemdecl.js file contains declaration like this:

`js
/*
*
* WARNING!
* DO NOT EDIT THIS MANUALLY - YOUR CHANGES WILL BE OVERWRITTEN!
*
* Generated by bemdecl:all
* Source file: test/fixtures/templates/web-sites/wix/index.html
*
*/
exports.blocks = [
{
"block": "b-foo",
"elem": "bar"
},
{
"block": "b-text",
"elems": [
{
"elem": "huge",
"mods": [
{
"mod": "font-size",
"val": "xlarge"
}
]
}
],
"mods": [
{
"mod": "font-family",
"val": "arial"
}
]
}
];
`

$3

Source files and destination directory should be pointed through the src and dest properties respectively. Both properties are required to work the plugin. Task fails if src and (or) dest property undefined.

#### The src property

This property may handle the following types data: String, Array or Object. There is some restrictions for the Object form. Each value should be either String or Array. In other words it does not handle Object as value for particular key (at the moment).

All empty, undefined, false and duplicate values will be filtered before processing.

Allowed to use path names or globbing patterns to point source files. See more at Configuring Tasks: Globbing Patterns.

#### The dest property

This one is not flexible as src. It accepts String value only.

#### In action

As String

`js
bemdecl: {
all: {
options: { },
src: 'templates/*/.html',
dest: 'bem/bundles.generated'
}
}
`

or composite String (delimiter depends on platform: : on Unix, ; on Windows)

`js
bemdecl: {
all: {
options: { },
src: 'templates/foo/*.html:!templates/foo/bar.html',
dest: 'bem/bundles.generated'
}
}
`

As Array

`js
bemdecl: {
all: {
options: { },
src: [ 'templates/*/.html' ],
dest: 'bem/bundles.generated'
}
}
`

As Object. All values are plain String or Array. Duplicates and undefined members will be filtered.

`js
bemdecl: {
all: {
options: { },
src: {
foo: [
'templates/foo/*.html',
'templates/bar/*.html'
],
qux: 'templates/qux/*/.html'
},
dest: 'bem/bundles.generated'
}
}
`

Release History

See Changes.md` file.

License

_grunt-tt2-bem_ is licensed under the [MIT license][].

[MIT license]: http://www.tldrlegal.com/license/mit-license