BemEntityName
BEM entity name representation.

Contents
Install
$ npm install --save @bem/entity-name
Usage
const BemEntityName = require('@bem/entity-name');
const entityName = new BemEntityName({ block: 'button', elem: 'text' });
entityName.block;
entityName.elem;
entityName.mod;
entityName.id;
entityName.type;
entityName.isEqual(new BemEntityName({ block: 'button' }));
entityName.isEqual(new BemEntityName({ block: 'button', elem: 'text' }));
API
constructor({ block, elem, mod })
block | string | The block name of entity. |
elem | string | The element name of entity. |
mod | string , object | The modifier of entity.
If specified value is string then it will be equivalent to { name: string, val: true } . Optional. |
mod.name | string | The modifier name of entity. |
mod.val | string , true | The modifier value of entity. Optional. |
BEM entities can be defined with a help of JS object with the following fields:
block
— a block name. The field is required because only a block exists as an independent BEM entity
elem
— an element name.
mod
— a modifier.
The modifier consists of a pair of fields mod.name
and mod.val
. This means that the field mod.val
without mod.name
has no meaning.
const BemEntityName = require('@bem/entity-name');
new BemEntityName({
block: 'button',
mod: { name: 'view', val: 'action' }
});
new BemEntityName({
block: 'button',
mod: { val: 'action' }
});
To describe a simple modifier the mod.val
field must be omitted.
new BemEntityName({ block: 'button', mod: 'focused' });
new BemEntityName({
block: 'button',
mod: { name: 'focused', val: true }
});
block
The name of block to which this entity belongs.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button' });
name.block;
elem
The element name of this entity.
If entity is not element or modifier of element then returns empty string.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', elem: 'text' });
name.elem;
mod
The modifier of this entity.
Important: If entity is not a modifier then returns undefined
.
const BemEntityName = require('@bem/entity-name');
const blockName = new BemEntityName({ block: 'button' });
const modName = new BemEntityName({ block: 'button', mod: 'disabled' });
modName.mod;
blockName.mod;
type
The type for this entity.
Possible values: block
, elem
, blockMod
, elemMod
.
const BemEntityName = require('@bem/entity-name');
const elemName = new BemEntityName({ block: 'button', elem: 'text' });
const modName = new BemEntityName({ block: 'menu', elem: 'item', mod: 'current' });
elemName.type;
modName.type;
scope
The scope of this entity.
Important: block-typed entities has no scope.
const BemEntityName = require('@bem/entity-name');
const buttonName = new BemEntityName({ block: 'button' });
const buttonTextName = new BemEntityName({ block: 'button', elem: 'text' });
const buttonTextBoldName = new BemEntityName({ block: 'button', elem: 'text', mod: 'bold' });
buttonName.scope;
buttonTextName.scope;
buttonTextBoldName.scope;
id
The id for this entity.
Important: should only be used to determine uniqueness of entity.
If you want to get string representation in accordance with the provisions naming convention you should use @bem/naming package.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'disabled' });
name.id;
isSimpleMod()
Determines whether modifier simple or not.
NOTE: For entity without modifier isSimpleMod()
returns null
.
const BemEntityName = require('@bem/entity-name');
const modName = new BemEntityName({ block: 'button', mod: { name: 'theme' } });
const modVal = new BemEntityName({ block: 'button', mod: { name: 'theme', val: 'normal' } });
const block = new BemEntityName({ block: 'button' });
modName.isSimpleMod();
modVal.isSimpleMod();
block.isSimpleMod();
isEqual(entityName)
entityName | BemEntityName | The entity to compare. |
Determines whether specified entity is the deepEqual entity.
const BemEntityName = require('@bem/entity-name');
const inputName = new BemEntityName({ block: 'input' });
const buttonName = new BemEntityName({ block: 'button' });
inputName.isEqual(buttonName);
buttonName.isEqual(buttonName);
belongsTo(entityName)
entityName | BemEntityName | The entity to compare. |
Determines whether specified entity belongs to this.
const BemEntityName = require('@bem/entity-name');
const buttonName = new BemEntityName({ block: 'button' });
const buttonTextName = new BemEntityName({ block: 'button', elem: 'text' });
const buttonTextBoldName = new BemEntityName({ block: 'button', elem: 'text', mod: 'bold' });
buttonTextName.belongsTo(buttonName);
buttonName.belongsTo(buttonTextName);
buttonTextBoldName.belongsTo(buttonTextName);
buttonTextBoldName.belongsTo(buttonName);
valueOf()
Returns normalized object representing the entity name.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'focused' });
name.valueOf();
toJSON()
Returns raw data for JSON.stringify()
purposes.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'input', mod: 'available' });
JSON.stringify(name);
toString()
Returns string representing the entity name.
Important: if you want to get string representation in accordance with the provisions naming convention
you should use @bem/naming package.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'focused' });
name.toString();
static create(object)
Creates BemEntityName instance by any object representation or a string.
Helper for sugar-free simplicity.
object | object , string | Representation of entity name. |
Passed Object could have the common field names for entities:
block | string | The block name of entity. |
elem | string | The element name of entity. Optional. |
mod | string , object | The modifier of entity.
If specified value is string then it will be equivalent to { name: string, val: true } . Optional. |
val | string | The modifier value of entity. Used if mod is a string. Optional. |
mod.name | string | The modifier name of entity. Optional. |
mod.val | string , true | The modifier value of entity. Optional. |
modName | string | The modifier name of entity. Used if mod.name was not specified. Optional. |
modVal | string , true | The modifier value of entity. Used if neither mod.val nor val were not specified. Optional. |
const BemEntityName = require('@bem/entity-name');
BemEntityName.create('my-button');
BemEntityName.create({ block: 'my-button' });
BemEntityName.create({ block: 'my-button', mod: 'theme', val: 'red' });
BemEntityName.create({ block: 'my-button', modName: 'theme', modVal: 'red' });
BemEntityName.create({ block: 'my-button', mod: 'focused' });
static isBemEntityName(entityName)
Determines whether specified entity is an instance of BemEntityName.
entityName | * | The entity to check. |
const BemEntityName = require('@bem/entity-name');
const entityName = new BemEntityName({ block: 'input' });
BemEntityName.isBemEntityName(entityName);
BemEntityName.isBemEntityName({ block: 'button' });
Serialization
The BemEntityName
has toJSON
method to support JSON.stringify()
behaviour.
Use JSON.stringify
to serialize an instance of BemEntityName
.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'input', mod: 'available' });
JSON.stringify(name);
Use JSON.parse
to deserialize JSON string and create an instance of BemEntityName
.
const BemEntityName = require('@bem/entity-name');
const str = '{"block":"input","mod":{"name":"available","val":true}}';
new BemEntityName(JSON.parse(str));
TypeScript support
The package includes typings for TypeScript. You have to set up transpilation yourself. When you set module
to commonjs
in your tsconfig.json
file, TypeScript will automatically find the type definitions for @bem/entity-name
.
The interfaces are provided in global namespace BEMSDK.EntityName
. It is necessary to use interfaces in JsDoc.
Debuggability
In Node.js, console.log()
calls util.inspect()
on each argument without a formatting placeholder.
BemEntityName
has inspect()
method to get custom string representation of the object.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'input', mod: 'available' });
console.log(name);
You can also convert BemEntityName
object to string
.
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'input', mod: 'available' });
console.log(`name: ${name}`);
Deprecation
Deprecation is performed with depd.
To silencing deprecation warnings from being output use the NO_DEPRECATION
environment variable.
NO_DEPRECATION=@bem/entity-name node app.js
More details in depd
documentation
License
Code and documentation © 2016 YANDEX LLC. Code released under the Mozilla Public License 2.0.