Live LESS Theme Customizer - Documentation

Last update: 2014-06-10
Support: http://codecanyon.net/user/virtuosoft

Contents

Preface

Please do not use less files on a deployed site, because it is slow and javascript dependent. Use the customized, compiled CSS instead!

Examples

What is Less and how to use it with a theme

Less is a CSS pre-processor fully backwards compatible with any existing CSS. It can use variables and functions. You can start the work by just duplicating your existing CSS file with a .less extension and include it in the HTML file instead of the original CSS file (CSS and Less files can be used together in the HTML, and the Less file will behave just like a CSS file, so practically you can link a CSS file first and overwrite some styles with a less file - and make the variables customizable by this tool). You can define and use any number of variables, and the customizer provides a "Related variables" feature, which greatly helps the users find the proper variables when they are wanting to customize a specific element of the theme.

Please read the documentation of Less to become familiar with it (but you can even start with the Quick example, it's enough for basic functionality).

How to use this tool

First you need to use some Less in your theme

There must be a Less file included in the customizable html document. The variable definitions must be in an individual Less file and you must @include the variable definitions in the style definition Less file. More from it later.
You have to also include the /dist/lessjs.min.js file which compiles Less into CSS in the browser, and jQuery is a prerequisite to Less (any jQuery version after 1.7.2 should work): 

<link rel="stylesheet/less" type="text/css" href="less/styles.less">
<script src="/dist/jquery-1.11.3.min.js"></script>
<script src="/dist/lessjs.min.js"></script>

All variables that are defined in the provided variable-definition less file are customizable. The type of the variable is automatically determined from the default value of the variable (color pickers are automatically appearing on color values).

Then set up the customizer

The customizer.html is part of the tool and is needed for the customizer to function correctly (although you are free to rename it, it can be index.html if you prefer but then you have to name the customizable html file differently). It opens the desired customizable theme in an iframe automatically. The settings for the customizer must be specified at the very end of the customizer.html. Always customize these according to your needs.
The only limitation is that the customizer and the customizable theme must be on the same domain. 

<script>
  var customizer = LiveLessThemeCustomizer({// can call methods on the customizer variable
    context: 'theme1',                      // can use different theme customizations on the
                                            // same domain by using different context names
    htmlsrc: 'index.html',                  // defines the index page of the theme you want to customize
    lessvariablessrc: 'less/variables.less' // defines the less file that holds the less variable definitions
  });

</script>

Note that the preview can be a multi-page theme and you only need to define the index page of it!

Methods

The customizer provides the following methods for manipulating the theme and to get the current data: 

// get the current Less variables object
customizer.getLessVariables();

// update Less variables from object
customizer.updateLessVariables({'@body-bg': 'white'});

// update Less variables from Less string
customizer.importLessVariablesFromString('@body-bg: white;');

// get the Current Less variables as string
customizer.getLessVariablesString();

// reset all variables to their default values
customizer.resetLessVariablesToDefaults();

// get the custom Less code that is applied after the linked Less file's contents
customizer.getCustomLessCode();

// set the custom Less code that is applied after the linked Less file's contents
customizer.setCustomLessCode('body{background-color: white;}');

// get the current CSS as string
customizer.getCompiledCssString();

// get the current minified CSS as string
customizer.getCompiledCssStringMinified();

// get the preview document
customizer.getPreview();

Required files

These files must remain in the /dist folder (they are included in customizer.html):

The Less parser must be included in the customizable theme file(s) (you can NOT use the file that is provided on the official Less site, because this tool is using a slightly modified version):

Example configuration

index.html: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <link id="generatedcss" rel="stylesheet/less" type="text/css" href="styles.less">
    <script src="/dist/jquery-1.11.3.min.js"></script>
    <script src="/dist/lessjs.min.js"></script>
  </head>
  <body>
    <p>Lorem ipsum...</h1>
  </body>
</html>
styles.less: 
@import "variables.less"; // the variable definitions MUST be in an individual file

body {
  background-color: @bg-color;
  color: contrast(@bg-color, @text-dark, @text-light, @contrast-treshold);
}
variables.less: 
@bg-color: #0e0e0e;
End of the customizer.html file: 
<script>
  LiveLessThemeCustomizer({
    htmlsrc: 'index.html',
    lessvariablessrc: 'variables.less'
  });
</script>

Now open customizer.html in a modern browser, and your theme should be editable.

Using multiple variables files - overwriting default values in a different file

It is possible to load multipe variables files to the customizer.
An example use case is when the tool is used to customize Bootstrap. We can load the original variables.less file, and an other one which overwrites those default values. This is the recommended way to customize Bootstrap as it is much easier to maintain (we can upgrade to a newer Bootstrap version with some new variables, without the need to merge it with our changes by hand).

<script>
  LiveLessThemeCustomizer({
    htmlsrc: 'bootstrap-site.html',
    lessvariablessrc: ['bootstrap/variables.less', 'variables-overwrites.less']
  });
</script>

Less variables file definition syntax

This tool is using the same syntax that Bootstrap's customizer is using.

You can use the following comment syntaxes in the file that defines the less variables (you can use markdown formatting!):

Define group of variables

Note: Every header definition starts a new group. If accordion style is enabled in the configuration, then these will be the accordion headers.

//== Header

Define subheader

//=== Subheader

Description

//## This is a description.

Variable help

//** This is a quick help for the @variable variable.
@variable: #fff;

Hide variables from the customizer

Note: All variables are hidden since the next header definition. 

//-- The following variables are hidden from the customizer
@variable1: value1;
@variable2: value2;

The related variables feature provides a filter for those variables that affects an element on the preview page. To define them, you need to set a data attribute named data-relatedvars on the desired element and list the related variables in it (note that the position of these elements will be modified to relative - absolute, fixed or static positioned elements may not work well with this feature): 

<pre data-relatedvars="pre-color,pre-border-color,pre-padding,pre-border-width">
  This is a preview of a <pre> element.
</pre>

Customizer sidebar buttons

Device compatibility

This tool is designed for desktop browsers (IE10+). Any mobile/tablet should work, but they are not officially supported.

Sources and licenses

Live LESS Theme Customizer is using the following public libraries: