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.

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