Skip to content

Module Configuration

Jump to bottom
esr360 edited this page Jan 17, 2020 · 26 revisions

One of the most powerful aspects of Cell is the ability to configure the modules that you create. Modules can be configured by either Sass, JavaScript or JSON.

Module configuration allows you to:

How Module Configuration Works

You can achieve basic configration of your Cell modules using vanilla Sass:

$myModule: (
  'size': 14px,
  'color': red
) !default;

@include module('myModule') {
  font-size: map-get($myModule, 'size');
  color: map-get($myModule, 'color');
}

...but to take advantage of the benefits listed above, configuration for a module should exist under a $config variable as a Sass map (similar to the above example). If it exists, this map will be used by various internal mechanisms of Cell, as well as gaining all the natural benefits of the above example:

$config: (
  ...
);

@include module('myModule') {
  ...
}

This variable will be looked up every time the module() mixin is invoked/included, so it's important that at the point of invoking module(), the $config variable has all the final values required by your module instance. This is good to keep in mind when using theming, where you may need to merge values from your theme/some other source (if you were using JavaScript/JSON for configuration and theming, this would be handled automatically):

$anotherSource: (
  'color': green
);

$config: map-merge-deep(
  'size': 14px,
  'color': red
), $anotherSource;

@include module('myModule') {
  ...
}

Accessing Configuration From Inside Modules

Cell provides the this() utility function which is used for retreiving values from configuration. You can also use the map-get() or map-get-deep() functions to retreive a value from $config:

Inside Your Module
font-size: map-get($config, 'size')
Equivalent To
font-size: this('size')

Creating a Module's Configuration

Depending on your workflow and how you intend to use Cell, the $config map can either be created manually or automatically.

If you want to use JavaScript/JSON for configuration, the $config variable will be created automatically using the values from your JavaScript/JSON. Otherwise, the variable can be created by calling the create-config() utility function when creating a Module Mixin.

For all other advanced scenarios, the variable can be created manually.

The Magic of Configuration

Once the $config variable has been created with your desired properties, you can now learn how these properties can be used to your benefit.

Remember that the source of your configuration might be JavaScript/JSON, but in this case by the time it reaches Cell it will be converted to a Sass map under the $config variable. So whilst the below examples use Sass maps, you might be working with, say, a JSON object - but the magic is in the key names, which are common to both Sass Maps and JavaScript/JSON Objects.

Name your module using configutation

By passing a value to the name property of your module's configuration, you do not need to pass a parameter to the module mixin (the value set by name will be used instead) (learn more).

Before
@include module('button') {
  ...
}
After
$config: (
  'name': 'button'
);

@include module {
  ...
}

Style modules/components using configuration

Read the Cell Query page for more information

Internally Cell has a powerful utility mixin called parse-cq. This mixin can accept a Sass map and invoke standard Cell mixins like modifier(), component(), sub-component(), hover() and context(), depending on the keys within the map.

This mixin gets invoked internally whenever the module() mixin is invoked, just after the @content directive is called, like so:

  ...

  // The internal `content` directive of the `module()` mixin
  @content;

  @include parse-cq($config);
}

This means if your configuration contains keys which Cell can infer behaviour from, and the corresponding value of each key is a map that contains either more keywords and/or CSS property names, then an appropriate Cell mixin will be invoked, writing new styles to the output.

To learn more about which mixins can be invoked and how to invoke them using keywords, see the Cell Query page

Configure internal Cell dynamics

Set module name

Please see the Name your module using configutation section.

Disable any CSS output

By passing an option of disable-output (with a value of true), you can prevent the module instance from outputting any CSS.

$config: (
  'disable-output': true
);

@include module('myModule') {
  display: block;
  color: red;
}
CSS Output

Useful Pages


Cell

Clone this wiki locally