Utility for working with Closure Templates, aka Soy, from within a node.js application. Supports dynamic recompilation and loading for fast iteration during development.
Either:
- Fork, clone or download the source from GitHub, or
- Install via NPM using
npm install soynode
var soynode = require('../lib/soynode')
soynode.setOptions({
outputDir: '/tmp/soynode-example'
, allowDynamicRecompile: true
})
soynode.compileTemplates(__dirname, function (err) {
if (err) throw err
// Templates are now ready to use.
console.log(soynode.render('example.message.hello', {
name: process.env.USER
, date: new Date().toLocaleTimeString()
}))
})Also, see examples/example.js.
soynode.get(templatename) - Returns a JS function corresponding to the template name.
soynode.render(templatename, data) - Returns a string that results from executing a template.
soynode.setOptions(opts) - Change the options, see section below.
soynode.compileTemplates(dir, callback) - Compiles and loads all .soy files in the directory.
soynode.compileTemplateFiles(files, callback) - Compiles and loads all .soy files.
soynode.loadCompiledTemplates(dir, callback) - Loads already compiled templates.
soynode.loadCompiledTemplateFiles(files, callback) - Loads already compiled templates.
Where "template name" is referred to, it means the namespace + template name as defined in the Soy
file, and the full JS name that the Soy Compiler generates, for example project.section.screen.
See the Hello World JS doc on
the Closure site for more background.
Options can be set via soynode.setOptions(options). Most of these mirror
the command-line arguments
for SoyToJsSrcCompiler. The keys can contain the following:
tmpDir{string} Path to a directory where temporary files will be written during compilation. {Deprecated: use outputDir} [Default: /tmp/soynode]inputDir{string} Optional path to a directory where files will be read. When compiled from a directory, this option will be overwritten with the caller inputDir. [Default: process.cwd()]outputDir{string} Path to a directory where files will be written. [Default: null]uniqueDir{boolean} Determines whether the compiled files will be placed in a unique directory. [Default: true]allowDynamicRecompile{boolean} Whether to watch for changes to the templates. [Default: false]loadCompiledTemplates{boolean} Whether or not to load the compiled templates. Relevant when you only need to build templates. [Default: true]eraseTemporaryFiles{boolean} Whether to erase temporary files after a compilation. This option does nothing if allowDynamicRecompile is on, because allowDynamicRecompile reuses the files. [Default: false]concatOutput{boolean} Whether the compiled soy.js files should be joined into a single file. This is helpful for loading templates in a browser and simplest to use whenoutputDiris explicitly set anduniqueDiris false. [Default: false]concatFileName{string} File name used for concatenated files, only relevant when concatOutput is true, ".soy.concat.js" is appended, so don't include ".js" yourself. [Default: compiled]locales{Array.} List of locales to translate the templates to.messageFilePathFormat{string} Path to the translation file to use, which can contain any of the placeholders allowed on the --messageFilePathFormat option of SoyToJsSrcCompiler.jar.cssHandlingScheme{string} Processing options for thecsscommand. More infouseClosureStyle{boolean} Whether or not to use goog.provide and goog.require for JS functions and Soy namespaces.shouldGenerateJsdoc{boolean} Whether or not to generate JSDoc on each template function, with type info for the Closure Compiler. More infoshouldProvideRequireSoyNamespaces{boolean} Use this option to enable usage with Closure Library. More infoshouldProvideRequireJsFunctions{boolean} Use this option to enable usage with Closure Library. More infoprecompiledDir{string} A directory of precompiled soy.js files. Soynode will check these first and use them if available. You can set this to the same value as outputDir to re-use results from previous runs.
NOTE: Options should be set before templates are loaded or compiled.
To take advantage of soy's translation features through soynode, you should set the locales and messageFilePathFormat options, like in the example below:
var soynode = require('../lib/soynode')
soynode.setOptions({
locales: ['pt-BR', 'es'],
messageFilePathFormat: '/tmp/soynode-example/translations.xlf',
outputDir: '/tmp/soynode-example'
})
soynode.compileTemplates(__dirname, function (err) {
if (err) throw err
// Templates are now ready to use, render specifying the desired locale.
console.log(soynode.render('example.message.hello', {}, {}, 'pt-BR'))
console.log(soynode.render('example.message.hello', {}, {}, 'es'))
})The templates are loaded using Node's VM Module. This allows us to
execute the generated .soy.js files as is without a post processing step and without leaking the
template functions into the global scope.
Calling soynode.get executes code which returns a reference to the template function within the
VM Context. The reference is cached, providing a 10x speed up over fetching the template function
each time, or evaluating it in place and returning the template output over the VM boundary.
Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.
Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests.
Dan Pupius (personal website), supported by The Obvious Corporation.
Copyright 2012 The Obvious Corporation.
Licensed under the Apache License, Version 2.0.
See the top-level file LICENSE.txt and
(http://www.apache.org/licenses/LICENSE-2.0).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent