https://github.com/dfkaye/stringtemplate
[ experimental: do not use this brain ] minimalist logic-less templates in JavaScript
https://github.com/dfkaye/stringtemplate
Last synced: 3 months ago
JSON representation
[ experimental: do not use this brain ] minimalist logic-less templates in JavaScript
- Host: GitHub
- URL: https://github.com/dfkaye/stringtemplate
- Owner: dfkaye
- Created: 2014-08-21T18:43:27.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2014-10-27T18:09:21.000Z (over 10 years ago)
- Last Synced: 2025-02-02T14:48:27.413Z (4 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.61 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
stringtemplate
==============
[]
(https://travis-ci.org/dfkaye/stringtemplate)
[ v0.0.11 ~ NOT STABLE ~ TOKENS & DOCS UNDER REVIEW ~ 21 OCT 2014 ]
## Minimalist Logic-less Templates in JavaScript
`stringtemplate` is a strict separation or "logic-less" template module, that
performs the "merge" operation between a document string with "holes" and data
for filling this out.
`stringtemplate` takes an "eval-less" approach, due to the arrival of
[Content Security Policy]
(http://matthewrobertson.org/blog/2012/07/10/javascript-templates-and-chromes-content-security-policy/),
a very serious restriction coming to our "modern" browsers that financial,
medical, retailing and other security-sensitive entities will embrace
increasingly over time.
`stringtemplate` supports no formatting or escaping characters, case logic,
quiet references, fallbacks for unexpected values, helpers, includes or
inheritance. The focus is on "simple" transformations
For more on strict separation, see
+ [background](./doc/parr.md)
+ [objections](./doc/cons.md)
You may view a slightly dated presentation about this project on rawgit at
https://rawgit.com/dfkaye/stringtemplate/master/shower/index.html.
## API
`stringtemplate` adds a `template()` method to `String.prototype` and
`Function.prototype` that act as a batch string#replace, using `$token$`
placeholders for values/objects and `$#objectOrArray$` and `$/objectOrArray$`
tokens to demarcate iterable data with `$.$` for array indexes or `$.key$`
for key-value data.
+ `String.prototype.template(data)` accepts a (required) data object or array.
The string body on which this method is invoked should contain at least one
token. If no tokens are found, or the data param specified is not an object or
an array, the original string is returned without modification. Here's the token
set that this method looks for:
- $placeholder$ ~ use value found at data.placeholder
- $path.name$ ~ use value found at data.path.name
- $#path.name$ ~ marks the start of an iteration ~ must have a matching end
token, $/path.name$
- $/path.name$ ~ marks the end of an iteration ~ must have a matching start
$#path.name$ token
- $.$ ~ inside an iteration, use object value at each index [0, 1, 2...]
- $.key$ ~ inside an iteration, use value found at [index].name
- $#.$ ~ start of a collection inside an iteration
- $/.$ ~ end of a collection inside an iteration
- $#.key$ ~ key-value collection inside an iteration
- $/.key$ ~ end key-value collection inside an iteration
+ `Function.prototype.template(data)` - originally inspired by @rjrodger's
[mstring](https://github.com/rjrodger/mstring), this method deals with the lack
of multi-line docstring (aka heredoc or quasi-literal) support in JavaScript.
- returns `docstring` found by parsing contents between /*** and ***/
delimiters in function body and concatenates rows of text with newline
character to preserve the docstring's vertical structure
- returns an empty string if no delimiters found
- accepts an optional data argument:
+ if `data` is an object or an array, this method returns the result of
`docstring.template(data)`;
+ otherwise, returns the docstring unmodified.
- removes line comments found within delimiters `// so you can annotate lines`
NB: to get past minifiers that remove block comments from source files, you can
use this [workaround for UglifyJS2]
(http://dfkaye.github.io/2014/03/24/preserve-multiline-strings-with-uglify/)
to preserve the three-asterisk delimiters.
# Examples
[ STILL IN PROGRESS ~ 18 OCT 2014 ]
## values
var s = [
'
title: $title$
',
'long name: $person.fullname$
'
].join('');
var d = {
title: 'value test',
person: {
fullname: 'my longer name'
}
};
var t = s.template(d);
var expected = '
title: value test
long name: my longer name
';
console.log(t === expected); // => true
## simple array
var s2 = [
'
- ',
- $.$ ',
'$#.$',
'
'$/.$',
'
].join('');
var d2 = ['foo', 'bar', 'baz', 'quux'];
var t2 = s2.template(d2);
var expected = '
- foo
- bar
- baz
- quux
console.log(t2 === expected); // => true
## complex data - objects in an array
var list = [
'
- ',
- $.street$ ',
- $.city$, $.state$ ',
'$#addresses$',
'
'
'$/addresses$',
'
].join('\n');
var t = list.template({
addresses: [
{ street: '123 fourth street', city: 'cityburgh', state: 'aa' },
{ street: '567 eighth street', city: 'burgville', state: 'bb' },
{ street: '910 twelfth street', city: 'villetown', state: 'cc' }
]
});
var expected = [
'
- ',
- 123 fourth street ',
- cityburgh, aa ',
- 567 eighth street ',
- burgville, bb ',
- 910 twelfth street ',
- villetown, cc ',
'',
'
'
'',
'
'
'',
'
'
'',
'
].join('\n');
console.log(t === expected); // => true
## combining template results
[ TODO ]
## more interesting examples
[ TODO function#template ]
[ TODO css generator ]
[ TODO html generator ]
# License
[JSON License (Modified MIT)](./JSON.license)
# Tests
Tests are currently run with `mocha` using the `assert` module, the `qunit` ui
and the `spec` reporter.
## node
`npm test`
## testem
`npm run testem`
Browser tests run fine with `testem`, but mocha (on node) and testem do not play
as well together on a Windows laptop (like mine). YMMV.
## rawgit
run browser-suite on rawgit (opens new tab|window)