New approach to configuring elements (#366)

docs/src/dom.md

@@ -27,7 +27,9 @@ attributes:
 {{#include ../../src/test/kotlin/kweb/docs/dom.kt:setattributes}}
 ```
 
-Attributes can also be specified in an `element` block:
+The created [Element](https://docs.kweb.io/api/kweb-core/kweb/-element/index.html) 
+is passed to the `{block}` as a parameter, which can be used to set attributes on the 
+element, add listeners, or set the element's text or innerHtml:
 
 ```kotlin
 {{#include ../../src/test/kotlin/kweb/docs/dom.kt:attr2}}
@@ -52,7 +54,6 @@ Alternatively we can use the `new {}` function to add children to a pre-existing
 
 ```kotlin
 {{#include ../../src/test/kotlin/kweb/docs/dom.kt:children_new}}
-
 ```
 
 ## Reading from the DOM

src/main/kotlin/kweb/Element.kt

@@ -685,19 +685,11 @@ open class Element(
  */
 fun <ELEMENT_TYPE : Element, RETURN_VALUE_TYPE> ELEMENT_TYPE.new(
     insertBefore: String? = null,
-    receiver: ElementCreator<ELEMENT_TYPE>.() -> RETURN_VALUE_TYPE
+    receiver: ElementCreator<ELEMENT_TYPE>.(ELEMENT_TYPE) -> RETURN_VALUE_TYPE
 )
         : RETURN_VALUE_TYPE {
     return receiver(
-        /**
-         * Returns an [ElementCreator] which can be used to create new elements and add them
-         * as children of the receiver element.
-         *
-         * @receiver This will be the parent element of any elements created with the returned
-         *           [ElementCreator]
-         * @Param position What position among the parent's children should the new element have?
-         */
-        ElementCreator(element = this, insertBefore = insertBefore)
+        ElementCreator(element = this, insertBefore = insertBefore), this
     )
 }
 

src/main/kotlin/kweb/ElementCreator.kt

@@ -57,7 +57,7 @@ open class ElementCreator<out PARENT_TYPE : Element>(
      * @param namespace If non-null elements will be created with [Document.createElementNS()](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS)
      *                  with the specified namespace. If null then Kweb will use [Document.createElement](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement).
      */
-    fun element(tag: String, attributes: Map<String, JsonPrimitive> = attr, namespace: String? = null, new: (ElementCreator<*>.() -> Unit)? = null): Element {
+    fun element(tag: String, attributes: Map<String, JsonPrimitive> = attr, namespace: String? = null, new: (ElementCreator<*>.(Element) -> Unit)? = null): Element {
 
         val mutAttributes = HashMap(attributes)
 
@@ -160,7 +160,7 @@ open class ElementCreator<out PARENT_TYPE : Element>(
         }
 
         if (new != null) {
-            newElement.new { new() }
+            newElement.new { new(newElement) }
         }
 
         return newElement
@@ -231,6 +231,9 @@ open class ElementCreator<out PARENT_TYPE : Element>(
     @Deprecated("Use element instead (as of v0.12.8)", ReplaceWith("element", "kweb.ElementCreator.element"))
     val parent get() = element
 
+    @Deprecated("div { element { set(\"foo\", \"bar\")} } ===> div { it.set(\"foo\", \"bar\") }",
+        ReplaceWith("receiver(element)")
+    )
     fun element(receiver : (PARENT_TYPE).() -> Unit) {
         receiver(element)
     }

src/main/kotlin/kweb/html/Document.kt

@@ -26,10 +26,10 @@ class Document(val receiver: WebBrowser) : EventGenerator<Document> {
 
     val body = BodyElement(receiver, "K_body")
 
-    fun body(new: (ElementCreator<BodyElement>.() -> Unit)? = null) : BodyElement {
+    fun body(new: (ElementCreator<BodyElement>.(BodyElement) -> Unit)? = null) : BodyElement {
         if (new != null) {
             val ec = ElementCreator(element = body, insertBefore = null)
-            new(ec)
+            new(ec, body)
             receiver.addCloseListener {
                 ec.cleanup()
             }
@@ -39,10 +39,10 @@ class Document(val receiver: WebBrowser) : EventGenerator<Document> {
 
     val head = HeadElement(receiver, "K_head")
 
-    fun head(new: (ElementCreator<HeadElement>.() -> Unit)? = null) : HeadElement {
+    fun head(new: (ElementCreator<HeadElement>.(HeadElement) -> Unit)? = null) : HeadElement {
         if (new != null) {
             val ec = ElementCreator(element = head, insertBefore = null)
-            new(ec)
+            new(ec, head)
             receiver.addCloseListener {
                 ec.cleanup()
             }