Skip to content

N
node-sass
Commit 9cc9b315 by Adeel Mujahid
Options

Merge pull request #684 from Jakobo/node_callbacks 

Adding a backwards compatible node-style callback
parents 43dbafb8 a84fcea4
Showing with 128 additions and 74 deletions
README.md
......@@ -42,7 +42,9 @@ If this project is missing an API or command line flag that has been added to [l
## Install
npm install node-sass
```
npm install node-sass
```
Some users have reported issues installing on Ubuntu due to `node` being registered to another package. [Follow the official NodeJS docs](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager) to install NodeJS so that `#!/usr/bin/env node` correctly resolved.
......@@ -53,20 +55,18 @@ Compiling versions 0.9.4 and above on Windows machines requires [Visual Studio 2
```javascript
var sass = require('node-sass');
sass.render({
file: scss_filename,
success: callback
[, options..]
});
file: scss_filename,
[, options..]
}, function(err, result) { /*...*/ });
// OR
var result = sass.renderSync({
data: scss_content
[, options..]
data: scss_content
[, options..]
});
```
### Options
The API for using node-sass has changed, so that now there is only one variable - an options hash. Some of these options are optional, and in some circumstances some are mandatory.
The API for using node-sass has changed, so that now there is only one options hash. In the options hash, some items are optional, others may be mandatory depending on circumstances.
#### file
`file` is a `String` of the path to an `scss` file for [libsass] to render. One of this or `data` options are required, for both render and renderSync.
......@@ -82,11 +82,11 @@ The callback function is passed a results object, containing the following keys:
* `css` - The compiled CSS. Write this to a file, or serve it out as needed.
* `map` - The source map
* `stats` - An object containing information about the compile. It contains the following keys:
* `entry` - The path to the scss file, or `data` if the source was not a file
* `start` - Date.now() before the compilation
* `end` - Date.now() after the compilation
* `duration` - *end* - *start*
* `includedFiles` - Absolute paths to all related scss files in no particular order.
* `entry` - The path to the scss file, or `data` if the source was not a file
* `start` - Date.now() before the compilation
* `end` - Date.now() after the compilation
* `duration` - *end* - *start*
* `includedFiles` - Absolute paths to all related scss files in no particular order.
#### error
`error` is a `Function` to be called upon occurrence of an error when rendering the scss to css. This option is optional, and only applies to the render function.
......@@ -140,64 +140,88 @@ You must define this option as well as `outFile` in order to generate a source m
#### sourceMapContents
`sourceMapContents` is a `Boolean` flag to determine whether to include `contents` in maps.
### The `render` Callback (starting from v2.1)
node-sass supports standard node style asynchronous callbacks with the signature of `function(err, result)`. In error conditions, the `error` argument is populated with the error object. In success conditions, the `result` object is populated with an object describing the result of the render call.
#### The Error Object
* `message` - The error message.
* `line` - The line number of error.
* `column` - The column number of error.
* `status` - The status code.
* `file` - The filename of error. In case `file` option was not set (in favour of `data`), this will reflect the value `stdin`.
#### The Result Object
* `css` - The compiled CSS. Write this to a file, or serve it out as needed.
* `map` - The source map
* `stats` - An object containing information about the compile. It contains the following keys:
* `entry` - The path to the scss file, or `data` if the source was not a file
* `start` - Date.now() before the compilation
* `end` - Date.now() after the compilation
* `duration` - *end* - *start*
* `includedFiles` - Absolute paths to all related scss files in no particular order.
### Examples
```javascript
var sass = require('node-sass');
sass.render({
file: '/path/to/myFile.scss',
data: 'body{background:blue; a{color:black;}}',
success: function(result) {
// result is an object: v2 change
console.log(result.css);
console.log(result.stats);
console.log(result.map)
},
error: function(error) { // starting v2.1 error is an Error-typed object
// error is an object: v2 change
console.log(error.message);
console.log(error.status); // changed from code to status in v2.1
console.log(error.line);
console.log(error.column); // new in v2
},
importer: function(url, prev, done) {
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
contents: result.data
});
});
// OR
var result = someSyncFunction(url, prev);
return {file: result.path, contents: result.data};
},
includePaths: [ 'lib/', 'mod/' ],
outputStyle: 'compressed'
file: '/path/to/myFile.scss',
data: 'body{background:blue; a{color:black;}}',
success: function(result) {
// result is an object: v2 change
console.log(result.css);
console.log(result.stats);
console.log(result.map)
},
error: function(error) { // starting v2.1 error is an Error-typed object
// error is an object: v2 change
console.log(error.message);
console.log(error.status); // changed from code to status in v2.1
console.log(error.line);
console.log(error.column); // new in v2
},
importer: function(url, prev, done) {
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
contents: result.data
});
});
// OR
var result = someSyncFunction(url, prev);
return {file: result.path, contents: result.data};
},
includePaths: [ 'lib/', 'mod/' ],
outputStyle: 'compressed'
}, function(error, result) {
// starting v2.1 the node-style callback has error (Object) and result (Object)
// the objects are identical to those provided for the error and success keys
// in the options object
});
// OR
var result = sass.renderSync({
file: '/path/to/file.scss',
data: 'body{background:blue; a{color:black;}}',
outputStyle: 'compressed',
outFile: '/to/my/output.css',
sourceMap: true, // or an absolute or relative (to outFile) path
importer: function(url, prev, done) {
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
contents: result.data
});
});
// OR
var result = someSyncFunction(url, prev);
return {file: result.path, contents: result.data};
},
file: '/path/to/file.scss',
data: 'body{background:blue; a{color:black;}}',
outputStyle: 'compressed',
outFile: '/to/my/output.css',
sourceMap: true, // or an absolute or relative (to outFile) path
importer: function(url, prev, done) {
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
contents: result.data
});
});
// OR
var result = someSyncFunction(url, prev);
return {file: result.path, contents: result.data};
},
}));
console.log(result.css);
......
lib/index.js
......@@ -127,7 +127,7 @@ function getSourceMap(options) {
* @param {Object} options
* @api private
*/
function getOptions(options) {
function getOptions(options, cb) {
options = options || {};
options.comments = options.source_comments || options.sourceComments || false;
options.data = options.data || null;
......@@ -150,21 +150,30 @@ function getOptions(options) {
var success = options.success;
options.error = function(err) {
var payload = util._extend(new Error(), JSON.parse(err));
if (cb) {
cb.call(options.context, payload, null);
}
if (error) {
error.call(options.context, util._extend(new Error(), JSON.parse(err)));
error.call(options.context, payload);
}
};
options.success = function() {
var result = options.result;
var stats = endStats(result.stats);
var payload = {
css: result.css,
map: result.map,
stats: stats
};
if (cb) {
cb.call(options.context, null, payload);
}
if (success) {
success.call(options.context, {
css: result.css,
map: result.map,
stats: stats
});
success.call(options.context, payload);
}
};
......@@ -194,8 +203,8 @@ var binding = require(getBinding());
* @api public
*/
module.exports.render = function(options) {
options = getOptions(options);
module.exports.render = function(options, cb) {
options = getOptions(options, cb);
var importer = options.importer;
......@@ -243,7 +252,6 @@ module.exports.renderSync = function(options) {
if(status) {
result.stats = endStats(result.stats);
return result;
}
......
test/api.js
......@@ -411,6 +411,28 @@ describe('api', function() {
});
});
describe('.render(options, cb)', function() {
it('should compile sass to css with file', function(done) {
var expected = 'div {\n color: yellow; }';
sass.render({
data: 'div {color: yellow;}'
}, function(err, result) {
assert.equal(result.css.trim(), expected);
done();
});
});
it('should throw error status 1 for bad input', function(done) {
sass.render({
data: '#navbar width 80%;'
}, function(err) {
assert(err.message);
assert.equal(err.status, 1);
done();
});
});
});
describe('.renderSync(options)', function() {
it('should compile sass to css with file', function(done) {
var expected = read(fixture('simple/expected.css'), 'utf8').trim();
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment