README.md in bem-constructor-0.1 vs README.md in bem-constructor-0.1.1

- old
+ new

@@ -4,23 +4,21 @@ By enforcing a consistent and programatic way of defining objects (blocks, elements and modifiers) it ensures a more structured, robust and secure object codebase that is easy to understand and maintain. Objects defined using the constructor are impossible to modify and reassign by mistake or omission. Jump to [🍔 The Burger Example™](#example) to see the mixins in action. ----- - ## Key ideas The key ideas behind this library are well explained by Harry Roberts in his articles [Immutable CSS](http://csswizardry.com/2015/03/immutable-css/), [More Transparent UI Code with Namespaces](http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/) and [MindBEMding – getting your head ’round BEM syntax](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/), ### 1. Immutability Some CSS objects in your project shouldn't be able to change (mutate). They have a very specific role and you need to make sure they're not reassigned somewhere else in your codebase. In order to ensure immutability you'll need three things: a way of defining those objects, a way of recognising them and a way to guarantee you won't be able to modify them later on. By constructing objects programatically you can be confident that they are assigned once and just once. ### 2. Namespacing -Objects have a clear function. Whethere they are components, utilities o dirty hacks, we need a consistent way of telling them apart. By namespacing objects, our UI code becomes more transparent and understandable. BEM Constructor supports the following object types: +Objects have a clear function. Whether they are components, utilities o dirty hacks, we need a consistent way of telling them apart. By namespacing objects, our UI code becomes more transparent and understandable. BEM Constructor supports the following object types: - Objects - Components - Utilities - Themes @@ -33,12 +31,10 @@ ### 3. BEM structure BEM objects are composed of a block and any number of elements and/or modifiers. Using the BEM syntax for naming classes you'll produce structured code that helps you and other developers understand at a glance the relationship between those classes. The BEM constructor takes care of generating bem-compliant selectors. ----- - ## Installation There are 3 ways of installing BEM Constructor: ### Download @@ -54,12 +50,10 @@ ### Compass extension 1. `gem install bem-constructor` 2. Add `require 'bem-constructor'` to your `config.rb` ----- - ## Usage Import it into your main stylesheet: @import 'bem-constructor'; @@ -130,40 +124,37 @@ Scopes allow you to isolate code you don't have control over. @include scope($name) { ... } - ----- - ## Options ### Namespaces Switch namespaces on/off by setting the following variable: - $bem-use-namespaces: false; // defaults to true + $bem-use-namespaces: false; // defaults to true Override the default block namespaces: - $bem-block-namespaces: ( - 'object': 'obj', // defaults to 'o' - 'component': 'comp', // defaults to 'c' - 'utility': 'helper', // defaults to 'u' - ); + $bem-block-namespaces: ( + 'object': 'obj', // defaults to 'o' + 'component': 'comp', // defaults to 'c' + 'utility': 'helper', // defaults to 'u' + ); Override the default theme namespace: - $bem-theme-namespace: 'theme'; // defaults to 't' + $bem-theme-namespace: 'theme'; // defaults to 't' Override the default state namespace: - $bem-state-namespace: 'has'; // defaults to 'is' + $bem-state-namespace: 'has'; // defaults to 'is' Override the default hack namespace: - $bem-hack-namespace: 'it-wasnt-me-'; // defaults to '_' + $bem-hack-namespace: 'it-wasnt-me-'; // defaults to '_' ### BEM separators @@ -171,24 +162,21 @@ - Two underscores (__) for elements - Two hyphens for modifiers (--). You can customize them to whatever fits you needs: - $bem-element-separator: '-'; // Defaults to '__' + $bem-element-separator: '-'; // Defaults to '__' - $bem-modifier-separator: '-_-_'; // Defaults to '--' + $bem-modifier-separator: '-_-_'; // Defaults to '--' - ----- - ##<a name="example"></a> 🍔 The Burger Example™ *Disclaimer: the following Sass code may not compile into a real burger.* -```` scss +````scss @include object('burger') { texture: juicy; @include element('lettuce', 'tomato') { @@ -233,19 +221,20 @@ @include state('cold') { taste: terrible; } } +```` The compiled CSS: -```` css +````css /* The main Burger object */ .o-burger { texture: juicy; } - /* lettuce and Tomato elements */ + /* Lettuce and Tomato elements */ .o-burger__lettuce, .o-burger__tomato { quality: fresh; } /* Cheese element */ .o-burger__cheese { type: gouda; } @@ -265,18 +254,18 @@ .o-burger--veggie .o-burger__meat { type: lentils; } /* Veggie Burger block modifier modifies the Extra Topping element too */ .o-burger--veggie .o-burger__extra-topping { ingredient: avocado; } - /* But we are hackers and couldn't resist adding some Bacon back */ + /* But as hackers we couldn't resist the urge to add some Bacon back */ ._o-burger--veggie .o-burger__extra-topping { ingredient: bacon; } /* When the party Theme is Mexican, we make everything spicy */ .t-mexican .o-burger { spicy: hell-yeah; } - /* And we're all sad when the burge Is Cold */ + /* And we're all sad when a burger Is Cold */ .o-burger.is-cold { taste: terrible; } - +```` ## This is overkill, who is this for? If constructing objects programatically seems too verbose or abstract to you that's perfectly OK. This tool is not for everybody. However if you need to enforce a strict way of writing BEM objects in your project, want to make sure they won't mutate and thus produce more secure CSS, then this tool might help you.