grunt-libsass-image

One off the biggest lacks, when switching from Compass to Libsass are the loosing off the Image Handling. This Plugin try to compensate it. It runs over your Image directory and generate a Image Map.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-libsass-image --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-libsass-image');

The "libsass_image" task

Overview

In your project's Gruntfile, add a section named libsass_image to the data object passed into grunt.initConfig().

grunt.initConfig({
  libsass_image: {
    all: {
      files:[{
        cwd:"tmp/assets/img/",
        src: [
          "single/**/*.{png,jpg,gif,jpeg}",
          "textures/**/*.{png,jpg,gif,jpeg}",
          "svg/**/*.png"
        ],
        dest: "src/scss/maps/_imagemap.scss"
      }],
      options:{
        prefix: ""
      }
    }
  },
});

Options

options.prefix

Type: String Default value: ''

Prefix the Target Selector in the Image Map. Normaly not needed.

Best use case

Seperate the Images in different Folders, when using the Mixins. The Target Selector based on the Name off the image, prefixed with the folder name.

• SVG (and PNG Fallbacks) in svg/
• Textures in textures/
• Single Images in single/

The Plugin generate now a image map:

$map-images: (  
  (selector file width heigth name ext)
  (svg-bubble 'bubble.png' 32px 32px 'bubble' '.png')
  (svg-check 'check.png' 34px 32px 'check' '.png')
  (svg-checkin2 'checkin2.png' 32px 32px 'checkin2' '.png')
  (svg-circle-blank 'circle-blank.png' 27px 32px 'circle-blank' '.png')
  (svg-circle 'circle.png' 27px 32px 'circle' '.png')
  (textures-elipse-2x 'elipse-2x.png' 314px 222px 'elipse-2x' '.png')
  (textures-elipse 'elipse.png' 157px 111px 'elipse' '.png')
  (single-header-corner 'header-corner.png' 402px 220px 'header-corner' '.png')
  (single-logo-2x 'logo-2x.png' 254px 251px 'logo-2x' '.png')
  (single-logo 'logo.png' 128px 126px 'logo' '.png')
);

SASS Mixins

// Variables 
$img-url     : '../img/';
$single-url  : '../img/single/';
$texture-url : '../img/textures/';
$svg-url     : '../img/svg/';


// Internal Mixin: Get Image Dimension
// Write the dimension off a Image in the CSS
//
// $width    [string] = The Width off the Image
// $height   [string] = The Height off the Image
// $option   [string] = both: height & width | width: width | height: height
@mixin _getImageDimensions($width, $height, $option) {
  @if $option == both {
    width: $width;
    height: $height; } 
  @else if $option == height { 
    height: $height; } 
  @else if $option == width { 
    width: $width; }
}

// Mixin: Images
// Including Single Images from the Single Directory as Background Image.
// 
// $image      [string]  = Name off the Image
// $dimensions [string]  = both: height & width | width: width | height: height
// $pos        [string]  = The Image Position - can be 'false'
// $retina     [boolean] = With set on 'true' the retina fallback will be included
@mixin image($image, $dimensions: both, $pos: false, $retina: false) {
  $imageTarget: single-#{$image};
  
  $imgFile  : null !default;
  $imgWidth : null !default;
  $imgHeight: null !default; 
  $imgName  : null !default;
  $imgExt   : null !default; 
  
  // Get Image Information
  @each $id in $map-images {
    @if nth($id,1) == $imageTarget {
      $imgFile   : nth($id,2);
      $imgWidth  : nth($id,3);
      $imgHeight : nth($id,4);
      $imgName   : nth($id,5);
      $imgExt    : nth($id,6); } } 

  background-image: url('#{$single-url}#{$imgFile}');
  background-repeat: no-repeat;
  @if $pos != false { background-position: $pos; }
  
  @include _getImageDimensions($imgWidth, $imgHeight, $dimensions);
 
  @if $retina != false {
    $imageRetinaTarget: single-#{$image}-2x;
    $secondaryImage: #{$single-url}#{$imgName}-2x#{$imgExt};
    
    .retina & {    
      background-image: url('#{$single-url}#{$imgName}-2x#{$imgExt}');
      background-size: $imgWidth $imgHeight;
    } 
  } 
} 

// Mixin: SVGPNG
// Include the SVG Background Image with a PNG Fallback.
// 
// $image      [string]  = Name off the Image - the SVG File must be in the Same directory
// $dimensions [string]  = both: height & width | width: width | height: height
// $pos        [string]  = The Image Position - can be 'false'
@mixin svgpng($image, $dimensions: both, $pos: false) {
  $imageTarget: svg-#{$image};
  
  $imgFile  : null !default;
  $imgWidth : null !default;
  $imgHeight: null !default; 
  $imgName  : null !default;
  $imgExt   : null !default; 
  
  // Get Image Information
  @each $id in $map-images {
    @if nth($id,1) == $imageTarget {
      $imgFile   : nth($id,2);
      $imgWidth  : nth($id,3);
      $imgHeight : nth($id,4);
      $imgName   : nth($id,5);
      $imgExt    : nth($id,6); 
    } 
  } 
  
  background-image: url('#{$svg-url}#{$imgFile}');

  @if $pos != false { background-position: $pos; }
    
  background-repeat: no-repeat;

  @include _getImageDimensions($imgWidth, $imgHeight, $dimensions);
  
  .svg & {
    $ext: '.svg';
    backround-image: url('#{$svg-url}#{$imgName}#{$ext}');
    background-size: $imgWidth $imgHeight; 
  }
} 


// Mixin: Textures
// Including Textures Images from the textures Directory as Background Image.
// 
// $image      [string]  = Name off the Image
// $repeat     [string]  = How the Image would be repeated. x : repeat-x | y : repeat-y
// $pos        [string]  = The Image Position - can be 'false'
// $retina     [boolean] = With set on 'true' the retina fallback will be included
@mixin texture($image, $repeat: d, $pos: false, $retina: false) {
  $imageTarget: textures-#{$image};
  
  $imgFile  : null !default;
  $imgWidth : null !default;
  $imgHeight: null !default; 
  $imgName  : null !default;
  $imgExt   : null !default; 
  
  // Get Image Information
  @each $id in $map-images {
    @if nth($id,1) == $imageTarget {
      $imgFile   : nth($id,2);
      $imgWidth  : nth($id,3);
      $imgHeight : nth($id,4);
      $imgName   : nth($id,5);
      $imgExt    : nth($id,6); } } 

  background-image: url('#{$texture-url}#{$imgFile}');

  @if $pos != false { background-position: $pos; }
  
  @if $repeat == x {
    background-repeat: repeat-x;
    height: $imgHeight; } 
  @else if $repeat == y {
    background-repeat: repeat-y;
    width: $imgWidth; } 
  
  @if $retina != false {
    .retina & {    
      background-image: url('#{$texture-url}#{$imgName}-2x#{$imgExt}');
      background-size: $imgWidth $imgHeight;  
    } 
  } 
} 

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Based on CSS-Image

Release History

(Nothing yet)