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:

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.

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 :

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 :

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 :

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. It loads an Object called 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 :

Code Snippet

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

example :

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 :

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 :

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 :

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.

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 :

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

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. Visit my site