grunt-fscss

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

grunt-fscss

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

This plugin requires Grunt ~0.4.5

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');

Type: String Default: \n\n

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.

Type: number Default:

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

Type: string Default:

Possible options: revision

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
          }
        }
      }
    },
  },
})

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. 
    },
  },
})

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;
}

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'],
      }
    }
  }
})

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 */
}

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;
}

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.

See CHANGELOG.md