Utilities

• create-config
• enabled
• value-enabled
• option
• setting
• this
• theme
• show

Create-Config

Used to merge a module's default configuration with any custom configuration

create-config($defaults, $custom, $parser)

This function also creates a global variable: $config - normally the return value of this function would be assigned to a $config variable, but there are certain usecases where you may wish to assign the value to a unique variable so it can be exposed globally - for such cases the $config variable that is required internally by Cell is generated automatically when using create-config() (with the return value of the create-config() call being used as the assignment). See an example).

Param	Type	Info
$defaults	Map	The map which holds default configuration
[$custom]	Map	The map which holds custom values
[$parser]	String	Name of function to use as a custom parser for configuration

$parser

This function will be invoked on the resultant merged map of $defaults and $custom (or just $defaults if $custom isn't passed) like so:

call(get-function($parser), $map-merged)

This is useful to act as an effective middleware for your configuration, should you need to perform any operations on it before returning it.

Example

@function config-middleware($config) {
  // recurse the function on maps
  @if type-of($config) == 'map' {
    @each $key, $value in $config {
      $config: map-set($config, $key, config-middleware($value));
    }
  }

  // convert all string values in $config to uppercase
  @if (type-of($config) == 'string') {
    $config: to-upper-case($config);
  }

  @return $config;
}

$config: create-config((
  name: 'accordion',
  color: red
), $parser: 'config-middleware');

@include module {
  ...
}

Output

.ACCORDION, [class*="ACCORDION--"] {
  color: red;
}

Enabled

Return a CSS property if the passed option is determined to be enabled

enabled($option, $true-value, $false-value)

The value will be determined to be enabled if:

• The value evaluates to a truthy value - unless the value is a map which contains an enabled key that evaluates to a falsey value

This function will only work if create-config() has been called within the module (or if you have manually created a local $config map)

Param	Type	Info
$option	(String|List)	The option of interest
$true—value	*	The value to return if $option is determined to be enabled
$false—value	*	The value to return if $option is not determined to be enabled

Example

$config: (
  name: 'accordion',
  someOption: true,
  foo: (
    bar: (
      enabled: true
    )
  )
);

@include module {
  color: enabled('someOption', red, blue);
  font-family: enabled(('foo', 'bar'), 'Comic Sans', 'Helvetica');        
  ...
}

Value Enabled

Determine if a passed value should be considered 'enabled'

value-enabled($value)

The value will be determined to be enabled if:

• The value evaluates to a truthy value - unless the value is a map which contains an enabled key that evaluates to a falsey value

Param	Type	Info
$value	*	The value to test for enablement

Example

$config: (
  name: 'accordion',
  foo: (
    bar: (
      enabled: true
    )
  )
);

@include module {
  @if value-enabled(map-get-deep('foo', 'bar')) {
    // add some styles
  }       

  ...
}

Option

Return the value of a module's option

This is an alias function for map-get-deep

option($args...)

Example

$config: (
  name: 'accordion',
  foo: 'bar'
);

@include module {
  @if option($accordion, 'foo') {
    // add some styles
  }       

  ...
}

Retreive Config From Other Modules

This is useful for retrieving config from other modules whose configuration is globally exposed:

$header: create-config((
  name: 'header',
  height: 50px
)) !global;

@include module {    
  ...
}

$billboard: create-config((
  name: 'billboard',
  padding-top: option($header, 'height')
)) !global;

@include module {    
  ...
}

However, the recommendation in this case would be to extract the common value to a theme.

Setting

Alias function for option()

This

Get a value from the module's configuration

this($options...)

This is similar to the option() function except you don't need to pass the first argument - the function will always use the current module's configuration (i.e $config).

Example

$config: (
  name: 'header',
  colors: (
    base-color: red
  )
);

@include module {    
  color: this('colors', 'base-color');
  // this is the same as:
  // color: option($header, 'colors', 'base-color');
}

Theme

Get a value from $theme if it exists

theme($options...)

This is similar to the option() function except you don't need to pass the first argument - the function will always use $theme as the first argument (this is useful when using JavaScript for configuration).

Example

@import '../../themes/myTheme.js';
@import 'config.js';

@include module {
  color: theme('primaryColor');
  // this is equivalent to:
  color: option($theme, 'primaryColor');
  // which in turn is equivalent to:
  color: map-get-deep($theme, 'primaryColor');
}