.. _clientjs: The Javascript Client ===================== The Pico Javascript client makes it simple to call your API from a web application. The client automatically generates proxy module objects and functions for your API so you can call your API functions just like any other library functions. All serialisation of arguments and deserialisation of responses is taken care of by the client so you can focus on your application logic. The only thing you need to be aware of is that all function calls are asynchronous returning promises. Basic Structure --------------- The basic structure of a web app using the Pico Javascript client is as follows: .. code-block:: html :linenos: :emphasize-lines: 6,8,13,15-18 Pico Example

* Line 6: We include Pico's ``pico.js`` library inside the `head` of the document. * Line 8: We load our ``example`` module definition as JavaScript in the `head`. * Line 13: In a `script` element in the `body` we import our ``example`` module assigning it to the ``example`` variable. * Line 15: We use our ``hello`` function. * Line 16-18: We assign a callback to the ``promise``. The order and position of these elements within the document is important. `pico.js` must always be loaded before the module is loaded and these both must be in the `head` of the document to ensure they have completed by the time they are used later. Promises -------- The proxy functions generated by the client are asynchronous, meaning that they will not wait for the result before returning. This is due to the nature of how HTTP requests work in the browser. Instead they immediately return a ``promise`` which later resolves and calls a callback with the result as a parameter. The ``promise`` object has two methods of interest: ``then`` and ``catch``. .. code-block:: js var p = example.hello('world') p.then(function(result){ console.log(result) }) p.catch(function(err){ console.error(err) }) The callback function passed to ``.then`` is called when the promise resolves successfully. If an error occurs then the function passed to ``.catch`` is called. If you don't set a catch callback any errors are ignored. The ``error`` object passed to ``catch`` callback contains a ``.message`` and ``.code`` property which describe the exception that occurred on the Python side and the relevant HTTP status code. API --- Asynchronous functions ^^^^^^^^^^^^^^^^^^^^^^ Each of these functions is asynchronous, so they return a `Promise`. .. js:function:: pico.loadAsync(module) :param string module: The name of the module to load. Load the Python module named `module`. The module proxy will be passed to the promise callback. Submodules may be loaded by using dotted notation e.g. `module.sub_module`. .. js:function:: pico.reload(module_proxy) :param object module_proxy: The module to reload. Reload the module definition and recreate the module proxy for the supplied `module_proxy` object. Note that `module_proxy` is a module proxy object, not a string. Synchronous functions ^^^^^^^^^^^^^^^^^^^^^ .. js:function:: pico.importModule(module) :param string module: The name of the module to import. :returns: the proxy module object. Note the module definition must have been previously loaded using ``pico.loadAsync`` or by loading ``/.js`` in a `script` tag in the `head` of the document. .. js:function:: pico.loadModuleDefinition(module_definition) :param object module_definition: An object representing the definition of the module. :returns: the proxy module object. This function creates a proxy module from the given definition and stores it in the internal module registry for later import with `pico.importModule`. It also returns the proxy module directly. This function is called internally by the ``/.js`` loading mechanism. .. js:function:: pico.help(proxy_object) :param object proxy_object: The function or module proxy you want help for. :returns: the docstring of a proxy module or function.