Skip to content

Updating the page

Text, values, attributes, classes

document.set_text("title", f"Hello, {name}")              # plain text, safe for any string
document.set_value("email", "ada@example.org")            # input/textarea/select value
document.set_checked("remember", True)
document.set_attribute("save", "disabled", "")            # boolean attribute on
document.remove_attribute("save", "disabled")
document.set_attribute("bar", "style", "width:40%")       # inline style
document.add_class("row-4", "selected")
document.remove_class("row-4", "selected")

Read back with get_text, get_value, get_checked, and for attributes document.command("get_attribute", element="bar", name="style")["value"].

Prefer toggling classes and letting CSS do the work. For example, to filter a log by level, give each row its level as a class and switch one class on the container instead of re-rendering rows:

#log.min-WARN .DEBUG, #log.min-WARN .INFO { display: none; }
document.remove_class("log", "min-INFO"); document.add_class("log", "min-WARN")

The hidden attribute works too: set_attribute(id, "hidden", "") / remove_attribute(id, "hidden").

Render a list or table from data

Build markup with escaped values and replace the container's children:

import html

def render(items):
    rows = "".join(
        f'<li id="item-{item.id}"><span class="name">{html.escape(item.name)}</span>'
        f'<button id="item-{item.id}-delete">Delete</button></li>' for item in items)
    document.replace_html("items", rows or '<li class="empty">Nothing here</li>')

Re-rendering a list of a few hundred rows this way is simple and fast. Handlers delegated to the container (element="items") keep working. Table rows (<tr>) can be rendered into a <tbody id>. (data_table.py, process_viewer.py)

Screenshot: py-sdk-data_table

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Screenshot: py-sdk-process_viewer

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Keep accessibility attributes in step with the view, for example the sort state of a column header: {"op": "set_attribute", "element": "col-Name", "name": "aria-sort", "value": "ascending"}.

Append without re-rendering

document.insert_html("log", f'<div class="line">{html.escape(text)}</div>')   # position="beforeend"
document.insert_html("log", "<div>first</div>", position="afterbegin")

position is beforebegin, afterbegin, beforeend or afterend.

Batch several changes

document.batch([...]) applies up to 1024 operations in one round trip and one transaction: all are applied or none.

document.batch([
    {"op": "insert_html", "element": "log", "position": "beforeend", "html": rows},
    {"op": "trim_children", "element": "log", "keep": 500, "from": "start"},   # drop oldest rows
    {"op": "set_text", "element": "count", "text": f"{total} records"},
])

Batch ops: set_text, set_attribute, remove_attribute, add_class, remove_class, insert_html, replace_children_html, remove_element, move_element, append_text, trim_children. If one fails (say, an unknown id), the error names it and nothing changed.

A batch is also the way to keep related changes consistent. The counter example updates the number, two state classes and a bounded history in one transaction (counter.py):

Screenshot: py-sdk-counter

Real capture on KDE Plasma 6.6 Wayland with the released packages.

document.batch([
    {"op": "set_text", "element": "value", "text": str(value)},
    {"op": "add_class" if value < 0 else "remove_class", "element": "value", "name": "negative"},
    {"op": "insert_html", "element": "history", "position": "afterbegin",
     "html": f"<li>{html.escape(f'{reason} -> {value}')}</li>"},
    {"op": "trim_children", "element": "history", "keep": 8, "from": "end"},   # drop the oldest
])

trim_children keeps keep children and removes the rest from the start or the end.

Elements without ids

Use nodes:

first_item = document.node(reference=document.query_nodes("#menu li")["nodes"][0]["node"])
first_item.add_class("active")
document.node("menu").trim_children(10)          # keep the 10 newest children

(dom_explorer.py)

Screenshot: py-sdk-dom_explorer

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Counting and finding

document.query_nodes(".line.ERROR")["total"]     # number of matches
document.query("#todos li")["ids"]                # ids of matching elements that have one
document.command("has_element", element="todo-3")["exists"]

Styles at run time

sheet = document.add_stylesheet(":root { --accent: #c2410c; }")["sheet"]
document.replace_stylesheet(sheet, ":root { --accent: #2563eb; }")
document.computed_style(["color", "display"], "status")["properties"]["display"]["value"]
document.set_environment(color_scheme="dark")      # drives @media (prefers-color-scheme: dark)

Scrolling

document.scroll_into_view("row-120", block="center")
document.command("set_scroll_follow", element="log", follow=True)   # stay at the end as rows arrive
document.scroll_to(y=0)

Loading a whole new page

window.load_html(html) / window.load_file(path) replaces the document. The previous Document, its nodes and subscriptions become stale: register handlers again on the new window.document. Inline HTML is limited to 1 MiB; keep large content in files or render it in pages.


Source: nativehtmlkit-python/docs/guides/updating-the-page.md ยท edit the page there.