grunt-fscss

Replaces media references in CSS files with valid FirstSpirit $CMS_REF(media:"")$ function calls.

Getting Started

This plugin requires Grunt ~1.0.0

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-fscss --save-dev

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

grunt.loadNpmTasks('grunt-fscss');

The "fscss" task

Options

seperator

Type: String Default: \n\n

addFileNameComment

Type: boolean Default: false

This option will add the source filename as a css comment at the end of each line where a url() call got replaced with a $CMS_REF()$ function call. This feature is mainly for debugging purposes.

abs

Type: number Default: undefined

Global $CMS_REF()$ `abs configuration for all referenced files.

cacheStrategy

Type: string Default: undefined

Possible options: revision

fileMapping

Type: object Default: {}

If you need to make sure that a file gets a custom reference name in generated CSS or you want to overwrite global abs configuration, fileMappingis the way to go:

grunt.initConfig({
  fscss: {
    dist: {
      options: {
        fileMapping: {
          // short syntax, just configure a custom reference name
          '/my/image.gif': 'my_image_2',
          // if you want to configure a custom reference name and an abs configuration:
          '/my/super/image.png': {
            referenceName: 'overwrite_ref_name',
            abs: 2
          }
        }
      }
    },
  },
})

Usage exmples

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

grunt.initConfig({
  fscss: {
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

A Simple example

In this example, the default options are used to replace image references to FirstSpirit $CMS_REF(media:"")$ function calls:

grunt.initConfig({
  fscss: {
    dist: {
      files: {
        'path/to/output-fs.css': ['path/to/input.css'],
      }
    }
  }
})

Some sample replacement could be:

.box {
  background: url('images/my-Great-Picture.png') no-repeat;
}

gets replaced with:

.box {
  background: url('$CMS_REF(media:"my_great_picture")$') no-repeat;
}

Multiple files per target

You can also configure multiple files that get concatenated to one output file like in this example:

grunt.initConfig({
  fscss: {
    dist: {
      options: {
        seperator: '\n\n /* next file */ \n\n'
      },
      files: {
        'path/to/output-fs.css': ['path/to/input1.css', 'path/to/input2.css'],
      }
    }
  }
})

File comments in compiled CSS

When you enable the option addFileNameComment the processor will add comments to the end of the line with the source filenames that got replaced. Here's an example:

grunt.initConfig({
  fscss: {
    options: {
      addFileNameComment: true
    }
    dist: {
      files: {
        'path/to/output-fs.css': ['path/to/input.css'],
      }
    }
  }
})

Some sample output could be:

.box {
  background: url('images/my-Great-Picture.png') no-repeat;
}

gets replaced with:

.box {
  background: url('$CMS_REF(media:"my_great_picture")$') no-repeat; /* my_great_picture = images/my-Great-Picture.png */
}

Cache Strategy

When you set the option cacheStrategy to revision, grunt-fscss will add a ?rid query parameter with the FirstSpirit release revsion id to all CMS_REF calls. When no release revision ID is defined, FirstSpirit will fallback to #global.now.timeInMillis:

.box {
  background: url('images/my-Picture.png') no-repeat;
}

gets replaced with:

.box {
  background: url('$CMS_REF(media:"my_picture")$?rid=$CMS_VALUE(ref(media:"my_picture").target.releaseRevision.id, default:#global.now.timeInMillis)$') no-repeat;
}

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.

Changelog

See CHANGELOG.md