Create a selector object

Before writing blocks of property and values, we have to set up selectors that will target DOM elements.

What is a selector object

Usually selectors are just strings. But with Trowel we need to be able to add modifiers, tags, media-queries… to our selector in a dynamic way for making Trowel variables possible.

That’s why selectors are objects, this way we can set/get/append properties to our selectors in order to print it out dynamically depending of Trowel variables’ flags.

But objects do not exists in Sass : selector object are in facts maps with as key what we call a property (and as a value… its value). Those selectors objects are created and manipuled with the function selector().

Create our first selector object

To initialize a selector object, we just require to set the block string of our selector (remember we are strongly committed to the BEM philosophy).

We will -as you can see in the snippet below- use the selector() function with as parameter new and then a string that will be our selector’s block.

// initialize a selector object
$btn--selector: selector(new 'btn');

// it equals in css to :
.btn { ... }

You can also create a new selector object with a specific syntax settings. It will overrule the syntax settings from the $trowel-config variable for this selector and its descendant.

// selector syntax options
$btn--syntax: (
  'prefix': 'c',
  'separator': (
    'prefix': '-',
    'element': '__',
    'modifier': '--',
  ),
);

// initialize a selector object
$btn--selector: selector(new 'btn' with $button--syntax);

// it equals in css to :
.c-btn { ... }

Notice that selectors initialized are only class. It cannot be id’s or tag elements. Tag elements can be added to the class via flags.

Extend our selector object

Our selector object is initialized and we can now extend it by adding properties that will specify more it.

To set or append properties to the selector, we once again have to use the function selector(), and depending of its parameter, the function will return the selector object with new or edited properties.

To understand how works selectors objets and the function selector(), try some of the functions listed below and then debug your selector variable to see how it looks like

The list of the extensions possible

Let suppose we have a $btn--selector variable where we had already initialized a selector object with the function selector(new 'btn').

In the table below we list all the possibilty to extend this selector object. Keep in mind that the selector() must be stocked into a variable.

Some properties (pseudo-classes, modifiers, modifiers-element, attributes, parents) are collections, that means they can have several values. That is why there is two starting keywords for selector() function :

• set redefines the whole properties (you can write the value has a list or just a string if your collection is just one item)
• append add a new item to the propertie’s collection.

Be aware that when the selector() function starts with the append keyword, the property name is written in singular ('modifiers' becomes 'modifier').

Print selector

Even if most of the time we will use the mixin statement() to print out a selector, you may sometime to just generate the string from your selector object for flexibility.

It is possible with the function print-selector() as shown below

// we create a selector object
$btn--selector: selector(new 'btn');

// we print out the selector with the `print-selector()` function
#{print-selector($button--selector)} svg {
  vertical-align: middle;
}

// it will be compiled into :
.btn svg {
  vertical-align: middle;
}

We got our selectors, but we need now to implement our Trowel variables in order to make the Trowel sauce !