1 | # Syrup
|
2 |
|
3 | A collection of shared UI utilities and libraries leveraged by [AI2](http://github.com/allenai) when developing interfaces.
|
4 |
|
5 | Specifically, syrup provides:
|
6 |
|
7 | * A series of [gulp](http://gulpjs.com) tasks for building a single-page client-side application.
|
8 | * A collection of [less](http://lesscss.org) styles. To see them in action, visit the [demo](http://allenai.github.io/syrup).
|
9 |
|
10 | ## Requirements
|
11 |
|
12 | * [nodejs](http://nodejs.org) >= 0.12.7 is required.
|
13 |
|
14 | ## Installation
|
15 |
|
16 | Install via [npm](http://npmjs.org):
|
17 |
|
18 | ```shell
|
19 | npm install syrup
|
20 | ```
|
21 |
|
22 | ## Gulp
|
23 |
|
24 | Syrup includes a series of gulp tasks useful for building a single-page client-side application.
|
25 |
|
26 | The [gulp tasks](#gulp-tasks) provided by syrup can be initialized like so in your `gulpfile.js`:
|
27 |
|
28 | ```javascript
|
29 | // gulpfile.js
|
30 | var gulp = require('gulp');
|
31 | var syrup = require('syrup');
|
32 |
|
33 | syrup.gulp.init(gulp);
|
34 | ```
|
35 |
|
36 | A build can then be triggered from the terminal:
|
37 |
|
38 | ```
|
39 | gulp build
|
40 | ```
|
41 |
|
42 | Watch your project for changes dynamically and start a static HTTP server for previewing the result:
|
43 |
|
44 | ```
|
45 | gulp watch-and-serve
|
46 | ```
|
47 |
|
48 | Read about all of the available [gulp tasks](#gulp-tasks), the default [project structure](#project-structure) or the full API offered by the [`syrup.gulp.init()`](#gulp-init).
|
49 |
|
50 | ## <a name="less"></a> LESS
|
51 |
|
52 | To include the all of the less styles provide by syrup, simply add the following line to your less stylesheet:
|
53 |
|
54 | ```css
|
55 | @import '../../node_modules/syrup/less/syrup.less';
|
56 | ```
|
57 |
|
58 | ## <a name="gulp-tasks"></a> Gulp Tasks
|
59 |
|
60 | Syrup provides the following tasks:
|
61 |
|
62 | - `clean`
|
63 | * Removes all build artifacts
|
64 | * `less`
|
65 | * Compiles and minifies LESS files to CSS files.
|
66 | * `jslint`
|
67 | * Lints JS files using [jshint](https://www.npmjs.com/package/gulp-jshint).
|
68 | * `js`
|
69 | * Bundles, minifies and obfuscates `js` files using [browserify](http://browserify.org) into a single, bundled script. Uses [babel](https://babeljs.io/) to provide support for ECMA6 features and [ReactJS](http://reactjs.com).
|
70 | * `assets`
|
71 | * Copies all assets into the build directory.
|
72 | * `html`
|
73 | * Copies the `index.html` file into the build directory after running the `js`, `assets`, and `less` tasks.
|
74 | * `build`
|
75 | * Builds the project by running the `assets`, `jslint`, `js`, `less`, and `html` tasks.
|
76 | * `watch`
|
77 | * Watches the project for changes and rebuilds the affected components as they occur.
|
78 | * `serve`
|
79 | * Runs an [express](http://expressjs.com) HTTP serving serving the application.
|
80 | * `watch-and-serve`
|
81 | * Runs the `watch` and `serve` tasks.
|
82 |
|
83 | ## <a name="project-structure"></a> Default Project Structure
|
84 |
|
85 | The following project structure is expected by default, but can be changed via the `paths` parameter
|
86 | of [`syrup.gulp.init()`](#gulp-init):
|
87 |
|
88 | ```javascript
|
89 | {
|
90 | // the location of your application's index.html file
|
91 | html: 'app/index.html',
|
92 | // the less files which will be watched for changes
|
93 | allLess: 'app/**/*.less',
|
94 | // the less entry-point
|
95 | less: 'app/main.less',
|
96 | // all js files to be linted using eslint
|
97 | jsLint: 'app/**/*.js',
|
98 | // the js entry-point
|
99 | js: 'app/app.js',
|
100 | // static assets (images, fonts, etc)
|
101 | assets: 'app/assets/**/*',
|
102 | // the location of build output
|
103 | build: 'build'
|
104 | }
|
105 | ```
|
106 |
|
107 | ## <a name="gulp-init"></a> Gulp API
|
108 |
|
109 | ```javascript
|
110 | /**
|
111 | * Registers default gulp tasks.
|
112 | *
|
113 | * @param {object} gulp The gulp library.
|
114 | * @param {object} [options] Optional object definining configuration
|
115 | * parameters.
|
116 | * @param {boolean} [options.compressJs=true] If true javascript will be minified.
|
117 | * Defaults to true. This causes the build
|
118 | * to become significantly slower.
|
119 | * @param {boolean} [options.sourceMaps=true] Enables javascript source maps. Defaults
|
120 | * to true.
|
121 | * @param {boolean} [options.compressCss=true] If true styles will be compressed.
|
122 | * Defaults to true.
|
123 | * @param {boolean} [options.detectGlobals=true] Enables browserify global detection and
|
124 | * inclusion. This is necessary for certain
|
125 | * npm packages to work when bundled for
|
126 | * front-end inclusion. Defaults to true.
|
127 | * @param {boolean} [options.insertGlobals=false] Enables automatic insertion of node
|
128 | * globals when preparing a javascript
|
129 | * bundler. Faster alternative to
|
130 | * detectGlobals. Causes an extra ~1000
|
131 | * lines to be added to the bundled
|
132 | * javascript. Defaults to false.
|
133 | * @param {boolean} [options.disableJsLint=false] Disables javascript linter. Defaults to false.
|
134 | * @param {boolean} [options.handleExceptions=false] If an exception is encountered while
|
135 | * compiling less or bundling javascript,
|
136 | * capture the associated error and output
|
137 | * it cleanly. Defaults to false.
|
138 | * @param {string} [options.jsOut] Overrides the default filename for the
|
139 | * resulting javascript bundle. If not set
|
140 | * the javascript file will be the same name
|
141 | * as the entry point.
|
142 | * @param {boolean} [options.disableBabel=false] Optionally disable babel, the es6 to es6
|
143 | * (and react JSX) transpiler.
|
144 | * See http://babeljs.io for more information.
|
145 | * @param {boolean} [options.enableStringify=false] Optionally enable stringify, a browserify
|
146 | * transform that allows HTML files to be
|
147 | * included via require.
|
148 | * @param {number} [options.port=4000] Optional port for the HTTP server started
|
149 | * via the serve task. Defaults to 4000.
|
150 | * @param {object} [configParameters] Optional map of configuration keys. If
|
151 | * set each key is searched for in the built
|
152 | * HTML and replaced with the corresponding
|
153 | * value.
|
154 | * @param {object} [paths] Optional object defining paths relevant
|
155 | * to the project. Any specified paths are
|
156 | * merged with the defaults where these paths
|
157 | * take precedence.
|
158 | * @param {string} paths.base The base directory of your project where
|
159 | * the gulpfile lives. Defaults to the
|
160 | * current processes working directory.
|
161 | * @param {string} paths.html Path to the project's HTML files.
|
162 | * @param {string} paths.jsLint Path to the javascript files which should
|
163 | * be linted using eslint.
|
164 | * @param {string} paths.js Javascript entry point.
|
165 | * @param {string} paths.allLess Path matching all less files which should
|
166 | * be watched for changes.
|
167 | * @param {string} paths.less The less entry-point.
|
168 | * @param {string} paths.assets Path to the project's static assets.
|
169 | * @param {string} paths.build Output directory where the build artifacts
|
170 | * should be placed.
|
171 | *
|
172 | * @returns {undefined}
|
173 | */
|
174 | syrup.gulp.init(gulp, options, configParameters, paths)
|
175 | ```
|