Properties

Properties are a purpose specific SCSS file which may define colors, phrases, and options for a running instance. Variables defined by the properties configuration file may be configured per-instance.

File Format

The properties configuration file is a plain SCSS file that accepts values/variables only. Unlike regular SCSS variables, these values may be overridden when nesting the site, and also accessed from additional locations (server-side JavaScript, Mustache templates, and of course imported into other SCSS files).

Create a file at the root /🎨.scss to define your properties. This is a limited SCSS file for variables only. The following SCSS data types are supported: string, boolean, color (hex/rgb/preset), url. URLs must be absolute and point to static images contained in the source.

SCSS Access

From another SCSS file, access variables defined in the properties file just as you would any other SCSS import:


@import '/🎨';

body{
  background-image: $image-background
}
    

Mustache Access

There are several different ways to use or import properties from Mustache. Note that url(...) values are unwrapped to their paths only.

Direct Access


<!--TEMPLATE mustache-->

<img src="{{🎨.image-background}}">
    

Import Alias


<!--TEMPLATE mustache-->
{{% import * as Properties from '🎨'}}

<img src="{{Properties.image-background}}">
    

Specific Variable(s)


<!--TEMPLATE mustache-->
{{% import {image-background} from '🎨'}}

<img src="{{image-background}}">
    

JavaScript Access

A SCSS/CSS friendly convention is to use dashes for variables names such as $color-primary. If you choose this naming convention, simply be aware that from JavaScript that same variable is accessed with an underscore: Properties.color_primary Alternatively keep the dash using bracket syntax: Properties['color-primary']

From a server side JavaScript file import the properties:


import * as Properties from '🎨';

if (Properties['some-boolean-option']){
   ...
}
    

In JavaScript, string variables should be accessed as methods:


import * as Properties from '🎨';

let msg = Properties.hello();
    

Categories

There are several preset categories to group by properties by: style, messages, and options. Category presets provide a hint to the Stacklane console UI on how to group and display properties to a user configuring them. If no category is specified then style is the default.


/**
 * @category messages
 */

$ui-home: 'Home';
$ui-sign-in: 'Sign In';

/**
 * @category style
 */

$bg-color: aliceblue;
    

Use Cases

Instance-Specific Options

Certain capabilities may be optional, and checked in JavaScript or Mustache logic.


$use-new-feature: true;
    

Interface Messages

Consider centralizing your interface messages/phrases into the properties file. This will later allow localizing/translating these phrases in separate, language-specific properties files. For example:


$ui-home: 'Home';
$ui-sign-in: 'Sign In';
    

Then in a Mustache template:


<!--TEMPLATE mustache-->

<span>{{ 🎨.ui-home }}</span>
<span>{{ 🎨.ui-sign-in }}</span>
    

Arguments are supported, for example:

 
$ui-hello: 'Hello, {0}';
    

Then in a Mustache template:


<!--TEMPLATE mustache-->
{{ % import {Me} from '👤' }}

<span>{{ 🎨.ui-hello Me.name }}</span>
    

Results in:


Hello, John
    

Argument formatting options are based on the ICU project.

Modes

Consider using boolean values to provide advanced configuration or "modes" to a site. Because the values are accessible from all locations, you can go deeper than CSS alone. For example in /🎨.scss:


$my-mode: true;
        

Then in a Mustache template:


<!--TEMPLATE mustache-->
{{% import {my-mode} from '🎨'}}

{{#my-mode}}
Using special mode.
{{/my-mode}}
        

Formatting

Quotes

The straight single quote / apostrophe (U+0027) denotes literal characters. Therefore in a message it should not be used for visible text. Instead use left curly (U+2018) and right curly (U+2018) single quotes. For example on a Mac, these are option ] and shift option ].


$action-added: 'You just added ‘{0}’';