Colouro Sync

Colouro Sync is a tool for real-time synchronization of the color scheme being edited in Colouro app. Each time color scheme is updated, it gets stored into defined file.

Getting started

Install colouro-sdk package into your node project:
```
 npm install --save-dev colouro-sdk
```

Create template CSS/SCSS/LESS file like this (Sass example named scss/colors.scss.in):

 $primary-foreground:     {{fg-maj}};
 $primary-background:     {{bg-maj}};
 $secondary-foreground:   {{fg-min}};
 $secondary-background:   {{bg-min}};
 $middleground:           {{mg}};

In root of your project create colouro.json file with this content:

 {
     "host": "192.168.0.42:8080",
     "template-file": "scss/colors.scss.in",
     "dest": "scss/colors.scss"
 }

In your SASS/LESS stylesheets:
1. Include the file stated in dest field of colouro.json config,
2. Use color variables.
Run Colouro app on your handset, connected to same wireless as the computer with node project.
1. In the application open connect dialog and copy the address of your handset to value of host field of colouro.json file.
Open terminal and run following npm command in root of your node project:
```
 npx colouro-sync
```
Run browser-sync task like gulp dev. Make sure that the generated file is watched for changes.

Tip: If you use gulp for building your project, you may omit the step 6 and run colouro-sync within gulp dev process. See Using with gulp section bellow for more details.

Template file syntax

In Getting started section we created simple Sass template without going into details. It may be easy to see that the template uses handlebar syntax with five named variables being expanded. These variables denote individual color purpose (semantic) as set in color scheme being edited in Colouro app.

{{fg-maj}}—major foreground,
{{bg-maj}}—major background,
{{fg-min}}—minor foreground,
{{bg-min}}—minor background,
{{mg}}—mid-ground.

`colouro.json` config file

Colouro Sync uses simple json config file being located in project root under colouro.json file with following fields:

host (string): IP address and port (always 8080) with Colouro app server running at handset, e.g. 192.168.0.1:8080
template-file (string): relative file path of template file to be expanded with current scheme colors, e.g. scss/colors.scss.in,
dest (string): relative file path of to be generated from template, e.g. scss/colors.scss,
verbose (boolean): turn the verbose mode on/off.

Version control

If your project uses some version control system like git, you may wonder what files you should store in your repository so other team members can use Colouro real-time preview (e.g. during brainstorming session).

To share the Colouro workflow, you should store following files in repository:

template file as stated in template-file field of colouro.json file,
generated file as stated in dest field of colouro.json file,
colouro.json file with configuration.

However storing colouro.json is recommend, there's stated a host with IP that may change frequently. To simplify version control, you can create colouro.local.json file in your project root with following content (replace the IP address with your handset address as displayed in Colouro app connect dialog):

{
  "host":"10.20.30.40:8080"
}

The colouro.local.json file should marked as ignored for your version system. In case of git you may add the file into your .gitignore like this:

echo colouro.local.json >> .gitignore

Using with gulp

There is a better way to setup your gulp-based workflow than running the npx colouro-sync command in own terminal window.

You may extend your gulpfile.js to make the colouro-sync functionality available right from gulp "files-watching-process".

There are just two simple steps:

At beginning of your gulpfile.js import a colouroSync function like this:
```
 const colouroSync = require('colouro-sdk').colouroSync;
```
Call the colouroSync() in any task that gets executed (usually at place where browserSync is initialized).

For instance I'm used to workflow used by StartBootstrap templates. In this case the "files-watching" task is called dev. This task depends on browserSync task which is responsible for intializing the browserSync. That's the right place to initialize the colouroSync too like this:
```
// Configure the browserSync task
gulp.task('browserSync', function() {

  // NOTE: following line was added to initialize colouro-sync
  colouroSync();

  browserSync.init({
    server: {
      baseDir: "./"
    }
  });
});
```
Note that the example above still uses the colouro.json (and colouro.local.json) config files. All the config properties can also be passed to colouroSync function as object. See colouroSync JSDoc for more info.