-

docs/tutorial.md

@@ -203,3 +203,61 @@ session.waitTillUserClosesSessionOr(exit)
 
 Now if we run it with `./on-click.sc` and click the button, the script will terminate.
 
+## Reading updated values
+
+Some UI element values, like input boxes, can be changed by the user. We can read the changed value at any point of our
+code or install an onChange handler so that we read the value as soon as the user changes it.
+
+Let's see how we can just read the value. The following script will create an email input box and a button. Whenever
+the button is pressed, it will read the email and create a new paragraph with the email value.
+
+[read-changed-value.sc](../example-scripts/read-changed-value.sc)
+
+![read-value](images/tutorial/read-value.png)
+
+```scala
+#!/usr/bin/env -S scala-cli project.scala
+
+import org.terminal21.client.*
+import org.terminal21.client.components.*
+import org.terminal21.client.components.std.Paragraph
+import org.terminal21.client.components.chakra.*
+
+Sessions.withNewSession("read-changed-value-example", "Read Changed Value"): session =>
+  given ConnectedSession = session
+
+  val email = Input(`type` = "email", value = "[email protected]")
+  val output = Box()
+
+  Seq(
+    FormControl().withChildren(
+      FormLabel(text = "Email address"),
+      InputGroup().withChildren(
+        InputLeftAddon().withChildren(EmailIcon()),
+        email
+      ),
+      FormHelperText(text = "We'll never share your email.")
+    ),
+    Button(text = "Read Value").onClick: () =>
+      val value = email.current.value
+      output.current.addChildren(Paragraph(text = s"The value now is $value")).renderChanges()
+    ,
+    output
+  ).render()
+
+  session.waitTillUserClosesSession()
+```
+
+The important bit is this:
+
+```scala
+    Button(text = "Read Value").onClick: () =>
+      val value = email.current.value
+      output.current.addChildren(Paragraph(text = s"The value now is $value")).renderChanges()
+```
+
+When the button is clicked, we get the current state of the `email` input box via `email.current`. And then get it's value, `email.current.value`.
+
+Also in order to append a new paragraph to the `output`, we get the current state of it (which includes any previous paragraphs we have added) and then
+add a paragraph as a new child. Then we render the changes of `output` which includes the paragraphs.
+

example-scripts/read-changed-value.sc

@@ -0,0 +1,30 @@
+#!/usr/bin/env -S scala-cli project.scala
+
+import org.terminal21.client.*
+import org.terminal21.client.components.*
+import org.terminal21.client.components.std.Paragraph
+import org.terminal21.client.components.chakra.*
+
+Sessions.withNewSession("read-changed-value-example", "Read Changed Value"): session =>
+  given ConnectedSession = session
+
+  val email = Input(`type` = "email", value = "[email protected]")
+  val output = Box()
+
+  Seq(
+    FormControl().withChildren(
+      FormLabel(text = "Email address"),
+      InputGroup().withChildren(
+        InputLeftAddon().withChildren(EmailIcon()),
+        email
+      ),
+      FormHelperText(text = "We'll never share your email.")
+    ),
+    Button(text = "Read Value").onClick: () =>
+      val value = email.current.value
+      output.current.addChildren(Paragraph(text = s"The value now is $value")).renderChanges()
+    ,
+    output
+  ).render()
+
+  session.waitTillUserClosesSession()