From 374c45c225ee65807bc85e7d40f39f1eed47fd95 Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Thu, 9 Mar 2017 11:12:57 +0300 Subject: [PATCH 1/2] added translation --- docs/depsjs/depsjs.en.md | 330 ++++++++----- docs/depsjs/specification.en.md | 845 ++++++++++++++++++++++++++++++++ docs/depsjs/specification.ru.md | 2 +- 3 files changed, 1047 insertions(+), 130 deletions(-) create mode 100644 docs/depsjs/specification.en.md diff --git a/docs/depsjs/depsjs.en.md b/docs/depsjs/depsjs.en.md index c5459a48..5cb67bcc 100644 --- a/docs/depsjs/depsjs.en.md +++ b/docs/depsjs/depsjs.en.md @@ -1,206 +1,278 @@ -# deps.js — a technology to declare dependencies in BEM +# Technology for declaring dependencies -The process of building a page in different technologies is based on declaring BEM entities in a BEM tree. +* [Introduction](#Introduction) +* [Notation](#Notation) +* [DEPS syntax](#DEPS-syntax) +* [Examples](#Examples) -There are two ways to form a page: +## Introduction - * **static** — make a full page build and publish the result - * **dynamic** — start with building all static files (for example, CSS, JS, templates), then create a dynamic BEM tree in runtime and apply templates to it. +In the BEM methodology, dependencies on other blocks, elements, modifiers, and technologies can be declared using `deps.js` files. -During static page building, its BEM tree contains all BEM entities (except blocks without DOM representation and blocks which are expanded from within templates). If a block is defined in the BEM tree, the build process will build all the required technologies (such as CSS or JS) into common files, from all redefinition levels. +The basic principles of code organization and storage are applied to `deps.js` files: -When forming a dynamic page, we have no BEM tree on the project build phase; that's why we have to declare all BEM entities which we might need. +* Code is divided into separate parts. The logic of each block and its optional elements and modifiers is defined in separate files. +* Files are grouped in directories – `deps.js` files for each component are stored according to the [file system](https://en.bem.info/methodology/filestructure/) rules for BEM projects. -In both cases, `deps.js` files are used to specify explicit dependencies on other blocks, elements, modifiers and technologies. +Dependencies are defined for all [BEM entities](https://en.bem.info/methodology/key-concepts/#bem-entity) that are distributed across the project's file system and aren't included in the [declaration](https://en.bem.info/methodology/declarations/). + +As an example, let's look at a [search form](https://en.bem.info/methodology/build/#describing-dependencies) that is created from the `input` block and the `button` block. + +**Example** + +The `search-form` block in the project's file structure: + +```files +search-form/ # Directory of the `search-form` block + search-form.bemhtml.js # Template of the `search-form` block +``` + +Template of `search-form.bemhtml.js`: -Let the `b1.bemhtml.js` template contain the following code: ```js -block b1, content: [ - { - block: 'b2' - }, - { - block: 'b3' - } -] +block('search-form')( + content()({ + block: 'input' + },{ + block: 'button' + }) +); +``` + +To include styles and scripts from the `input` and `button` blocks, you will need to create the `search-form.deps.js` file. + +The `search-form` block in the project's file structure after defining dependencies: + +```files +search-form/ # Directory of the `search-form` block + search-form.bemhtml.js # Template of the `search-form` block + search-form.deps.js # `search-form.deps.js` file ``` -To include styles and scripts for `b2` and `b3` blocks into the project, we have to create a `b1.deps.js` with the following contents: +`search-form.deps.js` file: + ```js ({ - mustDeps: { block: 'b2' }, - shouldDeps: { block: 'b3' } + shouldDeps: [ + { block: 'input' }, + { block: 'button' } + ] }) ``` -If elements and modifiers are standalone files on a file structure and not mentioned in the incoming BEMJSON file, they must be declared the same way. +The build will include all the implementation technologies for the `input` and `button` blocks. + +![Building a BEM project](https://cdn.rawgit.com/bem-archive/bem-tools/dev/docs/depsjs/build__decl__search-form.svg) + +## Notation + +To abbreviate dependencies in comments, use the following notation: + +* `/* b1 → b2 */` — block `b1` is dependent on block `b2` (`shouldDeps`) +* `/* b1 ⇒ b2 */` — block `b1` is dependent on block `b2` (`mustDeps`) +* `/* b1 → b1__e1 */` — block `b1` is dependent on its element `b1__e1` +* `/* b1 → b1_m1_v1 */` — block `b1` is dependent on its modifier `b1_m1_v1` +* `/* b1 → b1__e1_m1_v1 */` — block `b1` is dependent on the modifier of its element `b1__e1_m1_v1` +* `/* b1.js → b2.bemhtml */` — block `b1` in the JavaScript implementation is dependent on block `b2` in BEMHTML implementation. + +## DEPS syntax + +A **DEPS entity** is an entity that defines a dependency between BEM entities. -## deps.js syntax +There are several ways to represent a DEPS entity in the `.deps.js` file: -To present a deps-entity in a `deps.js` file, use this syntax: ```js ({ - /* deps-entity */ + /* DEPS entity */ }) ``` -deps-entities in a file can be represented as an array if there is a dependency on a specific technology: -```js -([{ - /* deps-entity 1 */ -},{ - /* deps-entity 2 */ -}]) -``` +The full notation of a DEPS entity looks like this: -Full declaration of a deps-entity looks like this: ```js -{ - block : 'bBlock', - elem : 'elem', - mod : 'modName', - val : 'modValue', - tech : 'techName', - mustDeps : [], - shouldDeps : [], - noDeps : [], - include : false -} +/* DEPS entity */ +({ + block: 'block-name', + elem: 'elem-name', + mod: 'modName', + val: 'modValue', + tech: 'techName', + shouldDeps: [ /* BEM entity */ ], + mustDeps: [ /* BEM entity */ ], + noDeps: [ /* BEM entity */ ] +}) ``` -All of the deps-entity parameters are optional. The `block`, `elem`, `mod`, `val`, and `tech` parameters specify the entity to add a dependency for, while `mustDeps`, `shouldDeps` and `noDeps` define the dependency itself: +**Note** All fields are optional. + +The fields in a DEPS entity can be divided into the following groups: + +* Defining the BEM entity: + + * `block` (string) — Block name. + * `elem` (string) — Element name. + * `mod` (string) — Modifier name. + * `val` (string) — Modifier value. + +* Defining the implementation of the BEM entity: + + * `tech` (string) — The technology to collect dependencies for. - * `block` (string) — block name - * `elem` (string) — element name - * `mod` (string) — modifier name - * `val` (string) — block modifier value - * `tech` (string) — technology you include dependencies for (for example, JS) - * `mustDeps` (array or object) — defines dependencies that are guaranteed to be included into the resulting build (before the code of a block that originally defined those dependencies) - * `shouldDeps` (array or object) — defines dependencies which can be included in any order - * `noDeps` (array or object) — cancels a certain dependency (for example, `i-bem__dom_init_auto`). +* Defining the dependency: + + * `shouldDeps` (array/object) — Defines dependencies that can be included in any order. + * `mustDeps` (array/object) — Defines dependencies that must be included in the build result before the code of the BEM entity where these dependencies are declared. + * `noDeps` (array/object) — Cancels existing dependencies declared on other [redefinition levels](https://en.bem.info/methodology/key-concepts/#redefinition-level) (for example, `i-bem__dom_init_auto`). + +### Fields that define the BEM entity + +The fields specify which BEM entity needs the dependencies included. They can be restored from the context by the file name. So the following statements for the file `b1__e1_m1_v1.deps.js` are equivalent: -As all the fields for the current entity can be read from its file name, the following two dependency definitions for a `b1__e1_m1_v1.deps.js` file are equivalent: ```js +/* b1__e1_m1_v1 → b2 */ ({ - block : 'b1', - elem : 'e1', - mod : 'm1', - val : 'v1', - mustDeps : { block : 'b2' } + block: 'b1', + elem: 'e1', + mod: 'm1', + val: 'v1', + shouldDeps: { block: 'b2' } }) ``` ```js +/* b1__e1_m1_v1 → b2 */ ({ - mustDeps : { block : 'b2' } + shouldDeps: { block: 'b2' } }) ``` -`mustDeps`, `shouldDeps` and `noDeps` parameters accept these BEM entities as values: `block`, `elem`, `mods`. Alternatively, you can use an extended syntax where elements and modifiers can accept an array: +### Field that defines the implementation technology for the BEM entity - * `elems` (array) — allows to connect several block elements, as well as the block itself - * `mods` (object) — an object with arrays as key values. +It specifies which [implementation technology](https://en.bem.info/methodology/key-concepts/#implementation-technology) to include the dependency for. If the `tech` field or its value is omitted, the dependency is considered general and applies to all technologies. -To declare dependencies on BEM entities which were missing during a build process, use `'mustDeps'` or `'shouldDeps'`. Build system will add these declarations to a `deps.js` bundle flat list which will be used as a basis to build all technologies on all redefinition levels. +> Including dependencies for a technology is used, for example, to create a client JavaScript bundle that only has templates for the blocks that will be used in the browser. In this case, part of the templating happens on the server side, so some of the templates are never used in the client. -`'noDeps'` cancels dependencies on lower redefinition levels. +**Example** -## Build details +`search-form.deps.js` file: -In BEM methodology, `deps.js` is a technology and, as such, it conforms to unified technology building rules. +```js +/* search-form → button.bemhtml; search-form → input.bemhtml */ +({ + shouldDeps: [ + { block: 'button', tech: 'bemhtml' }, + { block: 'input', tech: 'bemhtml' } + ] +}) +``` -By default, dependency description file is located in the block folder; its name corresponds to a block name, with an extra `'.deps.js'` extension. +Only the specified implementation technology will be included in the build. -`deps.js` allows for defining dependencies on any block, element or modifier, in any technology. +![Build for a technology](https://cdn.rawgit.com/bem-archive/bem-tools/dev/docs/depsjs/build__decl__search-form__tech.svg) -Assume that we have four redefinition levels in our project: a `bem-core` library, common blocks, platform blocks and page blocks: -``` -prj/ - libs/bem-core/common.blocks/ - common.blocks/ - desktop.blocks/ - desktop.bundles/page-name/blocks/ -``` +### Fields that define the dependency -You should only point once to `'{ block: button }'` in a BEM tree for the build system to crawl all redefinition levels and include all the necessary files: +The `mustDeps` and `shouldDeps` fields define dependencies, and the `noDeps` field cancels existing dependencies that are declared on other redefinition levels. -```css -@import url(../../libs/bem-core/common.blocks/button/button.css); -@import url(../../common.blocks/button/button.css); -@import url(../../desktop.blocks/button/button.css); -@import url(blocks/button/button.css); -``` +**Comparing shouldDeps and mustDeps** + +Sometimes you need to [change the block implementation](https://en.bem.info/methodology/key-concepts/#block-redefinition) by changing the block on another redefinition level. In this case, the original implementation of the block must be added to the build before the code with additional rules. + +The `mustDeps` field specifies dependencies that are added to the build results before the code of the BEM entity where these dependencies are declared. If dependencies are defined using `shouldDeps`, they can be added in any order. -Building process is the same for any other required technology (for example, JS, templates, documentation). +> More information about the [DEPS syntax](specification.en.md). -Assume that the BEM tree is changed in runtime, and in the user's browser, a `desktop.blocks/button` block includes an `e1` element from `common.blocks/button` block. +## Examples + +### Including a block + +`b1 → b2` — block `b1` is dependent on block `b2` + +`b1.deps.js` file: -Here is how we could define this dependency in `desktop.blocks/button/button.deps.js`: ```js +/* b1 → b2 */ ({ - shouldDeps : { block : 'button', elem : 'e1' } + shouldDeps: [ + { block: 'b2' } + ] }) ``` -After performing a build for the CSS technology, the following files will be included into the project: -```css -@import url(../../libs/bem-core/common.blocks/button/button.css); -@import url(../../common.blocks/button/button.css); -@import url(../../desktop.blocks/button/button.css); -@import url(blocks/button/button.css); -@import url(../../common.blocks/button/__e1/button__e1.css); -@import url(../../desktop.blocks/button/__e1/button__e1.css); -@import url(blocks/button/__e1/button__e1.css); +### Including an element + +`b1 → b1__e1` — block `b1` is dependent on its element `b1__e1` + +`b1.deps.js` file: + +```js +/* b1 → b1__e1 */ +({ + shouldDeps: [ + { block: 'b1', elem: 'e1' } + ] +}) ``` -According to specified dependencies, all the declared BEM entities are included from both upper and lower redefinition levels. -## Examples of dependency declaration +> **Note** The `elem` field only adds the element, not the block itself. + +### Including a modifier -### Include an element only +#### Key-value modifier + +`b1 → b1_m1_v1` — block `b1` is dependent on its key-value modifier `b1_m1_v1` + +`b1.deps.js` file: -`elem` includes only an element, not the block itself. ```js -{ - block : 'b1', - elem : 'e1' -} +/* b1 → b1_m1_v1 */ +({ + shouldDeps: [ + { block: 'b1', mod: 'm1', val: 'v1' } + ] +}) ``` -Same applies to `mod` and `val`. +#### Boolean modifier -### Include several elements +`b1 → b1_m1` — block `b1` is dependent on its boolean modifier `b1_m1` + +`b1.deps.js` file: -The `elems` behavior is somewhat different from `elem`, as it includes the block itself along with the specified elements. ```js -{ - block : 'b1', - elems : ['e1', 'e2'] -} +/* b1 → b1_m1 */ +({ + shouldDeps: [ + { block: 'b1', mod: 'm1' } + ] +}) ``` -The `elems` key may contain not only a name, but a full description of elements being included: +*OR* + +`b1.deps.js` file: + ```js -{ - block : 'b1', - elems : [ - { elem : 'e1' }, - { elem : 'e2', mods : { m1 : 'v1' } } +/* b1 → b1_m1 */ +({ + shouldDeps: [ + { block: 'b1', mod: 'm1', val: true } ] -} +}) ``` -### Include dependencies for specific technologies +### Including dependencies for technologies + +`b1.js → b2.bemhtml` — block `b1` in the JavaScript implementation is dependent on block `b2` in the BEMHTML implementation + +`b1.deps.js` file: -To include `b1` block templates with `_m1_v1` modifier as a part of a client-side JS build, use the following syntax to specify dependencies in a deps-entity: ```js -{ +/* b1.js → b2.bemhtml */ +({ tech: 'js', - mustDeps: [ - { - block: 'b1', - mods: { m1: 'v1' }, - tech: 'bemhtml' - } + shouldDeps: [ + { block: 'b2', tech: 'bemhtml' } ] -} +}) ``` diff --git a/docs/depsjs/specification.en.md b/docs/depsjs/specification.en.md new file mode 100644 index 00000000..1b9e1a46 --- /dev/null +++ b/docs/depsjs/specification.en.md @@ -0,0 +1,845 @@ +# DEPS specification + +* [Introduction](#introduction) +* [Notation](#notation) +* [DEPS syntax](#deps-syntax) +* [DEPS entity fields](#deps-entity-fields) +* [Syntactic sugar](#syntactic-sugar) +* [Examples of declarations](#examples-of-declarations) + +## Introduction + +**DEPS** is a [technology for defining dependencies](depsjs.en.md) in BEM. + +A **DEPS entity** is an entity that defines a dependency between [BEM entities](https://en.bem.info/methodology/key-concepts/#bem-entity). + +Dependencies are defined as JavaScript objects in files with the `.deps.js` extension. + +The full notation of a DEPS entity looks like this: + +```js +/* DEPS entity */ +({ + block: 'block-name', + elem: 'elem-name', + mod: 'modName', + val: 'modValue', + tech: 'techName', + shouldDeps: [ /* BEM entity */ ], + mustDeps: [ /* BEM entity */ ], + noDeps: [ /* BEM entity */ ] +}) +``` + +> **Note** All fields are optional. + +## Notation + +To abbreviate dependencies in comments, use the following notation: + +* `/* b1 → b2 */` — block `b1`is dependent on block `b2` (`shouldDeps`) +* `/* b1 ⇒ b2 */` — block `b1` is dependent on block `b2` (`mustDeps`) +* `/* b1 → b1__e1 */` — block `b1` is dependent on its element `b1__e1` +* `/* b1 → b1_m1_v1 */` — block `b1` is dependent on its modifier `b1_m1_v1` +* `/* b1 → b1__e1_m1_v1 */` — block `b1` is dependent on the modifier of its element `b1__e1_m1_v1` +* `/* b1.js → b2.bemhtml */` — block `b1` in the JavaScript implementation is dependent on block `b2` in the BEMHTML implementation + +## DEPS syntax + +A DEPS entity can be represented in the `.deps.js` file using: + +1. Parentheses `()`. + + ```js + ({ + /* DEPS entity */ + }) + ``` + +2. An array literal `[]`. + + ```js + [{ + /* DEPS entity */ + }, + { + /* DEPS entity */ + }] + ``` + +## Fields of a DEPS entity + +They can be divided into the following groups: + +* Defining the BEM entity: + + * [block](#block) + * [elem](#elem) + * [mod](#mod) + * [val](#val) + +* Defining the implementation of the BEM entity: + + * [tech](#field-that-defines-the-implementation-technology-for-a-bem-entity) + +* Defining the dependency: + + * [mustDeps](#mustdeps) + * [shouldDeps](#shoulddeps) + * [noDeps](#nodeps) + +> **Note** In addition to the fields described, you can use [syntactic sugar](#syntactic-sugar) to improve code readability. + +### Fields that define the BEM entity + +The fields specify which BEM entity needs the dependencies included. They are optional and can be restored from the context by the file name. + +So the statements for the file `b1__e1_m1_v1.deps.js` are equivalent to: + +```js +/* b1__e1_m1_v1 → b2 */ +({ + block: 'b1', + elem: 'e1', + mod: 'm1', + val: 'v1', + shouldDeps: { block: 'b2' } +}) +``` + +```js +/* b1__e1_m1_v1 → b2 */ +({ + shouldDeps: { block: 'b2' } +}) +``` + +#### block + +The `block` field sets the name of the block. + +Type: `String`. + +```js +// Block b1 +({ + block: 'b1' +}) +``` + +#### elem + +The `elem` field sets the name of the element. + +Type: `String`. + +```js +// Element b1__e1 +({ + block: 'b1', + elem: 'e1' +}) +``` + +#### mod + +The `mod` field sets the name of the modifier for the block or element. + +Type: `String`. + +```js +// Modifier of the block b1_m1 set to true +({ + block: 'b1', + mod: 'm1' +}) + +// Modifier of the element b1__e1_m1 set to true +({ + block: 'b1', + elem: 'e1', + mod: 'm1' +}) +``` + +#### val + +The `val` field sets the modifier value. If `val` is omitted, the modifier is assumed to be set to `true`. + +Type: `String`, `Boolean`. + +The examples below specify the accepted data type: + +* String (`String`). + + ```js + // Modifier b1_m1_v1 set to v1 + ({ + block: 'b1', + mod: 'm1', + val: 'v1' + }) + ``` + +* Boolean, Logical type (`Boolean`). + + ```js + // Modifier b1_m1 set to true + ({ + block: 'b1', + mod: 'm1', + val: true + }) + ``` + +### Field that defines the implementation technology for the BEM entity + +The `tech` field specifies which [implementation technology](https://en.bem.info/methodology/key-concepts/#implementation-technology) to include the dependency for. If `tech` is omitted, the dependency is considered general and applies to all technologies. + +Including dependencies for a technology is used, for example, to create a client JavaScript bundle that only has templates for the blocks that will be used in the browser. In this case, part of the templating happens on the server side, so some of the templates are never used in the client. + +Type: `String`. + +```js +({ +// Block b1 in JavaScript + block: 'b1', + tech: 'js' +}) +``` + +### Fields that define the dependency + +The `shouldDeps` and`mustDeps` fields define the dependency, and `noDeps` cancels it + +#### shouldDeps + +The `shouldDeps` field defines dependencies that can be included in any order. + +Type: `Object[]`. + +```js +/* b1 → BEM entity */ +({ + block: 'b1', + shouldDeps: [ + { /* BEM entity */ } + ] +}) +``` + +#### mustDeps + +The `mustDeps` field specifies dependencies that are added to the build results before the code of the BEM entity where these dependencies are declared. + +Type: `Object[]`. + +```js +/* b1 ⇒ BEM entity */ +({ + block: 'b1', + mustDeps: [ + { /* BEM entity */ } + ] +}) +``` + +#### noDeps + +The `noDeps` field cancels existing dependencies declared on other [redefinition levels](https://en.bem.info/methodology/key-concepts/#redefinition-level). + +Type: `Object[]`. + +```js +/* common.blocks + b1 → BEM entity */ +({ + block: 'b1', + shouldDeps: [ + { /* BEM entity */ } + ] +}) + +/* desktop.blocks */ +({ + block: 'b1', + noDeps: [ + { /* BEM entity */ } + ] +}) +``` + +In this example, dependencies on the `common.blocks` level include a BEM entity that is necessary for implementing the `b1` block. On the `desktop.blocks` level, this dependency is canceled. + +> **Note** More information about [redefinition levels in BEM](https://en.bem.info/methodology/key-concepts/#redefinition-level). + +## Syntactic sugar + +* [elem](#elem-1) +* [elems](#elems) +* [mods](#mods) +* [shouldDeps, mustDeps, noDeps](#shoulddeps-mustdeps-nodeps) + +### elem + +The `elem` field can accept an array of strings as a value (`String[]`): + +```js +// Elements b1__e1 and b1__e2 +({ + block: 'b1', + elem: [ + 'e1', + 'e2' + ] +}) +``` + +### elems + +The `elems` field sets the element name and expands into `shouldDeps`. So the statements for the file `b1.deps.js` are equivalent to: + +```js +({ + /* b1 → b1__e1; b1 → b1__e2 */ + block: 'b1', + elems: [ + 'e1', + 'e2' + ] +}) +``` + +```js +({ + /* b1 → b1__e1; b1 → b1__e2 */ + block: 'b1', + shouldDeps: [ + { + elem: [ + 'e1', + 'e2' + ] + } + ] +}) +``` + +Type: `String`, `Object`, `String[]`, `Object[]`. + +The examples below specify the accepted data type: + +* `String`. + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + elems: 'e1' + }) + ``` + +* Object (`Object`). + + ```js + /* b1 → { ElemDepsEntity } */ + ({ + block: 'b1', + elems: { /* { ElemDepsEntity } */ } + }) + ``` + +* Array of strings (`String[]`). + + ```js + /* b1 → b1__e1; b1 → b1__e2 */ + ({ + block: 'b1', + elems: [ + 'e1', + 'e2' + ] + }) + ``` + +* Array of objects (`Object[]`). + + ```js + /* b1 → { ElemDepsEntity }; b1 → { ElemDepsEntity } */ + ({ + block: 'b1', + elems: [ + { /* { ElemDepsEntity } */ }, + { /* { ElemDepsEntity } */ } + ] + }) + ``` + +**ElemDepsEntity** is a JavaScript object with the following fields: + +```js +/* elemDepsEntity */ +({ + elem: 'elem-name', + mod: 'modName', + val: 'modValue', + tech: 'techName', + shouldDeps: [ /* BEM entity */ ], + mustDeps: [ /* BEM entity */ ], + noDeps: [ /* BEM entity */ ] +}) +``` + +> **Note** The `elem` field is required. + +### mods + +The `mods` field sets the modifier name and value and expands into `shouldDeps`. So the statements for the file `b1.deps.js` are equivalent to: + +```js +({ + /* b1 → b1_m1_v1; b1 → b1_m1_v2 */ + block: 'b1', + mods: { m1: [ + 'v1', + 'v2' + ] + } +}) +``` + +```js +({ + /* b1 → b1_m1_v1; b1 → b1_m1_v2 */ + block: 'b1', + shouldDeps: [ + { + block: 'b1', + mod: 'm1', + val: 'v1' + }, + { + block: 'b1', + mod: 'm1', + val: 'v1' + } + ] +}) +``` + +Type: `String[]`, `Object`. + +The examples below specify the accepted data type: + +* Array of strings (`String[]`). + + ```js + /* b1 → b1_m1; b1 → b1_m2 */ + ({ + block: 'b1', + mods: [ + 'm1', + 'm2' + ] + }) + ``` + +* The object where the property value might be: + + * String (`String`). + + ```js + /* b1 → b1_m1_v1 */ + ({ + block: 'b1', + mods: { m1: 'v1' } + }) + ``` + + * Boolean, Logical type (`Boolean`). + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + mods: { m1: true } + }) + ``` + + * Array of strings (`String[]`). + + ```js + /* b1 → b1_m1_v1; b1 → b1_m1_v2 */ + ({ + block: 'b1', + mods: { m1: [ + 'v1', + 'v2' + ] + } + }) + ``` + +### shouldDeps, mustDeps, noDeps + +Type: `String`, `Object`, `String[]`. + +The examples below specify the accepted data type: + +* String (`String`). + + ```js + /* b1 → b2 */ + ({ + block: 'b1', + shouldDeps: 'b2' + }) + ``` + +* Object (`Object`). + + ```js + /* b1 → BEM entity */ + ({ + block: 'b1', + shouldDeps: { /* BEM entity */ } + }) + ``` + +* Array of strings (`String[]`). + + ```js + /* b1 → b2; b1 → b3 */ + ({ + block: 'b1', + shouldDeps: [ + 'b2', + 'b3' + ] + }) + ``` + +## Examples of declarations + +* [Including a block](#including-a-block) +* [Including an element](#including-an-element) +* [Including a boolean modifier](#including-a-boolean-modifier) +* [Including a key-value modifier](#including-a-key-value-modifier) +* [Including dependencies for a technology](#including-dependencies-for-a-technology) +* [elem & elems](#elem--elems) +* [mod & mods](#mod--mods) +* [elems & mods](#elems--mods) + +### Including a block + +`b1 → b2` — block `b1` is dependent on block `b2`. + +The dependency can be declared as: + +* An object array (`Object[]`). + + ```js + /* b1 → b2 */ + ({ + block: 'b1', + shouldDeps: [ + { block: 'b2' } + ] + }) + ``` + + **Syntactic sugar** + +* A string (`String`). + + ```js + /* b1 → b2 */ + ({ + block: 'b1', + shouldDeps: 'b2' + }) + ``` + +* An object (`Object`). + + ```js + /* b1 → b2 */ + ({ + block: 'b1', + shouldDeps: { block: 'b2' } + }) + ``` + +* An array of strings (`String[]`). + + ```js + /* b1 → b2 */ + ({ + block: 'b1', + shouldDeps: [ + 'b2' + ] + }) + ``` + +### Including an element + +`b1 → b1__e1` — block `b1` is dependent on its element `b1__e1`. + +The dependency can be declared as: + +* An array of objects (`Object[]`). + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + shouldDeps: [ + { block: 'b1', elem: 'e1' } + ] + }) + ``` + + **Syntactic sugar** + +* A string (`String`). + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + elems: 'e1' + }) + ``` + +* An object (`Object`). + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + shouldDeps: { elem: 'e1' } + }) + ``` + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + elems: { elem: 'e1' } + }) + ``` + +* An array of strings (`String[]`). + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + elems: [ + 'e1' + ] + }) + ``` + +* An array of objects (`Object[]`). + + ```js + /* b1 → b1__e1 */ + ({ + block: 'b1', + elems: [ + { elem: 'e1' } + ] + }) + ``` + +### Including a boolean modifier + +`b1 → b1_m1` — block `b1` is dependent on its boolean modifier `b1_m1`. + +The dependency can be declared as: + +* An array of objects (`Object[]`). + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + shouldDeps: [ + { block: 'b1', mod: 'm1', val: true } + ] + }) + ``` + + **Syntactic sugar** + +* An object (`Object`). + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + shouldDeps: { block: 'b1', mod: 'm1', val: true } + }) + ``` + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + shouldDeps: { mod: 'm1', val: true } + }) + ``` + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + mods: { m1: true } + }) + ``` + +* An array of strings (`String[]`). + + ```js + /* b1 → b1_m1 */ + ({ + block: 'b1', + mods: [ + 'm1' + ] + }) + ``` + +### Including a key-value modifier + +`b1 → b1_m1_v1` — block `b1` is dependent on its key-value modifier `b1_m1_v1`. + +The dependency can be declared as: + +* An array of objects (`Object[]`). + + ```js + /* b1 → b1_m1_v1 */ + ({ + block: 'b1', + shouldDeps: [ + { block: 'b1', mod: 'm1', val: 'v1' } + ] + }) + ``` + + **Syntactic sugar** + +* An object (`Object`). + + ```js + /* b1 → b1_m1_v1 */ + ({ + block: 'b1', + shouldDeps: { mod: 'm1', val: 'v1' } + }) + ``` + + ```js + /* b1 → b1_m1_v1 */ + ({ + block: 'b1', + mods: { m1: 'v1' } + }) + ``` + + ```js + /* b1 → b1_m1_v1 */ + ({ + block: 'b1', + mods: { m1: [ + 'v1' + ] + } + }) + ``` + +### Including dependencies for technologies + +`b1.js → b2.bemhtml` — block `b1` in the JavaScript implementation is dependent on block `b2` in the BEMHTML implementation + +The dependency can be declared as: + +* An array of objects (`Object[]`). + + ```js + /* b1.js → b2.bemhtml */ + ({ + block: 'b1', + tech: 'js', + shouldDeps: [ + { block: 'b2', tech: 'bemhtml' } + ] + }) + ``` + + **Syntactic sugar** + +* An object (`Object`). + + ```js + /* b1.js → b2.bemhtml */ + ({ + block: 'b1', + tech: 'js', + shouldDeps: { block: 'b2', tech: 'bemhtml' } + }) + ``` + +### elem & elems + +Using the `elem` and `elems` fields together. + +```js +/* b1__e1 → b1__e2 */ +({ + block: 'b1', + elem: 'e1', + elems: [ + 'e1', + 'e2' + ] +}) +``` + +> **Note** Self-dependencies `/* b1__e1 → b1__e1 */` don't have a purpose, so they are ignored. + +### mod & mods + +Using the `mod` and `mods` fields together. + +```js +/* b1_m1_v1 → b1_m1_v2 */ +({ + block: 'b1', + mod: 'm1', + val: 'v1', + mods: { m1: [ + 'v1', + 'v2' + ] + } +}) +``` + +> **Note** Self-dependencies `/* b1_m1_v1 → b1_m1_v1 */` don't have a purpose, so they are ignored. + +### elems & mods + +Using the `elems` and `mods` fields together. + +```js +/* b1 → b1__e1; b1 → b1_m1_v1 */ +({ + block: 'b1', + elems: 'e1', + mods: { m1: 'v1' } +}) +``` diff --git a/docs/depsjs/specification.ru.md b/docs/depsjs/specification.ru.md index aef1e918..7b6e0751 100644 --- a/docs/depsjs/specification.ru.md +++ b/docs/depsjs/specification.ru.md @@ -194,7 +194,7 @@ ### Поле определяющее технологию реализации БЭМ-сущности -Поле `tech` указывает, для какой [технологии реализации]((https://ru.bem.info/methodology/key-concepts/#Технология-реализации)) необходимо подключить зависимость. В случае, когда `tech` не указано, зависимость считается общей и относится ко всем технологиям. +Поле `tech` указывает, для какой [технологии реализации](https://ru.bem.info/methodology/key-concepts/#Технология-реализации) необходимо подключить зависимость. В случае, когда `tech` не указано, зависимость считается общей и относится ко всем технологиям. Подключение зависимостей по технологии используется, например, для того, чтобы собрать в клиентский JavaScript-бандл шаблоны только тех блоков, которые будут использованы в браузере. При такой схеме часть шаблонизации происходит на стороне сервера и, следовательно, некоторые шаблоны на клиенте никогда не используются. From 9a9056d2d8541e0e8eb52c6c1d918c9f01509bec Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Thu, 9 Mar 2017 11:27:41 +0300 Subject: [PATCH 2/2] correct anchors --- docs/depsjs/depsjs.en.md | 8 ++++---- docs/depsjs/specification.en.md | 10 ++++------ docs/depsjs/specification.ru.md | 2 -- 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/depsjs/depsjs.en.md b/docs/depsjs/depsjs.en.md index 5cb67bcc..0a46a791 100644 --- a/docs/depsjs/depsjs.en.md +++ b/docs/depsjs/depsjs.en.md @@ -1,9 +1,9 @@ # Technology for declaring dependencies -* [Introduction](#Introduction) -* [Notation](#Notation) -* [DEPS syntax](#DEPS-syntax) -* [Examples](#Examples) +* [Introduction](#introduction) +* [Notation](#notation) +* [DEPS syntax](#deps-syntax) +* [Examples](#examples) ## Introduction diff --git a/docs/depsjs/specification.en.md b/docs/depsjs/specification.en.md index 1b9e1a46..3e2a3266 100644 --- a/docs/depsjs/specification.en.md +++ b/docs/depsjs/specification.en.md @@ -3,7 +3,7 @@ * [Introduction](#introduction) * [Notation](#notation) * [DEPS syntax](#deps-syntax) -* [DEPS entity fields](#deps-entity-fields) +* [DEPS entity fields](#fields-of-a-deps-entity) * [Syntactic sugar](#syntactic-sugar) * [Examples of declarations](#examples-of-declarations) @@ -80,7 +80,7 @@ They can be divided into the following groups: * Defining the implementation of the BEM entity: - * [tech](#field-that-defines-the-implementation-technology-for-a-bem-entity) + * [tech](#field-that-defines-the-implementation-technology-for-the-bem-entity) * Defining the dependency: @@ -271,8 +271,6 @@ Type: `Object[]`. In this example, dependencies on the `common.blocks` level include a BEM entity that is necessary for implementing the `b1` block. On the `desktop.blocks` level, this dependency is canceled. -> **Note** More information about [redefinition levels in BEM](https://en.bem.info/methodology/key-concepts/#redefinition-level). - ## Syntactic sugar * [elem](#elem-1) @@ -525,7 +523,7 @@ The examples below specify the accepted data type: * [Including an element](#including-an-element) * [Including a boolean modifier](#including-a-boolean-modifier) * [Including a key-value modifier](#including-a-key-value-modifier) -* [Including dependencies for a technology](#including-dependencies-for-a-technology) +* [Including dependencies for a technology](#including-dependencies-for-technology) * [elem & elems](#elem--elems) * [mod & mods](#mod--mods) * [elems & mods](#elems--mods) @@ -761,7 +759,7 @@ The dependency can be declared as: }) ``` -### Including dependencies for technologies +### Including dependencies for technology `b1.js → b2.bemhtml` — block `b1` in the JavaScript implementation is dependent on block `b2` in the BEMHTML implementation diff --git a/docs/depsjs/specification.ru.md b/docs/depsjs/specification.ru.md index 7b6e0751..3f407f09 100644 --- a/docs/depsjs/specification.ru.md +++ b/docs/depsjs/specification.ru.md @@ -271,8 +271,6 @@ В данном примере на уровне `common.blocks` по зависимостям подключается некая БЭМ-сущность, необходимая для реализации блока `b1`. На уровне `desktop.blocks` данная зависимость отменяется. -> **Примечание** Подробнее об [уровнях переопределения в БЭМ](https://ru.bem.info/methodology/key-concepts/#Уровень-переопределения). - ## Синтаксический сахар * [elem](#elem-1)