From 21749ef0d3651e15daf130ca7732798c17ffca6f Mon Sep 17 00:00:00 2001 From: Ben Croker Date: Fri, 6 Dec 2024 23:50:10 -0600 Subject: [PATCH] Improve getting started guide --- site/routes_home.templ | 2 +- site/static/md/guide/getting_started.md | 112 +++++++++++++----------- 2 files changed, 60 insertions(+), 54 deletions(-) diff --git a/site/routes_home.templ b/site/routes_home.templ index 6f29157fb..c4d6223d5 100644 --- a/site/routes_home.templ +++ b/site/routes_home.templ @@ -15,7 +15,7 @@ templ Home() { >` }} {{ - usageSample := ` + usageSample := `
` }} diff --git a/site/static/md/guide/getting_started.md b/site/static/md/guide/getting_started.md index ea4140110..6d395a473 100644 --- a/site/static/md/guide/getting_started.md +++ b/site/static/md/guide/getting_started.md @@ -52,15 +52,15 @@ Datastar uses signals to manage state. You can think of signals as reactive vari Datastar provides us with a way to set up two-way data binding on an element using the [`data-bind`](/reference/plugins_dom#bind) attribute, which can be placed on any HTML element that users can directly input data or choices from (`input`, `textarea`, `select`, `checkbox` and `radio` elements). ```html - + ``` This creates a new signal called `input`, and binds it to the element's value. If either is changed, the other automatically updates. -An alternative syntax also exists for `data-bind`, in which the value is used as the signal name. This can be useful depending on the templating language you are using. +An alternative syntax exists for `data-bind`, in which the value is used as the signal name. This can be useful depending on the templating language you are using. ```html - + ``` ### `data-text` @@ -86,7 +86,7 @@ To see this in action, we can use the [`data-text`](/reference/plugins_dom#text) -This sets the text content of an element to the value of the signal `input.value`. The `.value` is required to denote a the use of a signal's *value* in the expression. +This sets the text content of an element to the value of the signal `input`. The `.value` is required to denote the signal's *value* in the expression. The value of the `data-text` attribute is an expression that is evaluated, meaning that we can use JavaScript in it. @@ -115,13 +115,15 @@ The [`data-computed`](/reference/plugins_core#computed) attribute creates a new ```html
- +
Will be replaced with the contents of the repeated signal
``` +This results in the `repeated` signal's value always being equal to the value of the `input` signal repeated twice. Computed signals are useful for memoizing expressions containing other signals. +
@@ -137,13 +139,13 @@ The [`data-computed`](/reference/plugins_core#computed) attribute creates a new ### `data-show` -The [`data-show`](/reference/plugins_browser#show) attribute can be used to show or hide an element based on whether a JavaScript expression evaluates to `true` or `false`. +The [`data-show`](/reference/plugins_browser#show) attribute can be used to show or hide an element based on whether an expression evaluates to `true` or `false`. ```html ``` -This results in the button being visible only when the input is _not_ empty. +This results in the button being visible only when the input is _not_ an empty string (this could also be written as `!input.value`).
@@ -169,11 +171,7 @@ The [`data-class`](/reference/plugins_dom#class) attribute allows us to add or r ``` -Since the expression evaluates to `true` or `false`, we can rewrite this as `!input.value`. - -```html - -``` +If the expression evaluates to `true`, the `hidden` class is added to the element; otherwise, it is removed.
@@ -186,12 +184,12 @@ Since the expression evaluates to `true` or `false`, we can rewrite this as `!in
-
-The `data-class` attribute can also be used to add or remove multiple classes from an element using a set of key-value pairs, where keys represent class names and values represent expressions. +The `data-class` attribute can also be used to add or remove multiple classes from an element using a set of key-value pairs, where the keys represent class names and the values represent expressions. ```html @@ -205,7 +203,7 @@ The [`data-attributes`](/reference/plugins_dom#attributes) attribute can be used ``` -This results in the button being given the `disabled` attribute whenever the input is empty. +This results in a `disabled` attribute being given the value `true` whenever the input is an empty string.
@@ -223,7 +221,7 @@ This results in the button being given the `disabled` attribute whenever the inp
-The `data-attributes` attribute can also be used to add or remove multiple classes from an element using a set of key-value pairs, where keys represent class names and values represent expressions. +The `data-attributes` attribute can also be used to set the values of multiple attributes on an element using a set of key-value pairs, where the keys represent attribute names and the values represent expressions. ```html @@ -231,26 +229,26 @@ The `data-attributes` attribute can also be used to add or remove multiple class ### `data-signals` -So far, we've created signals on the fly using `data-bind` and `data-computed-*`. All signals are merged into a global set of signals that are accessible from anywhere in the DOM. +So far, we've created signals on the fly using `data-bind` and `data-computed`. All signals are merged into a global set of signals that are accessible from anywhere in the DOM. -We can create a signal using the [`data-signals`](/reference/plugins_core#signals) attribute. +We can also create signals using the [`data-signals`](/reference/plugins_core#signals) attribute. ```html
``` -Adding `data-signals` to multiple elements is allowed, as signals are _merged_ into the existing signals (values defined later in the DOM tree override those defined earlier). +Using `data-signals` _merges_ one or more signals into the existing signals. Values defined later in the DOM tree override those defined earlier. Signals are nestable using dot-notation, which can be useful for namespacing. ```html -
+
``` -The `data-signals` attribute can also be used to merge multiple signals using a set of key-value pairs, where keys represent signal names and values represent expressions. +The `data-signals` attribute can also be used to merge multiple signals using a set of key-value pairs, where the keys represent signal names and the values represent expressions. ```html -
+
``` ### `data-on` @@ -261,7 +259,7 @@ The [`data-on`](/reference/plugins_dom#on) attribute can be used to attach an ev ``` -This results in the `input` signal's value being set to an empty string when the button element is clicked. If the `input` signal is used elsewhere, its value will automatically update. This can be used with any valid event name such as `data-on-keydown`, `data-on-mouseover`, etc. +This results in the `input` signal's value being set to an empty string whenever the button element is clicked. This can be used with any valid event name such as `data-on-keydown`, `data-on-mouseover`, etc.
@@ -279,8 +277,9 @@ This results in the `input` signal's value being set to an empty string when the
-So what else can we do with these expressions? Anything we want, really. -See if you can follow the code below _before_ trying the demo. +So what else can we do now that we have declarative signals and expressions? Anything we want, really. + +See if you can follow the code below based on what you've learned so far, _before_ trying the demo. ```html
@@ -411,13 +407,23 @@ Note that elements using the `data-indicator` attribute _must_ have a unique ID
-We're not limited to just `GET` requests. We can also send `GET`, `POST`, `PUT`, `PATCH` and `DELETE` requests, using the `sse()` with a `method:'post'` for example. +The `data-indicator` attribute can also be written with the value used as the signal name. +```html + + ``` One of the benefits of using SSE is that we can send multiple events (HTML fragments, signal updates, etc.) in a single response. @@ -426,45 +432,45 @@ One of the benefits of using SSE is that we can send multiple events (HTML fragm ## Actions -Actions in Datastar are helper functions that are available in `data-*` attributes and have the syntax `actionName()`. We already saw the `sse` action above. Here are a few other common actions. +Actions in Datastar are helper functions that are available in `data-*` attributes and have the syntax `actionName()`. We already saw the `sse()` action above. Here are a few other common actions. ### `setAll()` The `setAll()` action sets the values of multiple signals at once. It takes a path prefix that is used to match against signals, and a value to set them to, as arguments. ```html - + ``` -This sets the values of all signals containing `form_` to `true`, which could be useful for enabling input fields in a form. +This sets the values of all signals nested under the `form` signal to `true`, which could be useful for enabling input fields in a form. ```html - Checkbox 1 - Checkbox 2 - Checkbox 3 - + Checkbox 1 + Checkbox 2 + Checkbox 3 + ```
-
@@ -480,29 +486,29 @@ The `toggleAll()` action toggles the values of multiple signals at once. It take This toggles the values of all signals containing `form.` (to either `true` or `false`), which could be useful for toggling input fields in a form. ```html - Checkbox 1 - Checkbox 2 - Checkbox 3 - + Checkbox 1 + Checkbox 2 + Checkbox 3 + ```