NodeInterval v0.0.7
: _ _ _ : _ | | _() | |_ _ __ __ | | : | ' \ / \ / ` |/ \ | ' | __/ \ '\ \ / / ` | | : | | | | () | (_| | / | | | | || / | \ V / (| | | : || |_|_/ _,|_||| |_|___|_| _/ _,|_| : : Automation for lazy people.
- What it does
NodeInterval promotes code organization by allowing you to move your JavaScript templates out of your html page and into organized files and folders. When ran, it collects all the files in your templates folders, orders them alphabetically by script id, and inserts them into a text document(s) of your choice.
NodeInterval contains a watch option that enables you to leave it running in a seperate tab to automatically run the above process anytime a template has been modified.
NodeInterval is commonly used in [http://documentcloud.github.com/backbone/], [http://maccman.github.com/spine/], and similiar web application frameworks that rely heavily on embedded templates.
Think of it as a simple version of [http://sass-lang.com/] for your JavaScript templates.
- Features
- Works with all templating solutions including [http://documentcloud.github.com/underscore/] and [http://api.jquery.com/category/plugins/templates/]. (The only requirement is that the template needs to have an id property since they are oganized alphabetically.)
- Hidden files inside of template folder (files that begin with "." like .git, .svn, and .DS_Store) are automatically ignored.
- Profiles the time it takes to render all templates.
- Supports multiple sets of input and output files (see example in =sample/nodeinterval.js=).
- Can be used with build tools like [http://www.gnu.org/software/make/] and [http://ant.apache.org/].
- Has clean, date-stamped, and color-coded command-line output: : $ node nodeinterval.js : 18 Aug 01:47:49 - INFO: NodeInterval is watching for changes. Press Ctrl-C to stop. : 18 Aug 01:47:49 - INFO: overwrite ../assets/index.html : 18 Aug 01:47:49 - INFO: Completed in 0.001 seconds. : 18 Aug 01:48:04 - INFO: >>> Change detected to: ~/git/projectName/src/templates/signon/signon.tmpl : 18 Aug 01:48:04 - INFO: overwrite ../assets/index.html : 18 Aug 01:48:04 - INFO: Completed in 0.002 seconds.
- Requirements
- You must have [http://nodejs.org/] installed.
- [http://npmjs.org/] (Node package Manager) if you want to install this package using it.
- Installing and using
Note: Your application should have a clean folders architecture differentiating compiled vs source files. See the section below on "Sample web application layout" for a decent one. It's a lot simpler than it sounds.
There are two ways to install: Cloning this repo or using [http://npmjs.org/]. Once you have the package installed feel free to modify and use the sample script in the =samples= directory.
: cd bin # Your scripts directory. : npm install NodeInterval : cp node_modules/nodeinterval/samples/nodeinterval.sh . : emacs nodeinterval.sh # Setup your variable paths with your favorite editor. : chmod u+x nodeinterval.sh : ./nodeinterval.sh # Start watching your files
Alternatively, you can use the sample .js file instead of the .sh version and run it like so:
: node nodeinterval.js
- Usage
It's best to create a Node or shell script that you can call via command line. A copy of this example is included in the =samples= directory.
: var Nodeinterval = require('nodeinterval'), : ni = new Nodeinterval.Watcher({ : inputFile: '../path/to/raw/index.html', : outputFile: '../path/to/rendered/index.html', : replacementString: '@templates@', : watchFolder: '../path/to/templates/' : }).startWatch();
Options you can pass to =new Nodeinterval.Watcher= are:
| Option | Description | default | |---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------| | =inputFile= | is the main template you want to duplicate. | '../src/index.html' | | =outputFile= | is the relative or absolute path to the file you want to create (that's a copy of =inputFile= with the =replacementString= replaced with all your templates. | '../assets/index.html' | | =replacementString= | is the string inside of =inputFile= that you want to replace with all your templates. | '@templates@' | | =watchFolder= | is the relative or absolute path to the folder you want to monitor. | '../src/templates/' |
Once a new =Nodeinterval.Watcher= is created. It has the additional api methods. Some methods are chainable.
| Method | Description | |-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | startWatch | Turns on the monitoring service. All files in =watchFolder= are now being watched for changes. Chainable. | | stopWatch | All files in =watchFolder= are now not being watched. Chainable. | | updateIndex | This is called internally anytime a change is detected. Replaces =outputFile= with a version of =inputFile= with =replacementString= replaced with contents of =watchFolder=. | | | |
NodeInterval can also watch multiple input and output files. Just use an array to specify filenames under =inputFile= and =outputFile=. This is good, for example, where you have two sets of html files, one for uncompressed js and css and one for compressed css and js, and you want both files to render your templates on change.
- Sample web application layout
If you don't have a good web application layout. Here's a good one to follow:
: . : ├── assets <== Your compressed assets, ready for production. : │ ├── images : │ ├── index.html <== "Built" html file with your rendered templates. : │ ├── js : │ └── css : ├── bin <== Shell scripts. "npm install nodeinterval" here. : │ ├── node_modules <== This folder will automatically be created. : │ │ └── nodeinterval <== nodeinterval and it's dependencies will be : │ │ installed here. : │ ├── nodeinterval.sh <== This sample file (and the .js) version is inside : │ │ of nodeinterval/samples/. Use it if you like. : │ └── sasswatch.sh <== I like to create a Sass executable for watching : │ my CSS files as well. (not part of this project) : └── src <== Raw uncompressed code here, where you should be : │ editing your codez. : ├── index.html <== Raw index.html files with "replacementString" : │ where you want the templates. : ├── css <== Uncompressed CSS assets. : ├── js <== Uncompressed JS assets. : └── templates <== Your .js templates. These can be all in one : folder or seperated out into many folder deep, : according to section. Incude the part : in your templates.
- Running the unit tests
- NodeInterval's unit tests are written using [http://vowsjs.org/].
- If you want to run the unit tests, you must clone this repo and not use the NPM version.
: cd tests; node run-tests.js
- Change log
- 2011-10-05 - 0.0.7
- NodeInterval now works with build tools like [http://www.gnu.org/software/make/] and [http://ant.apache.org/]. To support this NodeInterval no longer starts the watch process until =NodeInterval.startWatch= is ran.
- Update sample scripts to contain a --watch option to opt in on monitoring files. If not specified runs only once and quits.
- Update unit-tests to support the above.
- Turn off monitoring in unit-tests when the test is done.
- 2011-09-18 - 0.0.6
- Templates are now outputted in alphabetical order by script id. This adds consistency to commit diffs among other things.
- 2011-09-18 - 0.0.5
- Now supports watching multiple set of input and output files (use an array under =inputFile= and =outputFile=.
- 2011-08-22 - 0.0.4
- Added improved way of instantiating (new NodeInterval.Watcher), see docs.
- Added init defaults if you don't pass them.
- New APIs: .startWatch, .stopWatch
- Added [http://vowsjs.org/] unit tests. (=cd tests; node run-tests.js= to run)
- 2011-08-18 - 0.0.1 - First version
- Known issues:
- NodeInterval currently doesn't watch for new files or know when an existing file is removed. You should probably stop (ctrl-c) and start NodeInterval again when adding or removing a new template. This feature will be added in a future version.
- Thanks
Internally NodeInterval uses the following (included) node packages: [https://github.com/DelvarWorld/Simple-Node-Logger], [https://github.com/jorritd/node-watch], and [https://github.com/documentcloud/underscore].
- Contribute
Feedback and contributions (via pull requests) are more than welcome. Please add a test to the unit tests if it's a new feature. NodeInterval is really young and mostly written in one night. I'll be updating it with features as I use it in my daily projects.