Style Editor

The Style Editor allows a developer to isolate specific elements of the design and present options to the user in an easy-to-use interface. Using those options, a user can make presentational changes - or 'tweaks' - to those elements without having to know or edit CSS code.

Basic Syntax

Tweaks, which are added to a template's CSS or LESS files, are based on LESS variables and a JSON object that defines the style options. It looks like this.

/* tweak definitions */

// tweak: { "type" : "value", "title" : "Page Width", "min" : 500, "max" : 1400 }
@pageWidth: 600px;

// tweak: { "type" : "color", "title" : "Page Background Color" }
@pageBackgroundColor: whitesmoke;


/* styles elsewhere using the tweak variables */

.container {
  width: @pageWidth;
  background-color: @pageBackgroundColor;
}

Note: The Tweak syntax is dependent on being commented out. Ensure you have two forward slashes and a space preceding your tweak, exactly as shown above.

If you're not familiar with variables you can read more about them at LESSCSS.org.

Types of Tweaks

Value

A range slider, which returns a unit of measurement, will be added to the Style Editor. Developers can define the minimum and maximum values, default value, sensitivity of the slider as it is moved, and the number of steps included in the slider.

// tweak: { "type" : "value", "title" : "Logo Size", "min" : 50, "max" : 150, "step" : 5 }
@logoHeight: 75px;

.logo {
  max-height: @logoHeight;
}

Color

A color picker will be added to the Style Editor and will return whichever color format used in the CSS (e.g. hex, rgba).

// tweak: { "type" : "color", "title" : "Text Color" }
@textColor: #444444;

body {
  color: @textColor;
}

Typography

A series of typographic options that match the class's CSS properties will be added to the Style Editor.

// tweak: { "type" : "font", "title" : "Body Font" }
.body-font {
  font-family: Helvetica, Arial, sans-serif;
  font-weight: 400;
  font-style: normal;
  font-size: 16px;
  letter-spacing: 0em;
  line-height: 1.2em;
  text-transform: none;
}

<!-- assign the font mixin elsewhere -->
body {
  .body-font;
}

Checkbox

A class will be added to the body when a checkbox is checked. The active key/value pair defines whether or not a checkbox is checked or unchecked by default.

// tweak: { "type" : "checkbox", "title" : "Hide Social Icons", "active" : false }

.hide-social-icons .social-icons {
  display: none;
  visibility: hidden;
}

Dropdown

A class will be added to the body depending on which option is selected.

// tweak: { "type" : "dropdown", "title" : "Layout", "options" : [ "Left", "Center", "Right" ], "default" : "Center" }

.layout-left .container {
  float: left;
}
.layout-center .container {
  margin: 0 auto;
}
.layout-right .container {
  float: right;
}

Image

An image upload field will be added to the Style Editor. This is mainly useful for purely presentational images that are set in the CSS, like background images.

// tweak: { "type" : "image", "title" : "Background Image" }
.bg-image {
  background-image: url('/assets/noise.png');
  background-size: cover;
  background-position: center center;
  background-attachment: fixed;  
}

body {
  .bg-image;
}

Organization

As style options grow more numerous there are a few tools to help organize the style options for users.

Categories

Categories allow you to easily group several style options together. The syntax is very simple, just add a key value pair to a tweak. If the values in two category key/value pair match they will be grouped together under that title.

// tweak: { "type" : "color", "title" : "Link Color", "category" : "Links" }
@linkColor: #FFF;

// tweak: { "type" : "color", "title" : "Link Hover Color", "category" : "Links" }
@linkHoverColor: #CCC;

.link {
    color: @linkColor;
    &:hover {
        color: @linkHoverColor;
    }
}

Targets

Targets are visual editing tools that pair an element with its style options. When users access the style editor they can click an element and see all the style options associated with it.

NOTE: This is a beta feature. Its syntax may change in the future and there may be bugs when implementing it.

Developers must specify which tweaks to target when a user clicks on an element. Here is a look at the basic syntax. Notice the target key/value pair at the end of each tweak.

// tweak: { "type" : "color", "title" : "Link Color", "target" : ".link" }
@linkColor: #FFF;

// tweak: { "type" : "color", "title" : "Link Hover Color", "target" : ".link" }
@linkHoverColor: #000000;

.link {
  color: @linkColor;
  &:hover {
    color: @linkHoverColor;
  }
}

The target property does not respect browser specificity rules. Target rules should always avoid ambiguity. For the best results use a single class for the target property and the same class for the tweak's styles.

Show Only When Present

The showOnlyWhenPresent property defines which style tweaks correlate with which HTML elements, and makes style tweaks visible only when those elements are present.

List all the elements that relate to that style tweak, comma separated, as the example shows below.

// tweak: { "type" : "color", "title" : "Sidebars Background Color", "showOnlyWhenPresent" : '#left-sidebar, #right-sidebar'}
@sidebarsBackgroundColor: #FFF;

JavaScript Integration

Tweak values and events can be used in JavaScript. This is useful when your scripts access any style of any element that can be changed in the Style Editor.

Get Tweak Value

A tweak's value can be used in JavaScript in two steps. First, in your CSS or LESS document add a key/value pair to your tweak that sets js to true.

// tweak: { "type" : "color", "title" : "Base Text Color", "js" : true }
@textColor: #FFF;

Then, in your JavaScript, use the following line to get the value of the LESS variable.

var tweakValue = Y.Squarespace.Template.getTweakValue('textColor');

Tweak Change Event

JavaScript functions might need to execute on tweak change. For instance, if the JavaScript gets a value of an element that can be changed by tweak, the function will need to run again to detect the new value. The syntax below shows how to listed for the tweak:change event.

Y.Global.on('tweak:change', function (f) {
    console.log('You changed the ' + f.getName());
    // f.getName() in this example will return the title of the tweak.
});

Tweak Reset Event

All of the tweaks may be reset to their default values using the "Reset" button. The syntax below shows how to listen for the tweak:reset event.

Y.Global.on('tweak:reset', function (f) {
    console.log('You reset all the styles.')
});