4) APyaX Client-side API

To call a python function from JavaScript via APyaX:

  1. The python function must take a first parameter named "apyax". When the function is invoked, this parameter passes in an object with methods that expose the APyaX server-side API. Further positional parameters can be added as required by the function, of course. The functionality exposed by this object is

  2. Include the python script containing the function to be called in the page using the <script> tag. Set the type attribute to "text/python" and set the src attribute to point to the location of the python script relative to the page. You cannot place inline python code within the <script> tag.

  3. You can then invoke the python function from JavaScript. Pass in an apyax JavaScript object as the first parameter, followed by the parameters to be passed to the python function.

The apyax JavaScript object has the following methods:

function apyax(responseHandler,errorHandler)
function apyax(responseHandler,errorHandler)

Constructs an apyax object

Parameters
resultHandlera JavaScript function. If provided, this callback is invoked and passed the result returned from the remote execution of a python function.
errorHandlera JavaScript function. If provided, this callback is invoked and passed a string describing the error which occurs if the remote execution fails. For more details on the format of the error string, see the section Error Handling.
Return Value
a constructed apyax object

method apyax.setResponseHandler
apyax.prototype['setResponseHandler'] = function (handler)

apyax.setResponseHandler

method apyax.setResponseHandler

Parameters
handlerthe response handler to use to return the result of an apyax call

method apyax.getResponseHandler
apyax.prototype['getResponseHandler'] = function ()

apyax.getResponseHandler

method apyax.getResponseHandler

Return Value
the response handler to be used to return the result of an apyax call

method apyax.setErrorHandler
apyax.prototype['setErrorHandler'] = function (value)

apyax.setErrorHandler

method apyax.setErrorHandler

Parameters
handlerthe error handler to use to return error details if an apyax call fails

method apyax.getResponseHandler
apyax.prototype['getErrorHandler'] = function ()

apyax.getResponseHandler

method apyax.getResponseHandler

Return Value
the response handler to be used to return error details if an apyax call fails

method apyax.setSynchronous
apyax.prototype['setAsynchronous'] = function (flag)
Select synchronous or asynchronous mode for an APyaX call

In the default asynchronous mode, the call to the python function is dispatched to the server and the client function returns immediately. When the server completes the call, the result is passed back to the client and the JavaScript resultHandler or errorHandler callbacks (if provided in the constructor) are called, passing in the result value returned by the function or a string describing the error, respectively.

In synchronous mode the subsequent remote call to the python function is made synchronously (the client code waits for the server to execute the call) and the result is returned.

Parameters
flagtrue to select synchronous mode, false to select asynchronous mode

method apyax.isSynchronous
apyax.prototype['isAsynchronous'] = function (flag)

apyax.isSynchronous

method apyax.isSynchronous

Return Value
true if synchronous mode is selected, false if asynchronous mode is selected

Behind the scenes the parameter values to be passed over to the python function and the returned result are packed into an XMLHttpRequest request and response objects, using a method called JSON-RPC to encode objects (which can include arrays and dictionaries as well as numbers and strings) into text.