0. Introduction
Since the introduction of Ajax, server-side templating is becoming redundant.
Objective:
To make production of Ajax web pages easier.
Goal:
To create a client-side templating engine written in Javascript.
Target:
All major browsers.
ChangeLog:
v0.1.7 - Includes an xml parser that overrides all browsers to make this project compatible to all of them.
v0.1.8 - Most parts of the project work in all browsers, but function insertBeforeTableRow does not work in IE when the calling object is not specified.
v0.2.0 - Going more OOP. Less and less programming knowledge required to use ecAjax. Now usable in IE8 too. Extended features such as insertBeforeTableRow are not yet debugged yet, so do not try to use the extended features.
v0.2.1 - Bug fix elementNode.insertBefore() and swapNodes(). Feature added to [:LOOP:].
v0.2.2 - Bug fix emulation of FormData. send() method of XML objects now enhanced with the ability to send(HTMLFormElement).
v0.2.3 - Bug fix IE cache problem, parseXML, parseFormat, console, replaceIntoTableRow, insertBeforeTableRow. Introducing "Recursion" in formatting.
v0.2.4 - Optimize loops for performance. Enhance "Recursion" in formatting so that disordered elements can still be displayed.
v0.2.5 - Bug fix XML.reset() and memory leaks in cross-browser xmlHttpRequest.
v0.9.0 - Most functions are put under variables named C, D, E, or J. "new XML" is now replaced by "new J.XML". A good number of changes are made but will be documented later. A lot of features are pending for changes, so prepare to make amendments if v0.9 is to be used.
v0.9.1 - Improved error handling in xmlHttpRequest. Now supports IE7+.
v0.9.2 - Supports JSON. The original J variable is now renamed as A. "new J.XML" should now be replaced by "new A.XML". Defining img_dir is now treated differently (see below).
v0.9.4 - Minor bug fix here or there. Introduce [:USE anotherJXON:] syntax to template. Load JXON synchronously if node.format() is called but anotherJXON is not yet loaded, while calling node.format() through JXON.display(), node.replaceIntoTableRow() and node.insertBeforeTableRow() will load anotherJXON asynchronously.
v0.9.5 - Bugfix String.splice for IE, bugfix [:RECURSION:], introduced new A.HTML to load HTML files (how HTML files should be handled will be dealt with later), reduced code size of processQueue and hence improved efficiency, combined JXON.send and JXON.loadSource to reduce code size and simplify maintainence.
v0.9.6 - Bugfix node.evalExpr for expressions involving back-referencing variables. Modified C.include to prevent browsers from caching javascript files.
v0.9.7 - Bugfix parseXML and parseJSON in parsing multi-line data. Bugfix [:IF:]...[:ELSEIF:]...[:ELSE:]...[:ENDIF:] syntax in templates. node.format() now escapes " and ' with " and ' respectively in variables. new A.HTML is removed (turns out this is completely useless).
v0.9.8 - Bugfix here or there. Sorry for not recording where fixed >_<!
v0.9.9 = Bugfix in evalExpr. Rewrote a few regex for better syntax and maintainance. The way to defined variables inside a template has been changed. This will be the final syntax for defining variables. See below for details.
1. How to start ecAjax
<script src="ecAjax.js"></script>
OR
<script src="ecAjax.js">
#define img_dir img_dir_which_contains_ajax-loader.gif
#define other_constants if_you_like
</script>
2. How to load an xml or json
var myXML=new A.XML({
source:'your_xml_url',
text:'Alternative text in place of loading from source',
defaultDiv:'some_div_id',
defaultTemplate:'templating text' OR 'some_HTMLElement_id_that_contains_templating_text',
autoLoad:true,
autoDisplay:true});
var myJSON=new A.JSON({
etc: etc});
3. Simple example of text for XML (should be left out if source is already defined):
<xml>\
<product id="PC102">\
<name>Hamburg</name>\
<type>Waste</type>\
<category>Junk</category>\
<cost>0.5</cost>\
</product>
<product id="XXL-10">\
<name>French Fries</name>\
<type>Waste</type>\
<category>Junk</category>\
<cost>20000</cost>\
</product>\
</xml>
If you use new A.JSON instead, the text should correspondingly be JSON.
4. Simple example of templating text:
<table>\
[:LOOP product:]\
[:IF_FIRST:]<tr><td><b>$name</b> $type</td></tr>\
[:ELSE:]<tr><td>$name $type $cost</td></tr>\
[:ENDIF:]\
[:ENDLOOP:]\
</table>
(remove the \ if written inside HTMLElement)
5. Variables used in formatting output
$name OR
$../name (../ can be repeated) OR
$\n\name OR
$\n\../name (../ can be repeated)
where name is the nodeName or attributeName, ../ stands for parentNode, n is an integer larger than zero and stands for n th back reference out of [:USE:]
OR
$#token
where token can be a constant defined with #define in the script section, or a global variable (including array).
OR
${expression}
where expression is an arithmetic expression, using variables described above.
e.g. ${score*100}.
e.g. ${cost>1000}.
6. Syntax used in formatting output
Sorry for the ugly syntax, but [: and :] are delimiters, not optional.
a. [:IF ${expr1}:]|[:IF_FIRST:]|[:IF_LAST:]...[[:ELSEIF ${expr2}:]]...[[:ELSEIF ${expr3}:]]...etc...[[:ELSE:]]...[:ENDIF:]
expr1, expr2, ... are conditional expressions, such as cost>1000.
b. [:LOOP element [${expr}]:]...[[:NOLOOP:]]...[:ENDLOOP:]
E.g.: (Complete programme)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<script src="ecAjax.js"></script>
<script>
var month=',Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec'.split(',');
var myXML=new XML({
text:'\
<xml>\
<term>1<from>2</from><to>5</to></term>\
<term>2<from>6</from><to>9</to></term>\
<term>3<from>10</from><to>12</to></term>\
</xml>',
defaultDiv:'schoolYear',
defaultTemplate:'schoolYear',
autoLoad:true,
autoDisplay:true});
</script>
</head>
<body>
<div id="schoolYear">
[:LOOP term:]
Term $term starts from $#month[from] till $#month[to]<br />
[:IF_FIRST:]<b>School Hour: 8:00 am to 2:00 pm</b><br />[:ENDIF:]
[:NOLOOP:]
No term defined
[:ENDLOOP:]
</div>
</body>
</html>
c. [:RECURSION element [${expr}]:]...[:SIBLINGS:]...[:CHILDREN:]...[:ENDSIBLINGS:]...[:ENDRECURSION:]
E.g.: (Complete programme)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<script src="ecAjax.js"></script>
<script>
var myXML=new A.XML({
text:"\
<xml>\
<assessment id=1 pid=0>\
Assignment\
<score>20</score>\
</assessment>\
<assessment id=2 pid=0>\
Quiz\
<score>40</score>\
</assessment>\
<assessment id=3 pid=0>\
Examination\
<score>80</score>\
</assessment>\
<assessment id=4 pid=3>\
Paper I\
<score>40</score>\
</assessment>\
<assessment id=5 pid=3>\
Paper II\
<score>50</score>\
</assessment>\
<assessment id=6 pid=3>\
Paper III\
<score>60</score>\
</assessment>\
<assessment id=7 pid=6>\
Q1\
<score>40</score>\
</assessment>\
<assessment id=8 pid=6>\
Q2\
<score>80</score>\
</assessment>\
<assessment id=9 pid=6>\
Q3\
<score>20</score>\
</assessment>\
</xml>",
defaultTemplate:"\
[:RECURSION assessment:]\
<ul>\
[:SIBLINGS:]<li>$assessment: $score[:CHILDREN:]</li>[:ENDSIBLINGS:]\
</ul>\
[:ENDRECURSION:]",
defaultDiv:'List',
autoLoad:true,
autoDisplay:true});
</script>
<body>
<div id="List"></div>
</body>
</html>
7. Further example
Here is an example that illustrate how you can login and logout without reloading the whole page using ecAjax:
...
<script>
...
var XAUTHN_S_LOGOUT=0;
var XAUTHN_S_COMPLETE=1;
...
var loginXML=new A.XML({
source:'login.xml.php',
defaultDiv:'loginBox',
defaultTemplate:'loginBox',
autoLoad:true,
autoDisplay:true,
});
...
</script>
...
<body>
...
<div id="loginBox">
[:IF ${login==#XAUTHN_S_COMPLETE}:]
Welcome, $username
<br /><a href="../">Go to common section</a>
<br /><a href="#" onClick="loginXML.loadSource('logout=')">Logout</a>
[:ELSE:]
[:IF ${login!=#XAUTHN_S_LOGOUT}:]<font style="color:red;font-weight:bolder;">Invalid user or password!</font>[:ENDIF:]
<form>
<table>
<tr><td>User</td><td><input type="text" name="username" /></td></tr>
<tr>
<td>Password</td><td><input type="password" name="password" /></td>
<td><input type="button" value="login" onClick="loginXML.loadSource(this.form)" /></td>
</tr>
</table>
</form>
[:ENDIF:]
</div>
...
</body>
...
login.xml.php returns the following on successful login:
<xml>
<login>1</login>
<username>username</username>
<gid>1</gid>
</xml>
login.xml.php returns the following on failure login:
<xml>
<login>2</login>
<username></username>
<gid></gid>
</xml>
login.xml.php returns the following on logout:
<xml>
<login>0</login>
<username></username>
<gid></gid>
</xml>
