BEM Components Library

What is this?

BEM is an open-source library that provides a set of ready-made visual components (blocks) for creating web interfaces.

The library provides design themes. This version introduces the "islands" theme, which implements the new Yandex design. Features include supporting multiple themes at once, and creating new themes.

Levels
Blocks
Supported browsers
Technologies
Tools
Usage
Library distributions
Development
Maintainers
Workflow

Additional information

Levels

common.blocks — support of any devices and browsers.
desktop.blocks — support of desktop browsers.
touch.blocks — implementation of specific features for touch platforms.
touch-phone.blocks — implementation of specific features for smartphones.
touch-pad.blocks — implementation of specific features for tablets.
design/<common|desktop|touch|touch-phone|touch-pad>.blocks — implementation of various designs (themes).

Blocks

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 for Internet Explorer 8
Touch
Android 4+
iOS 5+
Internet Explorer 10+

Support for Internet Explorer 8

To support Internet Explorer 8, you must add

es5-shim;
style files with the *.ie.styl extension to the page. To do this, specify them in the build config (see this example) and add comments in the page section (see this example). You can also enable styles for Internet Explorer 8 at the template level.

Technologies

Tools

Assemblers

Optimizers

Code analysis

jshint
jscs

Other

Autoprefixer — used during assembly to generate vendor prefixes for supported browsers based on the configuration.

Usage

Use bem-tools or ENB to connect the library to the project. Specify the library name and version in the configuration file for your chosen assembly tool.

For projects developed on project-stub, the library is enabled by default.

Library distributions

Source

For technically identical services and projects that use a preprocessor and template engine listed in the Tools section.

Compiled

For services and projects that do not use a preprocessor or use one that is not listed in the Tools section.

Library

To include the library by linking to a page, similar to jQuery or Bootstrap.

To choose this method, execute npm run dist in the library root after setting up npm dependencies. As a result, bundles are generated in the dist folder.

Development

Working copy
How to contribute
Testing
JavaScript unit tests
Regression tests for layout
Tests for templates

Working copy

Get sources:

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

Install dependencies (of tools):

$ npm install

To then run locally installed tools, use export PATH=./node_modules/.bin:$PATH or any alternative method.

Install dependent libraries:

$ bower install

Build examples and tests:

$ npm run build-all

Start the development server:

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

Note: For information about assembling individual blocks, see the section Tests for templates.

Code analysis:

$ npm run lint

Testing

JavaScript unit tests

The npm run test-specs command launches unit tests on JS.

To launch point-based assembly, use the command enb make specs desktop.specs/<block-name> (for example, enb make specs desktop.specs/input).

Tests will be run automatically on Travis for each pull request.

Regression tests for layout

Gemini is used for layout testing.

Tests for each block are stored in a separate block-name.gemini.js file in the gemini/ directory. Locally, test are executed manually. On Travis, tests are executed automatically. For Selenium Grid, the SauceLabs service is used.

For executing tests locally, you need to:

Create an OpenSauce account in SauceLabs.
Install the Sauce Connect utility.
Set up environment variables (SAUCE_USERNAME and SAUCE_ACCESS_KEY).
Launch the src utility (SauceConnect) and wait for the tunnel to be opened.
Run the tests using npm run gemini.
If you need to make new versions of screenshots, use the command npm run gemini-gather.

When developing new tests to speed up local execution:

Install and run Selenium Server or PhantomJS.
In the .gemini.yml file, change the gridUrl option to http://localhost:4444/.
Run the tests.

For more information about using Gemini with various backends, read the article Gemini quick start.

Note: You need to save screenshots from SauceLabs in the repository. This helps to avoid discrepancies when rendering fonts.

Before commiting new or modified reference images, you must:

Make sure the images are correct. To find differences between the old and new versions, use the Araxis Merge utility or something similar.
Use ImageOptim to compress the images (this is the most effective tool for compressing images as of May, 2014).

Tests for templates

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

Add a test for a block

Create a directory named [block name].tmpl-specs in the block's directory at the necessary level. Test files will be stored in this directory.
Create a pair of BEMJSON and HTML files for each test. The BEMJSON file contains an example for the block, and the HTML file contains the sample HTML code that should result after applying the block template to the BEMJSON example. File names must match (other than the extensions) for the same test. For example, 10-default.bemjson.js and 10-default.html.

Multiple tests can be written for a block and, accordingly, each test consists of two files (BEMJSON and HTML) with the same name.

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 build and run tests, use:

magic run tmpl-specs

To build tests on the required definition level, use:

magic make desktop.tmpl-specs

To build tests only for a specific block, use:

magic make desktop.tmpl-specs/button

If the build procedure is successful, tests are run automatically, and you will see all test results. If the result of applying the template does not match with the block sample in HTML, you will see an error in the log indicating how it differs from the block sample.

All tests are run automatically using Travis on each pull request.

Maintainers

Workflow

Current tasks are listed on a special Agile Board.

Task statuses:

backlog — Unsorted tasks that need to be discussed by the team to evaluate them and decide how to implement them. This status also applies to tasks that need additional information.
ready — Tasks that have been investigated and a decision has been made on how to implement them.
in progress — Tasks that have a specific assignee and are currently in progress.
done — Tasks that have been closed over the last seven days (this is a temporary technical limitation of our Agile Board).

km256 / bem-components Goto Github PK

bem-components's Introduction