grunt-contrast-glue

A wrapper for the Glue spriting tool, offering some advanced options.

This plugin is initially based on grunt-glue which was being used for some of our projects. However, we needed to add some features to cover High Contrast Mode for accesibility purposes.

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:

1npm install grunt-glue-hcm --save-dev

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

1grunt.loadNpmTasks('grunt-glue-hcm');

The "glue" task

Overview

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

1grunt.initConfig({
2  glue: {
3    options: {
4      // Task-specific options go here.
5    },
6    your_target: {
7      // Target-specific file lists and/or options go here.
8    },
9  },
10})

Options

All options are from the original Glue documentation. However, there are some new options:

#### high-contrast-mode

This is the reason this task was born! When you enable High Contrast Mode in Windows, you can't see any background images because they're turned off. That's cool sometimes but it's definitelly not when you are using a sprite for all the things. A button should be visible after all, right?

This mode will overwrite your output CSS from something like this:

1.sprite-play {
2	background-position: -190px -175px;
3	width: 95px;
4	height: 95px;
5}

To something like this:

1.hcm {
2	display: inline-block;
3	background-image: none !important;
4	overflow: hidden;
5	position: relative;
6}
7.hcm:before {
8	position: relative;
9	content: url('../img/_sprite.png');
10}
11.sprite-play {
12	background-position: -190px -175px;
13	width: 95px;
14	height: 95px;
15}
16.sprite-play.hcm:before {
17	width: 95px;
18	height: 95px;
19	margin: -175px 0 0 -190px;
20	display: block;
21}

So now it's up to you for the image to be high contrast mode compatible or not. You have to manually add the class .hcm to the element you want to be compatible in order to trigger this new behaviour.

If you are thinking, what is this High Contrast Mode thing? And why all this hassle? You should probably check this article on Yahoo which explains the issue, and the solution, really clearly.

A note of warning

Please, be aware that the Grunt task won't check if the parameters are correct. For example, if you provide a wrong padding setting, it's likely that Glue will complain (and the task as well) but the task doesn't perform any checks on that.

Also, you should know that every parameter which is not equal to false, will be passed as a parameter to Glue.

This is an example of how the task should look like:

glue: {
    dev: {
        files : [{
          src : 'test/img/sprite/',
          img : 'test/img/',
          css : 'test/css/'
        }],
        options: {
          retina: true,
          optipng: true,
          recursive: true,
          "high-contrast-mode": true,
          "sprite-namespace": "sprite"
        }
    }
}

Where:

* `src` : Is where your sprite images are located.
* `img` : Is where the sprite(s) will be located by Glue.
* `css` : Is where the css/less/scss file will be located by Glue.

Note that you can provide as many paths as you like to the files array.

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.

ToDo

* Testing! Testing is pending on this package.