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:

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:

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

The "bemdecl" task

Overview

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

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.

Options

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.

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.

Usage Example

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

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:

/*
 *
 * 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"
            }
        ]
    }
];

Source (templates) and destination (declarations) files

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

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

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

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

As Array

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.

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.