XTiger XML with AXEL tutorial
Part 3 : rendering a template within an Ajax response object to a div inside a Web page

DEPRECATED: this is a deprecated API since axel version 1.3.2
use the $axel object instead

The 3 most common ways to generate editors from document templates are to embed the template within a standalone Web page, in an iframe, or within an Ajax response object. In all the cases a few lines of Javascript codes are then necessary to actually turn the template into an editor.

This document describes the second third. The part 1 and the part 2 of this tutorial describe the other methods. While reading this tutorial do not forget to look at the source code and the explanations (use the show/hide buttons). You may also have a look at the source of this page as it contains itself all the code examples.

Show All the code examples and explanations at once

Step 1: include AXEL library inside your Web page (show source)

In addition to the AXEL Javascript source code you must also include the global AXEL CSS file

<script type="text/javascript" src="{PATH-TO}/axel/axel.js"></script>
<link rel="stylesheet" href="{PATH-TO}/axel/axel.css" type="text/css"></link>

show explanation

The src attribute of the script element must point to the location where you have copied the AXEL library file which is distributed inside the axel/ folder. You can regenerate a new AXEL library file with your own selection of plugins by editing the scripts/build.xml file and by using the build.lib target to rebuild the library with ant (cd scripts; ant build.lib).

The global AXEL CSS file is available inside the axel/ folder with the other bundles that contain resources for the editors.

Step 2 : Load a template within the iframe (show source)

Click on load to load the template inside an XML document into the memory.

var result = new xtiger.util.Logger();
xtDoc = xtiger.cross.loadDocument(url, result);
if (result.inError()) { 
  alert(result.printErrors()); 
}  else {
  alert('Template loaded');
}

Step 3 : Transform the template (show source)

Click on transform to transform the template and copy the resulting editor inside the div below

var form = new xtiger.util.Form('{PATH-TO}/axel/bundles');
form = new xtiger.util.Form('{PATH-TO}/axel/bundles');
form.setTemplateSource(xtDoc);
form.setTargetDocument (document, 'container', true);
form.enableTabGroupNavigation();
if (! form.transform()) { 
  alert(form.msg); // feedback about errors
}

show explanation

There are only a few differences with the Step 2 of part 1

First, the XML document passed to setTemplateSource and that defines the template to transform is the XML document returned by the Ajax call in Step 2

Second, the call to setTargetDocument is essential as it tells the library where to copy the result of the transformation of the template. The first argument is the target document and the second argument is the id of an element of the target document (e.g. a div) that will receive the transformed template. If the last argument is set to true, then all the children of the target element will be removed first. This may be useful if you download multiple templates at different moments within the same Web page

Finally, note that since the AXEL global CSS file has been included in the target Web page in Step 1, it is not necessary to call injectStyleSheet as with the iframe method method described in part 2. However the drawback of this method is that if your template file includes external CSS files, you must explicitely include them in the target Web page

Template File copied to a div after transformation

Step 4 : Load an XML document (sample.xml) into the editor (show source)

Click on load to feed the template with the XML file.

Currently an XML file can be loaded only once and just after the template has been transformed. This is a limitation with the library, you can try to load data files more than once inside the same template, but you may obtain unpredictable results. If you need to do this then you should reload the template and transform it first.

var result = new xtiger.util.Logger();
var data = xtiger.cross.loadDocument('sample.xml', result);
if (data) {
  var dataSrc = new xtiger.util.DOMDataSource(data);
  if (form.loadData(dataSrc, result)) {
    alert('Data loaded');
  }
}
if (result.inError()) { alert(result.printErrors()); }

show explanation

This is the same as in Step 3 of part 1

Step 5 : Dump the XML document from the editor (show source)

Click on dump to print below the current content of the target XML document (you can edit it first). The content is dumped as a string.

var dump = new xtiger.util.DOMLogger ();
form.serializeData (dump);
var xmlString = dump.dump();
var n = document.getElementById('content');
n.firstChild.data = xmlString;

show explanation

This is the same as in Step 4 of part 1

Last update: Stéphane Sire, June 3 2010