Construct 3 icon

Construct 3

Documentation

AJAX

Published 23 Aug, 2017
1,008 words
~4-7 mins

The AJAX plugin allows you to fetch the content of a URL, or post data to a website. You can also use it to load project files. Its name derives from "Asynchronous JavaScript and XML", a technique familiar to most web developers.

How to make a request

The basic usage of the AJAX object consists of:

  1. Use the Request action to load a URL.
  2. A moment later after the request completes, On completed triggers.
  3. The LastData expression can be used to access the content of the response.

The tokenat system expression may be useful to split simple responses. Alternatively, you can read LastData in other formats by using other plugins, such as the XML object, loading Array data, and so on.

Tags

A different tag can be provided for each request. This is a simple string you set to tell apart different requests. For example, on startup you may request both foo.json with tag "foo" and bar.json with tag "bar". When the first request completes, On "foo" completed triggers; when the second request completes, On "bar" completed triggers. Requests can complete in a different order to the order they were made, so without tags it would be impossible to tell which request was completing.

Making AJAX requests cross-domain or in preview

By default, browsers block AJAX requests across domains. This means, for example, a game on construct.net can request other pages on construct.net, but cannot request pages on facebook.com. This is an important security feature of web browsers (it is not specific to Construct or its AJAX object).

Also, when previewing in Construct the game runs on its own domain at preview.construct.net. Therefore AJAX requests to any other domain will typically fail during preview, unless the server explicitly allows cross-domain requests.

If you want AJAX requests to your server to work from any domain, or in preview, you can configure it to send the following HTTP header:

Access-Control-Allow-Origin: *

This will enable AJAX requests from any domain, but you should still be aware of the possible security implications of this. For more information on cross-domain requests see HTTP access control (CORS) on MDN.

In NW.js

When exporting desktop applications with NW.js, the AJAX object can also load files from the application folder. Simply use the Request URL action and enter the name of a file in the same directory as the application, e.g. "example.txt". Note if a project file exists with the same name, this will always load the project file instead.

MIME types

AJAX requests for files on your own server requires that your server has the correct MIME types set up.

AJAX conditions

On completed

Triggered when a request with the same tag has completed successfully. The LastData expression contains the response.

On any completed

Triggered when any request has completed successfully. The Tag expression identifies the request, and LastData contains the response.

On error

Triggered when a request with the same tag has failed. This can be for a number of reasons, such as the server being down or the request timing out. (The LastData expression is not set since there is no response.)

On any error

Triggered when any request has failed. The Tag expression identifies the request.

On progress

For long running requests (e.g. downloading a large file), On progress triggers periodically and updates the Progress expression with the state of the request. This is useful for making progress bars for AJAX requests.

AJAX actions

Override MIME type

In some cases you may wish to interpret the server's response with a different MIME type to the one the server indicates. For example a misconfigured server may return a text file with the wrong character set, and you want to force the response to be interpreted as UTF-8. In this case you could override the MIME type as text/plain; charset=utf-8 to avoid garbling the text. This action only applies to the next AJAX request that is made, after which the MIME type will be set back to the default setting of accepting what the server response indicates.

Post to URL

Send a request with data to a URL and retrieve the response. A tag is provided to match it up with the On completed, On progress and On error triggers. Construct does not automatically URL encode the post data - use the URLEncode system expression to ensure the data is in the correct format for posting. Note post data is in the same format as a query string, e.g. "foo=1&bar=2". The method can also be specified: by default it is POST, but for some APIs you may need to change this to PUT, DELETE or another HTTP method.

Request URL

Send a GET request to retrieve the contents of a URL. A tag is provided to match it up with the On completed, On progress and On error triggers.

Request project file

Request the contents of a project file. A tag is provided to match it up with the On completed, On progress and On error triggers.

Set request header

Set a HTTP header on the next AJAX request that is made. After the next AJAX request all the headers set with this action are cleared again, so it only takes effect once.

Set timeout

Set the amount of time a request has to complete in seconds; if the timeout expires without the request completing successfully, it will instead fail and trigger On error. This action only affects subsequent requests, and does not affect any requests that have already started. If the timeout is set to -1 it restores the default browser timeout.

AJAX expressions

LastData

The contents of the last response. This is set in the On completed trigger.

Progress

Return the progress of the AJAX request in an On progress event. The progress is represented as a number from 0 to 1, e.g. 0.5 for half completed.

Tag

The tag of the AJAX request in a trigger. This is useful to identify requests in On any completed or On any error.