BEM Components Library

What is this?

bem-components is a library of blocks that provides ready-made form controls and some other blocks. The library contains base realizations of the blocks that are abstracted from the design. Few optional design themes are available.

Structure
- Levels
- Blocks
- Technologies
- Tools
- Optomizers
- Linters
- Autoprefixer
Usage
Supported browsers
Migration
Changelog
Maintainers
Development principles
- Delivery cases
Development
Workflow

Structure

Levels

common.blocks — support of any devices and browsers.
desktop.blocks — support of desktop browsers.
touch.blocks — implementation of some touch platforms specifics.

Blocks

Technologies

Tools

Optimizers

Linters

jshint
jscs

Autoprefixer

Autoprefixer

Usage

You can use any way you are familiar with to include the library into your project. For example, you can use bem-tools or ENB. To connect the library to your project use the configuration file of the selected building tool.

If you use project-stub to start your project, you do not need to connect the library – it is connected by default.

Supported browsers

Desktop
- Firefox (the last two stable versions)
- Chrome (the last two stable versions)
- Safari (the last two stable versions)
- Yandex (the last two stable versions)
- Opera 12.6+
- Internet Explorer 9+
- Partial support of Internet Explorer 8 (more info)
Touch
- Android 4+
- iOS 5+
- Internet Explorer 10+

Support IE8

To support IE8, you must include es5-shim and additional style files with the *.ie.styl extension to the page. To do this add them to buid config (like this) and add the conditional comments to the page block, as shown below:

{
    block : 'page',
    title : 'Support IE8',
    head : [
        {
            elem : 'conditional-comment',
            condition : '> IE 8',
            msieOnly : false,
            content : { elem : 'css', url : '_simple.css' } // styles for all browsers, including IE9+
        },
        {
            elem : 'conditional-comment',
            condition : '<= IE 8',
            content : { elem : 'css', url : '_simple.ie.css' } // styles for IE8 and lower
        }
    ],
    scripts : [
        {
            elem : 'conditional-comment',
            condition : '< IE 9',
            content : { elem : 'js', url : '//yastatic.net/es5-shims/0.0.1/es5-shims.min.js' }, // adding es5-shim for IE8 and lower
        },
        { elem : 'js', url : '_simple.js' }
    ]
}

Also, you can do it with the help of templates on your own level.

Changelog

You can check the changelog at the Changelog page.

Migration

Check the migration details at the Migration page when available.

Maintainers

Development principles

The base of all development principles of bem-components is the experience of our development team. For our library we take the best solutions from the past to create a new well-thought-out product called bem-components.

Open source project

GitHub is a platform for bem-components library development. We set all tasks, development raodmap and milestones using GitHub. Any developer could participate in the project: everyone could create an issue with some problems description or send a pull request with some code improvements.

Automatization

We try to automize all possible processes: a developer should not perform repetitive actions, there are robots for this.

Bleeding edge

We develop our library with a focus on the future: we supports only the latest browsers and tools. The library must not lose its relevance during the development process.

Optimization

We apply the optimization solutions for each block during the development to avoid the optimization of the already released code.

Muli-themes support

bem-components supports more then one theme simultaneously. For today the main theme of the library is islands. This theme implements the new Yandex design.

There is an additional temporary theme called simple in the library design. This theme was created to check the correct work of the library with more then one connected theme.

Selectors in a theme context

The library allows you to use different themes within a one page of the project. Besides, you could use native controls of your browser, for this do not use theme design in your project.

Platforms support

The library supports the following platforms: desktop and touch (mobile + tablet). All blocks of the library work correct on all available platforms.

Delivery cases

Source

Used for the technically identical projects that use the same preprocessor and template engine.

Compiled

Used for the projects that use any other preprocessor or do not use it at all.

Library

Used for the possibility to connect the library using links (like jQuery or Bootstrap).

Development

Working copy

Get the source code:

$ git clone git://github.com/bem/bem-components.git
$ cd bem-components

Install the dependencies:

$ npm install

You need export PATH=./node_modules/.bin:$PATH or any alternative way to run locally-installed ENB.

Install all necessary libraries:

$ bower install

Build and run tests and examples:

$ npm run build-all

Run development server:

$ npm start
$ open http://localhost:8080/

Check the coding style:

$ npm run lint

How to contribute

Create an issue with a proper description.
Decide which version needs your changes.
Create a feature branch with an issue number and a version (issues/<issue_number>@v<version_number>) based on a version branch. For example, for an issue #42 and a version 2: git checkout -b issues/42@v2. If you need changes for several versions, each of them has to have a feature branch.
Commit changes (you can test your changes running npm test) and push. Rebase your branch on a corresponding version branch if needed.
Create a pull request from your feature branch; or several pull requests if you changed several versions.
Link your pull request with an issue number any way you like. For example, leave a comment with the issue number.
Wait for your pull request and the issue closes ;-)

Modular testing

JavaScript unit tests

To run JS unit tests use npm run test-specs command. You may also specify the target, e.g. enb make specs desktop.specs/input to run just input tests.

All tests will be run automatically using Travis on each pull request.

Regression tests of layout

We use Gemini for layout testing.

Tests for each block are stored in a separate file block-name.gemini.js in a directory gemini/. All tests could be executed manually or automatically using Travis. We use SauceLabs service as a Selenium Grid.

Use OpenSauce account in SauceLabs and Sauce Connect utility to run tests locally.

Developers of BEM team could use bem-components account (we do not publish login and password because of the limit for three concurrent browsers launch; it is much more efficiently to use different free accounts for manual testing).

For tests execution you need the following:

Set up environment variables (SAUCE_USERNAME and SAUCE_ACCESS_KEY).
Run sc utility (SauceConnect) and wait for a tunnel initialization.
Run the tests using npm run gemini.
To collect new versions of the screenshots use npm run gemini-gather.

In case you write new tests for local usage, you can run your own Selenium Server or PhantomJS with WebDriver server. For this:

Install and run selenium-server or PhantomJS.
Correct gridUrl option to http://localhost:4444/ in .gemini.yml file.
Run tests.

Read a detailed description of Gemini work with different types of backends for additional information.

NB You have to commit screenshots to the repository from SauceLabs to avoid minor differences in fonts rendering.

Before commit some new or modified pattern you have to:

Check the validity. If in doubt, use Araxis Merge utility or something like this to see the difference between two versions of the pattern.
Compress them using ImageOptim utility (this is the most effective tool for images compression for May 2014).

Tests for templates

Build tools for the library allow you to build and run tests on BEMHTML and BH block templates.

To add a test for a block, you need to add a directory named [block name].tmpl-specs on your definition level. All test files will be stored in it.

Each test consists of a pair of files implemented in following technologies: BEMJSON and HTML. Each block could have more then one pair of such files. You could give any name to the file. But the file names (without extensions) within the one pair for one test must coincide. For example, 10-default.bemjson.js and 10-default.html.

For each block:

BEMJSON file contains an example for a block;
HTML file contains standard HTML code – a block sample.

Block sample in HTML is a block implementation result that becomes available after applying a template to the BEMJSON example.

desktop.blocks
    └── myblocks
        ├── myblock.bemhtml.js
        ├── myblock.bh.js
        ├── ...
        └── myblock.tmpl-specs
            ├── 10-default.bemjson.js
            ├── 10-default.html
            ├── 20-advanced.bemjson.js
            └── 20-advanced.html

To run tests for templates use:

magic run tmpl-specs

To run tests for required definition level use:

magic make desktop.tmpl-specs

To run tests for a specific block use:

magic make desktop.tmpl-specs/button

If build procedure is successful, tests will be run automatically. After that you will see all test results.

If the result of applying the template does not match with the block sample in HTML, then you will see errors in the log with description of the difference from the block sample.

All tests will be run automatically using Travis for each pull request.

Workflow

The issue list included in the current scope is displayed on a special Agile Board.

Issues on the Agile Board can be in four statuses:

backlog — issues that need to disassemble, evaluate and make a decision about their implementation. In this status can also be issues that need clarifying information.
ready — disassembled issues the decision about which implementation is adopted.
in progress — issues with a specific assignee which is already in work.
done — resolved issues, which were closed during the last seven days (this is a temprorary technical limitation of the selected Agile Board).

b7acksec / bem-components Goto Github PK

bem-components's Introduction