XTiger XML with AXEL tutorial
Part 1 : making an auto-editable template
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 first method. The part 2 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.
Template directly embedded within this page
List of persons to great:
Step 1: write your Web page as a document template
This Web page is based on a simple cross-browser template skeleton. As you can see the part of the page in the box above is editable. You can also use the Template.xhtml file as a starting point (show source)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger"> <head> <!-- Use UTF-8 and omit xml protocol at the top for IE --> <meta http-equiv="content-type" content="text/html; charset=UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=8;" /> <meta name="description" content="XTiger XML document template" /> <meta name="keywords" content="template, XTiger" /> <title>XTiger XML with AXEL tutorial</title> <xt:head version="1.1" templateVersion="1.0" label="greetings"> <xt:component name="personList"> <ul> <xt:repeat minOccurs="0" maxOccurs="*" label="persons"> <li> <xt:use types="text" param="shape=parent-75px;type=textarea" label="name">name</xt:use><xt:menu-marker/> </li> </xt:repeat> </ul> </xt:component> </xt:head> <!-- See Step 2 --> </head> <body> <div id="document"> <p class="template">Template directly embedded within this page</p> <p>List of persons to great:</p> <xt:use types="personList"/> </div> </body> </html>
The best compromise to be able to open your Web page in standard compliant browsers AND in Internet Explorer is to save the file as UTF-8 and to omit the xml protocol declaration (i.e. <?xml version="1.0" encoding="UTF-8"?>). So the file should start directly with an XHTML DOCTYPE declaration. It is recommended to read the HTML Compatibility Guidelines from the XHTML 1.0 Recommendation before writing template files.
It is wised to specify the content-type with a meta element, this improves MIME-Type sniffing when opening the file directly from a local file system on Internet Explorer. If you access the file from a Web server, you should serve it with a MIME TYPE set to application/xhtml+xml, except for Internet Explorer that only supports text/html when serving the template directly within a Web page. Eventually you can specify Microsoft X-UA-Compatible property to tell Internet Explorer to open the page in a specific mode, currently AXEL works with IE 7 and IE 8.
Step 2: include AXEL library and template transformation code inside your template
You can directly cut and paste the code fragment below into the <head> element of the template document (show source)
<script type="text/javascript" src="{PATH-TO}/axel/axel.js"></script> <link rel="stylesheet" href="{PATH-TO}/axel/axel.css" type="text/css"></link> <script type="text/javascript"> var form; function init() { form = new xtiger.util.Form('{PATH_TO_BUNDLES}'); form.setTemplateSource(document); form.enableTabGroupNavigation(); if (! form.transform()) { alert(this .form.msg); } } xtdom.addEventListener(window, 'load', init, false); </script>
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 generate a new AXEL library file with your own selection of plugins by editing the scripts/build.xml file and with a build.lib target with ant (cd scripts; ant build.lib).
You must include the global AXEL CSS file which is available inside the axel/ folder with the other bundles that contain resources for the editors.
Usually the best place to transform the Web page into an editor is within an initialization function registered on the window load event. You can use the utility xtdom.addEventListener cross-browser method for registering the event handler or any other method.
The xtiger.util.Form constructor needs to get the URL of the bundles/ folder that contains some resources such as icons for the library and which is distributed inside the axel/bundles folder
The call to setTemplateSource defines the template to transform, in that case it is the document as the template is embedded inside the Web page.
The call to enableTabGroupNavigation is optional as this features is not fully implemented nor supported, it's goal is to enable keyboard tab navigation between the document input fields
The transform method takes an optional error logger as parameter, it returns true on success. In case of error you can use form.msg to print the latest error message.
Step 3 : 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()); }
The xtiger.util.Logger object is an optional error logger object that can be passed to some of the libarary functions to log errors.
The most important part is to create an xtiger.util.DOMDataSource object initialized with an XML Document object containing the XML data to feed into the transformed template with the loadData method.
You may use the xtiger.cross.loadDocument method to load an XML file from its URL, it uses an internal XMLHTTPRequest object to do the query (or an ActiveX object on Internet Explorer 7) and returns the response.XML parsed document, but you can also use any other method you prefer. You can also notice that depending on the browser that method may not work if it is called to load local files (URLs starting with the file:// protocol)
Step 4 : 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;
You need to instantiate an xtiger.util.DOMLogger object first and pass it to the serializeData method to accumulate the XML content. Then you obtain a string representation of the XML content with the dump method, it is up to you to use that string as you want (e.g. send it through Ajax to a server).
Last update: Stéphane Sire, June 3 2010