''updated for version 2.5.0''

[{TableOfContents}]

!!!Browser based Javascript management

Beginning with version 2.3.0 ztemplates includes a small javascript library that makes writing AJAX and JavaScript based applications more easy.

[The zscript library can be found here|zscript source], a version is also provided with the ztemplates distribution.

See [Clean Up Your JavaScript with ztemplates and jQuery|http://css.dzone.com/articles/clean-your-javascript] published on dzone by Gerd Ziegler

See [Dynamic Javascript Loading with zscript and jquery|http://css.dzone.com/articles/dynamic-javascript-loading] published on dzone for a short introduction.

The library uses jquery, so make sure to include your preferred version.

To use include the following to your html head section:

{{{


  <head>
    <script type="text/javascript" src="jquery-x.x.x.js"></script>

    <script type="text/javascript" src="${contextPath}/ztemplates/zscript.js"></script>
    <script type="text/javascript" src="${contextPath}/ztemplates/zscript-definitions.js"></script>
  </head>

}}}

Now for each piece of javascript functionality you want to make available to your webapp add a annotated class and a template containing the javascript. The annotation ensures that ztemplates will find the javascript and adds it to zscript-definitions.js.
All javascript snippets are collected and added to that file, in undefined order. Therefore use the closure pattern as shown later.

Define a java class and annotate it with @ZScriptDefinition. Provide a name to the annotation. The name __must__ match the name of the variable defined in the javascript snippet. The class-name does not matter, but you may find it useful to name your script classes ZScript_name so you can easily find them.

For example to define a javascript closure named 'user' do the following:


{{{

@ZRenderer(ZVelocityRenderer.class)
//this defines a javascript object called 'user'
@ZScriptDefinition("user")
public class ZScript_user
{
}

}}}

and a javascript template in ZScript_user.vm at the same location as the class:

{{{

var user = function() {
//private area
	var loggedIn;

	function isLoggedIn() {
		return loggedIn;
	}
	
	function setLoggedIn(loggedInParam) {
		loggedIn = loggedInParam;
	}

        //helper, not visible from the outside
        function helper() {
           ...
        }	
	
//public area containes public methods that can be used from outside
	return {
		isLoggedIn: function () {
			return isLoggedIn();
		},
		setLoggedIn: function (loggedIn) {
			setLoggedIn(loggedIn);
		}
	};
}();

}}}

To use the javascript from your html page or from another script write:

{{{

//javascript library 'user' is required here, so declare this dependency
//and wait for callback when library is available
zscript.requires(['user'], function(){
   user.setLoggedIn(true);
   if(user.isLoggedIn()){
     alert('logged in!');
   }
});

}}}

The requires method from zscript takes a callback that will be called after all required scripts provided to the call (in this case 'user') are loaded.

The order in which the callbacks are called is preserved.

You may define other javascripts like this:

{{{

zscript.define('mylib', '/js/mylib.js'); //map name to url

}}}

ztemplates will ensure the javascript is loaded whenever you use it in a zscript.requires([['mylib'], function(){}) callback.

Be aware of the cross-domain restrictions placed upon the locations of your scripts, so best load them from the same server as your html.

Because there is no defined order in which the scripts are loaded the closures should not contain logic other than declaring dependencies:

{{{

var user = function() {
	var loggedIn;

        //Declare all the libraries used by this library here, will be executed before requires callbacks
        zscript.requiresInScript(['dialog', 'mylib' ]);

        //Not allowed here, make this in a method and call the method from outside.
        dialog.showDialog();

	function setLoggedInImpl(loggedInParam) {
                //OK here in function as dependency has been declared above and this will be
                //called later from html page 
                dialog.show('Something');
		loggedIn = loggedInParam;
	}

	function isLoggedInImpl() {
                //OK, as dependency has been declared above.
                mylib.doSomething();
		return loggedIn;
	}
	
	
	
	return {
		isLoggedIn: function () {
			return isLoggedInImpl();
		},
		setLoggedIn: function (loggedIn) {
			return setLoggedInImpl(loggedIn);
		}
	};
}();

}}} 

!!!Configuration

See [Context Configuration] for configuration parameters.