OneGate supports AJAX methodology, making it very easy on the server side to let your applications dynamically affect pages without refreshing the entire page. There are a few things to keep in mind when using OneGate for AJAX work. We'll cover them here.

MIME Types

When using OneGate for AJAX work, you should always make sure the MIME type is application/xml unless you know what you're doing and have reason to set it otherwise. In the standard paradigm, you're supposed to be returning XML data, so this is the correct setting. You can change it if you need to. But whatever setting you use should be the case across the board. Every MIME type setting for all output types should be set to the same value.

Multiple Testbeds, CGI, and AJAX

Traditionally, OneGate runs in CGI mode. You could set the MIME types all manually for your main "default" testbed personality (ie., "onegate") if all you were doing was AJAX. However, if you need to use OneGate for multiple roles (such as CGI and AJAX concurrently on the same system), achieving this is quite easy.

In this case, you should use the Multiple Testbed Functionality to achieve this. Let us assume you want to use CGI, but you also have some AJAX functionality you'd like to roll in. Your main configurations may all use text/html. However, if you create any testbed that ends in _ajax (ie., onegate_ajax, onegate_development_ajax, etc.), any testbed that ends with that suffix automatically has all MIME types set to application/xml. They can be overridden in the configuration files if necessary, but it's an easy way to set yourself up with an AJAX-specific personality for OneGate that lets you coexist with your CGI functionality. Likewise, the default caching is defaulted to off for the AJAX testbeds, but can also be overridden.

Please read the documentation regarding multiple testbeds to learn how to configure these.

Error Checking

OneGate will make use of error files you have written, substituting tokens if you're using that functionality. See: Output Substitution Tokens for more information.

However, even if you have a custom error page, there are a few errors that could possibly occur in a misconfigured system prior to the point the error page could be obtained for use. In this case, an internal error format is used.

If this kind of error is triggered, the first thing to note is that the HTTP status code returned from the server will be 244. This is an extended success code, but it's meant to inform you that you've received OneGate's internal error XML because it had no choice. You should handle this appropriately.

The second thing to know is what you're parsing if you get HTTP status 244 in this type of situation. The DTD for these errors is:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE OG_Error [
<!ELEMENT OG_Error (OG_Code,OG_Text,OG_Devel,OG_Version,OG_Program,OG_Session)>
<!ELEMENT OG_Code (#PCDATA)>
<!ELEMENT OG_Text (#PCDATA)>
<!ELEMENT OG_Devel (#PCDATA)>
<!ELEMENT OG_Version (#PCDATA)>
<!ELEMENT OG_Program (#PCDATA)>
<!ELEMENT OG_Session (#PCDATA)>
]>

An actual example of the XML would be:

<OG_Error>
     <OG_Code>5</OG_Code>
     <OG_Text>No program set given.</OG_Text>
     <OG_Devel>Development debugging disabled.</OG_Devel>
     <OG_Version>04.00.00</OG_Version>
     <OG_Program>Fairlight OneGate v04.00.00</OG_Program>
     <OG_Session>1171416241-7171</OG_Session>
</OG_Error>

An example of the JavaScript to get the relevant data would is:

if (http_request.status == 200) {
     // Do whatever you'd do on success...
} else if (http_request.status == 244) {
     // OneGate internal failsafe error.
     var xmldoc = http_request.responseXML;
     var ogcode = xmldoc.getElementsByTagName('OG_Code')[0].childNodes[0].nodeValue;
     var ogtext = xmldoc.getElementsByTagName('OG_Text')[0].childNodes[0].nodeValue;
     var ogdev = xmldoc.getElementsByTagName('OG_Devel')[0].childNodes[0];
     if (! ogdev) {
          ogdev = 'Development debugging off.';
     } else if (ogdev) {
          var ogdev = xmldoc.getElementsByTagName('OG_Devel')[0].childNodes[0].nodeValue;
     }
     var ogprog = xmldoc.getElementsByTagName('OG_Program')[0].childNodes[0].nodeValue;
     // Do something with these values to indicate failure.
} else {
     // Generic transport failure unrelated to OneGate.  Handle apprpriately.
}

For anyone doing AJAX work, it's as simple as configuring up your program sets, making sure you add a check for a potential 244 HTTP status code return, and doing the rest of whatever you're doing AJAX-wise. Technically, you don't even need to specifically handle the information that comes back in the case of a 244 request if you only check for status 200 and consider anything else a failure; but if you need the information, it's there.

You can test OneGate in an AJAX context here.