Introduction

ZParse is a multi-purpose, extensible, self-defineable javascript template parsing system which lets you define your templating rules. It acts like a preprocessor and parses strings containing defined delimiters and tags into a javascript function. It is similar to TrimPath JavaScript Template. The difference and its strength is that instead of defining the syntax inside the script it allows YOU to create and define the syntax yourself as you need. Of course there is a default syntax included for people who don't need a custom syntax. But the main intention for me creating this parser is to be multi-purpose, so it can fullfill your demand. Therefore extensibility is very essential. Another strength of this parser is, that it parses the template tags into a DOM-like tree instead of replacing the tags with pre-defined functions to give you more flexibility and opportunity to take full advantage of javascript templating.

Download ZParse v0.1 now. Or zparse.js, zparse.uncompressed.js, implementation.js only.
It is actually only tested in ie7 (minimal test ie6, it works recently), opera9 and firefox2. please contact me for bugs

Features at glance:

• Lightweight code to include (3kb compressed js file).
• Very extensible
• Self-defineable syntax
• DOM-like tag parsing. Instead of search and replace
• Advanced tag handling. Allows you to gain access to its children and ancestors
• Advanced arguments handling. You can create argument like "create {object} extends {class}" and you will get object and class as your arguments variables
• A powerful-enough standard syntax

ZParse is open source, released under the very liberal MIT License, so feel free to do anything you want with it.

Using ZParse

First, in your HTML/JSP/PHP/ASP file, include the {your script path}/zparse.js JavaScript file.

<script language="javascript" src="script/zparse.js"></script> The zparse.js file can live anywhere you want and may be renamed. It has no dependencies to other files. For example, you might move it to script/lib/zparse.js or js/zparse.js.

After including zparse.js, a JavaScript variable named ZParse will hold an Object ready for you to use.

ZParse Class

ZParse is a namespace combined with a Class. As a Class it can construct parser objects, which is independent to each other. So many parser with different syntax rules can be created without conflict.

usage :

new ZParse(implementation)

parameters :

implementation {Object}, Syntax rules to be implemented.

example :

var imp = {...}; // Syntax Rules var parser = new ZParse(imp);

ZParse.prototype.parse

Parse template string to template function. After executing this function, properties sourceArray, sourceTree, functionText and function functionScript(data) can be accessed.

usage :

parser.parse(implementation)

parameters :

source {String}, Template string to be parsed.

return :

{Boolean}, Parsing status, false if failed, true if succeeded.

example :

var imp = {...}; // Syntax Rules var parser = new ZParse(imp); var succ = parser.parse('Hello ${friend}, My name is ${name}. I am ${age} years old.'); if(succ) alert(parser.functionText);

ZParse.prototype.process

Process created template function with data resource. This function requires the execution of parse() function.

usage :

parser.process(data, bind)

parameters :

data {Object}, data that will be used when executing template function.
bind {Object}, 'this'-object to be binded in template function.

return :

{String}, text output.

example :

var imp = {...}; // Syntax Rules var parser = new ZParse(imp); parser.parse('Hello ${friend}, My name is ${name}. I am ${age} years old.'); var output = parser.process({friend:'all', name:'Rizqi', age:17}); // returns: Hello all, My name is Rizqi. I am 17 years old.

ZParse.parseXMLToJSON

Simple but good DOM/XML to JSON converter.

usage :

ZParse.parseXMLToJSON(xmlObject)

Default Syntax

This section describes the syntax for ZParse default implementation, explaining its usage and available markups and tags.

First, you have to include implementation.js. <script language="javascript" src="script/implementation.js"></script> It loads an Object called Implementation. var parser = new ZParse(Implementation);

Print

You can print any javascript expression except { } using ${expr} . If you need to use { }, you can use <$expr:> instead.

syntax :

${ javascript variable to print }
<$ javascript variable to print :>

example :

<div id="card"> <div>name: ${name} </div> <div>address: <$getAddress({name:name}):> </div> </div>

Code Snippet

You can insert javascript code by using <% your code %>.

example :

<% var name = "Solid Snake", address = "somewhere"; %> <div id="card"> <div>name: ${name} </div> <div>address: ${address} </div> </div>

Statements

Statement tags are nestable in just like JavaScript statement blocks ( if / else / for ) are nestable.

if, elseif, else. Conditional statements

You can use if / else condition as you do in javascript.

syntax :

<:if condition :> todo <:/if:>
<:elseif condition :> todo <:/elseif:>
<:else:> todo <:/else:>

example :

<% var name = "Solid Snake", address = "somewhere"; %> <div id="card"> <:if name && address:> <div>name: ${name} </div> <div>address: ${address} </div> <:/if:> <:elseif name:> <div>name: ${name} </div> <:/elseif:> <:else:> no card loaded. <:/else:> </div>

for, foreach, else. Conditionable loop statements

You can use for / foreach loop statement as you do in javascript. You can also create an exception if the object you iterate undefined or if the array doesn't contain any element by using else tag after for / foreach tag.

syntax :

<:for index in array/object :> todo <:/for:>
<:foreach element in array/object :> todo <:/foreach:>
<:else:> todo <:/else:>

example :

<% var cards = [ {name:'John Woo', address: 'Hollywood'}, {name:'Adolf Hitler', address: 'Hell'}, {name:'Josef Stalin', address: 'Hell'}, {name:'Solid Snake', address: 'Somewhere'} ]; %> <table> <tr> <th>Nr.</th> <th>Name</th> <th>Address</th> </tr> <:for i in cards:> <tr> <td>${i}</td> <td>${cards[i].name}</td> <td>${cards[i].address}</td> </tr> <:/for:> <:else:> <tr> <td colspan="3">no data!!!</td> </tr> <:/else:> </table>

Macro declaration

A macro is like a javascript function, except the body of the macro is another zparse template, not javascript. Macro name can be any javascript variable or even a property of a javascript object. use $data.{macroName} if you want to declare your object in data resource or use window.{macroName} if you want your macro to be declared as global function.

syntax :

<:macro name( arg1 [, arg2 ...] ):> todo <:/macro:>
<:macro object.name( arg1 [, arg2 ...] ):> todo <:/macro:>

example :

<% var cards = [ {name:'John Woo', address: 'Hollywood'}, {name:'Adolf Hitler', address: 'Hell'}, {name:'Josef Stalin', address: 'Hell'}, {name:'Solid Snake', address: 'Somewhere'} ]; %> <:macro createRow(data):> <tr> <td>${data.name}</td> <td>${data.address}</td> </tr> <:/macro:> <table> <tr> <th>Nr.</th> <th>Name</th> <th>Address</th> </tr> <:for i in cards:> ${createRow(cards[i])} <:/for:> <:else:> <tr> <td colspan="3">no data!!!</td> </tr> <:/else:> </table>

cdata

You can use the cdata markup syntax to tell zparse to ignore processing for a block of text. The text will be emitted without any tag or markup processing.

syntax :

<:cdata:> ... <:/cdata:>

limitation :

because the implementation is executed after building the DOM-like tree, any zparse tags inside the cdata block must be valid. So if you have any if, else, elseif, for, forelse, macro, etc. in cdata you have to close them properly.

Tutorial

coming soon...

Creating Custom Template Rules

With ZParse you are allowed to create your own rules. This can be realized with the implementation object. The implementation object is a simple javascript object with certain structure.

var myImplementation = { // delimiter without tagname 'delimiterName1': { opener: '{%', // delimiter opener syntax closer: '%}', // delimiter closer handler: function(tree, content, caller){ // tag handler var ThingsBetweenOpenerAndCloser = tree.argSource; return someKindOfScriptAsString; // return output string } }, // delimiter with tagname 'delimiterName2': { opener: '{:', closer: ':}', tags: { // single tag, no end tag. It can't have any child tags. example: {:tagname1 whatever:} 'tagname1': { type: 'single', handler: function(tree, content, caller){ var ThingsAfterTagName = tree.argSource; // returns "whatever" in example case return someKindOfScriptAsString; } }, // block tag, it can have children. Similar to statements in default implementation 'tagname2': { type: 'block', handler: function(tree, content, caller){ var ThingsInsideThisBlock = content; // parsed content var ContentBeforeParsed = tree.innerSource; return someKindOfScriptAsString; } }, // tag with arguments 'tagname3': { type: 'block', noTextBefore: true, // Delete text before this tag. arguments: '{subclass} extends {parentclass}', handler: function(tree, content, caller){ var subclass = tree.arguments.subclass; var parentclass = tree.arguments.parentclass; return someKindOfScriptAsString; } } } } };

delimiter and tag name

They are just placeholders, it's not restricted to anything.

opener and closer

Opener and closer can be any character that you wish to be delimiter for your template tag. For example, if you want to have syntax like ${variable}, you have to define ${ as opener and } as closer.

tag type

There are currently 2 types implemented: single and block. Single tags can't contain any child and can't be nested. Block tags can contain children and can be nested, but they'll have to be closed properly.

example :

{:single "I am a single tag, I can not be nested":} {:block "I can have children, but I have to be closed properly":} {:child "0":},{:child "1":},{:child "2":} {:/block:}

tag arguments

Arguments are automatically parsed argument string. It is optional, if you use it, tree.arguments.{your argument} will be accessible. If not you can still use tree.argSource to gain access inside delimiter.

tree argument

Tree is current child to be parsed in handler function. It is a DOM-like object that contains properties. It has information about its parent, children, arguments, etc.

parameters :

tagname {string} its tagname
delimiter {string} its delimiter name
arguments {object} arguments generated by arguments-parser
argSource {string} Things inside delimiter without tagname
innerSource {string} all inside the block as unparsed string
parent {tree object} tree parent object
children {tree object} children inside the block
nr {number} its number as parent's child. you can obtain the next or previous child by invoking tree.parent.children[tree.nr+1]

content

If you have a block tag, you can access content argument. It contains the parsed string of the children. If you want to access the unparsed string use tree.innerSource.

caller

With caller you have access to the parser object that calls the handler.

Demo

• Dynamic Table demo
• ZParse Test Site

About Me

I am Rizqi, born in Indonesia, living in Hamburg, Germany. I have experiences in coding javascript since I was 14. But I was too shy and lazy to be active in the web. So this is my first contribution to the net. I appreciate any kind of response from you (except spam), please contact me.