Introduction

Installation

Frequently asked questions

Syntax, keywords and built-in functions

Standard distribution

import implementation

Browser interface

Brython-specific built-in modules

Working with Brython

Brython for Firefox OS

Cookbook

 

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 attribute "checked" is "checked", and the value of property "checked" is the boolean "true".

Besides the attributes defined by the specification for a given tag, custom attributes can be defined (template engine 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 window left borderR
abs_topintegerposition of the element relatively to the window top borderR
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 (1)R/W
parentDOMNode instancethe element's parent (None for doc)R
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 (1)R/W
widthintegerelement width in pixels (2)R/W

(1) 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 integer, not strings ending with px.

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

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

zone = document['zone']
del 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]