From c26760b2c31c82f7ddbeff8062316475776dd261 Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 14 May 2024 16:52:02 -0500 Subject: [PATCH 1/4] add new pyweb.ui.elements section --- docs/user-guide/dom.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/user-guide/dom.md b/docs/user-guide/dom.md index 45ebc3a..1659693 100644 --- a/docs/user-guide/dom.md +++ b/docs/user-guide/dom.md @@ -272,6 +272,33 @@ The `ElementCollection` class currently supports the following attributes: * `html`: changes the `html` attribute on all the elements of a collection. * `value`: changes the `value` attribute on all the elements of a collection. + +## PyWeb.ui + +Pyweb.ui is a umbrella package that focused on providing access to the extensive +web APIs supported by the browser, with simpler, smaller and pythonic interface. + +### pyweb.ui.elements + +As mentioned in the above section about PyDom, the Standard Web APIs are massive +and not always very user-friendly. While `PyDom` focuses on querying and interacting +with existing elements in a web page, `pyweb.ui.elements` is a module focused +on providing a pythonic interface to create new elements on a web page. + +PyWeb is build on top of the foundation, provided by PyScript and PyDom, extending +it with features focused on creating and customizing new elements on a web page. +These elements are a subclass of pydom.Element and are fully compattible with the +pydom Element API. + + +!!! warning + + PyDom is currently a work in progress. + + We welcome feedback and suggestions. + + + ## Working with JavaScript There are three ways in which JavaScript can get into a web page. From 5bc1965102a847b4ab5d93454a0eef2a47a139ff Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 14 May 2024 16:52:30 -0500 Subject: [PATCH 2/4] add element creation section --- docs/user-guide/dom.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/user-guide/dom.md b/docs/user-guide/dom.md index 1659693..9aeafd7 100644 --- a/docs/user-guide/dom.md +++ b/docs/user-guide/dom.md @@ -298,6 +298,19 @@ pydom Element API. We welcome feedback and suggestions. +#### Creating a new element + +The element creation API provided by `pyweb.ui.elements` is focused on being simple +and idiomatic. In fact, to create an element simply instantiate the type of element +you need, providing all the properties supported by that element. Here's an example +of creating a new button with a custom style + +```python +# This will change the text of all H1 elements in the page +from pyweb.ui.elements import button +btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=True, style={margin: '5px'}) +``` + ## Working with JavaScript From 64f7ef479166a3606b4527e7e5668f0965eeabc0 Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 14 May 2024 16:53:21 -0500 Subject: [PATCH 3/4] add working with elements children section --- docs/user-guide/dom.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/user-guide/dom.md b/docs/user-guide/dom.md index 9aeafd7..147ea47 100644 --- a/docs/user-guide/dom.md +++ b/docs/user-guide/dom.md @@ -311,6 +311,24 @@ from pyweb.ui.elements import button btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=True, style={margin: '5px'}) ``` +#### Working with container elements + +Many elements are meant to be container elements and have children under them. +`pyweb.ui.elements` provides 2 mains ways to add children to an element: + + +##### specifing the children of an element during creation + +Elements that support children, like `div`, allow users to specify their children +elements during the `Element` creation. For instance, let's modify the example above +to create the button inside a div. + +```python +from pyweb.ui.elements import button +btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=True, style={margin: '5px'}) +page_div = div([button]) +``` + ## Working with JavaScript From f70304a342071b33a5746b9127141ddca391af5f Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 14 May 2024 16:53:59 -0500 Subject: [PATCH 4/4] more children manipulation and element event management --- docs/user-guide/dom.md | 49 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/user-guide/dom.md b/docs/user-guide/dom.md index 147ea47..c227627 100644 --- a/docs/user-guide/dom.md +++ b/docs/user-guide/dom.md @@ -316,6 +316,55 @@ btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=Tr Many elements are meant to be container elements and have children under them. `pyweb.ui.elements` provides 2 mains ways to add children to an element: +##### adding children to an element after creation + +Moving elements around and adding children to an elements is a very common use case. +It's possible to add new elements to an existing element by simply using the +`append` method. For instance, let's rewrite the example above to add the button to +the div after element creation and actually append the div to the body of the page. + +```python +# This will change the text of all H1 elements in the page +from pyweb import pydom +from pyweb.ui.elements import button + +btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=True, style={margin: '5px'}) +page_div = div() +page_div.append(btn_open_dialog) +pydom.body.append(page_div) +``` + +##### mapping elements to events + +As mentioned above, `pyweb.ui.elements` is built on top and fully compattible +with `pyscript` built-ins and `pydom`. For this reason, the best way to +attach event handlers to an element is to simply use the `@when` decorator +provided by `PyScript`. So, just like before, let's rewrite the example above +to change the background color of the button when the button is clicked. + + +```python +import random +from pyweb import pydom +from pyweb.ui.elements import button + +btn_open_dialog = button("Open Dialog", title='open dialog button', draggable=True, style={margin: '5px'}) +page_div = div() +page_div.append(btn_open_dialog) + +def random_color(): + """returns a random string representing and rgb color""" + rgbl=[255,0,0] + return tuple(random.shuffle(rgbl)) + +@when('click', btn_open_dialog) +def change_background_color(event=None): + # assign a random RGB color + btn_open_dialog.style['background-color'] = random_color() + +pydom.body.append(page_div) +``` + ##### specifing the children of an element during creation