docs: examples

Author: jkelleyrtp

Cargo.toml

@@ -30,6 +30,7 @@ split-debuginfo = "unpacked"
 
 [dev-dependencies]
 futures = "0.3.15"
+log = "0.4.14"
 # For the tide ssr examples
 # async-std = { version="1.9.0", features=["attributes"] }
 # tide = { version="0.16.0" }

examples/README.md

@@ -1,29 +1,50 @@
 # Examples
 
-Most of these examples are run through webview so you don't need the dioxus cli installed to preview the functionality. Anything labeled `_web` will need to be built with the Dioxus CLI to preview features that only a native bundle can handle.
+Most of these examples are run through webview so you don't need the dioxus cli installed to preview the functionality.
 
-List of examples:
+These examples are fully-fledged micro apps. They can be ran with the `cargo run --example XYZ`
 
-| Example                                 | What it does |
-| --------------------------------------- | ------------ |
-| [The basics](./basics.rs)               | this does    |
-| [fine grained reactivity](./signals.rs) | this does    |
-| Global State Management                 | this does    |
-| Virtual Refs                            | this does    |
-| Inline Styles                           | this does    |
-| Conditional Rendering                   | this does    |
-| Maps/Iterators                          | this does    |
-| Render To string                        | this does    |
-| Component Children                      | this does    |
-| Function Driven children                | this does    |
-| Memoization                             | this does    |
-| Borrowed Data                           | this does    |
-| Fragments                               | this does    |
-| Null/None Components                    | this does    |
-| Spread Pattern for props                | this does    |
-| Controlled Inputs                       | this does    |
-| Custom Elements                         | this does    |
-| Testing And debugging                   | this does    |
-| Asynchronous Data                       | this does    |
-| Fiber/Scheduled Rendering               | this does    |
-| CSS Compiled Styles                     | this does    |
+| Example                                             | What it does                                | Status |
+| --------------------------------------------------- | ------------------------------------------- | ------ |
+| [The basics](./basics.rs)                           | A few basic examples to preview Dioxus      | 🛠      |
+| [fine grained reactivity](./signals.rs)             | Escape `diffing` by writing values directly | 🛠      |
+| [Global State Management](./statemanagement.rs)     | Share state between components              | 🛠      |
+| [Virtual Refs]()                                    | Cross-platform imperative elements          | 🛠      |
+| [Inline Styles](./inline-styles.rs)                 | Define styles for elements inline           | 🛠      |
+| [Conditional Rendering](./conditional-rendering.rs) | Hide/Show elements using conditionals       | ✅     |
+
+These examples are not necessarily meant to be run, but rather serve as a reference for the given functionality.
+
+| Example                                             | What it does                                    | Status |
+| --------------------------------------------------- | ----------------------------------------------- | ------ |
+| [The basics](./basics.rs)                           | A few basic examples to preview Dioxus          | 🛠      |
+| [fine grained reactivity](./signals.rs)             | Escape `diffing` by writing values directly     | 🛠      |
+| [Global State Management](./statemanagement.rs)     | Share state between components                  | 🛠      |
+| [Virtual Refs]()                                    | Cross-platform imperative elements              | 🛠      |
+| [Inline Styles](./inline-styles.rs)                 | Define styles for elements inline               | 🛠      |
+| [Conditional Rendering](./conditional-rendering.rs) | Hide/Show elements using conditionals           | ✅     |
+| [Maps/Iterators](./iterators.rs)                    | Use iterators in the rsx! macro                 | 🛠      |
+| [Render To string](./tostring.rs)                   | Render a mounted virtualdom to a string         | 🛠      |
+| [Component Children](./children.rs)                 | Pass children into child components             | 🛠      |
+| [Function Driven children]()                        | Pass functions to make VNodes                   | 🛠      |
+| [Memoization & Borrowed Data](./memo.rs)            | Suppress renders, borrow from parents           | ✅     |
+| [Fragments](./fragments.rs)                         | Support root-less element groups                | ✅     |
+| [Null/None Components](./empty.rs)                  | Return nothing!                                 | 🛠      |
+| [Spread Pattern for props](./spreadpattern.rs)      | Manually specify and override props             | ✅     |
+| [Controlled Inputs](./controlled-inputs.rs)         | this does                                       | 🛠      |
+| [Custom Elements]()                                 | Define custom elements                          | 🛠      |
+| [Web Components]()                                  | Custom elements to interface with WebComponents | 🛠      |
+| [Testing And debugging]()                           | this does                                       | 🛠      |
+| [Asynchronous Data]()                               | Using suspense to wait for data                 | 🛠      |
+| [Fiber/Scheduled Rendering]()                       | this does                                       | 🛠      |
+| [CSS Compiled Styles]()                             | this does                                       | 🛠      |
+| [Anti-patterns](./antipatterns.rs)                  | A collection of discouraged patterns            | ✅     |
+| [Complete rsx reference](./rsx_usage.rs)            | A complete reference for all rsx! usage         | ✅     |
+| [Event Listeners](./listener.rs)                    | Attach closures to events on elements           | ✅     |
+
+These web-specific examples must be run with `dioxus-cli` using `dioxus develop --example XYZ`
+
+| Example | What it does |
+| ------- | ------------ |
+| asd     | this does    |
+| asd     | this does    |

examples/listener.rs

@@ -21,10 +21,10 @@ fn main() {}
 /// Antipattern: Iterators without keys
 /// -----------------------------------
 ///
-/// This is considered an anti-pattern for performance reasons. Dioxus must diff your current and old layout and must
+/// This is considered an anti-pattern for performance reasons. Dioxus will diff your current and old layout and must
 /// take a slower path if it can't correlate old elements with new elements. Lists are particularly susceptible to the
 /// "slow" path, so you're strongly encouraged to provide a unique ID stable between renders. Additionally, providing
-/// the *wrong* keys is even worse. Keys should be:
+/// the *wrong* keys is even worse - props might be assigned to the wrong components! Keys should be:
 /// - Unique
 /// - Stable
 /// - Predictable
@@ -39,7 +39,7 @@ static AntipatternNoKeys: FC<NoKeysProps> = |cx| {
     rsx!(in cx, ul {
         {cx.data.iter().map(|(k, v)| rsx!(li { "List item: {v}" }))}
     });
-    // Like this:
+    // RIGHT: Like this:
     rsx!(in cx, ul {
         {cx.data.iter().map(|(k, v)| rsx!(li { key: "{k}", "List item: {v}" }))}
     })

examples/antipatterns.rs examples/reference/antipatterns.rsexamples/antipatterns.rs renamed to examples/reference/antipatterns.rs

@@ -0,0 +1,10 @@
+use dioxus::prelude::*;
+fn main() {}
+
+static Example: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+
+        }
+    })
+};

examples/reference/async.rs

@@ -0,0 +1,10 @@
+use dioxus::prelude::*;
+fn main() {}
+
+static Example: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+
+        }
+    })
+};

examples/reference/basics.rs

@@ -0,0 +1,45 @@
+//! Example: Children
+//! -----------------
+//!
+//! Dioxus supports passing children in from the parent. These children are allocated in the parent and just forced
+//! into the child. Components that pass in children may not be safely memoized, though in practice its rare for a
+//! change in a parent to not result in a different set of children.
+//!
+//! In Dioxus, children can *only be a list*. Unlike React, you cannot pass in functions or arbitrary data. This is
+//! partially a limitaiton in having static types, but is rather intentional to encourage the use of attributes where
+//! arbitrary child data might normally be used. Check out the `function driven children` example for how to adopt your
+//! React pattern for Dioxus' semantics.
+//!
+//! Dioxus will let you use the `children` method more than once - and it's semantically *okay* - but you'll likely
+//! ruin your page if you try to clone elements in this way. Under the hood, Dioxus shares a "mounted ID" for each node,
+//! and mounting the same VNode in two places will overwrite the first mounted ID. This will likely lead to dead elements.
+//!
+//! In the future, this might become a runtime error, so consider it an error today.
+
+use dioxus::prelude::*;
+fn main() {}
+
+static App: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+            Banner {
+                p { "Some Content1" }
+            }
+            Banner {
+                p { "Some Content2" }
+            }
+        }
+    })
+};
+
+static Banner: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+            h1 { "This is a great banner!" }
+            div { class: "content"
+                {cx.children()}
+            }
+            footer { "Wow, what a great footer" }
+        }
+    })
+};

examples/reference/children.rs

@@ -0,0 +1,92 @@
+//! Example: Conditional Rendering
+//! ------------------------------
+//!
+//! This example shows how to hide or show elements using conditional rendering.
+//!
+//! Often times you might want to display a different UI given some sort of condition. This is called "conditonal rendering".
+//! In Dioxus, you can perform conditional rendering with optionals or matching.
+//!
+//! The rsx! and html! macro accepts anything that is `IntoIter<Item = impl IntoVnode>`. Options and Results both implement
+//! IntoIter for impl VNode, so you can use option/result for conditional rendering.
+
+use dioxus::prelude::*;
+
+fn main() {}
+
+// Convert a boolean conditional into a hide/show
+#[derive(PartialEq, Props)]
+struct MyProps {
+    should_show: bool,
+}
+static Example: FC<MyProps> = |cx| {
+    cx.render(rsx! {
+        div {
+            {cx.should_show.then(|| rsx!{
+                h1 { "showing the title!" }
+            })}
+        }
+    })
+};
+
+// Convert a boolean conditional into an either/or
+// Because rsx! is lazy (produces a closure), we cannot use it in two branch arms. To use it in matching/branching, we
+// must render it.
+//
+// Dioxus will let you render any `LazyNodes` into a `VNode` with `cx.render`. `rsx!` also supports the `in cx` syntax
+// which will do essentially the same thing as `cx.render`.
+//
+// In short:
+// `rsx!(in cx, ...)` is shorthand for `cx.render(rsx!(...))`
+#[derive(PartialEq, Props)]
+struct MyProps1 {
+    should_show: bool,
+}
+static Example1: FC<MyProps1> = |cx| {
+    cx.render(rsx! {
+        div {
+            // With matching
+            {match cx.should_show {
+                true => cx.render(rsx!(div {"it is true!"})),
+                false => rsx!(in cx, div {"it is false!"}),
+            }}
+
+            // or with just regular conditions
+            {if cx.should_show {
+                rsx!(in cx, div {"it is true!"})
+            } else {
+                rsx!(in cx, div {"it is false!"})
+            }}
+
+            // or with optional chaining
+            {
+                cx.should_show
+                .then(|| rsx!(in cx, div {"it is false!"}))
+                .unwrap_or_else(|| rsx!(in cx, div {"it is false!"}))
+            }
+        }
+    })
+};
+
+/// Matching can be expanded
+
+#[derive(PartialEq)]
+enum Color {
+    Green,
+    Yellow,
+    Red,
+}
+#[derive(PartialEq, Props)]
+struct MyProps2 {
+    color: Color,
+}
+static Example2: FC<MyProps2> = |cx| {
+    cx.render(rsx! {
+        div {
+            {match cx.color {
+                Color::Green => rsx!(in cx, div {"it is Green!"}),
+                Color::Yellow => rsx!(in cx, div {"it is Yellow!"}),
+                Color::Red => rsx!(in cx, div {"it is Red!"}),
+            }}
+        }
+    })
+};

examples/reference/conditional_rendering.rs

@@ -0,0 +1,10 @@
+use dioxus::prelude::*;
+fn main() {}
+
+static Example: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+
+        }
+    })
+};

examples/reference/controlled_inputs.rs

@@ -0,0 +1,10 @@
+use dioxus::prelude::*;
+fn main() {}
+
+static Example: FC<()> = |cx| {
+    cx.render(rsx! {
+        div {
+
+        }
+    })
+};