idom 0.4.0

Control the web with Python

iDOM

Libraries for creating and controlling interactive web pages with Python 3.6 and above.

• Python Documentation
• Javascript Documentation

iDOM is still young. If you have ideas or find a bug, be sure to post an issue or create a pull request. Thanks in advance!

Try it Now

Click the badge above to get started! It will take you to a Jupyter Notebooks hosted by Binder with some great examples.

Or Install it Now

pip install idom

At a Glance

iDOM can be used to create a simple slideshow which changes whenever a user clicks an image.

import idom

@idom.element
async def Slideshow(self, index=0):
    events = idom.Events()

    @events.on("click")
    async def change():
        self.update(index + 1)

    url = f"https://picsum.photos/800/300?image={index}"
    return idom.node("img", src=url, eventHandlers=events)

server = idom.server.sanic.PerClientState(Slideshow)
server.daemon("localhost", 8765).join()

Running this will serve our slideshow to "https://localhost:8765/client/index.html"

You could even display the same thing in a Jupyter notebook!

idom.display("jupyter", "https://localhost:8765/stream")

Every click will then cause the image to change (it won't here of course).

Breaking it Down

That might have been a bit much to throw out at once. Let's break down each piece of the example above:

@idom.element
async def Slideshow(self, index=0):

The idom.element decorator indicates that the asynchronous function to follow returns a data structure which represents a user interface or Document Object Model (DOM). We call this structural representation of the DOM a [Virtual DOM] (VDOM) - a term familiar to those who work with ReactJS. In the case of Slideshow it will return a VDOM representing an image which, when clicked, will change.

    events = idom.Events()

Events creates an object to which event handlers will be assigned. Adding an Events object to a VDOM will given you the ability to respond when users interact with you interface. Under the hood though, Events is just a mapping that conforms to the VDOM event specification.

    @events.on("click")
    def change():
        self.update(index + 1)

By using the Events object we created above, we can register a function as an event handler. In this case our handler is listening for onClick events and will be called once a user clicks on the image. All supported events are listed here.

You can add parameters to this handler which will allow you to access attributes of the JavaScript event which occurred in the browser. For example when a key is pressed in an <input/> element you can access the key's name by adding a key parameter to the event handler.

Inside the handler itself we update self which is out Slideshow element. Calling self.update(*args, **kwargs) will schedule a new render of the Slideshow element to be performed with new *args and **kwargs.

    url = f"https://picsum.photos/800/300?image={index}"
    return idom.node("img", src=url, eventHandlers=events)

We return a VDOM for an <img/> element which draws its image from https://picsum.photos and will respond to the events we defined earlier. Similarly to the events object idom.node returns a mapping which conforms to the VDOM mimetype specification

server = idom.server.sanic.PerClientState(Slideshow)
server.daemon("localhost", 8765).join()

This sets up a simple web server which will display the layout of elements and update them when events occur over a websocket. The server has "per client state" because each client that connects to it will see a fresh view of the layout. If clients should see views with a common state you can use the SharedClientState server.

To display the layout we can navigate to http://localhost:8765/client/index.html or use idom.display() to show it in a Jupyter Notebook via a widget. The exact protocol for communicating VDOM over a network is not documented yet.

Adding iDOM To Existing Applications

If you want to add iDOM to an existing server you can register its routes instead:

from sanic import Sanic

app = Sanic()
extension = idom.server.sanic.PerClientState(Slideshow)
extension.configure(url_prefix="/idom").register(app)

app.run()