Browser interface
Brython-specific built-in modules
Working with Brython
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 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:
| Name | Type | Description | R = read only
R/W =
read + write |
| abs_left | integer | position of the element relatively to the document left border (1) | R |
| abs_top | integer | position of the element relatively to the document top border (1) | R |
| bind | method | event binding, see the section events | - |
| children | list | the element's children of type element (not text) |
R |
| child_nodes | list | the element's children of any type |
R |
| class_name | string | the name of the element's class (tag
attribute class) | R/W |
| clear | method | elt.clear() | - |
| 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. |
- |
| get | method | selects elements (cf access to elements) | - |
| height | integer | element height in pixels (2) | R/W |
| html | string | the 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.
| - |
| inside | method | elt.inside(other) tests if elt is
contained inside element other | - |
| left | integer | the position of the element relatively to
the left border of the first positioned parent (3) | R/W |
| parent | DOMNode instance | the 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 |
| select | method | elt.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 |
- |
| text | string | the text inside the element | R/W |
| top | integer | the position of the element relatively to
the upper border of the first positioned parent (3) | R/W |
| width | integer | element 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]
|
