Susy 3.0.8

Syntax Utilities for Extending Susy

There are many steps involved when translating between the Susy syntax layer, and the Su core math. That entire process can be condensed with these two functions. For anyone that wants to access the full power of Susy, and build their own plugins, functions, or mixins – this is the primary API for compiling user input, and accessing the core math.

This is the same technique we use internally, to keep our API layer simple and light-weight. Every function accepts two arguments, a “shorthand” description of the span or context, and an optional settings-map to override global defaults.

  • Use susy-compile() to parse, merge, and normalize all the user settings into a single map.
  • Then use su-call() to call one of the core math functions, with whatever data is needed for that function.

Examples

scss Susy API gutter function 
@function susy-gutter(
  $context: susy-get('columns'),
  $config: ()
) {
  // compile and normalize all user arguments and global settings
  $context: susy-compile($context, $config, 'context-only');
  // call `su-gutter` with the appropriate data
  @return su-call('su-gutter', $context);
}
scss Sample span mixin for floated grids 
@mixin span(
  $span,
  $config: ()
) {
  $context: susy-compile($span, $config);
  width: su-call('su-span', $context);

  $end: map-get($context, 'span') + map-get($context, 'location') - 1;
  $is-last: ($end == map-get($context, 'columns'));

  @if $is-last {
    float: right;
  } @else {
    float: left;
    margin-right: su-call('su-gutter', $context);
  }
}

Related

@function susy-compile()

@function su-call()

@function susy-compile()

Susy’s syntax layer has various moving parts, with syntax-parsing for the grid/span shorthand, and normalization for each of the resulting values. The compile function rolls this all together in a single call – for quick access from our internal API functions, or any additional functions and mixins you add to your project. Pass user input and configuration maps to the compiler, and it will hand back a map of values ready for Su. Combine this with the su-call function to quickly parse, normalize, and process grid calculations.

Parameters & Return

$short: null (list | map)

Shorthand expression to define the width of the span, optionally containing:

  • a count, length, or column-list span;
  • at $n, first, or last location on asymmetrical grids;
  • narrow, wide, or wider for optionally spreading across adjacent gutters;
  • of $n <spread> for available grid columns and spread of the container (span counts like of 6 are only valid in the context of symmetrical grids);
  • and set-gutters $n to override global gutter settings

$config: null (map)

Optional map of Susy grid configuration settings

$context-only: false (bool)

Allow the parser to ignore span and span-spread values, only parsing context and container-spread

@return (map)

Parsed and normalized map of settings, based on global and local configuration, alongwith shorthad adjustments.

Example

scss 
$user-input: 3 wide of susy-repeat(6, 120px) set-gutters 10px;
$grid-data: susy-compile($user-input, $susy);

@each $key, $value in $grid-data {
  /* #{$key}: #{$value}, */
}
css compiled 
/* columns: 120px 120px 120px 120px 120px 120px, */
/* gutters: 10px, */
/* spread: 0, */
/* container-spread: -1, */
/* span: 3, */

Related

@function su-call()

Requires

@function susy-settings()

@function susy-normalize()

@function susy-parse()

Used By

@function susy-span()

@function susy-gutter()

@function susy-slice()

@function susy-svg-grid()

@function su-call()

The Susy parsing and normalization process results in a map of configuration settings, much like the global $susy settings map. In order to pass that information along to Su math functions, the proper values have to be picked out, and converted to arguments.

The su-call function streamlines that process, weeding out the unnecessary data, and passing the rest along to Su in the proper format. Combine this with susy-compile to quickly parse, normalize, and process grid calculations.

Parameters & Return

$name: ('su-span' | 'su-gutter' | 'su-slice')

Name of the Su math function to call.

$config: (map)

Parsed and normalized map of Susy configuration settings to use for math-function arguments.

@return (*)

Results of the function being called.

Example

scss 
$user-input: 3 wide of susy-repeat(6, 120px) set-gutters 10px;
$grid-data: susy-compile($user-input, $susy);

.su-span {
  width: su-call('su-span', $grid-data);
}
css compiled 
.su-span {
  width: 390px;
}

Related

@function susy-compile()

Requires

@function _susy-error() [private]

@function su-span()

@function su-gutter()

@function su-slice()

Used By

@function susy-span()

@function susy-gutter()

@function susy-slice()

@function susy-svg-grid()

@function _susy-svg-offset() [private]