XTiger XML with AXEL tutorial
Part 2 : rendering a template in an iframe

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 method. The part 1 and the part 3 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)

<script type="text/javascript" src="{PATH-TO}/axel/axel.js"></script>

show explanation

The src attribute 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).

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

Click on load to load the template in the iframe below.

var iframe = document.getElementById('container');
iframe.setAttribute('src', '../templates/Hello-world.xhtml');

show explanation

The iframe will show only the body part of the template until you transform it in Step 3. The components declared in the head section are not visible.

Template File in an iframe

Step 3 : Transform the template (show source)

Click on transform to turn the template in the iframe into an editable document. Alternatively we could have registered an onload event handler on the iframe to transform the template once it is loaded

var form = new xtiger.util.Form('{PATH-TO}/axel/bundles');
var result = new xtiger.util.Logger();
form.setTemplateSource(iframe.contentDocument);
form.enableTabGroupNavigation();
if (form.transform(result)) { 
  form.injectStyleSheet('{PATH-TO}/axel/axel.css', result);
}
if (result.inError()) { // Optional feedback about errors
  alert(result.printErrors()); 
}

show explanation

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

First, we use an optional xtiger.util.Logger object to accumulate error messages when calling transform and injectStyleSheet

Second, the XML document passed to setTemplateSource and that defines the template to transform is now the contentDocument property of the iframe. You must be aware that in some versions of Internet Explorer you should test for the existence of the contentDocument property first, and use iframe.contentWindow.document if it does not exists

Third, as the template file does not directly include the AXEL global CSS file, we need to inject it in the iframe with a call to injectStyleSheet with a URL pointing to the location of that file which is distributed inside the axel/ folder

Fourth, because we used an optional xtiger.util.Logger object to accumulate errors, we use it to print an error message in case of failure.

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