Permalink
Browse files

Merge pull request #6 from bengourley/master

Add test and improve readme
  • Loading branch information...
serby committed Mar 26, 2012
2 parents 99f7116 + 6647f4f commit 3ebce501f0fadd1029a3ed26140db0cc72c9a0bf
Showing with 95 additions and 24 deletions.
  1. +66 −23 README.md
  2. +5 −0 test/assets-alt/d.js
  3. +24 −1 test/compact.test.js
View
@@ -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)
View
@@ -0,0 +1,5 @@
+var square = function (x) {
+ return x * x;
+};
+
+square(10);
View
@@ -4,7 +4,8 @@ var path = require('path')
, async = require('asyncjs');
var srcPath = __dirname + '/assets'
- , destPath = __dirname + '/tmp';
+ , destPath = __dirname + '/tmp'
+ , altPath = __dirname + '/assets-alt';
function createFiles(done) {
mkdirp(destPath, done);
@@ -54,6 +55,28 @@ describe('compact.js', function() {
it('should succeed with valid namespace', function() {
compact.addNamespace('global').addJs.should.be.a('function');
});
+
+ it('should add a source path to the lookup chain when given', function () {
+
+ compact.addNamespace('alternative', altPath);
+
+ // Lookup item in added path
+ (function () {
+ compact.ns.alternative.addJs('d.js');
+ }).should.not.throw();
+
+ // Lookup item in default path
+ (function () {
+ compact.ns.alternative.addJs('a.js');
+ }).should.not.throw();
+
+ // Lookup item that doesn't exist in either path
+ (function () {
+ compact.ns.alternative.addJs('xyz.js');
+ }).should.throw('Unable to find \'xyz.js\'');
+
+ });
+
});
describe('Namespace', function() {

0 comments on commit 3ebce50

Please sign in to comment.