Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 171 lines (123 sloc) 5.396 kb
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
1 ---
2 layout: default
3 permalink: docs/js.html
4 ---
5
6 # JavaScript API
1da9e42 TJ Holowaychuk js api docs
tj authored
7
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
8 Simply `require` the module, and call `render()` with the given string of Stylus code, and (optional) `options` object.
9
10 Frameworks utilizing Stylus should pass the `filename` option to provide better error reporting.
1da9e42 TJ Holowaychuk js api docs
tj authored
11
12 var stylus = require('stylus');
13
14 stylus.render(str, { filename: 'nesting.css' }, function(err, css){
15 if (err) throw err;
16 console.log(css);
17 });
18
19 We can also do the same thing in a more progressive manner:
20
21 var stylus = require('stylus');
22
23 stylus(str)
24 .set('filename', 'nesting.css')
25 .render(function(err, css){
26 // logic
27 });
28
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
29 ## .set(setting, value)
337118a TJ Holowaychuk Started @import docs. Closes #88
tj authored
30
31 Apply a setting such as a `filename`, or import `paths`:
32
33 .set('filename', __dirname + '/test.styl')
34 .set('paths', [__dirname, __dirname + '/mixins'])
35
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
36 ## .include(path)
cc45141 TJ Holowaychuk Added Renderer#include(path). Closes #214
tj authored
37
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
38 A progressive alternative to `.set('paths',...)` is `.include()`. This is ideal when exposing external Stylus libraries which expose a path.
cc45141 TJ Holowaychuk Added Renderer#include(path). Closes #214
tj authored
39
40 stylus(str)
41 .include(require('nib').path)
42 .include(process.env.HOME + '/mixins')
43 .render(...)
44
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
45 ## .import(path)
52f7f77 TJ Holowaychuk Added .import() method to js api. Closes #95
tj authored
46
47 Defer importing of the given `path` until evaluation is performed. The example below is essentially the same as doing `@import 'mixins/vendor'` within your Stylus sheet.
48
49 var stylus = require('../')
50 , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');
51
52 stylus(str)
53 .set('filename', __dirname + '/test.styl')
54 .import('mixins/vendor')
55 .render(function(err, css){
56 if (err) throw err;
57 console.log(css);
58 });
59
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
60 ## .define(name, node)
05ef2d5 TJ Holowaychuk Added support for Renderer#define(name, node) to define a global
tj authored
61
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
62 By passing a `Node`, we may define a global variable. This is useful when exposing conditional features within your library depending on the availability of another. For example the **Nib** extension library conditionally supports node-canvas, providing image generation.
63
64 However, this is not always available, so Nib may define:
05ef2d5 TJ Holowaychuk Added support for Renderer#define(name, node) to define a global
tj authored
65
66 .define('has-canvas', stylus.nodes.false);
f0ffffc TJ Holowaychuk docs for previous commit
tj authored
67 .define('some-setting', new stylus.nodes.String('some value'));
68
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
69 Stylus also casts JavaScript values to their Stylus equivalents when possible. Here are a few examples:
f0ffffc TJ Holowaychuk docs for previous commit
tj authored
70
71 .define('string', 'some string')
72 .define('number', 15.5)
73 .define('some-bool', true)
74 .define('list', [1,2,3])
1005b09 TJ Holowaychuk Added JavaScript -> Stylus node coercion utilities
tj authored
75 .define('list', [1,2,[3,4,[5,6]]])
5df60ec TJ Holowaychuk Added JavaScript object coercion support
tj authored
76 .define('list', { foo: 'bar', bar: 'baz' })
f0ffffc TJ Holowaychuk docs for previous commit
tj authored
77 .define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])
05ef2d5 TJ Holowaychuk Added support for Renderer#define(name, node) to define a global
tj authored
78
3801d0b TJ Holowaychuk Added: cast return values from js functions
tj authored
79 These same rules apply to return values in js functions as well:
80
81 .define('get-list', function(){
82 return ['foo', 'bar', 'baz'];
83 })
84
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
85 ## .define(name, fn)
1da9e42 TJ Holowaychuk js api docs
tj authored
86
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
87 This method allows you to provide a JavaScript-defined function to Stylus. Think of these as you would JavaScript-to-C++ bindings. When there's something you cannot do in Stylus, define it in JavaScript!
1da9e42 TJ Holowaychuk js api docs
tj authored
88
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
89 In this example, we define four functions: `add()`, `sub()`, `image-width()`, and `image-height()`. These functions must return a `Node`, this constructor and the other nodes are available via `stylus.nodes`.
1da9e42 TJ Holowaychuk js api docs
tj authored
90
91 var stylus = require('../')
92 , nodes = stylus.nodes
93 , utils = stylus.utils
94 , fs = require('fs');
95
96 function add(a, b) {
97 return a.operate('+', b);
98 }
99
100 function sub(a, b) {
101 return a.operate('-', b);
102 }
103
104 function imageDimensions(img) {
105 // assert that the node (img) is a String node, passing
106 // the param name for error reporting
b490a65 TJ Holowaychuk removed instanceof usage in utils
tj authored
107 utils.assertType(img, 'string', 'img');
1da9e42 TJ Holowaychuk js api docs
tj authored
108 var path = img.val;
109
110 // Grab bytes necessary to retrieve dimensions.
111 // if this was real you would do this per format,
112 // instead of reading the entire image :)
113 var data = fs.readFileSync(__dirname + '/' + path);
114
115 // GIF
116 // of course you would support.. more :)
117 if ('GIF' == data.slice(0, 3).toString()) {
118 var w = data.slice(6, 8)
119 , h = data.slice(8, 10);
120 w = w[1] << 8 | w[0];
121 h = h[1] << 8 | h[0];
122 }
123
124 return [w, h];
125 }
126
127 function imageWidth(img) {
128 return new nodes.Unit(imageDimensions(img)[0]);
129 }
130
131 function imageHeight(img) {
132 return new nodes.Unit(imageDimensions(img)[1]);
133 }
134
135 stylus(str)
136 .set('filename', 'js-functions.styl')
137 .define('add', add)
138 .define('sub', sub)
139 .define('image-width', imageWidth)
140 .define('image-height', imageHeight)
141 .render(function(err, css){
142 if (err) throw err;
143 console.log(css);
144 });
145
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
146 For further reference (until documentation is complete) please see the following files:
1da9e42 TJ Holowaychuk js api docs
tj authored
147
0ab9219 Edited documentation text for clarity, phrasing, punctuaton, grammar, et...
Zearin authored
148 - `lib/nodes/*`
149 - `lib/utils.js`
de43ffe TJ Holowaychuk .use() docs
tj authored
150
0a85298 Roman Komarov Added YAML front matter, fixed headers
kizu authored
151 ## .use(fn)
de43ffe TJ Holowaychuk .use() docs
tj authored
152
153 When called, the given `fn` is invoked with the renderer, allowing all of the methods above to be used. This allows for plugins to easily expose themselves, defining functions, paths etc.
154
155 var mylib = function(style){
156 style.define('add', add);
157 style.define('sub', sub);
158 };
159
160 stylus(str)
161 .use(mylib)
162 .render(...)
a8276e3 Allow plugins to be used in stylus.render options
Jason Sandmeyer authored
163
164 When calling the `render()` method with options, the `use` option can be given
165 a function or array of functions to be invoked with the renderer.
166
167 stylus.render(str, { use: mylib }, function(err, css){
168 if (err) throw err;
169 console.log(css);
170 });
Something went wrong with that request. Please try again.