Using JavaScript

Note

JavaScript support is new in version 4.1. Embedded Python support is new in version 4.19. Make sure you are using the latest version of TkinterWeb.

Overview

Scripting support makes it easy to embed JavaScript or Python code in your document.

JavaScript is fully supported through Mozilla’s SpiderMonkey engine, but not all DOM commands are supported. See the Document Object Model Documentation for an exhaustive list of supported DOM commands.

Setup

To enable JavaScript support in TkinterWeb, first install PythonMonkey using pip:

$ pip install pythonmonkey

Skip this step if you are embedding Python code in your document.

Or when installing TkinterWeb, use:

$ pip install tkinterweb[javascript]

Then add yourhtmlframe.configure(javascript_enabled=True) to your script or add the parameter javascript_enabled=True when creating your HtmlFrame, HtmlLabel, or HtmlText widget.

Only enable JavaScript in documents with code you know and trust.

How-to

To change the color and text of a <p> element when clicked, you could use the following:

yourhtmlframe = tkinterweb.HtmlFrame(root, messages_enabled=True, javascript_enabled=True)
yourhtmlframe.load_html("""
    <script>
    function changeColor(element) {
        element.style.color = "blue"
        element.textContent = "I've been clicked!"
    }
    </script>
    <div id='container'><p onclick="changeColor(this)">Hello, world!</p></div>
    """)

Add the defer attribute to the relevant <script> element if you want it to run after the page loads. Otherwise, the script will be executed as soon as it is encountered in the document.

The following JavaScript event attributes are supported: onchange, onload, onclick, oncontextmenu, ondblclick, onmousedown, onmouseenter, onmouseleave, onmousemove, onmouseout, onmouseover, and onmouseup.

Tip

As of version 4.25, it is highly recommended to enable debug messages (i.e. via HtmlFrame(root, messages_enabled=True, ...)) when testing new scripts. Otherwise, if a script fails it will fail silently.

Embedding Python in your document

To run embedded scripts as Python code instead of JavaScript, simply use the parameters javascript_enabled=True and javascript_backend="python" when creating your HTML widget. Ensure you are running code you trust.

Like normal JavaScript code, by default scripts can access the document property and inline event callbacks can also access the this property. You will need to register new objects if you want the document’s scripts to be able to access other functions, classes or variables.

That’s it!

Registering new objects

To register new objects, use JSEngine.register(). This gives the document’s scripts access to Python objects. This, for instance, can be used to implement a window API or to add a callback for the JavaScript alert() function:

yourhtmlframe = tkinterweb.HtmlFrame(root, messages_enabled=True, javascript_enabled=True)
def open_alert_window(text):
    ## Do stuff
yourhtmlframe.javascript.register("alert", open_alert_window)
yourhtmlframe.load_html("<script>alert('Hello, world!')</script><p>Hello, world!</p>")

Using your own interpreter

Alternatively, you can register your own callback for <script> elements using the on_script parameter:

yourhtmlframe = tkinterweb.HtmlFrame(root, messages_enabled=True)
def handle_scripts(attributes, tagcontents):
    ## Do stuff
yourhtmlframe.configure(javascript_enabled=True, on_script=handle_scripts)
yourhtmlframe.load_html("<div id='container'><script>// Do stuff</script><p>Test</p></div>")

You can also use the on_element_script parameter to handle event scripts (i.e. handle an element’s onclick attribute). The element’s corresponding Tkhtml node, relevant event, and code to execute will be passed as parameters.

If needed you can always then create an HTMLElement instance from a Tkhtml node:

from tkinterweb.dom import HTMLElement
...
yourhtmlelement = HTMLElement(yourhtmlframe.document, yourtkhtmlnode)

---

It is also possible to interact with the document through Python instead. See Manipulating the Page.

Please report bugs or request new features on the issues page.