UNPKG

7.42 kBMarkdownView Raw
1# Syrup
2
3Syrup is a collection of shared UI utilities and libraries leveraged by [AI2](http://github.com/allenai) when developing interfaces.
4
5## Installation
6
7Install via `npm`:
8
9```shell
10npm install syrup
11```
12
13## API
14
15### syrup.gulp.init(gulp, [options, configParameters, paths])
16
17```javascript
18/**
19 * Registers default gulp tasks.
20 *
21 * @param {object} gulp The gulp library.
22 * @param {object} [options] Optional object definining configuration
23 * parameters.
24 * @param {boolean} [options.compressJs=true] If true javascript will be minified.
25 * Defaults to true. This causes the build
26 * to become significantly slower.
27 * @param {boolean} [options.sourceMaps=true] Enables javascript source maps. Defaults
28 * to true.
29 * @param {boolean} [options.compressCss=true] If true styles will be compressed.
30 * Defaults to true.
31 * @param {boolean} [options.detectGlobals=true] Enables browserify global detection and
32 * inclusion. This is necessary for certain
33 * npm packages to work when bundled for
34 * front-end inclusion. Defaults to true.
35 * @param {boolean} [options.insertGlobals=false] Enables automatic insertion of node
36 * globals when preparing a javascript
37 * bundler. Faster alternative to
38 * detectGlobals. Causes an extra ~1000
39 * lines to be added to the bundled
40 * javascript. Defaults to false.
41 * @param {boolean} [options.disableJsHint=false] Disables jshint. Defaults to false.
42 * @param {boolean} [options.handleExceptions=false] If an exception is encountered while
43 * compiling less or bundling javascript,
44 * capture the associated error and output
45 * it cleanly. Defaults to false.
46 * @param {string} [options.jsOut] Overrides the default filename for the
47 * resulting javascript bundle. If not set
48 * the javascript file will be the same name
49 * as the entry point.
50 * @param {boolean} [options.disableBabel=false] Optionally disable babel, the es6 to es6
51 * (and react JSX) transpiler.
52 * See http://babeljs.io for more information.
53 * @param {boolean} [options.enableStringify=false] Optionally enable stringify, a browserify
54 * transform that allows HTML files to be
55 * included via require.
56 * @param {number} [options.port=4000] Optional port for the HTTP server started
57 * via the serve task. Defaults to 4000.
58 * @param {object} [configParameters] Optional map of configuration keys. If
59 * set each key is searched for in the built
60 * HTML and replaced with the corresponding
61 * value.
62 * @param {object} [paths] Optional object defining paths relevant
63 * to the project. Any specified paths are
64 * merged with the defaults where these paths
65 * take precedence.
66 * @param {string} paths.base The base directory of your project where
67 * the gulpfile lives. Defaults to the
68 * current processes working directory.
69 * @param {string} paths.html Path to the project's HTML files.
70 * @param {string} paths.jshint Path to the javascript files which should
71 * be linted using jshint.
72 * @param {string} paths.js Javascript entry point.
73 * @param {string} paths.allLess Path matching all less files which should
74 * be watched for changes.
75 * @param {string} paths.less The less entry-point.
76 * @param {string} paths.assets Path to the project's static assets.
77 * @param {string} paths.build Output directory where the build artifacts
78 * should be placed.
79 *
80 * @returns {undefined}
81 */
82syrup.gulp.init(gulp, options, configParameters, paths)
83```
84
85The default paths are as follows.
86
87```javascript
88{
89 base: process.cwd(),
90 html: 'app/index.html',
91 allLess: 'app/**/*.less',
92 less: 'app/main.less',
93 jshint: 'app/**/*.js',
94 js: 'app/app.js',
95 assets: 'app/assets/**/*',
96 build: 'build'
97}
98```
99
100Example:
101
102```javascript
103var gulp = require('gulp');
104var syrup = require('syrup');
105
106syrup.gulp.init(gulp);
107```
108
109Now, from the command line run:
110
111```
112gulp build
113```
114
115## Default Styles
116
117Example Use:
118
119```css
120@import '../../node_modules/syrup/less/syrup.less';
121```
122
123Included Stylesheets:
124
125* `syrup/less/syrup.less`: A collection of less styles which include:
126 * `syrup/less/colors.less`: Common colors.
127 * `syrup/less/defaults.less`: Opinionated defaults.
128 * `syrup/less/dimensions.less`: Variables related to standard site dimensions.
129 * `syrup/less/functions.less`: Utility functions.
130 * `syrup/less/icons.less`: Webfont icons.
131 * `syrup/less/reset.less`: Browser style normalization.
132 * `syrup/less/responsive.less`: Basic responsiveness for specified containers.
133 * `syrup/less/text.less`: Typographic styles.
134
135Colors:
136
137The following colors are available upon including `colors.less`:
138
139```less
140/* ==========================================================================
141 AI2 Brand Colors
142 ========================================================================== */
143
144@black: #202122;
145@dark-blue: #286a8e;
146@blue: #5ea5d9;
147@gold: #fcb431;
148@yellow: #fdea65;
149@off-black: #3e4346;
150@gray: #8c9296;
151@light-blue: #bed2dd;
152@light-gray: #e0e0e0;
153@white: #fff;
154
155@lighter-gray: lighten(@light-gray, 8%);
156@lighter-blue: lighten(@light-blue, 12%);
157
158@red: #a92020;
159@green: #3fb62c;
160@purple: #81288e;
161@orange: #e26622;
162
163@shadow: rgba(45,45,46,0.1);
164@dark-shadow: rgba(45,45,46,0.2);
165@translucent: rgba(255,255,255,.95);
166```