Table of Contents
- Install & Use
Install & Use
bemtosomewhere to your project:
git clone git://github.com/kizu/bemto.git
Include it in your
+b.block1 +e.element1 Foo +b.block2 +e('a')(href="#bar").element Bar +e.element2 Baz
would render to something like
<div class="block1"> <div class="block1__element1"> Foo </div> <div class="block2"> <a class="block2__element" href="#bar">Bar</a> </div> <div class="block1__element2"> Baz </div> </div>
“Block” is the main thing there. It creates the block from the first passed class and creates the context for all nested elements.
You can create block calling the
b mixin with some class attached to it:
That would render as
While the simple block's syntax, of course, is harder than the simple Jade's tags, the main point is to create the contexts for elements.
“Element” is a accessory element of the block. You can read on the concept of the elements in the bem methodology, or in the great article by Nicolas Gallagher (see the “Structured class names” part). Elements often are written using the block's name plus element's name with some separator (often
Bemto gives a convenient way to declare the elements: just use the
e mixin inside any block context:
+b.foo +e.bar baz
This would render like
<div class="foo"> <div class="foo__bar">baz</div> </div>
“Modifier” is a state of the block or element. It is often written with the addition of it's type and/or value after the single underscore like
block_mode_foo or just
block_foo. However, at the most cases, the block must contain either the original block/element's class, either the modifier class.
Bemto makes it easy to write such modifiers, 'cause you don't need now to write the same block's name twice:
<div class="block block_foo">bar</div>
See? You write just
.block_foo but by fact get the
But what if you need to have more than one modifier on one block or element? Bemto have a way to do so: add a class to your block or element starting with a modifier token:
+b.block_foo._bar._baz +e.element_type_lol._mode_moddy Blah
and that would render as
<div class="block block_foo block_bar block_baz"> <div class="block__element block__element_type_lol block__element_mode_moddy"> Blah </div> </div>
Changing the tag name
By default the blocks and elements render as
divs. You can change it by passing the desired tag name as an argument:
That would render as
Like any Jade tag or mixin, blocks and elements can take attributes that would go to the desired tags:
+b.foo(title="Oh, it's a title") +e('a').bar(href='#baz') baz
would render like
<div class="foo" title="Oh, it's a title"> <a class="foo__bar" href="#baz">baz</a> </div>
There are some tags like
img that must have at least one attribute set. Bemto would create attributes with some predefined values for such tags. So, for images this code —
+b.image(src="foo.png") would render
<img alt="" class="image" src="foo.png"/> — you can see that in that case there is the added empty
Also, in some cases there is a need to adjust some attributes according to other ones. For
img if the
alt is set, but the
title is not we'd need to set it to empty, 'cause there'd be a inconsistency between browsers (IE would show the
title bubble for
alt). And from the other side, if there is only
title set in an image, we'd need to clone it to
alt. Bemto do all those things.
Look at the previous example: you have there some excess code that you can throw away. It's the
('a') part — as long as you set the
href attribute, the block would automagically become the link. Also, there are other tags that you can omit:
ol context, or
span in any already inline context.
So, here is a bigger example:
+b('ul').list +b.list-item +e.link(href="foo") +e.text foo +b.list-item +e.link(href="bar") +e.text bar
Would render to
<ul class="list"> <li class="list-item"> <a class="list-item__link" href="foo"> <span class="list-item__text">foo</span> </a> </li> <li class="list-item"> <a class="list-item__link" href="bar"> <span class="list-item__text">bar</span> </a> </li> </ul>
For now that's all, but there would be other contexts in the future of bemto.
There are some settings you can set for different syntaxes of BEM.
For doing so, you must set them after including the
bemto like this:
- bemto_settings_prefix = '' - bemto_settings_element = '__' - bemto_settings_modifier = '_'
Here you can see all available settings with their default values.
If you'd like to prefix all your bemto-generated blocks, you can set the
bemto_settings_prefix setting to something, so it would be added to the beginning of all your blocks. Like this:
- bemto_settings_prefix = 'b-' +b.block +e.element foo
and that would then render as
<div class="b-block"> <div class="b-block__element"> foo </div> </div>
Setting for Element syntax
If you don't like the default elements syntax with the
__ delimiter, you can set using the
- bemto_settings_element = '-' +b.block +e.element foo
this would render to
<div class="block"> <div class="block-element"> foo </div> </div>
Setting for Modifier syntax
If you'd like to use different modifier syntax, like the one Nicolas Gallagher mentioned in his article, you can use the
- bemto_settings_modifier = '--' +b.block--modifier-name.--other-modifier foo
and that would expand to
<div class="block block--modifier-name block--other-modifier"> foo </div>
Using for building complex mixins
This is somewhat obvious, but I must mention that the bemto blocks would be great for using as the bricks for building more complex blocks. The Jade mixins work in the way where you can translate any attributes through to the any inner blocks. So you can do this:
mixin link(url) +b('span').link(href=url)&attributes(attributes) block
And then use it in this way:
+link('#Foo') Foo +link('https://github.com')._external Github +link('http://kizu.ru').url(rel="me") Here I am +link Ah, I'm not a link +link('https://github.com') +e.icon(src="http://favicon.yandex.net/favicon/github.com") +e.text Github
And that would render to
<a class="link" href="#Foo">Foo</a> <a class="link link_external" href="https://github.com">Github</a> <a class="link url" href="http://kizu.ru" rel="me">Here I am</a> <span class="link">Ah, I'm not a link</span> <a class="link" href="https://github.com"> <img alt="" class="link__icon" src="http://favicon.yandex.net/favicon/github.com"/> <span class="link__text">Github</span> </a>
There you can see almost all of the bemto features that can be used for any mixin with
attributes variable attached to any inner bemto block inside of it.
To be continued!
Id you'd like to follow on the bemto progress, follow me on twitter.
Copyright (c) 2012 Roman Komarov email@example.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.