Skip to content
Browse files

document and semantic renaming of things

  • Loading branch information...
1 parent 69f47d2 commit 1ddd0e7a92990efe325f6b39bf21034bd49a3078 @clux committed Nov 6, 2011
Showing with 54 additions and 6 deletions.
  1. +44 −0 Readme.md
  2. +6 −2 lib/domain/{version.coffee → vcs.coffee}
  3. +4 −4 lib/parser.coffee
View
44 Readme.md
@@ -0,0 +1,44 @@
+#Template VCS for modul8
+modul8-tmplver is a simple version control system for web application templates relying on [modul8](https://github.com/clux/modul8) for deployment.
+
+If a web application wants to store all the templates used by the application in localStorage, then they can become out of date with the server.
+This module allows these templates to always stay in sync with the server by bundling the current server versions of the templates and some helper methods to compare them.
+
+## Pre-Requisites
+All versions must be prepended with a new line with a version string line of form 'int.int.int'.
+This is a limitation if you need rendering of templates to happen on the server - the first line of each template has to be removed first.
+For web applications on the other hand, rendering happens entirely on the client side. We aim simply to facitilate this choice of behaviour.
+
+## Usage
+Install with
+
+ $ npm install m8-template-vcs
+
+then require, and pass it to modul8
+
+ var TemplateVcs = require('m8-template-vcs')
+ modul8('./client/app.js')
+ .use(new TemplateVcs('./directory/'))
+ .compile('./out.js')
+
+Optionally, an object can be specified as a second argument to the constructor to tweak the module's behavior. It's keys are:
+
+- `ext` - Extensions to filter the scanning by (defaults to '.html')
+- `domain` - Domain to export client versioning code to (defaults to 'template')
+- `key` - Key on the data domain to export the templates to (defaults to 'versions')
+
+
+## Behavior
+All files in a directory are scanned (recursively) for templates. If all matching files contain a valid template on the first line,
+the versions will be extracted and added to the data domain under a sensible key (base_dir+'/user/edit.html' => 'user/edit').
+
+The client can require tools for decoupling the version and the template from the file + methods for comparing different versions.
+This code is available on the template domain under `template::vcs`, wheras template versions are included on the data domain, where its container can be
+required under `data::versions`.
+
+With this data and code you will be able to simply check whether the template you've got in localStorage matches the one in your config.
+If it does, you can safely keep using the browser's cached version, if not, an ajax fetch is required.
+
+
+## License
+MIT Licensed - See LICENSE file for details
View
8 lib/domain/version.coffee → lib/domain/vcs.coffee
@@ -7,9 +7,13 @@ gt = (a, b) ->
gte = (a, b) ->
@gt(a,b) or @eq(a,b)
-read = (str) ->
+
+version = (str) ->
v = new String(str).match(/^(\d+)\.(\d+)\.(\d+)/) # very strict: wont even allow whitespace before version
return false if !v or v.length isnt 4
v[1..].map((n) -> parseInt(n,10))
-module.exports = {eq, gt, gte, read}
+template = (str) ->
+ str.replace(/^.*\n/,"")
+
+module.exports = {eq, gt, gte, version, template}
View
8 lib/parser.coffee
@@ -1,7 +1,7 @@
path = require 'path'
fs = require 'fs'
fsx = require 'fsx'
-version = require './domain/version'
+vcs = require './domain/vcs'
Parser = (@template_dir, @o={}) ->
@@ -14,13 +14,13 @@ Parser = (@template_dir, @o={}) ->
Parser::data = ->
vobj = {}
for file in fsx.readDirSync(@template_dir).files when path.extname(file) is @o.ext
- v = version.read(fs.readFileSync(file))
+ v = vcs.version(fs.readFileSync(file))
throw new Error("path: #{file} does not start with a valid version number") if !v
vobj[path.basename(file).split(@o.ext)[0]] = v
[@o.key, JSON.stringify(vobj)]
-Parser::domains = ->
- [@o.domain, __dirname+'/domain/'] # make tinysemver requireable as template::version on the client
+Parser::domain = ->
+ [@o.domain, __dirname+'/domain/'] # makes vcs requirable as template::vcs

0 comments on commit 1ddd0e7

Please sign in to comment.
Something went wrong with that request. Please try again.