misc stuff

build.gradle

@@ -11,8 +11,8 @@ allprojects {
 }
 
 buildscript {
-    ext.kotlin_version = '1.2.51'
-    ext.dokka_version = '0.9.15'
+    ext.kotlin_version = '1.2.60'
+    ext.dokka_version = '0.9.17'
     ext.ktor_version = '0.9.3'
 
     repositories {
@@ -35,7 +35,7 @@ buildscript {
 }
 
 group 'io.kweb'
-version '0.3.3'
+version '0.3.5'
 
 apply plugin: 'java'
 

src/main/kotlin/io/kweb/demos/todo/todoApp.kt

@@ -38,9 +38,11 @@ fun main(args: Array<String>) {
 
                 /** A KVar is similar to an AtomicReference in the standard Java
                     Library, but which supports the observer pattern and `map`
-                    semantics.  Here I set it to the current URL of the page.  This
-                    will update automatically the page's URL changes, and can be
-                    modified to update the page's URL, as you'll see below. */
+                    semantics.  Here I set it to the current URL of the page.
+
+                    This will update automatically if the page's URL changes, and
+                    if it is modified, the page's URL will change and the DOM will
+                    re-render _without_ a page reload.  Yes, seriously. */
                 val url: KVar<URL> = doc.receiver.url(simpleUrlParser)
 
                 /** s.content uses the semanticUIPlugin to use the excellent
@@ -67,7 +69,7 @@ fun main(args: Array<String>) {
                                     specific part of the page must be re-rendered if
                                     url.path[1] changes, which is very convenient
                                     for the developer in comparison to other frameworks,
-                                    while being efficient under-the-hood. */
+                                    while minimizing server-browser chatter. */
                                 render(url.path[1]) { listId ->
                                     try {
                                         /** Here I use the same render mechanism to tie DOM

src/main/kotlin/io/kweb/dom/element/events/ONImmediateReceiver.kt

@@ -6,6 +6,21 @@ import java.util.concurrent.ConcurrentHashMap
 import kotlin.reflect.KClass
 import kotlin.reflect.full.memberProperties
 
+/**s
+ * *Warning:* Do not use this before familiarizing yourself with the information below.
+ *
+ * Pro:
+ *   * Executes immediately, without any need for a server round-trip
+ * Con:
+ *   * What you can do in the callback shouldn't rely on and _certainly_ shouldn't modify any server-side state.  It's
+ *     use should probably be limited to cosmetic UI cues like spinners.  If you do the results could be very
+ *     unpredictable, and may cause bugs that are difficult to diagnose.
+ *
+ *     The reason is that the callback is actually only executed once.  Any instructions to the browser are recorded
+ *     and will simply be re-executed by the browser whenever this event occurs.  This neat trick is how we avoid
+ *     a server round-trip, but the price is additional caution about how we use it.
+ */
+
 @KWebDSL
 open class ONImmediateReceiver(internal val parent: Element) : Element(parent) {
 

src/main/kotlin/io/kweb/dom/element/events/on.kt

@@ -6,7 +6,30 @@ import io.kweb.dom.element.Element
  * Created by ian on 1/13/17.
  */
 
-
+/**
+ * Add an event callback to the `Element` that will be triggered on the server.
+ *
+ * Pro:
+ *   * Can do anything it wishes in the callback, including modifying server state.
+ * Con:
+ *   * Slight delay due to server-round trip for any DOM modifications in response to the event
+ */
 val Element.on: ONReceiver get() = ONReceiver(this)
 
+/**
+ * Add an event callback to the `Element` that will be triggered within the browser.
+ *
+ * *Warning:* Do not use this before familiarizing yourself with the information below.
+ *
+ * Pro:
+ *   * Executes immediately, without any need for a server round-trip
+ * Con:
+ *   * What you can do in the callback shouldn't rely on and _certainly_ shouldn't modify any server-side state.  It's
+ *     use should probably be limited to cosmetic UI cues like spinners.  If you do the results could be very
+ *     unpredictable, and may cause bugs that are difficult to diagnose.
+ *
+ *     The reason is that the callback is actually only executed once.  Any instructions to the browser are recorded
+ *     and will simply be re-executed by the browser whenever this event occurs.  This neat trick is how we avoid
+ *     a server round-trip, but the price is additional caution about how we use it.
+ */
 val Element.onImmediate : ONImmediateReceiver get() = ONImmediateReceiver(this)

src/main/kotlin/io/kweb/plugins/semanticUI/SemanticUIClasses.kt

@@ -166,6 +166,11 @@ class SemanticUIClasses : AttributeBuilder() {
         return this
     }
 
+    val copy : SemanticUIClasses get() {
+        classes("copy")
+        return this
+    }
+
     val column : SemanticUIClasses get() {
         classes("column")
         return this

src/main/kotlin/io/kweb/state/state.kt

@@ -42,6 +42,8 @@ open class KVal<T : Any?>(value: T) {
         listeners.remove(handle)
     }
 
+    // TODO: A cachetime could be specified, to limit recalculation, could be quite broadly useful for expensive
+    //       mappings
     fun <O : Any> map(mapper: (T) -> O): KVal<O> {
         if (isClosed) {
             throw IllegalStateException("Mapping an already closed KVar")