Sass - check variable for user input

Question

I'm working on building out a set of common SASS mixins. Some of these mixins have 5-10 variables, all with default values. I'd like a way to check whether a user has input values - not the variable contents, but whether there has been an actual user input. For example, in the following mixin:

@mixin backdrop($color: #000) {
    background-color: $color;
}

If a user, in their own code, calls:

@include backdrop(#000);

There should be no warning. Even though they have input the same value as the default, there is still a user input, so @warn is not required. However, if the user calls:

@include backdrop;

There should be a warning, to ensure the user knows about the possible variables.

This is a lot more useful for mixins with more variables. For example, let's say I have a standard button for my site:

@mixin button($background: #222, $textcolor: #fff, $corner-round: 5px) {
  background-color: $background;
  color: $textcolor;
  border-radius: $corner-round;
}

A user could input @include button; and they'd get a dark grey button with white text and 5px rounded corners. Often, if someone is using a mixin like this, which they didn't write themselves, they might assume - seeing @include button; used elsewhere in the code - that there were no variables. And I know best practice is to check an unfamiliar mixin for variables - but not everyone does this. So they might go in and type:

@include button;
background-color: #444;

to get a lighter grey button. I'd like to be able to warn a user who calls the mixin and provides no variables that, "Hey, there's some variables provided that you might want to use!" - that way, if they want to override the defaults, they can do it with as few lines of code as possible.

Does anyone know if this kind of user-input check is possible with SASS?

Marvin Marvin · Accepted Answer · 2017-05-04T19:43:43

@mixin backdrop($color: #000) { ... }
@include backdrop(#000); // there should be no warning
@include backdrop; // warning

Within the mixin you can't distinguish anymore if the value is given by the user or initialized with the default value. A way to solve this issue is to set a default value within the mixin signature that won't get passed in by the user. At this point I assume that you want to allow a user to get rid of any warnings by explicitly setting a value to null when using the mixin so that the default value is used (in other words: null is a valid user input to tell the mixin Yes, I'm aware of the variables but please use the default value).

We can then change the mixin signature to use false as initial default value so that we can see within the mixin if the value has been set or not. The actual default value is then set within the mixin and used only if the user has not provided any input. The code could then be like the following:

@function warn-on-false($mixin, $value, $default) {
  @if $value == false {
    @warn "Hey, there's some variables provided ... see mixin: #{$mixin}.";
    @return $default;
  } 
  @else if $value == null {
    @return $default;
  }
  @return $value;
}

@mixin button($background: false, $corner-round: false) {
  background-color: warn-on-false("button()", $background, "#222");
  border-radius: warn-on-false("button()", $corner-round, 5px);
}

.class {
  @include button; // warns for $background and $corner-round
}

.class2 {
  @include button("#444"); // warns for $corner-round
}

.class3 {
  @include button(null, 5px); // no warning
}

Console output (3x):

WARNING: Hey, there's some variables provided ... see mixin: button().
     on line 3 of style.scss, in `button'
     from line 28 of style.scss`

CSS output:

.class {
  background-color: "#222";
  border-radius: 5px;
}

.class2 {
  background-color: "#444";
  border-radius: 5px;
}

.class3 {
  background-color: "#222";
  border-radius: 5px;
}

This is yet just some food for thoughts that shows that and how it could be done. You could also think about modifying the warn-function so that it loops over a list of values, you call it then once within every mixin and only get a maximum of one warning per mixin call (in the above you get two warnings for .class). What I would do is to give advice to the user in the warning message and tell that null should explicitly be passed to the mixin if the default value should be used.

Sass - check variable for user input

2 Answers