Block Element Modifier (BEM) is a methodology that helps to write neat, reusable CSS classes. Components usually consist of a block and multiple elements inside this block. To apply styles to a component you simply add a CSS class to the block. BEM also requires you to add classes to the elements to make sure styles apply even if the DOM changes. Modifiers can be used to describe a special mutation of a block. Learn more about BEM at https://en.bem.info. A typical BEM pattern looks like this:

<div class="bem-block">
  <div class="bem-block__item">...</div>
  <div class="bem-block__item">...</div>
  <div class="bem-block__item">...</div>
</div>

<div class="bem-block bem-block--error">
  <div class="bem-block__item">...</div>
  <div class="bem-block__item">...</div>
</div>

The corresponding SCSS file would look like this:

.bem-block {

  color: white;

  &__item {
    margin-bottom: 10px;
  }

  &--error {
    color: red;
  }
}

The easiest way to apply all those CSS classes correctly is to use the BEMPlugin. To learn how to use Plugins, see Section 7.1, “Studio Plugins”. You will have to apply the plugin to the container and all items will automatically be provided with the correct CSS classes. The Plugin even takes care of items that are added later on.

<Container>
  <items>
  ...
  </items>
  <plugins>
    <ui:BEMPlugin block="bem-block"
                  defaultElement="item"
                  modifier="error"/>
  </plugins>
</Container>

BEM classes can be applied by using the untyped configuration bemElement:

<Container>
  <plugins>
    <ui:BEMPlugin block="bem-block"/>
  </plugins>
  <items>
    <Button u:bemElement="my-button"/>
  </items>
</Container>

The previous example adds the .bem-block__my-button CSS class to the button component. You can also add CSS classes to certain elements by using the BEMMixin. The mixin has to be used on components inside a container that uses the BEMPlugin. Since the Jangaroo compiler supports mixins, you can also write:

<Container>
  <items>
    <Button>
      <mixins>
        <ui:BEMMixin bemElement="my-button"/>
      </mixins>
    </Button>
  </items>
  <plugins>
    <ui:BEMPlugin block="bem-block"/>
  </plugins>
</Container>

If you want to add space between items of a container you can use the HorizontalSpacingPlugin or VerticalSpacingPlugin, which internally make use of the BEMPlugin and its default Element parameter.

<Container>
  <items>
    ...
  </items>
  <plugins>
    <ui:VerticalSpacingPlugin modifier="{SpacingBEMEntities.VERTICAL_SPACING_MODIFIER_200}"/>
  </plugins>
</Container>

The default spacing between items in a container that uses the Vertical- or HorizontalSpacingPlugin is 6 pixels. By using a modifier, this spacing can be adjusted. You can also enhance the plugin by passing other strings as the modifier parameter, but you will obviously have to write own styles for the resulting CSS classes.