summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2018-09-09 10:47:47 -0400
committerPaul Duncan <pabs@pablotron.org>2018-09-09 10:47:47 -0400
commitb4e1f4906a27619b3edffd791361694f00f38662 (patch)
tree243b603c73475dbb60286a0348b8e4e4d4b790b3
parent8a43f1af7f3c6bba5f01d2665862c63b610b5e67 (diff)
downloadluigi-template-b4e1f4906a27619b3edffd791361694f00f38662.tar.bz2
luigi-template-b4e1f4906a27619b3edffd791361694f00f38662.zip
js: add README.mkd
-rw-r--r--js/README.mkd213
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 &lt;Paul&gt;"
+
+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-&lt;Paul&gt;-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-&lt;Paul&gt;-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-&lt;Paul&gt;-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 &lt;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/