mirror of
https://github.com/pyscript/pyscript.git
synced 2026-02-12 22:00:56 -05:00
Add Element to the API reference (#998)
This commit is contained in:
Fábio Rosado
309
docs/reference/API/element.md
Normal file
309
docs/reference/API/element.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# `Element`
|
||||
|
||||
The `Element` API is a helpful way to create and manipulate elements in the DOM. It is a wrapper around the native DOM API, and is designed to be as intuitive as possible.
|
||||
|
||||
## Methods and Properties
|
||||
|
||||
| Property | Description |
|
||||
|----------|-----------------------------------------|
|
||||
| `element` | Returns the element with the given ID. |
|
||||
| `id` | Returns the element's ID. |
|
||||
| `value` | Returns the element's value. |
|
||||
| `innerHtml` | Returns the element's inner HTML. |
|
||||
|
||||
|
||||
|
||||
| Method | Description |
|
||||
|----------------------|--------------------------------------------------------------|
|
||||
| `write` | Writes `value` to element and handles various mime types. `append` defaults to `False`, if set to true, it will create a child element. |
|
||||
| `clear` | Clears the element's value or content. |
|
||||
| `select` | Select element from `query` which uses [Document.querySelector()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector). |
|
||||
| `clone` | Clones the with `new_id` if provided and `to` element if provided. |
|
||||
| `remove_class` | Removes one or more class name from the element. |
|
||||
| `add_class` | Adds one or more class name to the element. |
|
||||
|
||||
## Element.element
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-----------|---------|------|
|
||||
| | | |
|
||||
|
||||
The `element` property returns the DOM element with the given ID.
|
||||
|
||||
```html
|
||||
from pyscript import Element
|
||||
|
||||
my_div = Element('my-div')
|
||||
print(my_div.element)
|
||||
```
|
||||
|
||||
## Element.id
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-----------|---------|------|
|
||||
| | | |
|
||||
|
||||
Return the element's ID.
|
||||
|
||||
```html
|
||||
|
||||
<div id="my-div"></div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
my_div = Element('my-div')
|
||||
print(my_div.id) # prints 'my-div'
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.value
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-----------|---------|------|
|
||||
| | | |
|
||||
|
||||
Return the element's value.
|
||||
|
||||
```html
|
||||
<input id="my-input" value="hello world"></input>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
my_input = Element('my-input')
|
||||
print(my_input.value) # prints 'hello world'
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.innerHtml
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-----------|---------|------|
|
||||
| | | |
|
||||
|
||||
Return the element's inner HTML.
|
||||
|
||||
```html
|
||||
<div id="my-innerHtml">
|
||||
<b>hello world</b>
|
||||
</div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
my_innerHtml = Element('my-innerHtml')
|
||||
print(my_innerHtml.innerHtml) # prints <b> hello world </b>
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.write
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-------------|---------|-----------------------------|
|
||||
| `value` | | `str` or `__mime_type__` |
|
||||
| `append` | False | `bool` |
|
||||
|
||||
Writes `value` to element and handles various mime types. This method also contains a `append` parameter, which defaults to `False`.
|
||||
|
||||
Currently, these are the MIME types that are supported when rendering content using this method
|
||||
|
||||
| Method | Inferred MIME type |
|
||||
|---------------------|------------------------|
|
||||
| `__repr__` | text/plain |
|
||||
| `_repr_html_` | text/html |
|
||||
| `_repr_svg_` | image/svg+xml |
|
||||
| `_repr_png_` | image/png* |
|
||||
| `_repr_pdf_` | application/pdf |
|
||||
| `_repr_jpeg_` | image/jpeg* |
|
||||
| `_repr_json_` | application/json |
|
||||
| `_repr_javascript_` | application/javascript*|
|
||||
| `savefig` | image/png |
|
||||
|
||||
```html
|
||||
<div id="foo"></div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.write("Hello!")
|
||||
el.write("World!") # will replace the previous content
|
||||
</py-script>
|
||||
```
|
||||
|
||||
If we set `append` to `True`, it will create a child element using a `div`.
|
||||
|
||||
```html
|
||||
<div id="foo"></div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.write("Hello!", append=True)
|
||||
|
||||
# This will create a child div with the id "foo-1"
|
||||
el.write("World!", append=True)
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.clear
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-----------|---------|------|
|
||||
| | | |
|
||||
|
||||
Clears the element's value or content. For example, we can clear the value of an input element.
|
||||
|
||||
```html
|
||||
<input id="foo" value="Hello!"></input>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.clear() # Removes value from input
|
||||
</py-script>
|
||||
```
|
||||
|
||||
Or we can clear the content of a div element.
|
||||
|
||||
```html
|
||||
<div id="foo">Hello!</div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.clear() # Removes Hello from div content
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.select
|
||||
|
||||
Select element from `query`, it will look into the main Element if `from_content` is `True`. This method is a wrapper of [Document.querySelector()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
|
||||
|
||||
```html
|
||||
<div id="foo">
|
||||
<div id="bar"></div>
|
||||
</div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
bar = el.select("#bar")
|
||||
print(bar.id) # prints 'bar'
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.clone
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-------------|---------|-----------|
|
||||
| `new_id` | None | `str` |
|
||||
| `to` | None | `Element` |
|
||||
|
||||
Clones the element to a new element. You can provide `new_id` to set a different id to the cloned element. You can also use a `to` element to append the cloned element to.
|
||||
|
||||
```html
|
||||
<div id="foo">
|
||||
HI!
|
||||
</div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
el = Element("foo")
|
||||
# Creates two divs with the id "foo" and content "HI!"
|
||||
el.clone()
|
||||
</py-script>
|
||||
```
|
||||
|
||||
It's always a good idea to pass a new id to the element you are cloning to avoid confusion if you need to reference the element by id again.
|
||||
|
||||
```html
|
||||
<div id="foo">Hello!</div>
|
||||
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
# Clones foo and its contents, but uses the id 'bar'
|
||||
el.clone(new_id="bar")
|
||||
</py-script>
|
||||
```
|
||||
|
||||
You can also clone an element into another element.
|
||||
|
||||
```html
|
||||
<div id="bond">
|
||||
Bond
|
||||
</div>
|
||||
<div id="james">
|
||||
James
|
||||
</div>
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
bond_div = Element("bond")
|
||||
james_div = Element("james")
|
||||
|
||||
bond_div.clone(new_id="bond-2", to=james_div)
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.remove_class
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-------------|---------|-----------------------|
|
||||
| `classname` | None | `str` or `List[str]` |
|
||||
|
||||
Removes one or more class names from the element.
|
||||
|
||||
```html
|
||||
<div id="foo" class="bar baz"></div>
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
el = Element("foo")
|
||||
el.remove_class("bar")
|
||||
</py-script>
|
||||
```
|
||||
|
||||
You can also remove multiple classes by passing a list of strings.
|
||||
|
||||
```html
|
||||
<div id="foo" class="bar baz"></div>
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
|
||||
el = Element("foo")
|
||||
el.remove_class(["bar", "baz"]) # Remove all classes from element
|
||||
</py-script>
|
||||
```
|
||||
|
||||
## Element.add_class
|
||||
|
||||
| Parameter | Default | Type |
|
||||
|-------------|---------|-----------------------|
|
||||
| `classname` | None | `str` or `List[str]` |
|
||||
|
||||
Adds one or more class names to the element.
|
||||
|
||||
```html
|
||||
<style> .red { color: red; } </style>
|
||||
<div id="foo">Hi!</div>
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.add_class("red")
|
||||
</py-script>
|
||||
```
|
||||
|
||||
You can also add multiple classes at once by passing a list of strings.
|
||||
|
||||
```html
|
||||
<style> .red { color: red; } .bold { font-weight: bold; } </style>
|
||||
<div id="foo">Hi!</div>
|
||||
<py-script>
|
||||
from pyscript import Element
|
||||
el = Element("foo")
|
||||
el.add_class(["red", "bold"])
|
||||
</py-script>
|
||||
```
|
||||
Reference in New Issue
Block a user