Introduction

Installation

Limitations of the "file" protocol

Frequently asked questions

Syntax, keywords and built-in functions

Standard distribution

import implementation

Brython packages

Browser interface

Introduction - DOM API
Creating a document
Accessing elements
Attributes, properties and methods

Events
Mouse events
Keyboard events
Focus events
Drag events

Query string

Using Javascript objects and libraries

Brython-specific built-in modules

browser
browser.aio
browser.ajax
browser.html
browser.local_storage
browser.markdown
browser.object_storage
browser.session_storage
browser.svg
browser.template
browser.timer
browser.webcomponent
browser.websocket
browser.worker

Widgets
browser.widgets.dialog
browser.widgets.menu

interpreter
javascript

Working with Brython

Options of function brython()
Testing and debugging
Deploying an application

Cookbook

Hello world !
Insert content in an element
HTML markup (bold,italic...)
HTML table
Bind and unbind events
Handle options in a SELECT
Drag and drop
Get the content of an element
Read the content of a file
Store objects locally
Example of onmouseover
 

Elements attributes, properties and methods

DOM attributes and properties

The DOM defines two different concepts for elements :

  • attributes, which are defined in the HTML (or SVG) tag : for instance, <img src="icon.png"> defines the attribute src of the element created by the <img> tag
  • properties, that can be attached to an element by the dotted syntax : set by element.property_name = value, read by value = element.property_name

The DOM also defines a relation between some attributes and some properties:

  • generally, for the attributes that are expected for a given tag (eg "id" or "class" for any kind of tag, "src" for IMG tags, "href" for A tags, etc), when the attribute is set, the property is also set
  • most of the time, the property name is the same as the attribute name, but there are exceptions : the property for the attribute "class" is "className"
  • generally, the property value is the same as the attribute value, but not always : for instance, for an element defined by <INPUT type="checkbox" checked="checked">, the value of the attribute "checked" is the string "checked", and the value of the property "checked" is the boolean true

Besides the attributes defined by the specification for a given tag, custom attributes can be defined (template engines use this a lot) ; for these attributes, the property of the same name is not set. Custom properties can also be defined for an element, and this doesn't set the attribute of the same name.

Attribute values are always strings, while property values can be of any type.

Attributes are case-insensitive for HTML elements and case-sensitive for SVG elements ; properties are always case-sensitive.

Attributes and properties management in Brython

Brython manages DOM attributes with the attribute attrs of DOMNode instances ; it manages properties with the dotted syntax.

element.attrs is a dictionary-like object.

# set a value to an attribute
element.attrs[name] = value

# get an attribute value
value = element.attrs[name] # raises KeyError if element has no attribute
                            # "name"
value = element.attrs.get(name, default)

# test if an attribute is present
if name in element.attrs:
    ...

# remove an attribute
del element.attrs[name]

# iterate on the attributes of an element
for name in element.attrs:
    ...

for attr in element.attrs.keys():
    ...

for value in element.attrs.values():
    ...

for attr, value in element.attrs.items():
    ...

Brython-specific properties and methods

For convenience, Brython defines a few additional properties and methods:

NameTypeDescriptionR = read only
R/W = read + write
abs_leftintegerposition of the element relatively to the document left border (1)R
abs_topintegerposition of the element relatively to the document top border (1)R
bindmethodevent binding, see the section events-
childrenlistthe element's children in the document treeR
class_namestringthe name of the element's class (tag attribute class)R/W
clearmethodelt.clear() removes all the descendants of the element-
closest method elt.closest(tag_name) returns the first parent element of elt with the specified tag name. Raises KeyError if no element is found. -
getmethodselects elements (cf access to elements)-
heightintegerelement height in pixels (2)R/W
htmlstringthe HTML code inside the element R/W
index method elt.index([selector]) returns the index (an integer) of the element among its parent's children. If selector is specified, only the elements matching the CSS selector are taken into account ; in this case, if no element matches, the method returns -1. -
insidemethodelt.inside(other) tests if elt is contained inside element other-
leftintegerthe position of the element relatively to the left border of the first positioned parent (3)R/W
parentDOMNode instancethe element's parent (None for doc)R
scrolled_left integer position of the element relatively to the left border of the visible part of the document (1)L
scrolled_top entier position of the element relatively to the top border of the visible part of the document (1)L
selectmethodelt.select(css_selector) returns the elements matching the specified CSS selector-
select_one method elt.select_one(css_selector) returns the elements matching the specified CSS selector, otherwise None -
textstringthe text inside the elementR/W
topintegerthe position of the element relatively to the upper border of the first positioned parent (3)R/W
widthintegerelement width in pixels (2)R/W

(1) On page load, properties abs_left and scrolled_left of an element are the same, and the same for abs_top and scrolled_top. If the document is scrolled down by n pixels, abs_top always keeps the same value but scrolled_top is decremented by n

(2) Same as style.height and style.width but as integers.

(3) When going up the DOM tree, we stop at the first parent whose attribute style.position is set to a value different of "static". left and top are computed like style.left and style.top but are integers, not strings ending with px.

To add a child to an element, use the operator <= (think of it as a left arrow for assignment)

from browser import document, html
document['zone'] <= html.INPUT(Id="data")

Iterating on an element's children can be done using the usual Python syntax :

for child in element:
    ...

To destroy an element, use the keyword del

del document['zone']

The options collection associated with a SELECT object has an interface of a Python list :

  • access to an option by its index : option = elt.options[index]
  • insertion of an option at the index position : elt.options.insert(index,option)
  • insertion of an option at the end of the list : elt.options.append(option)
  • deleting an option : del elt.options[index]