Close GH-3: Grunt 0.4 compatible implementation.

gruntjs · Jan 30, 2013 · b5cbe65 · b5cbe65
1 parent fb81744
commit b5cbe65
Show file tree

Hide file tree

Showing 11 changed files with 363 additions and 75 deletions.
diff --git a/.jshintrc b/.jshintrc
@@ -1,14 +1,27 @@
 {
+  "globals": {
+    "before": false,
+    "describe": false,
+    "it": false
+  },
+  "node": true,
+  "browser": true,
+  "es5": true,
+  "esnext": true,
+  "bitwise": true,
+  "camelcase": true,
   "curly": true,
   "eqeqeq": true,
   "immed": true,
+  "indent": 2,
   "latedef": true,
   "newcap": true,
   "noarg": true,
-  "sub": true,
+  "quotmark": "single",
+  "regexp": true,
   "undef": true,
-  "boss": true,
-  "eqnull": true,
-  "node": true,
-  "es5": true
-}
+  "unused": true,
+  "strict": true,
+  "trailing": true,
+  "smarttabs": true
+}
diff --git a/AUTHORS b/AUTHORS
@@ -0,0 +1 @@
+Frederick Ros (https://github.com/sleeper)
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -8,37 +8,31 @@
 
 'use strict';
 
-module.exports = function(grunt) {
+module.exports = function (grunt) {
   // Project configuration.
   grunt.initConfig({
     jshint: {
       all: [
         'Gruntfile.js',
         'tasks/*.js',
-        '<%= nodeunit.tests %>'
+        'test/*.js'
       ],
       options: {
         jshintrc: '.jshintrc'
       }
     },
 
-    // Before generating any new files, remove any previously-created files.
-    clean: {
-      test: ['tmp']
-    },
-
-    // Configuration to be run (and then tested).
-    livereload: {
-      compile: {
-        files: {
-          'tmp/': ['test/fixtures/']
-        }
-      }
-    },
-
     // Unit tests.
-    nodeunit: {
-      tasks: ['test/*_test.js']
+    simplemocha: {
+      options: {
+        globals: ['should'],
+        timeout: 3000,
+        ignoreLeaks: false,
+        ui: 'bdd',
+        reporter: 'spec'
+      },
+
+      all: { src: 'test/**/*.js' }
     }
   });
 
@@ -48,12 +42,12 @@ module.exports = function(grunt) {
   // These plugins provide necessary tasks.
   grunt.loadNpmTasks('grunt-contrib-clean');
   grunt.loadNpmTasks('grunt-contrib-jshint');
-  grunt.loadNpmTasks('grunt-contrib-nodeunit');
+  grunt.loadNpmTasks('grunt-simple-mocha');
   grunt.loadNpmTasks('grunt-contrib-internal');
 
   // Whenever the "test" task is run, first clean the "tmp" dir, then run this
   // plugin's task(s), then test the result.
-  grunt.registerTask('test', ['livereload', 'nodeunit', 'clean']);
+  grunt.registerTask('test', ['simplemocha']);
 
   // By default, lint and run all tests.
   grunt.registerTask('default', ['test', 'build-contrib']);

diff --git a/README.md b/README.md
@@ -17,51 +17,115 @@ npm install grunt-contrib-livereload --save-dev
 ## Livereload task
 _Run this task with the `grunt livereload` command._
 
+### grunt-contrib-livereload [![Build Status](https://secure.travis-ci.org/gruntjs/grunt-contrib-livereload.png?branch=master)](http://travis-ci.org/gruntjs/grunt-contrib-livereload)
 
-_This plugin is a placeholder for the upcoming live reload task._
+> Reload assets live in the browser
+
+#### Getting Started
+If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide, as it explains how to create a [gruntfile][Getting Started] as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:
+
+```shell
+npm install grunt-contrib-livereload --save-dev
+```
+
+[grunt]: http://gruntjs.com/
+[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
+
+#### Introduction
+
+`grunt-contrib-livereload` is composed of 2 tasks:
+* one to setup a local server that will serve the needed js file and the wesocket that will control your browser (`livereload-start`)
+* one to trigger the reload of the browser(s) (`livereload`)
+
+Additionally a connect middleware is available to insert on the fly in your HTML page the snippet of javascript that will start he connect to the livereload server.
+
+This task support multi-browser: all the browsers listening on the tiny-lr port will be reloaded at the same time.
+
+Note that `grunt-contrib-livereload` is designed to use [grunt-regarde](https://github.com/yeoman/grunt-regarde) instead `grunt-contrib-watch` (mainly due to shortcomings in the `watch` task which doesn't give access to changed files because it spawns tasks in subprocesses.)
+
+#### The livereload-start task
+
+This task starts a server in the background. This server (implemented thanks to [mklabs/tiny-lr](https://github.com/mklabs/tiny-lr)) will mainly in our case:
+* serve the `livereload.js`
+* act as a websocket server: each browser that opens a websocket to this server will be refreshed
+
+By default thsi server listens on port 35729, but this can be changed through the `port` options.
+
+#### The livereload task
+This task needs to be called to trigger a reload. It must be passed the list of files that have changed (i.e. `livereload:foo.txt:bar.txt`)
+
+#### The middleware
+A connect middleware (`livereloadSnippet`) is delivered as an helper (located in `grunt-contrib-livereload/lib/utils`). This middleware must be the first one inserted.
+
+It will insert on the fly, in your HTML, the needed snippet of javascript that will setup the connection to the `tiny-lr` server.
+
+```html
+<!-- livereload snippet -->
+          <script>document.write('<script src=\"http://'
+           + (location.host || 'localhost').split(':')[0]
+           + ':" + port + "/livereload.js?snipver=1\"><\\/script>')
+          </script>
+```
 
 ### Options
 
-#### optsion
+#### port
 
-Type: `Boolean`
-Default: `false`
+Type: `integer`
+Default: `35729`
 
-Description.
+The port the tiny-lr server should listen on.
 
 #### Example config
 
 ```javascript
-grunt.initConfig({
-  livereload: {                                  // Task
-    dist: {                                      // Target
-      options: {                                 // Target options
-
-      },
-      files: {                                   // Dictionary of files
-        'dist/': 'src/'      // 'destination': 'source'
-        'dist/': 'src/'
+'use strict';
+var path = require('path');
+var lrSnippet = require('grunt-contrib-livereload/lib/utils').livereloadSnippet;
+
+var folderMount = function folderMount(connect, point) {
+  return connect.static(path.resolve(point));
+};
+
+module.exports = function (grunt) {
+  // Project configuration.
+  grunt.initConfig({
+    connect: {
+      livereload: {
+        options: {
+          port: 9001,
+          middleware: function(connect, options) {
+            return [lrSnippet, folderMount(connect, '.')]
+          }
+        }
       }
     },
-    dev: {                                       // Another target
-      files: {
-        'dist/': 'src/'
-        'dist/': 'src/'
+    // Configuration to be run (and then tested).
+    regarde: {
+      fred: {
+        files: '*.txt',
+        tasks: ['livereload']
       }
     }
-  }
-});
 
-grunt.registerTask('default', ['livereload']);
+  });
+
+  grunt.loadNpmTasks('grunt-regarde');
+  grunt.loadNpmTasks('grunt-contrib-connect');
+  grunt.loadNpmTasks('grunt-contrib-livereload');
+
+  grunt.registerTask('default', ['livereload-start', 'connect', 'regarde']);
+};
 ```
 
 
+
 ## Release History
 
- * 2012-10-31   v0.1.0   Initial release.
+ * 2012-11-01   v0.1.0   Initial release.
 
 ---
 
 Task submitted by []()
 
-*This file was generated on Wed Jan 09 2013 20:23:58.*
+*This file was generated on Tue Jan 29 2013 01:18:12.*
diff --git a/docs/livereload-examples.md b/docs/livereload-examples.md
@@ -1,25 +1,42 @@
 ## Example config
 
 ```javascript
-grunt.initConfig({
-  livereload: {                                  // Task
-    dist: {                                      // Target
-      options: {                                 // Target options
+'use strict';
+var path = require('path');
+var lrSnippet = require('grunt-contrib-livereload/lib/utils').livereloadSnippet;
 
-      },
-      files: {                                   // Dictionary of files
-        'dist/': 'src/'      // 'destination': 'source'
-        'dist/': 'src/'
+var folderMount = function folderMount(connect, point) {
+  return connect.static(path.resolve(point));
+};
+
+module.exports = function (grunt) {
+  // Project configuration.
+  grunt.initConfig({
+    connect: {
+      livereload: {
+        options: {
+          port: 9001,
+          middleware: function(connect, options) {
+            return [lrSnippet, folderMount(connect, '.')]
+          }
+        }
       }
     },
-    dev: {                                       // Another target
-      files: {
-        'dist/': 'src/'
-        'dist/': 'src/'
+    // Configuration to be run (and then tested).
+    regarde: {
+      fred: {
+        files: '*.txt',
+        tasks: ['livereload']
       }
     }
-  }
-});
 
-grunt.registerTask('default', ['livereload']);
+  });
+
+  grunt.loadNpmTasks('grunt-regarde');
+  grunt.loadNpmTasks('grunt-contrib-connect');
+  grunt.loadNpmTasks('grunt-contrib-livereload');
+
+  grunt.registerTask('default', ['livereload-start', 'connect', 'regarde']);
+};
 ```
+
diff --git a/docs/livereload-options.md b/docs/livereload-options.md
@@ -1,8 +1,8 @@
 # Options
 
-## optsion
+## port
 
-Type: `Boolean`  
-Default: `false`
+Type: `integer`
+Default: `35729`
 
-Description.
+The port the tiny-lr server should listen on.
diff --git a/docs/livereload-overview.md b/docs/livereload-overview.md
@@ -1,2 +1,49 @@
+# grunt-contrib-livereload [![Build Status](https://secure.travis-ci.org/gruntjs/grunt-contrib-livereload.png?branch=master)](http://travis-ci.org/gruntjs/grunt-contrib-livereload)
 
-_This plugin is a placeholder for the upcoming live reload task._
+> Reload assets live in the browser
+
+## Getting Started
+If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide, as it explains how to create a [gruntfile][Getting Started] as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:
+
+```shell
+npm install grunt-contrib-livereload --save-dev
+```
+
+[grunt]: http://gruntjs.com/
+[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
+
+## Introduction
+
+`grunt-contrib-livereload` is composed of 2 tasks:
+* one to setup a local server that will serve the needed js file and the wesocket that will control your browser (`livereload-start`)
+* one to trigger the reload of the browser(s) (`livereload`)
+
+Additionally a connect middleware is available to insert on the fly in your HTML page the snippet of javascript that will start he connect to the livereload server.
+
+This task support multi-browser: all the browsers listening on the tiny-lr port will be reloaded at the same time.
+
+Note that `grunt-contrib-livereload` is designed to use [grunt-regarde](https://github.com/yeoman/grunt-regarde) instead `grunt-contrib-watch` (mainly due to shortcomings in the `watch` task which doesn't give access to changed files because it spawns tasks in subprocesses.)
+
+## The livereload-start task
+
+This task starts a server in the background. This server (implemented thanks to [mklabs/tiny-lr](https://github.com/mklabs/tiny-lr)) will mainly in our case:
+* serve the `livereload.js`
+* act as a websocket server: each browser that opens a websocket to this server will be refreshed
+
+By default thsi server listens on port 35729, but this can be changed through the `port` options.
+
+## The livereload task
+This task needs to be called to trigger a reload. It must be passed the list of files that have changed (i.e. `livereload:foo.txt:bar.txt`)
+
+## The middleware
+A connect middleware (`livereloadSnippet`) is delivered as an helper (located in `grunt-contrib-livereload/lib/utils`). This middleware must be the first one inserted.
+
+It will insert on the fly, in your HTML, the needed snippet of javascript that will setup the connection to the `tiny-lr` server.
+
+```html
+<!-- livereload snippet -->
+          <script>document.write('<script src=\"http://'
+           + (location.host || 'localhost').split(':')[0]
+           + ':" + port + "/livereload.js?snipver=1\"><\\/script>')
+          </script>
+```