bem-md-renderer

# BEMHTML: a templating engine for BEM **BEMHTML** is a templating engine for thous who are using [BEM metodology](https://bem.info/method) for web development. BEMHTML is: * an HTML layout in terms of blocks, elements and modifiers; * support of BEM-style CSS; * support of BEM-style JS; * declarative and impressive templates; * convenient code support for long-term developing projects. <a name="worldview"></a> ## BEMHTML: картина мира BEM methodology and BMHTML, as it's part, are the product of many-ears experience of web development and maintenance of web interfaces at Yandex. Web development at Yandex were affected by the following factors: * the need of creating a common portal style; * the need for long-term maintainable code; * the need of quick changes in the projects; * joint work on the code of different specialists. BEM was created as a solution for all these problems. At the first place it's a set of web development principles (a world-view), and only at second it's a technology. BEMHTML is one of technologies that helps to carry development according to BEM principles. Hence the problems, that BEMHTML is solving, are imposed by the same principles as for BEM. ## BEMHTML: картина мира After this principle stands a conviction that HTML and CSS are not suitable for a semantic description of web interfaces (as a framework). The reason is in the difference of interpretation of HTML and CSS for different browsers. As the result, one needs to include into HTML and CSS specific elements for providing a cross-browser compatibility. For example, in the recent past, for making a cross-browser rounded corners one needed to wrap an element in six nested `div`. Web interfaces should be described in hight-level terms (as header, button, menu, etc.). That allows us to separate **semantics** and **implementation**. Such contrast helps to divide the labor of those who design the structure of the interface (design, usability, connection with the back-end), and those who are aware of the subtleties of HTML coding (cross-browser compatibility, support for IE, etc.). The conversion (translation) of high-level interface terms in the low-level command language of the browser (HTML + CSS) reminds a compilation *assembler for the web*. ** The task for a templating engine: separate the logic of interface realization and HTML-representation. ** * Templates and the organization of interface (a set of element and layout for the page) should be described separately. BEM structure of interface is described by **BEM tree**. It's a hierarchical structure of blocks, elements and modifiers. * Templates define only the rules of HTML-decoration for the certain parts of the interface. According to BEM methodology, for each part of interface there is a corresponding ***BEM entity* (block or element with modifiers). ## BEMHTML: картина мира This principle is not unique for the web developing, and it's unlikely to cause objections. However technological features of many templating engines are often forcing to code duplication. This problem arises when the same interface element (for example a button) is being used many times. The code for the button has to be repeated on every page for every its usage. If the button changes, the developer will have to update templates of every page where the button appears. Even if the templating engine allows us to put the code for the button into the global function, in every page the button code needs to be replaced by the function call. **A templating engine should provide the ability of creation of flexible libraries of templates** Flexibility for a library means the following, for the project developer it's: * ability to use any template as a bock for the page building; * ability to modify easily any template in the project without making any changes in the library source code; for the library developer: * there should be no need of pre-design of special parts that can be overridden in the future. ### BEM BEMHTML is an expansion of BEM methodology to HTML. BEM gives an opportunity to designer, interface developer, JavaScript-coder to speak one language (in the same terms, these terms are Blocks, Elements, Modifiers). BEMHTML allows HTML coders to join them. ** The task: tools for HTML-development in terms of BEM.** * There should be a template for each BEM entity (block, element or modifier). * CSS integration within BEM style (BEM classes should be generated automatically for all blocks, elements and modifiers). * JS integration within BEM style (JS parameters should be generated automatically for blocks, elements and modifiers). ## Capability of BEMHTML ### Web-page in terms of BEM (Blocks, Elements, Modifiers) - Page structure is described in BEMJSON format, it's a JavaScript representation of the BEM tree; - The templating engine converts the BEM tree into a HTML code; - CSS integration within the BEM style - JS integration within the BEM style #### Examples The templating engine receives the following data: ```js { block: 'widgets', content: [ { elem: 'weather', content: 4 } ] } ``` There is no need in a template (the data is handled by default templates). The resulting HTML: ```xml <div class="widgets"> <div class="widgets__weather">4</div> </div> ``` If the `weather` block has a JavaScript realization with usage of `i-bem.js` one needs to use the following template for passing JavaScript parameters into the block: ```js block weather, js: { id: Math.random() * 1e4 } ``` The resulting HTML: ```xml <div class="widgets i-bem" onclick="return { 'weather': { 'id': 4321 } }"> <div class="widgets__weather">4</div> </div> ``` ### Syntax for data and templates description is based on JavaScript. - Declarative templates: the template consists of condition for usage (predicate) and data structure, that describes the resulting HTML (the template body). - JavaScript syntax is extend with a key-words (`block`, `elem`, `mods`, `elemMods`) for working with BEM entities. - For the templates an arbitrary JavaScript code can be used. There is no technical limitations placed by BEMHTML on operations in predicates or template. An efficiency and consistency of templates work is provided by developers agreements. - All BEMHTML templates are compiled in JavaScript, therefore it can be executed at the server side as well, as at the client side. #### Examples Definition of HTML tags in a declarative style: ```js block widgets { tag: 'ul' elem weather, tag: 'li' } ``` The resulting HTML: ```xml <ul class="widgets"> <li class="widgets__weather">4</li> </ul> ``` Arbitrary calculations performed in the template body: ```js block widgets, elem weather, content: { var oldContent = applyNext() return oldContent > 0 ? '+' : '' + oldContent + ' °C' } ``` The resulting HTML: ```xml <ul class="widgets"> <li class="widgets__weather">+4 °C</li> </ul> ``` ### Flexibility and extendability - BEMHTML allows us to separate a layout into an **independent blocks**, that can be combined among themselves without any restrictions. - ***Definition Levels* allow us to collect templates into libraries, and then can be used in other projects. #### Examples The input-data: ```js { block: page, content: [ { block: header, content: 'Title 1' }, { block: header, mods: { level: 2 }, content: 'Title 2' } ] } ``` Templates defined in the library: ```js block header, tag: 'h1' block header, mod level 2, tag: 'h2' ``` Templates defined in the project: ```js block header, tag: 'h2' block header, mod level 2, tag: 'h3' ``` The result: ```xml <div classs="page"> <h2 class="header"> Title 1 </h2> <h3 class="header header_level_2"> Title 2 </h3> </div> ``` ### Multi-time implementation - During runtime BEMHTML can generate additional elements, that are needed for solving layout problems (different kinds of wrappings). The initial data (BEM tree) can be modified during the templates implementation. Moreover, the same templates can be applied again to modified data. Therefore all layout wrappings can be implemented without messing-up the input data with extra elements. #### Examples The input data is a name of Yandex user: ```js { block: 'ya-user', content: 'Hamster' } ``` The template selects the first letter of the name and wraps it into instantly generated element: ```js block ya-user, content: { var oldContent = applyNext(); return [ { elem: 'first-letter', content: oldContent[0] }, oldContent.substring(1) ] } ``` The resulting HTML: ```xml <div class="ya-user"><div class="ya-user__first-letter">H</div>amster</div> ``` ## BEMHTML and other temlating engines <a name="andothers"></a> There are hundreds of different kinds of template engines. Among all of them several fields of application (generation of HTML and other text formats) and a few different approaches for text generation from data by using a template can be distinguished. By its approaches BEMHTML can be classified as "exotic". Let's take a look at several classification principles of templating engines and the place of BEMHTML among them. ### Classification by semantics (what does the templating engine) #### Strings interpolation The templating engine places a corresponding to needed data string into the text of template. In addition different conditions, variables and loops can be used. It's the largest class of templating engines. ```%username%, don't worry, be happy!``` Templaing engines of this kind: * [Mustache](http://mustache.github.com) * [Handlebars](http://handlebarsjs.com) * [Jade](https://github.com/visionmedia/jade) * [DustJS](http://linkedin.github.com/dustjs/) #### Data bind A templating engine associates data with HTML by using some rules. The rules are described separately form the HTML. ```js var html ="<span class="name"/> "+ "don't worry, be happy!" , data = { username: 'John Smith' } , map = plates.Map(); map.class('name').to('username'); plates.bind(html, data, map); ``` Examples: * [Transparency](https://github.com/leonidas/transparency) * [Flatiron.js](http://flatironjs.org/#templating) * [Angular.js](http://angularjs.org) * [Pure](http://beebole.com/pure/) **Live data bind**: the connection with a changing data can also be declared. An example of such templating engine is [Knockout.js](http://knockoutjs.com). #### Data driven A templating engine connects a data key-word with a fragment of input HTML. In this case at the begging we have the data structure, and later with help of templates it's converted into HTML. In the approaches mentioned above, a page is built form a template, that is filled up with some data. For example the XSLT template below doesn't place any restrictions on the data structure, it can include key-worlds: ```xml <xsl:template match="username"> <span class="name"> <xsl:apply-templates/> </span> </xsl:template> ``` It can also be used with the data: ```xml `<username>John Smith</username>, don't worry, be happy!` ``` Or: ```xml <ul> <li><username>Veni</username>,</li> <li><username>Vidi</username>,</li> <li><username>Vici</username></li> </ul> ``` Examples: * [XSLT](http://www.w3.org/TR/xslt) * BEMHTML ### Classification by semantics #### The final version of the text with special insertions This model is correlated with strings interpolation approach. A template looks very similar to the final HTML: ```xml <span class="name">[% username %]</span> ``` There is no need of learning a special syntax, and very often it's mentioned as an advantage of this approach. Examples: * [Mustache](http://mustache.github.com) * [Handlebars](http://handlebarsjs.com) * [DustJS](http://linkedin.github.com/dustjs/) #### Short HTML notation HTML language has a peculiar syntactic redundancy. Almost all tags have to be in pairs (one opening and one closing tag). For example if we want to declare 'there is a table', we need to mention `table` two times: in the opening tag and in the closing tag. To simplify code writing and make it more readable, some developers suggest to use the short notation for HTML. For example: ``` span.name #{username} ``` Example: #### The object-oriented syntax In this approach the rules for the HTML generation are described in a template, according to the data scope of the templating engine. ```js var html = "<span class="name"/> "+ "don't worry, be happy!" , data = { username: 'John Smith' } , map = plates.Map(); map.class('name').to('username'); plates.bind(html, data, map); ``` Examples: * [XSLT](http://www.w3.org/TR/xslt) * [Flatiron.js](http://flatironjs.org/#templating) * BEMHTML ### Classification by the base language #### One basic language The templating engine accepts only the certain programming language, and all control structures of the templates are written in this language. Examples: * [XSLT — XML](http://www.w3.org/TR/xslt) * [ECO — CoffeeScript](https://github.com/sstephenson/eco) * BEMHTML — JavaScript #### Compiling in a few different languages In the templating engine its own data scope is created. It's simple enough to allow compilation of control structures into a wide range of programming languages. Examples: * [TT2](http://www.template-toolkit.org/) * [Mustache](http://mustache.github.com) ### Why BEMHTML was build this way * **Data driven**. Templates are bounded to the data elements. Therefore it's possible to create templates as a **declarative** and **atomic** (independent and self-sufficient) statements, which connects an element with its representation in HTML. For example the *tag* of the *block "header" - `table`*. BEM-style CSS describes the style with atomic statements: the *color* of the *block "header" - red**. Such templates are similar to modules (in sense of the way they are built). Regardless to its location, the key-word will be handled by the same template. Hence there is no need of code duplication. Also the atomic statements is easy to redefine, therefore allows us to build flexible libraries. * **Subject-oriented syntax**. The main criteria for the syntax selection are: the small size of templates (without a need to repeat tags two times) and the ability to bound templates to BEM entities (but not to the HTML nodes). * **JavaScript is the basic language** JavaScript as a basic language gives many advantages: performance, portability, the active development of technologies, and the last but very important, it's familiar to HTML-coders. ### Why not XSLT? According to the classification mentioned above, BEMHTML fits to the same categories as XSLT. XSLT was being used a lot at Yandex. However BEM developers refused XSLT and developed their own templating engine because of the following reasons: * **Problems of Performance**. Implementation of transformations in XSLT has significant performance limitations. The solutions based on XSLT have significantly lower speed in comparison to the solutions based on other temolating engines. * **XSLT isn't being developed anymore**. In fact XSLT wasn't developing during the last few years. Despite the fact that in 2007 the specification XSLT 2.0 was published. Its implementation is still far from its serious usage in the real-world applications. In the absence of active development of XSLT one cannot expect performance improvements or extension of functionality. * **XSLT is not designed to work in BEM termss** In order to maximize the integration of templating engine in a set of bem-tools, a native support of BEM data scope is needed at the level of the template engine. ## How to try? ### A template of a project To start using BEHTML you need to clone [a project template](https://github.com/bem/project-stub). It has already: a prepared structure for a project, the blocks library [bem-bl](https://github.com/bem/bem-bl), environment customized for the building process and the result viewing, and very simple static page. In fact, the template of this project is a startup for a HTML coder. It can be extended with custom blocks, and any project can be based on it. ### Documentation * [Step-by-step BEMHTML guide](https://bem.info/technology/bemhtml/current/intro/) * [BEMHTML reference](https://bem.info/technology/bemhtml/current/reference/) * [bem-tools reference](https://bem.info/tools/bem/bem-tools/) * [The blocks bem-bl library documentation](https://bem.info/libs/bem-bl/)