Using Javascript objects

We have to handle the transition period when Brython is going to coexist with
Javascript ;-)

Accessing Brython objects from Javascript

By default, Brython only exposes two names in the global Javascript namespace:

brython() : the function run on page load

__BRYTHON__ : an object used internally by Brython to store the objects
needed for scripts execution

Consequently, by default, a Javascript program cannot access Brython objects.
For instance, for a function echo() defined in a Brython script
to react to an event on an element in the page, instead of using the regular
javascript syntax:

<button onclick="echo()">

(because the brython function echo is not accessible from Javascript), the
solution is to set an id to the element:

<button id="mybutton">

and to define the link between this element and the event click by :

from browser import document
document['mybutton'].bind('click',echo)

Another option is to force the introduction of the name echo in the
Javascript namespace, by defining it as an attribute of the object
window in module browser :

from browser import window
window.echo = echo

NOTE: This method is not recommended, because it introduces a risk of
conflict with names defined in a Javascript program or library used in the page.

Objects in Javascript programs

An HTML document can use Javascript scripts or libraries, and Python scripts
or libraries

The names added by Javascript programs to the global Javascript namespace are
available in Brython scripts as attributes of the object window defined in
the module browser

Javascript objects are converted into their Python equivalent in this way :

Javascript object (js_obj)

Python object (window.js_obj)

DOM element

instance of DOMNode

DOM event

instance of DOMEvent

Collection of DOM elements

list of DOMNode instances

null, true, false

None, True, False

Integer

instance of int

Float

instance of float

String

instance of str

Array

instance of list

The other Javascript objects are converted into an instance of the class
JSObject defined in module javascript. They can be converted into
a Python dictionary by :

py_obj = window.js_obj.to_dict()

If the Javascript object is a function, the arguments passed to the Python
function are converted into Javascript objects, using the reverse of the
above table.

Take care, a Javascript function can't be called with keyword arguments, this
raises a TypeError exception : if the function is defined by

function foo(x, y)

and if it is called from a Brython script by

window.foo(y=0, x=1)

passing the arguments in the excepted order is not possible, because the
Brython script doesn't know the signature of the Javascript function.

Using Javascript constructors

If a Javascript function is an object constructor, that can be called in
Javascript code with the keyword new, it can be used in Brython using
the new special method added by Brython to the Javascript object.

Other examples

You will find in the gallery other examples
of how to use Javascript librairies (Three, Highcharts, Raphael) in Brython
scripts.

Integration of a Javascript library in a Python module

Another way to integrate a library is to create a Python module than can
be imported in scripts, without having to load this library in the script
page.

For that, the library must be accessible through an Ajax call? It is loaded
by the function load(url) of the browser module, and the
names that it adds to the global Javascript namespace are exposed in the
Python module.

For instance, we can create a module jquery:

from browser import window, load
load("/path/to/jquery.min.js")
# jQuery adds the name jQuery to the global Javascript namespace
# (also called $, but this is not a valid Python identifier)
jq = window.jQuery

We can then use this module in a Brython page (notice that we don't load
jquery.js):