gulp-vash-static/README.md

Gulp plugin for converting Vash razor templates to static html

# gulp-vash-static
Gulp plugin for converting Vash razor templates to static html

*Keep in mind that this is just a thin wrapper around Vash Static and your issue is most likely with that.*

## Install

```
$ npm install --save-dev gulp-vash-static
```


## Usage
There are a few different functions you can call:
- 'precompile': Precompiles a vash templates and generates a json file with the template's name and contents in it.
- 'renderPage': Renders a 'page' vash template by name, which should be stored in the cacheDest, with optional helpers.
- 'watchModelsAndTemplates': Convenience function for watching models and templates.

This is my recommended setup, where all you need to call is 'gulp watch' to get started.

```js
var gulp = require('gulp');
var vashStatic = require('gulp-vash-static');

// The default is "pg" anyway, but this is just to show you that you can change it to another directory name if you wish
vashStatic.setPageDirType("pg");

var dirTypes = ["pg", "wg", "glb"]; // vashStatic module types
var APP = "dev/app/";
var PRECOMP_VASH = "precompiled-vash.json" // aka vash cache

gulp.task("precompile-vash", function() {
  return gulp.src([
        APP + "pg/**/*.vash"
      , APP + "wg/**/*.vash"
      , APP + "glb/**/*.vash"
      , "!" + APP + "glb/vash-helpers/*.vash" // leave out any vash helpers you have
    ])
    .pipe(vashStatic.precompile({
      debugMode: true, 
      dirTypes: dirTypes, 
      modelsPath: "bld/js/models.js",
      cacheFileName: PRECOMP_VASH
    }))
    .pipe(gulp.dest("bld/"))
})


gulp.task("pg-render-static", function() {
  
  return gulp.src(APP + "pg/**/*.vash")
    .pipe(vashStatic.renderPage({
      cacheDest: "bld/" + PRECOMP_VASH
      , helpers: [ APP "glb/vash-helpers/RenderWidget.vash" ] // optionally, you can add or override (same name) with custom helpers
      , omitSubDir: "tmpl" //omit a subdirectory that you might have that you don't want to be part of the template name
    }))
    .pipe(gulp.dest("bld/"))
})


// Combines models so they can be injected into templates when rendering. 
// This is suggested if you need a separate model per page. 
// Recommend using TypeScript because of it's similar syntax to C# models, which makes integration of Razor front end and back end easier. 
gulp.task("combine-models", function () {

  var src = [ 
        APP + "pg/**/mdl/*.ts"
      , APP + "wg/**/mdl/*.ts"
    ];

  return gulp.src(src)
    .pipe(ts({
        noImplicitAny: true,
        out: 'models.js'
    }))
    .pipe(gulp.dest("bld/js/"));
});


/*
Watches for any changes in vash templates or models, updates the precompiled template cache (on the file system), then renders the page marked by a flag (eg --home) by calling the 'pg-render-static' task.
Note that 'vashStatic.watchModelsAndTemplates' is not a gulp plugin, just a convenience function that abstracts away some complex logic.
Returns a stream from gulp plugin 'gulp-watch'.
*/
gulp.task("watch", function() {

  var vashSrc = [ // vash templates
      APP+"pg/**/*.vash"
    , APP+"wg/**/*.vash"
  ]
  , modelSrc = [ // template models
      APP + "pg/**/mdl/*.ts"
    , APP + "wg/**/mdl/*.ts"
  ]
  
  return vashStatic.watchModelsAndTemplates({
      gulp: gulp // pass in the instance of gulp you are using
    , vashSrc: vashSrc
    , modelSrc: modelSrc
    , modelsDest: "bld/js/models.js" // your combined models to inject when rendering templates
    , cacheDest: "bld/" + PRECOMP_VASH // cached templates JSON file, generated by 'precompile-vash' task 
    , debugMode: true // should be false for production to keep file size down
    , dirTypes: dirTypes // module types, eg ['pg', 'wg', 'glb']
    , pageTemplatePath: APP + "<%= type %>/<%= moduleName %>/tmpl/<%= fileName %>" // pattern to the vash template, using moduleName from the '--home' flag

    // existing gulp tasks to call when files are changed
    , combineModelsTask: 'combine-models'
    , precompileTask: 'precompile-vash'
    , pageRenderTask: 'pg-render-static'
  })
})
```

## API

### setPageDirType
Vash Static uses modules to organise your templates. By default it assumes you have at least a page module, which is abbreviated to 'pg' and is expected in the directory structure. With 'setPageDirType' you can change this, if you need to.


### getAllArgs
Gets the argument from the command-line that starts with '--', omitting the '--' and finishing at the next space.
The watch on models cannot detect the exact page that needs to be rendered, so assumes 'Index.vash'. You can specify a different page though by adding a '/MyPageName' (omit the file extension). 

#### parameters
- {string[]} - Optionally pass in custom args, say from a child process when testing. 
- returns {string} Argument value without the '--' prefix.

### overrideGetAllArgs
Allows you to optionally override the functionality of 'getAllArgs', so you can manipulate arguments. First param should be the function and it should return a manipulated string containing the page name.

### restoreGetAllArgs
Restores 'getAllArgs' after using 'overrideGetAllArgs'.

### suppressWarnings
This can be useful if you don't want to output lots of warnings in things like unit tests (which can be annoying).

#### parameters
- {boolean} - True to suppress console warnings. False to switch them back on again.



### precompileTemplateCache
Precompiles a vash templates and generates a json file with the template's name and contents in it.

#### options
- {boolean} debugMode (optional) - Production usage should pass false to keep file size down. Development should use true, for useful debugging info. Defaults to false. 
- {string[]} dirTypes (optional) - List of types. This type will be searched for in the filePath and is expected to be a full directory name. If not given, only page type will be used.
- {string} modelsPath (optional) - File path to the combined models js file, which can prepend your templates to provide model data. If not given, no models will be added.
- {string} cacheFileName (optional) - Name of the json file output. Defaults to 'precompiled-vash.json'.


### renderPage
Precompiles a vash templates and generates a json file with the template's name and contents in it.

#### options
- {string} cacheDest - Path to the JSON file containing the vash template cache.
- {string} omitSubDir (optional) - If given, will remove the first occurance of a sub-directory with this name when generating the template name.
- {string[]} helpers (optional) - Array of paths to use as Vash helpers. Defaults will be used, unless overridden by name. Otherwise both lists will be used.


### watchModelsAndTemplates
Convenience function for watching models and templates

#### options
- {object} gulp - instance of gulp
- {string} vashSrc - vash templates to watch (accepts globbing)
- {string} modelSrc - models to watch (accepts globbing)
- {string} modelsDest - path to the models JS destination (once they are combined)
- {string} cacheDest - path to the template cache destination
- {boolean} debugMode - If this is for production, should be false
- {string[]} dirTypes - Module types (eg "pg", "wg", glb), which correspond to parent directory name of template modules.
- {string} pageTemplatePath - String for determining the path of the page-level template, where only the page name is known (eg "<%= type %>/<%= moduleName %>/tmpl/<%= fileName %>").
- {string} combineModelsTask - Gulp task name for combining your models
- {string} precompileTask - Gulp task name for pre-compiling your vash templates
- {string} pageRenderTask - Gulp task name for rendering a page


## Release notes:
- Version 2.0.0 introduced some breaking API changes:
    1. `getFirstArg` was replaced by `getAllArgs`
    2. `overrideGetFirstArg` was replaced by `overrideGetAllArgs`
    3. `restoreGetFirstArg` was replaced by `restoreGetAllArgs`
    

## License
MIT © [Jim Doyle](http://jimdoyle.com.au)