Browse files

Improvements to readme

  • Loading branch information...
1 parent f1fea57 commit 6647f4fceb11cd89d5e8c4d6fb07f4bb90cdd025 @bengourley bengourley committed Mar 26, 2012
Showing with 66 additions and 23 deletions.
  1. +66 −23 README.md
View
89 README.md
@@ -1,75 +1,118 @@
-# compact.js - A simple JavaScript and CSS compacting middleware for express
+# compact.js
+A simple JavaScript compacting middleware for express
[![build status](https://secure.travis-ci.org/serby/compact.png)](http://travis-ci.org/serby/compact)
## Installation
- npm install compact
+ npm install compact
## Usage
-```js
+### Initialise compact:
+```js
var compact = require('compact').createCompact({
- srcPath: __dirname + '/public/src/',
- destPath: __dirname + '/public/compact/',
+ srcPath: __dirname + '/public/src/',
+ destPath: __dirname + '/public/compact/',
webPath: '/js/compact/',
debug: false
});
+```
+
+- `srcPath` is the path to your frontend JavaScript. (If you initialised your project with Express' quick start, you probably want to set this to `/public/javascripts`).
+- `destPath` is the path that compact should use to store the compacted assets.
+ If this directory does not exist, it will be created.
+- `webPath` is the public public facing route to your `destPath` (This will preceed the filename of the output `<script>` tags, so `webPath: '/js/compact/' -> <script src="/js/compact/myscript.js">`).
+- `debug` is optional. If set to true, the scripts will not be concatenated or minified.
+### Create namespaces:
+
+Namespaces are used to create different compilations of scripts. Usually, you will want to create a `global` namespace that is used everywhere:
+
+```js
compact.addNamespace('global');
compact.ns.global
- .addJs('/js/main.js')
- .addJs('/js/widget-a.js')
- .addJs('/js/widget-b.js');
+ .addJs('/js/main.js')
+ .addJs('/js/widget-a.js')
+ .addJs('/js/widget-b.js');
+```
+
+If you have some collection of scripts that will only be used on certain pages, it is a good idea to create a namespace for it. For example, if you have a banner and some ads that only appear on the homepage, and some UI that appears only on the profile page/section:
+```js
compact.addNamespace('home')
- .addJs('/js/banner.js')
- .addJs('/js/ads.js');
+ .addJs('/js/banner.js')
+ .addJs('/js/ads.js');
compact.addNamespace('profile')
- .addJs('/js/profile.js');
+ .addJs('/js/profile.js');
+```
+When creating a namespace, you can also pass in an extra `srcPath`. Calls to `addJs()` will look for the file in the given `srcPath`, and if not found it then tries the `srcPath` passed to `createCompact()`.
+
+```js
compact.addNamespace('comments', __dirname + 'libs/comments/public/src/' )
- .addJs('/js/paging.js');
- .addJs('/js/comments.js');
+ .addJs('/js/paging.js')
+ .addJs('/js/comments.js');
+```
-// All routes will have global
-app.use(compact.js(['global']))
+### Using the middleware:
+If you have created a `global` namespace, apply it to all routes like so:
+
+```js
+app.use(compact.js(['global']));
+```
+
+This will expose the view helper `compactJsHtml()` in your templates, so you can output the necessary `<script>` tags.
+
+Selectively apply namespaces to routes:
+
+```js
// Add some compacted JavaScript for just this route. Having the namespaces
// in separate arrays will produce a javascript file per array.
app.get('/', compact.js(['home'], ['profile']));
+app.get('/', function (req, res) {
+ /* Homepage logic here */
+});
-// Having different namespaces joined together will combine and output as one
-// javascript file.
+// Having different namespaces joined together
+// will combine and output as one javascript file.
app.get('/blog', compact.js(['comments', 'profile']));
-
+app.get('/', function (req, res) {
+ /* Blog page logic here */
+});
```
-Then in the view use the **compactJsHtml()** view helper in your jade
+Note: compact must be applied to your route *before* the route logic. This is so that the view helper is available when you try to render your layout.
+
+### Rendering
+
+Any route that has `compact.js()` applied will have the helper function `compactJsHtml()` available. This will render the relevant script tags. In Jade, Use like so:
```html
!=compactJsHtml()
```
-On / you'd get the following
+
+From the examples above, on `/` you'd get the following
```html
<script src="/js/compact/global.js"></script>
<script src="/js/compact/home.js"></script>
<script src="/js/compact/profile.js"></script>
```
-On /blog you'd get this
+And on `/blog` you'd get this
```html
<script src="/js/compact/global.js"></script>
<script src="/js/compact/comment-profile.js"></script>
```
-You also have access to the **compactJs()** helper which will return an array
-of files for you to include on the page.
+You also have access to the `compactJs()` helper which will return an array
+of files instead of the rendered html.
## Credits
[Paul Serby](https://github.com/serby/) follow me on [twitter](http://twitter.com/PabloSerbo)

0 comments on commit 6647f4f

Please sign in to comment.