broccoli-sass-image-vars

This is a simple broccoli plugin for generating Sass variables for your images.

Installation

npm install --save-dev broccoli-sass-image-vars

Usage examples

Plugin's first argument may be either a string (path to the directory with images) or a single broccoli tree, or even an array of paths and broccoli trees.

In the first case, you don't even need to specify the url_prefix option — the passed string will be the prefix of image URLs (you can also specify the image_root option to modify this prefix):

Brocfile.js

var imageVars = require( 'broccoli-sass-image-vars' );

var imagesTree = imageVars( 'webpub/images', {
    // Select only png and svg files under webpub/images directory
    input: [ '**/*.png', '**/*.svg' ],

    // Include data URI for all svg images and preloader.png:
    inline: [ '**/*.svg', 'preloader.png' ],

    // Specify the output Sass file:
    output: 'scss_compiled/_images.scss',

    // This prefix will be removed from the each image URL
    image_root: 'webpub',
});

In your Sass file you can import compiled variables as follows:

@import "scss_compiled/images";

.preloader:after{
    ...
    // preloader.png variables:
    width: $preloader_width;
    height: $preloader_height;
    content: $preloader_data_url // url('data:image/png;base64,....')
}

.some-resizable-bg{
    display: block;
    height: 0;
    background: $resizable_url no-repeat; // url('/images/resizable.png')
    background-size: 100%;
    padding-bottom: $resizable_padding
}

The full list of variables for the one image file:

• $filename_path — an URL string with path to the image
• $filename_url — value for css background-image property.
• $filename_data_url — the same as $filename_url, but includes data URI of image (note: variable exists only for the images are set in options.inline).
• $filename_width — the width of the image in pixels.
• $filename_height — the height of the image in pixels.
• $filename_padding — the padding-bottom css property value for the resizable backgrounds (see example above).

In the case, when you pass to the plugin a broccoli tree, created by another plugin (broccoli-imagemin, for example), you must specify the URL prefix with the option url_prefix:

Brocfile.js

var imageMin = require( 'broccoli-imagemin' );
var imageVars = require( 'broccoli-sass-image-vars' );

var optimizedImagesTree = imageMin( 'webpub/unoptimized', {
    interlaced: true,
    optimizationLevel: 3,
    progressive: true,
    lossyPNG: false
});

// By default, the "input" option is set to '*.*':
var imagesTree = imageVars( [ 'webpub/images', optimizedImagesTree ], {
    // Specify the output Sass file:
    output: 'scss_compiled/_images.scss',

    // Specify the URL prefix for images:
    url_prefix: '/images',
});

You can also setup any of plugin's options before creating trees:

Brocfile.js

var imageVars = require( 'broccoli-sass-image-vars' );

// This prefix will be removed from the each image URL:
imageVars.image_root = 'webpub';
// Turn on the query string cache buster for the each image URL:
imageVars.cache_buster = true;
// Specify the output Sass file:
imageVars.output = 'scss_compiled/_images.scss';

var imagesTree = imageVars( 'webpub/images' );

Documentation

imageVars( inputTree, options )

imageVars( [ tree1, tree2, ... ], options )

options.output {String}

Location of the output file with Sass variables.

[options.input] {Array|String}

An array of globs or a simple glob string for image files, for which sass variables must be created.

Default value: '*.*'

[options.inline] {Array|String}

An array of globs or a simple glob string for images, for which variables with data URI must be added.

Default value: []

[options.url_prefix] {String|null}

A prefix for the image URLs in Sass variables. Required when among the inputTree arguments is present a broccoli tree, returned by another plugin.

Default value: null

[options.image_root] {String|null}

A prefix which must be cut out from the image URLs. Used only when the all inputTree arguments are strings.

Default value: null

[options.cache_buster] {Boolean}

If is set to true, the cache busting via URL query string will be used (will append to the each image URL a string of form ?%ctime%, where %ctime% is a timestamp of the file last modification date).

Default value: false

Tests

npm install

npm test

License

This project is distributed under the MIT license.