doc/source/reference/javascript.rst
.. _js:
JavaScript
----------
:description: Use authomatic.js to run the login procedure in a centered popup and to delegate most of the work from your server to browser.
The ``authomatic.js`` library is here to make your life even easier.
It has a very tiny interface similar to it's Python sibling.
Yo can use it to:
* Process the *login procedure* in a popup window.
* Access **protected resources** in the most efficient way without any hassle.
.. warning::
The library is dependent on |jquery|_!
.. _js_setup:
.. js:function:: authomatic.setup(options)
Sets up all the library's options.
:param object options:
An object of following options:
.. js:attribute:: options.logging
:js:data:`bool` If ``true`` the library will log a lot of information to the console.
Popup options:
.. js:attribute:: options.popupWidth
:js:data:`int` The width of the popup in pixels. Default is ``800``.
.. js:attribute:: options.popupHeight
:js:data:`int` The height of the popup in pixels. Default is ``600``.
.. js:attribute:: options.popupLinkSelector
:js:data:`string` A |jquery| selector specifying links that should be affected by
:js:func:`.authomatic.popupInit`. Default is ``'a.authomatic'``.
.. js:attribute:: options.popupFormSelector
:js:data:`string` A |jquery| selector specifying forms that should be affected by
:js:func:`.authomatic.popupInit`. Default is ``'form.authomatic'``.
.. js:attribute:: options.popupFormValidator
:js:data:`function` A function which you can use to validate the form before the popup opens.
It accepts the |jquery| selected form. The popup gets opened only if it returns ``true``.
Callbacks:
.. js:attribute:: options.onPopupInvalid
:js:data:`function` Called when the popup form doesn't pass validation.
Accepts the form selected with |jquery| as the only argument.
.. js:attribute:: options.onPopupOpen
:js:data:`function` Called when the popup gets open.
Accepts the popup location URL as the only argument.
.. js:attribute:: options.onLoginComplete
:js:data:`function` Called when the popup gets closed after the login procedure is complete.
Accepts the :js:data:`.loginResult` object as the only argument.
.. _js_popup_init:
.. js:function:: authomatic.popupInit
If you call this function, all ``<a></a>`` and ``<form></form>`` elements with ``class="authomatic"``
will open a popup on click/submit. By links the location of the popup will be the value of ``href`` attribute,
by forms the value of ``action`` attribute with query string extracted from the form inputs.
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<title>Login Popup Example<title>
<!-- authomatic.js is dependent on jQuery -->
<script type="text/javascript" src="https://code.jquery.com/jquery-1.9.1.min.js"></script>
<script type="text/javascript" src="authomatic.js"></script>
</head>
<body>
<!-- Opens a popup with location = "login/facebook" -->
<a class="authomatic" href="login/facebook">Login with Facebook</a>
<!-- Opens a popup with location = "login/openid?id=me.yahoo.com" -->
<form class="authomatic" action="login/openid" method="GET">
<input type="text" name="id" value="me.yahoo.com" />
<input type="submit" value="Login with OpenID" />
</form>
<script type="text/javascript">
authomatic.popupInit();
</script>
</body>
</html>
.. _js_access:
.. js:function:: authomatic.access(credentials, url[, options])
Makes an asynchronous request to **protected resource** of a **user**.
Under the hood it tries to make the request as efficiently as possible
with the aim to save your backend's resources:
* By |oauth2|_ providers:
#. First a *cross-domain* XHR request is attempted.
#. If that fails it continues either with:
* A *JSONP* XHR request but only if the provider supports it and the request method is ``'GET'``
* Otherwise it will fetch the provider through backend.
* By |oauth1|_ providers the request must be signed using the **consumer secret** which cannot
be exposed in the client, so every request goes first to the backend.
Depending on provider the backend either:
* Fetches the provider and returns the result of the fetch.
* Returns signed *request elements* with which a *JSONP* XHR request is made.
:param string credentials:
Serialized :class:`.Credentials` of the **user**.
:param string url:
URL of the **protected resource**. Can include querystring and template tags in the form of
``https://example.com/api/{user.id}/profile``.
:param object options:
An object of following options.
.. note::
You can also specify all of these options in the :js:func:`.authomatic.setup`.
Values specified here will override the values specified in :js:func:`.authomatic.setup`
with the exception of callbacks.
.. js:attribute:: options.backend
:js:data:`string` URL of your *login handler*, or the handler where you call the
:meth:`.Authomatic.backend` function.
.. warning::
This parameter is required by all |oauth1| providers
and also by some |oauth2| providers.
.. js:attribute:: options.forceBackend
:js:data:`bool` If `true` requests will be fetched through backend by all **providers**.
.. js:attribute:: options.substitute
:js:data:`object` An object which will be used to replace template tags inside the :js:data:`URL`.
e.g. URL ``https://example.com/api/{user.id}/profile`` by substitute ``{user: {id: '123'}}``
will be rendered as ``https://example.com/api/123/profile``.
.. js:attribute:: options.params
:js:data:`object` The query parameters of the request.
.. js:attribute:: options.headers
:js:data:`object` The HTTP headers of the request.
.. js:attribute:: options.body
:js:data:`string` The body of the request.
.. js:attribute:: options.jsonpCallbackPrefix
:js:data:`string` Some providers don't support cross-domain requests.
In such case the function tries a *JSONP* request and will generate a temporary callback
in the global namespace with the name ``'authomaticJsonpCallback#'`` where ``#`` is an
integer unique for every callback. You can change the default ``'authomaticJsonpCallback'``
to whatever you want by specifying it in this option.
Callbacks:
.. warning::
Callbacks specified in :js:func:`.authomatic.setup` will not be overridden by
those specified here, but both will be called, whereas those specified in
:js:func:`.authomatic.setup` will be called first.
.. js:attribute:: options.onBackendStart
:js:data:`function` Called when :js:func:`.authomatic.access` contacts backend.
Accepts a object of parameters which will be sent to the backend as the only argument.
.. js:attribute:: options.onBackendComplete
:js:data:`function` Called when response returns from backend.
Accepts ``data``, ``textStatus`` and ``jqXHR`` as arguments in the specified order.
.. js:attribute:: options.onAccessSuccess
:js:data:`function` Called when a successful response returns from **provider**.
Accepts ``data``, ``textStatus`` and ``jqXHR`` as arguments in the specified order.
.. js:attribute:: options.onAccessComplete
:js:data:`function` Called when any response returns from **provider**.
Accepts ``textStatus`` and ``jqXHR`` as arguments in the specified order.