Shotenjin

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 13 Open GitHub ↗

Post-modern javascript templating system

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Name
====

Shotenjin - Post-modern JavaScript template engine

SYNOPSIS
========

Always classic:

var tenjin = new Shotenjin.Template({
            sources : 'Hello [% world %]'
        })
        
        var rendered = tenjin.render({
            world : 'world'
        })
        
        
Post-modern:

Template('Table.Cell', {
            template : '<td>[% text %]</td>'
        })
        
        
        Template('Table.Row', {
            use : 'Table.Cell',
        
            template : '<tr>[%\\ Joose.A.each(row, function (cell, index) { %][%= Table.Cell({ text : cell }) %][%\\})%]</tr>'
        })
        
        
        Template('Table', {
            use : 'Table.Row',
        
            template : '<table>[%\\ Joose.A.each(table, function (row, index) { %][%= Table.Row({ row : this.helper(row) }) %][%\\})%]</table>',
            
            methods : {
            
                helper : function () { ... }
            }
        })

var tableData = [
            [ '1',  '1', '2' ],
            [ '3',  '5', '8' ],
            [ '13','21','34' ]
        ]
        
        
        var rendered = new Table({ table : tableData })
        
        // or just
        
        var rendered = Table({ table : tableData })
        
Less-noisy with the helper script:

Template('Chapter', {
            
            template : {
                /*tj
                    <h2>[% title %]</h2>
                    <p> [% content %]</p>
                tj*/

/* GENERATED BY SHOTENJIN HELPER, DO NOT MODIFY DIRECTLY */
                sources : '<h2>[% title %]</h2>\n<p> [% content %]</p>'
            }
        })
        
        
        Template('Book', {
            
            template : {
                /*tj
                    [%\ this.wrapper(Chapter, { title : 'Chapter1' }, function () { %]                     
                        Text of first chapter.
                    [%\ }); %]

[%\ this.wrapper(Chapter, { title : 'Chapter2' }, function () { %]
                        Text of second chapter.
                    [%\ }) %]
                tj*/

/* GENERATED BY SHOTENJIN HELPER, DO NOT MODIFY DIRECTLY */
                sources : '[%\\ this.wrapper(Chapter, { title : \'Chapter1\' }, function () { %]                     \nText of first chapter.\n[%\\ }); %][%\\ this.wrap(Chapter, { title : \'Chapter2\' }, function () { %]\nText of second chapter.\n[%\\ }) %]'
            }
        })

var rendered = Book()

If you are reading this file as README from github, you may want to open [this link](http://samuraijack.github.com/Shotenjin) instead.

INSTALLATION
============

From `npm`:
    
    > [sudo] npm install shotenjin

Tarballs are available for downloading at: <http://search.npmjs.org/#/shotenjin>

SETUP
=====

In NodeJS:

require('task-joose-nodejs')
    require('shotenjin')
    
    
In browsers (assuming you've completed the 3.1 item from this [document](http://joose.github.com/Joose/doc/html/Joose/Manual/Installation.html)):

DESCRIPTION
===========

Shotenjin is a Yet Another JavaScript Templating Engine, based on Tenjin by [Makoto Kuwata](http://www.kuwata-lab.com/)
Shotenjin was ported to Joose, along with some improvements.

The main difference of Shotenjin from other templating solutions is that for the templating language it uses JavaScript itself. 
Thus, Shotenjin templates are not *compiled* into JavaScript, they are only *parsed*.

SYNTAX
=======

Shotenjin uses 3 types of template instructions. Keep in mind, that all them, in the same time, are just ordinary JavaScript expressions,
which are evaluated directly by the JavaScript engine of your choice, in the context of the template function (see below for its internal structure).

Escaped expressions
-------------------

Such expression are represented with the following construct:

[% name %]
        
        [% name + ' ' + surname %]
        
        [% Digest.MD5.md5_hex(response) %]

The value of the expression will be escaped before adding to template, according to this table:

'&'     : '&amp;'
        '<'     : '&lt;' 
        '>'     : '&gt;' 
        '"'     : '&quot;'

Unescaped expressions
---------------------

Such expression are represented with the following construct

[%= person.name %]
        
        [%= document.body.innerHTML %]

Memo - passed-through exactly (equally) as calculated

The value of the expression will *not* be escaped before adding to template. Thus, this expressions can be used to generate HTML markup.  
This instruction can be used to include the resulting content of another template for example, (see example with `Table` in Synopsys above)

Control statements
------------------

This type of instructions represent arbitrary JavaScript code, which will be added to template function unmodified. So, generally, 
it shouldn't return a value, but should modify the control flow:

[%\ for (var i = 0; i < persons.length; i++) { %]
                <tr><td>[% persons[i].name %]</td></tr>
        [%\ } %]        
                
        
        [%\ if (a == b) { %]
                <tr><td>[% person.name %]</td></tr>
        [%\ } else { %]        
                <tr><td>[% person.surname %]</td></tr>
        [%\ } %]

Multi-line code is ok:

[%\
            var sum = 0
            
            Joose.A.each(persons, function (person, index) {
                sum += person.parameter
            })
        %]
        Totally: [% sum %]
        
Memo - lambda function in Haskell.

As you can see any code can be embedded into templating function, and you don't need to learn one more language to create a template.

USAGE
=====

Classic
-------

Shotenjin can be used in "classic" way, in which you are responsible for instantiation and rendering:

var tenjin = new Shotenjin.Template({
            sources : 'Hello [% world %]'
        })
        
        var rendered = tenjin.render({
            world : 'Shotenjin'
        })

Post-modern
-----------

In the "post-modern" usage scenario, the template instance is embedded into Joose class:

Class('Table.Cell', {
            meta : 'Shotenjin',
            
            template : '<td>[% text %]</td>'
        })

Additional helper `Template` is introduced to simplify the declaration:

Template('Table.Cell', {
        
            template : '<td>[% text %]</td>'
        })
        
By default, the class with the embedded template is a subclass of `Shotenjin.Template`.

You can define additional methods (they will be available in templating function) or attributes, inherit from another template,
apply Roles or something else. Please refer to [Joose manual](http://bit.ly/joose_manual) to know what you can do with Joose classes.
A simple example:

Template('Table.Cell', {
            
            use : 'Text.Format',
        
            template : '<td>[% this.cellFormatter(text) %]</td>'
            
            methods : {
                
                cellFormatter : function (value) {
                    ...
                }
            }
        })

The created `Table.Cell` class will be a singleton, which is instantiated internally. Its external constructor (`Table.Cell`) will be 
binded to the `render` method, so, to render the template, call the constructor with the required data:

var rendered = new Table.Cell({ text : 'some text' })
        
        // or just
        
        var rendered = Table.Cell({ text : 'some text' })

**Note**: Constructor will return instance of String (new String()), so in the example above the following will be true: `typeof rendered == 'object``

Naturally, you can easily include such template into another template:

Template('Table.Row', {
            use : 'Table.Cell',
        
            template : '<tr>[%\\ Joose.A.each(row, function (cell, index) { %][%= Table.Cell({ text : cell }) %][%\\})%]</tr>'
        })

Helper script
-------------

You may have noticed, that writing templates into JavaScript can be a cumbersome task, because you need to manually escape each special symbol, like ` \ `
To address this issue `Shotenjin` comes with the helper script `shotenjin_embed.pl`. Its a simple shell script, which examine the passed file 
(or files in directory) for the templates, embedded into JavaScript comments `/*tj ... tj*/`

Template('Book', {
            
            template : {
                /*tj
                    [%\ this.wrapper(Chapter, { title : 'Chapter1' }, function () { %]                     
                        Text of first chapter.
                    [%\ }); %]

[%\ this.wrapper(Chapter, { title : 'Chapter2' }, function () { %]
                        Text of second chapter.
                    [%\ }) %]
                tj*/
            }
        })

Once found, script append such comments with the escaped version of the template:

Template('Book', {
            
            template : {
                /*tj
                    [%\ this.wrap(Chapter, { title : 'Chapter1' }, function () { %]                     
                        Text of first chapter.
                    [%\ }); %]

[%\ this.wrap(Chapter, { title : 'Chapter2' }, function () { %]
                        Text of second chapter.
                    [%\ }) %]
                tj*/

/* GENERATED BY SHOTENJIN.JOOSED HELPER, DO NOT MODIFY DIRECTLY */
                sources : '[%\\ this.wrap(Chapter, { title : \'Chapter1\' }, function () { %]                     \nText of first chapter.\n[%\\ }); %][%\\ this.wrap(Chapter, { title : \'Chapter2\' }, function () { %]\nText of second chapter.\n[%\\ }) %]'
            }
        })
        
Also, its possible to extract the content of the template from the external file:

Template('Book', {
            
            template : {
                /*tjfile(Book.tj.html)tj*/
            }
        })
By default, the location of the template file is determined relative of the source file itself, you can switch the relativity to the current working directory with the `--absolute` option.

Script is supposed to be run during your project's build phase. All modern IDE will allow you to automatically run the script, when one of the files in the project was modified,
so spend some time to examine your IDE's documentation for that.

Script accepts a single command-line argument, which should be either the path to file to examine, or the directory, which will be scanned for all `*.js` files.

Script also accepts an `--absolute` option, which will makes it to look for template files relative of current working directory.

API
===

During evaluation of the template, `this` value is associated with the instance of `Shotenjin.Template` (or its subclass), so naturally all the methods of this class are available.

Methods
-------

- `this.render(Object stash)`
 
Renders the template using data, passed in `stash`

- `this.capture(Function func)`
 
Captures the output, generated inside the passed function and returns it. For example:

[%\ var names = this.capture(function () {
            for (var i = 1; i <= 5; i++) { 
    %]
                [% persons[i].name %]
    [%\     }
        })
    %]
    
    [% names %]
 
A *new context* is derived for the passed function and the output of the outer template isn't modified.

- `this.echo(Object str1, Object str2, ...)`
 
Escapes and adds each of passed arguments to the output of the *current context*. Usually a *context* is a template itself, however nested contexts may be derived (see `this.capture` and `this.wrapper`)

- `this.echoRaw(Object str1, Object str2, ...)`
 
Unescaped version of `echo`.

- `this.wrap(Class|Shotenjin.Template template, Object stash, Function func)`
 
First captures the content generated into the passed `func`, then assign it to the `content` key of the passed `stash` object and renders the wrapping template with it.
Wrapping `template` can be passed as the instance of `Shotenjin.Template` or as Class.

- `this.escapeXml(String str)`
 
Escapes reserved HTML symbols in the `str` and returns modified string. Override this method if you need to implement more precise escaping rules.

Attributes
----------

These attributes can be either passed to constructor ("classic" way) or specified for class using `has` builder ("post-modern" way)

- `startTag`
 
String for opening tag. Default value is `[%`

- `endTag`
 
String for closing tag. Default value is `%]`

- `statementTagModifier`
 
Modifier to specify the statement instruction. Default value is ` \ `
    
 - `expressionTagModifier`
 
Modifier to specify the unescaped expression. Default value is `=`

WHITESPACE HANDLING
===================

The rules for whitespace processing:

- First of all, leading and trailing whitespace on each line is trimmed.

- If the control flow statement is followed with the newline, that newline will be "ate" and don't included into template's output.

- All other whitespace (including newlines after expressions) is preserved.

TEMPLATE STRUCTURE
==================

You may skip this section for the first-time reading.

Empty template body
-------------------

In the simplest case of empty template body, the template function looks like:

function (stash) { 
            this.startContext(); 
            
            eval(this.expandStashToVarsCode(stash));
             
            return this.endContext(); 
        }
    
This function accepts a single argument, which should be an `Object` (in JavaScript meaning) and which is called *stash*.
    
This statement

eval(this.expandStashToVarsCode(stash));
    
creates a local variable for each key of the stash, so later, any key of the stash can accessed directly by its name.

Stash can be also accessed directly, if you prefer:

[% stash.name %]
        
        [% stash.person.name %]

Ordinary text
-------------
    
If the template contains an ordinary text, like:

foo 'bar'

its translated as:
    
        function (stash) { 
            this.startContext(); 
            
            eval(this.expandStashToVarsCode(stash));
            
            __contexts[0].output.push('foo  \'bar\'\\n', "");
             
            return this.endContext(); 
        }

Escaped expression
------------------
   
        [% name[1] %]
    
Corresponds to:
        
        function (stash) {
            this.startContext();
            
            eval(this.expandStashToVarsCode(stash));
            
            __contexts[0].output.push(__me.escapeXml( name[1] ), "");
            
            return this.endContext();
        }
    
Note:
 - Whitespace immediately after opening tag / before closing tag is preserved.
 - A semicolon *is* added after expression.

Unescaped expression
------------------
   
        [%= name[1] %]
        
Is just passed through:
        
        function (stash) {
            this.startContext();
            
            eval(this.expandStashToVarsCode(stash));
            
            __contexts[0].output.push( name[1] , "");
            
            return this.endContext();
        }

Statements
----------

[%\ 
            for(var i in stash) {
                this.someFunc(p1, p2) 
            } 
        %]

Is passed through *completely* unmodified. *No semi-colons* are appended.
            
        function (stash) {
            this.startContext();
            eval(this.expandStashToVarsCode(stash));
            for(var i in stash) {
                this.someFunc(p1, p2) 
            } 
            return this.endContext();
        }

This means you need to care about any needed punctuation (as with usual code).
For example this template

[%\ for(var i in stash) { %][%\ this.echo('123') %][%\ this.echo('123') } %]
        
will produce        
        
        missing ; before statement

error. To fix it, add punctuation:

[%\ for(var i in stash) { %][%\ this.echo('123'); %][%\ this.echo('123') } %]

GETTING HELP
============

This extension is supported via github issues tracker: <http://github.com/SamuraiJack/Shotenjin/issues>

For general Joose questions you can also visit [#joose](http://webchat.freenode.net/?randomnick=1&channels=joose&prompt=1) 
on irc.freenode.org or mailing list at: <http://groups.google.com/group/joose-js>

ACKNOWLEDGEMENTS
================

Many thanks to Makoto Kuwata for his Tenjin implementation, on which this engine is based.

Shotenjin

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Shotenjin

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README