bem-components
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.
Additional information
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).Desktop
Touch
To support Internet Explorer 8, you must add:
*.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.Assemblers
Optimizers
Code analysis
Other
There are several ways to start using bem-components
. The best approach depends on your project’s requirements and its compatibility with the technologies and tools of the library, as well as on your experience with BEM projects.
Choose the most suitable method for your project:
Dist | Source | Compiled |
---|---|---|
Pre-assembled CSS and JavaScript code and library templates. Integrated by linking to the page. Doesn't require assembly or compatibility with your project. | The full source code of the library. Requires assembly. Your project must be fully compatible with the library’s technologies and tools. | The full source code of the library. Requires assembly. Differs from the Source method in that PostCSS is compiled into CSS. Suitable for projects where PostCSS is not used. |
The way you are using the library determines how to integrate it into your project:
We recommend using ENB or bem-tools to integrate the library.
As an example, you can use project-stub, where the library is enabled by default. You can also create a project and use the Yo generator to connect the library (this allows you to create the necessary project configuration).
The easiest way to connect the library to the project is to download the pre-assembled library files and use <link>
and <script>
elements to add them to HTML pages. There are several ways to do this:
For information about how to use the connected library files, see Working with the library.
Structure of the pre-assembled library
There are separate sets of files available for three platforms:
Each set includes:
bem-components.css
— Styles;bem-components.ie.css
— Styles for IE8 (more information);bem-components.js
— JavaScript;bem-components.bemhtml.js
— BEMHTML templates;bem-components.bh.js
— BH templates;bem-components.js+bemhtml.js
— Combines JavaScript code and BEMHTML templates for using templates in the browser;bem-components.js+bh.js
— Combines JavaScript code and BH templates for using templates in the browser;bem-components.no-autoinit.js
- JavaScript without automatic initialization. Use it if you need to write your own code in i-bem.js
;bem-components.no-autoinit.js+bemhtml.js
;bem-components.no-autoinit.js+bh.js
.Each set also includes the development versions of the same files (preserving the original formatting and comments).
The fastest and easiest way to connect the library to the project is to add the <link>
and <script>
elements to HTML pages:
<link rel="stylesheet" href="https://yastatic.net/bem-components/latest/desktop/bem-components.css">
<script src="https://yastatic.net/bem-components/latest/desktop/bem-components.js+bemhtml.js"></script>
Pattern for connecting a file from the CDN: //yastatic.net/library-name/version/platform/file-name
.
Example: //yastatic.net/bem-components/latest/desktop/bem-components.dev.js+bemhtml.js
.
Select the appropriate library version and download the archive. Unzip it. Add the files to the page using <link>
and <script>
elements:
<link rel="stylesheet" href="https://github.com/bem/bem-components/blob/v6/desktop/bem-components.css">
<script src="https://github.com/bem/bem-components/raw/v6/desktop/bem-components.js+bemhtml.js"></script>
The library code is on Github: https://github.com/bem/bem-components.
To run the build, use these commands:
# Clone the library source code
git clone https://github.com/bem/bem-components.git
# Switch to the library folder
cd bem-components
# Install the required dependencies
npm install
# Build Dist
npm run dist
As a result of the build, the files will be available in the bem-components-dist
folder. Connect the files in the page's HTML:
<link rel="stylesheet" href="https://github.com/bem/bem-components/blob/v6/bower_components/bem-components-dist/desktop/bem-components.css">
<script src="https://github.com/bem/bem-components/raw/v6/bower_components/bem-components-dist/desktop/bem-components.js+bemhtml.js"></script>
Provided Bower is already in your project, run the following command:
bower i bem/bem-components-dist
As a result of the build, the files will be available in the bem-components-dist
folder. Connect the files the same way as for the previous method:
<link rel="stylesheet" href="https://github.com/bem/bem-components/blob/v6/bower_components/bem-components-dist/desktop/bem-components.css">
<script src="https://github.com/bem/bem-components/raw/v6/bower_components/bem-components-dist/desktop/bem-components.js+bemhtml.js"></script>
There are two steps to working with the library:
The first step is always the same. The second step can be performed in three different ways, which you can combine as you wish:
Method 1. Copy the HTML from the example. To do this, go to the HTML
tab in the header of the example.
This is the easiest approach, but if templates are updated in future versions of the library, you will have to make the changes manually in each updated block.
Method 2. Use templating in the browser. Assembling the Dist
library includes pre-assembled BEMHTML and BH templates to choose from.
To do this, copy the sample BEMJSON code from the documentation and paste it into the page's HTML code. Use the BEMJSON
tab in the header of the example.
The page's HTML code will look like this:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>bem-components as a library</title>
<link rel="stylesheet" href="https://yastatic.net/bem-components/latest/desktop/bem-components.css">
</head>
<body class="page page_theme_islands">
<form class="form" action="/"></form>
<script src="https://yastatic.net/bem-components/latest/desktop/bem-components.no-autoinit.js+bemhtml.js"></script>
<script>
modules.require(['i-bem__dom', 'BEMHTML', 'jquery', 'i-bem__dom_init'], function(BEMDOM, BEMHTML, $, init) {
var html = BEMHTML.apply({
block : 'select',
mods : { mode : 'check', theme : 'islands', size : 'm' },
name : 'select1',
val : [2, 3],
text : 'Conference programme',
options : [
{ val : 1, text : 'Report' },
{ val : 2, text : 'Master class' },
{ val : 3, text : 'Round Table' }
]
});
BEMDOM.append($('.form'), html);
// NOTE: explicitly call `init();` if you need to initialize blocks from HTML markup
});
</script>
</body>
</html>
In contrast to the first method, this code won't require any changes to the markup when the library is updated to a new version. However, client-generated markup might not be indexed as well by search engines.
Method 3. Execute {BEMHTML,BH}.apply()
in Node.js and give the browser the prepared HTML:
var BEMHTML = require('./dist/desktop/bem-components.bemhtml.js').BEMHTML;
BEMHTML.apply({
block : 'select',
mods : { mode : 'check', theme : 'islands', size : 'm' },
name : 'select1',
val : [2, 3],
text : 'Conference programme',
options : [
{ val : 1, text : 'Report' },
{ val : 2, text : 'Master class' },
{ val : 3, text : 'Round Table' }
]
}); // returns HTML line
The library consists of blocks, which you can see represented visually in the bem-components
showcase. Blocks have states that determine the behavioral model. A block’s state is expressed through modifiers and specialized fields. Changing a modifier creates an event that can be used for working with the block.
There is no need to create a special BEM event if you can work with the modifier change event. Depending on what is used for changing a component’s state (a modifier or a field), different events are used:
value
fields, the change
event is used.bem-components
The controls in bem-components
can be used as the basis for creating other library components. Such controls don't have models as in HTML, and they can be used for tasks that don't require the semantics of a specific HTML model.
As an example, think of the "behavioral model" for the HTMLInputElement, which is a higher-level interface designed specifically for editing data. What is different about bem-components
blocks is that they can be used as the basis of a block in another library that will solve the same problem. But along with that, they can serve other purposes in the interface that don't require HTML input
semantics.
focused
modifierControls in bem-components have two types of focus, which are set using the modifiers focused
and focused-hard
. The type of focus determines the appearance of the control.
The modifier is chosen automatically based on how the focus is set:
focused
— Set for a mouse click on the control.focused-hard
— Set when the control is selected using the keyboard or through JavaScript. It highlights the component more obviously when it gets the focus. For example, in the Islands
theme, most of the controls get an extra border when focused-hard
is set.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
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.
Hermione is used for layout testing.
Tests for each block are stored in a separate block-name.hermione.js
file in the hermione/
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:
SAUCE_USERNAME
and SAUCE_ACCESS_KEY
).sc
utility (SauceConnect) and wait for the tunnel to be opened.hermione
.hermione gui
.When developing new tests to speed up local execution:
.hermione.conf.js
file, change the gridUrl
option to http://localhost:4444/
.For more information about using Hermione
with various backends, read the article Hermione 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:
Build tools for the library allow you to build and run tests on BEMHTML and BH block templates.
Add a test for a block
[block name].tmpl-specs
in the block's directory at the necessary level. Test files will be stored in this directory.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.
Current tasks are listed on a special Agile Board.
Task statuses:
Code and documentation © 2012 YANDEX LLC. Code released under the Mozilla Public License 2.0.