From d7a6885af653c8318913921dc28d98a840596c59 Mon Sep 17 00:00:00 2001
From: Sabine Lim <thesabinelim@gmail.com>
Date: Fri, 19 May 2023 17:32:38 +1000
Subject: [PATCH] Update xml.md (#86)

---
 docs/guides/xml.md | 180 ++++++++++++++++++++++++++++++---------------
 1 file changed, 122 insertions(+), 58 deletions(-)

diff --git a/docs/guides/xml.md b/docs/guides/xml.md
index 6762641..6fc9c5d 100644
--- a/docs/guides/xml.md
+++ b/docs/guides/xml.md
@@ -2,14 +2,14 @@ XML (eXtensible Markup Language) is a popular and widely-used markup language fo
 
 ## Loading an XML File in Basalt
 
-To load an XML file in Basalt, you'll need to use the `frame:loadLayout` function. This function reads an XML file and returns a table containing the parsed XML data.
+To load an XML file in Basalt, you'll need to use the `container:loadLayout` function. This function reads an XML file and runs any scripts or adds any objects within.
 
 Here's an example of how to load an XML file:
 
 ```lua
 local basalt = require("basalt")
 
-local main = basalt.createFrame():loadLayout("path/to/your/layout.xml")
+basalt.createFrame():loadLayout("path/to/your/layout.xml")
 ```
 
 Make sure that the specified XML file is accessible and located within your project's file system.
@@ -21,108 +21,172 @@ Basalt uses XML to define UI elements and their properties. By using XML, you ca
 Here's an example of an XML file that defines a simple UI layout for Basalt:
 
 ```xml
-<label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-<button id="okButton" text="OK" x="10" y="5" />
+<label text="Welcome to Basalt!" x="10" y="2" />
+<button text="OK" x="10" y="5" />
 ```
 
 In this example, we define a `Label` and a `Button` with their respective properties, such as `id`, `text`, `x`, and `y`.
 
-To use the loaded XML data to create the UI elements in Basalt, you can use `main:getXMLElements()`:
+## Props
+
+Properties, or props for short, allow the layout or object to take parameters as input which can be used in the layout. There are 2 types of props: hard-coded string props and computed props.
+
+Hard-coded string props use the `prop="some text"` syntax. The above example demonstrated this, but by using the computed `prop={some Lua expression}` syntax, these props can be used in a much more powerful way. Anything between the curly braces is evaluated as a Lua expression. For example:
+
+```xml
+<label text={"Some text concatenated with a number: " .. 420 * 7 + 9 } />
+```
+
+You can pass props to a layout in the form of a table to the `loadLayout` function:
 
 ```lua
 local basalt = require("basalt")
 
-local main = basalt.createFrame():loadLayout("path/to/your/layout.xml")
-
-local uiElements = main:getXMLElements()
+basalt.createFrame():loadLayout("path/to/your/layout.xml", { buttonText = "Click me!", onClick = function() basalt.log("Testing") end })
+```
 
-local titleLabel = uiElements["titleLabel"]
+Props can then be consumed within the layout in the form of the `props` global variable, accessible anywhere within the layout including within computed props.
 
-titleLabel:setText("New Title")
+```xml
+<button text={props.buttonText} onClick={props.onClick} />
 ```
 
-## Using Lua Code in XML
+## Scripts
 
-In addition to defining UI elements, you can also include Lua code within your XML files for Basalt. This allows you to perform more complex operations or customize your UI elements based on conditions or data.
+In addition to defining UI elements, you can also include Lua code within your XML files for Basalt. This allows you to perform more complex operations.
 
-To include Lua code in your XML file, you can use the `<script>` tag. Any Lua code enclosed within the `<script>` tag will be executed by Basalt when parsing the XML data.
+To include Lua code in your XML file, you can use the `<script>` tag. Any Lua code enclosed within the `<script>` tag will be executed by Basalt when parsing the XML data. This script shares the global scope with the computed props.
 
 Here's an example of how to include Lua code in your XML file:
 
 ```xml
-<label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-<button id="okButton" text="OK" x="10" y="5" />
 <script>
-    -- Lua code to change the text of the titleLabel based on a condition
-    if someCondition then
-        titleLabel:setText("Condition Met!")
+    if (props.isLoggedIn) then
+        labelText = "Logged in!"
+    else
+        labelText = "Logged out!"
     end
 </script>
+
+<label text={labelText} />
 ```
 
-To share variables or data between multiple `<script>` tags in your XML file, you can use the global shared table provided by Basalt. This table allows you to store values that can be accessed across different `<script>` tags in your XML file.
+## Nested layouts
 
-Here's an example of using the shared table to share data between two `<script>` tags:
+Sometimes a UI gets so complex that it becomes desirable to split it up into several sub-layouts. For this, you can import layouts within a layout:
 
 ```xml
-  <script>
-    -- Store a value in the shared table
-    shared.myValue = 42
-  </script>
-  <label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-  <button id="okButton" text="OK" x="10" y="5" />
-  <script>
-    -- Access the stored value from the shared table
-    local myValue = shared.myValue
-
-    -- Perform an operation using the shared value, e.g., update titleLabel's text
-    titleLabel:setText("Shared Value: " .. myValue)
-  </script>
+<script>
+    local basalt = require("basalt")
+    AnotherLayout = basalt.layout("path/to/another/layout.xml")
+</script>
+
+<label text="Nested layouts are fun" />
+<AnotherLayout someProp="Hello" anotherProp="World" aComputedProp={function() return "Basalt rules" end} />
 ```
 
-In this example, we first store a value in the shared table in one `<script>` tag, and then access that value in another `<script>` tag to update the titleLabel's text.
+This layout can be passed props like any other object in the layout, as seen in the example above.
+
+## Reactivity (BETA)
+
+Reacting to user input is easier than ever with Basalt XML's concept of reactive values and observers for said values. This powerful feature allows for properties to be derived automatically from reactive values, without needing the programmer to manually call functions to update the object.
 
-You can also include Lua code directly within event properties of UI elements. This allows you to execute specific actions or manipulate UI elements when certain events occur.
+To create a reactive value, simply use the `basalt.reactive(initialValue)` function, which returns getter and setter functions. For example:
+
+```xml
+<script>
+    local basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+</script>
+```
 
-To include Lua code in an event property, simply add the Lua code within the event property's value in the XML tag. The Lua code will be executed when the specified event is triggered.
+You could then hook up this reactive value to a property.
 
 ```xml
-<label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-<button id="okButton" text="OK" x="10" y="5" onClick="titleLabel:setText('Button clicked!')" />
+<script>
+    local basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+</script>
+
+<button text={"Times clicked: " .. getTimesClicked()} />
 ```
 
-or
+This subscribes the button text to the value of times clicked. If this value is updated via the setter function, the button text will automatically update as well. So let's add an onClick event to do this!
 
 ```xml
-<label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-<button id="okButton" text="OK" x="10" y="5">
-    <onClick>
-        titleLabel:setText('Button clicked!')
-    </onClick>
-</button>
+<script>
+    local basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+    onClick = function()
+        setTimesClicked(getTimesClicked() + 1)
+    end
+</script>
+
+<button text={"Times clicked: " .. getTimesClicked()} onClick={onClick} />
 ```
 
-In both examples, you can see that XML provides a straightforward way to build a Basalt user interface. The XML format allows you to define the UI structure and easily set properties for each UI element, such as position, size, and text.
+Voila. You now have a button that displays the number of times it's been clicked.
+
+# Effects
+
+In addition to reactive values, there are effects that are triggered by them. You can think about it like this: reactive values produce updates, while effects detect them and do something in response.
+
+Effects are created using the `basalt.effect(function)` function. Any reactive values that are accessed during the effect's execution are automatically subscribed to, and the effect will re-run in response to updates to these values.
+
+For example, you could create an effect that writes a message to the logs whenever the times clicked updates:
+
+```xml
+<script>
+    local basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+    onClick = function()
+        setTimesClicked(getTimesClicked() + 1)
+    end
+    basalt.effect(function()
+        basalt.log("Button clicked. New times clicked = " .. getTimesClicked())
+    end)
+</script>
+
+<button text={"Times clicked: " .. getTimesClicked()} onClick={onClick} />
+```
 
-Notably, you can access UI elements by their assigned ID directly in the event code. In the examples above, the titleLabel and okButton elements are accessed simply by referencing their IDs. This convenient feature eliminates the need to search for or store references to the elements in your code.
+In fact, props are internally implemented using effects! Effects that set the corresponding property in the object to the new reactive value.
 
-Remember: IDs have to be unique!
+# Derived values
 
-## Reactive properties (BETA)
+If reactive values are the source of truth, derived values can be thought of as a dependency that uses them and transforms them. Similarly to effects, they also update whenever the reactive values they observe update.
 
-Most properties can also be set to track a shared variable using the curly braces {} syntax. In this case, the initial value for the variable should be set inside the `<script>` tag. When this variable is modified, the rendered value will be automatically updated.
+To create a derived value, use the `basalt.derived(function)` function, which returns a getter function for the value. Any effect observing this derived value will update if the derived value updates, which itself updates in response to a source reactive value updating, in a chain reaction.
 
-The earlier example rewritten using reactive properties:
+The above button example could be rewritten as:
 
 ```xml
-<label id="titleLabel" text="Welcome to Basalt!" x="10" y="2" />
-<button id="okButton" text={shared.okButtonText} x="10" y="5">
-    <onClick>
-        shared.okButtonText = "Button clicked!"
-    </onClick>
-</button>
+<script>
+    local basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+    onClick = function()
+        setTimesClicked(getTimesClicked() + 1)
+    end
+    getButtonText = basalt.derived(function()
+        return "Times clicked: " .. getTimesClicked()
+    end)
+</script>
+
+<button text={getButtonText()} onClick={onClick} />
+```
+
+# Untracked reactive value access
+
+Sometimes you might want to use a reactive value in an unreactive way. Perhaps you would like a property to be computed based on it only once, never updating afterwards. This can be accomplished using the `basalt.untracked(function)` function:
 
+```xml
 <script>
-  shared.okButtonText = "OK"
+    basalt = require("basalt")
+    getTimesClicked, setTimesClicked = basalt.reactive(0)
+    onClick = function()
+        setTimesClicked(getTimesClicked() + 1)
+    end
 </script>
+
+<button text={"This value should never update: " .. getTimesClicked()} onClick={onClick}/>
 ```