1 | # Syrup
|
2 |
|
3 | Syrup is a collection of shared UI utilities and libraries leveraged by [AI2](http://github.com/allenai) when developing interfaces.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | Install via `npm`:
|
8 |
|
9 | ```shell
|
10 | npm 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 | */
|
82 | syrup.gulp.init(gulp, options, configParameters, paths)
|
83 | ```
|
84 |
|
85 | The 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 |
|
100 | Example:
|
101 |
|
102 | ```javascript
|
103 | var gulp = require('gulp');
|
104 | var syrup = require('syrup');
|
105 |
|
106 | syrup.gulp.init(gulp);
|
107 | ```
|
108 |
|
109 | Now, from the command line run:
|
110 |
|
111 | ```
|
112 | gulp build
|
113 | ```
|
114 |
|
115 | ## Default Styles
|
116 |
|
117 | Example Use:
|
118 |
|
119 | ```css
|
120 | @import '../../node_modules/syrup/less/syrup.less';
|
121 | ```
|
122 |
|
123 | Included 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 |
|
135 | Colors:
|
136 |
|
137 | The 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 | ```
|