Cross-domain Ajax

Making cross domain AJAX requests with contemporary browsers is an issue for any developer building a website using the Mapfluence Javascript API. Also known as cross-site scripting, browsers prevent XMLHttpRequests (aka AJAX requests) from requesting or posting to domains other than the host serving the web page. E.g. if your site is hosted at http://example.org, the client's browser will restrict any XMLHttpRequest to the example.org domain. The merits of this constraint are intensely debated and a number of technical work-arounds are available.

As a developer integrating with the Mapfluence Javascript API, you can address this issue in one of several ways.

1. Use your existing cross-domain solution

If you already use a system to address this on your site, we recommend you use it. The operative paradigm would be:

var queryurl = new MF.SpatialQuery({...}).url()
// dispatch queryurl to your own framework
...

2. Proxy requests to Mapfluence APIs

If your security requirements trump latency, proxying is your only solution. With this approach, route all Mapfluence requests through a proxy on your host server. Note, you do not to need proxy tile requests.

You can easily change the endpoint to your proxy; e.g. if your proxy lives at: http://example.org/myproxy, modify the MF.Globals variable in javascript as follows.

<html>
<head>
...
<!-- first include the Mapfluence Javascript library -->
<script src="http://spatial.mapfluence.com/js/api.js?v=0.1&apikey=..." type="text/javascript"></script>
<!-- now override the global vars -->
<script type="text/javascript">
   MF.Globals.GEOQUERY_SERVER = 'example.org/myproxy';
   MF.Globals.METADATA_SERVER = 'example.org/myproxy';
</script>
...

3. Use an existing Javascript Library

If you use a common Javascript library such as jQuery, Dojo, Prototype, or ExtJS, the library already has - or someone has extend it to - support cross domain requests. If you use the solution provided by that library, the operative paradigm to make remote calls would be:

var queryurl = new MF.SpatialQuery({...}).url()
// dispatch queryurl to your own framework
// e.g. with PrototypeJS
new Ajax.Request(queryurl);

4. Use the Mapfluence Javascript Client Proxy

You can optionally use the Mapfluence Client Proxy. To do so, include the proxy.js file after the Mapfluence library. To setup and make remote calls, do the following:

<script src="http://api.mapfluence.com/js/api.js?v=0.1&apikey=123" type="text/javascript"></script>
<!-- Include the proxy library -->
<script src="http://api.mapfluence.com/js/proxy.js" type="text/javascript"></script>
<script type="text/javascript">
  ...
  // use the execute method on MF.*Query objects, e.g.
  new MF.SpatialQuery({...}).execute()
  ...
  // use the load method on MF.*Loader objects, e.g.
  new MF.Meta.TableColumnLoader({...}).load()
  ...

  // a random URL.
  MF.proxyRequest("http://...",my_callback);
</script>

The Mapfluence Proxy is built around flXHR which requires the client to support Flash. See flXHR for more details on browser compatibility, etc.

Important note on security

Because the Mapfluence Proxy uses Flash to perform the request, the host site must have a crossdomain.xml properly configured at the root.

For example, if you execute in javascript MF.proxyRequest("http://www.yahoo.com"), an error will be generated:

Error: 15
Type: securityError
Description: A security sandbox error occured with the flXHR request.
Source Object Id: MF.Proxy

This is because the Yahoo! crossdomain.xml file prevents access from random hosts.

If this is greek and you plan using the The Mapfluence Proxy, see cross domain for details.