more children manipulation and element event management

fpliger · fpliger · commit f70304a34207 · 2024-05-14T16:53:59.000-05:00
diff --git 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
 
