diff options
| -rw-r--r-- | js/README.mkd | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/js/README.mkd b/js/README.mkd new file mode 100644 index 0000000..9f3e5e6 --- /dev/null +++ b/js/README.mkd @@ -0,0 +1,213 @@ +Luigi Template +============== + +Overview +-------- +Tiny JavaScript string templating library. + +Features +-------- + +* Filters, with common filters built-in. +* Template caching. +* Small: Less than 4k minified (see `luigi-template.min.js`), +* Stand-alone: No external dependencies (no jQuery, etc), +* Compatible: Works in browsers as old as IE9 +* MIT-licensed + +Usage +----- +A minimal template: + + // create template + var t = new LuigiTemplate('hello %{name}'); + + // run template, print result to console + console.log(t.run({ + name: 'Paul', + })); + + // prints "hello Paul" + +If you have a template that you only need to run one time, you can use +the `LuigiTemplate.run()` singleton to run it, like this: + + // create and run template in one shot + var r = LuigiTemplate.run('hello %{name}', { + name: 'Paul', + }); + + // print result to console + console.log(r); + + // prints "hello Paul" + +Templates parameters can be modified by filters. Filters are applied to +a parameter value by appending a `|` (pipe) character, followed by the +filter name. + +Here is the template from above, with the name value HTML-escaped using +a built-in filter: + + // create template that prints hello and the HTML-escaped name + var t = new LuigiTemplate('hello %{name | h}'); + + // run template, print result to console + console.log(t.run({ + name: '<Paul>', + })); + + // prints "hello <Paul>" + +The built-in templates are: + +* `uc`: Upper-case string. +* `lc`: Lower-case string. +* `s`: Returns `""` if the value is 1, and `"s"` otherwise. Used to + pluralize values. Example: + + console.log(LuigiTemplate.run('a: a%{a|s}, b: b%{b|s}, c: c%{c|s}'', { + a: 0, + b: 1, + c: 2, + })); + + // prints "a: as, b: b, c: cs" + +* `length`: Get the length of an array. +* `trim`: Trim leading and trailing whitespace from a string. +* `h`: HTML-escape a string value. +* `u`: URL-escape a string value. +* `json`: JSON-encode a value. + +You can create your own custom filters, too. + +The easiest way to create your own custom filter is to add it to the set +of global filters (`LuigiTemplate.FILTERS`), like so: + + // add global template filter + LuigiTemplate.FILTERS.barify = function(s) { + return 'bar-' + s + '-bar'; + }; + + // create template that uses custom global filter + var t = new LuigiTemplate('hello %{name | barify | h}'); + + // run template, print result to console + console.log(t.run({ + name: '<Paul>', + })); + + // prints "hello bar-<Paul>-bar" + +You can also create a custom filters and limit it to a particular +template by passing a hash as the second parameter to the +`LuigiTemplate` constructor, like this: + + // create template with custom template-specific filter + var t = new LuigiTemplate('hello %{name | barify | h}', { + barify: function(s) { + return 'bar-' + s + '-bar'; + }, + }); + + // run template, print result to console + console.log(t.run({ + name: '<Paul>', + })); + + // prints "hello bar-<Paul>-bar" + +You can pass arguments to your custom filters as well. Here's an +example: + + // create template with custom template-specific filter named + // "wrap", which wraps the value in the given filter parameters + var t = new LuigiTemplate('hello %{name | wrap head tail | h}', { + wrap: function(s, args) { + if (args.length == 2) { + return [args[0], s, args[1]].join('-'; + } else if (args.length == 1) { + return [args[0], s, args[0]].join('-'); + } else { + return s; + } + }, + }); + + // run template, print result to console + console.log(t.run({ + name: '<Paul>', + })); + + // prints "hello head-<Paul>-tail" + +If you have a lot of separate templates, or a few large templates, +then it's a good idea to use a template cache. + +A template cache will create templates as they are needed (also known as +"lazy initialization"), so the page or application loads quickly. A +template cache also caches instantiated (that is, created) templates for +future use, so using templates from the cache is fast, too. + +Finally, template caches serve as a good repository for all of the +templates in a script. + +Here's how you create a template cache: + + // create template cache with a single template + var cache = LuigiTemplate.cache({ + hello: 'hello %{name | uc | h}' + }); + + // run template, print result to console + console.log(cache.run('hello', { + name: '<Paul>', + })); + + // prints "hello <PAUL%gt;" + +Documentation +------------- +*TODO* + +Tests +----- +This `test/` directory contains the JavaScript test suite for the +JavaScript implementation of [Luigi Template][], written in [Mocha][] +and [Chai]. + +To run the test suite, load `test/test.html` in a browser. + +Author +------ +Paul Duncan ([pabs@pablotron.org][me])<br/> +https://pablotron.org/ + +License +------- +Copyright 2014-2018 Paul Duncan ([pabs@pablotron.org][me]) + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +[Luigi Template]: https://github.com/pablotron/luigi-template +[me]: mailto:pabs@pablotron.org +[Mocha]: https://mochajs.org/ +[Chai]: http://www.chaijs.com/ |