Introduction

By default, BXE loads and saves the XML files via the WebDAV protocol (with the HTTP methods GET and PUT). But BXE (at least since version 2.0) has a modular TransportDriver system, meaning you can write your own methods for loading and saving XML files.

Important:<br>
The following description does applies only to BXE 2.0 and above. It will not work in BXE 1.0.1 ! For using PHP along with BXE 1.0.1 please see SavingContent.

The following article shows how to implement your own transport driver with the name "example", which does a POST instead of a PUT and adds some additional values to the requests.

The Server Side

We assume, you want to run a little PHP script on the server side (it can be written in any language, of course), which handles the load and save. There's a script called getpost.php in the scripts/ directory in the distribution, which exactly does that. It takes the name of the file as a query parameter names XML. You can take this as a reference, if you like to.

Configuration

First thing you have to do, is to change your config.xml. Add the attribute "method" to the line, where the to be loaded XML file is defined, something like that (as child if <config><files><input>):

<file name="BX_xmlfile" method="example">getpost.php?XML=testdoc.xml</file>

Please note, that done to a security check the code above will not work with unchanged file getpost.php distributed with BXE 2.0 - you have to adjust the code.

Next you have to write a JavaScript file located at mozile/td/example.js with your example-transportdriver, which you also have to include into the files section. Add the following line to the to-be-loaded javascript files (within the <scripts> element):

<file>mozile/td/example.js</file>

JavasScript file

First thing we do for the actual coding is to generate a file in mozile/td called example.js (it could have any name, it just has to be the same as the one defined in the config.xml). Then we define a new class:

function mozileTransportDriver_example() {
}

To make life a little bit easier, we extend from the already existing http transport driver, so we do not have to implement everything all over again:

mozileTransportDriver_example.prototype = new mozileTransportDriver_http();

Now you already can GET the XML content from the server.

Saving with POST

In this example, we want to save the content with POST and have the name of the file in the parameter XML and the xml_content in the parameter content. For doing this, we have to overwrite the save method from http.js

mozileTransportDriver_http.prototype.save = function(filename, content, td) {
	this.p = new XMLHttpRequest();
	this.p.overrideMimeType("text/xml");
	this.p.onload = this.saveCallback;
	this.p.td = td;
	this.p.open("POST",filename );
	this.p.setRequestHeader("Content-type","application/x-www-form-urlencoded");
{panel}
        // Get XML filename, needed as GET parameter later
        // (You should add error handling here!):
        var filenameStart = bxe_config.xmlfile.indexOf('=') + 1;
        var xmlfile = bxe_config.xmlfile.substring(filenameStart,bxe_config.xmlfile.length);
{panel}
	var encodedContent = "XML=" + encodeURIComponent(xmlfile)  + "&content=" +encodeURIComponent(content);	
	this.p.send(encodedContent,true);
}

the line

var xmlfile = bxe_config.xmlfile.substring(filenameStart,bxe_config.xmlfile.length);

is needed, because we defined the xmlfile as getpost.php?XML=testdoc.xml in config.xml, so we have to get rid of the first part to have just the file name in the POST request. Below are some other solutions to that problem.

That's it. Now you have a working implementation which uses POST and GET

Server Responses

BXE decides with the help of HTTP status codes, if the request was successful or not. If it was successful, you should send back a "HTTP/1.1 204 No Content", a "HTTP/1.1 201 Created".

If there was an error, use anything else and BXE will show an alert, that the save didn't work.

If you want to have nice errormessages, you have to return this errormessage in a special XML format. It's the same format as Mozilla produces on XML errors.

<parsererror xmlns="http://www.mozilla.org/newlayout/xml/parsererror.xml">
{panel}
  Error during save
  <sourcetext>Some more text here, if you'd like
{panel}
--------------^</sourcetext>
</parsererror>

Then you get that message in the alert box.

Configuration for more parameters from config.xml

If you need to provide more than one parameter to the load/save procedure, you can define option values in config.xml and access them. Assuming you generate the config.xml on the server, that should be an easy task. Add for example the following to the XML file:

<options>
{panel}
 <option name="lang">de</option>
{panel}
</options>

You can then access that value with:

bxe_config.options['lang']

and for example add the following line to your transport driver.

encodedContent += "&lang=" + encodeURIComponent(bxe_config.options['lang']);

You can also access GET parameters from your initial BXE request (the one, which load index.html, not the XML loading request). You should have those values in the bxe_config.urlParams array.

For adding more parameters to the GET request for the XML content file, you can write a load method in your transport driver (see http.js for an example) and then change the line

docu.load(filename);

to

docu.load(filename + "&lang=" + encodeURIComponent(bxe_config.options['lang']);

and then you should have the parameter in the GET request as well.

How_to_implement_your_own_transport_driver