grunt-fscss
v0.5.2
Published
Replaces media references in CSS files with valid FirstSpirit $CMS_REF(media:"")$ function calls.
Downloads
11
Maintainers
Readme
grunt-fscss
Replaces media references in CSS files with valid FirstSpirit $CMS_REF(media:"")$ function calls.
Getting Started
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');
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, fileMapping
is 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