swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update local examples and docs to support new syntaxes

Browse Source
This commit is contained in:
Jonathan Kelley committed 2021-12-15 15:56:53 -05:00
1 parent e495b09bf1
commit 4de16c4779
118 files changed
+520 -1154
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/lib.rs
+87 -28
View File
@@ -10,8 +10,8 @@
//! This overview is provides a brief introduction to Dioxus. For a more in-depth guide, make sure to check out:
//! - [Getting Started](https://dioxuslabs.com/getting-started)
//! - [Book](https://dioxuslabs.com/book)
//! - [Reference](https://dioxuslabs.com/refernce-guide)
//! - [Reference](https://dioxuslabs.com/reference)
//! - [Community Examples](https://github.com/DioxusLabs/community-examples)
//!
//! # Overview and Goals
//!
@@ -22,34 +22,32 @@
//!
//! - Hooks for state
//! - VirtualDom & diffing
//! - Concurrency & asynchronous rendering
//! - Concurrency, fibers, and asynchronous rendering
//! - JSX-like templating syntax
//!
//! If you know React, then you know Dioxus.
//!
//! Dioxus is *substantially* faster than many of the other Rust UI libraries (Yew/Percy) and is *significantly* faster
//! than React, competitve with InfernoJS and frameworks like Svelte/SolidJS.
//! Dioxus is *substantially* more performant than many of the other Rust UI libraries (Yew/Percy) and is *significantly* more performant
//! than React - roughly competitve with InfernoJS.
//!
//! Remember: Dioxus is a library for declaring interactive user interfaces - it is not a dedicated renderer. Most 1st party renderers for Dioxus currently only support web technologies.
//!
//! ## Brief Overview
//!
//! All Dioxus apps are built by composing functions that take in a `Scope` and `Properties` and return an `Element`. A `Scope` holds
//! relevant state data for the the currently-rendered component.
//! All Dioxus apps are built by composing functions that take in a `Scope` which is generic over some `Properties` and return an `Element`.
//! A `Scope` holds relevant state data for the the currently-rendered component.
//!
//! To launch an app, we use the `launch` method for the specific renderer we want to use. In the launch function, was pass the app's `Component`.
//!
//! ```rust
//! use dioxus::prelude::*;
//!
//! fn main() {
//! dioxus::desktop::launch(App);
//! dioxus::desktop::launch(app);
//! }
//!
//! fn App(cx: Scope, props: &()) -> Element {
//! let mut count = use_state(cx, || 0);
//!
//! cx.render(rsx!(
//! div { "Count: {count}" }
//! button { onclick: move |_| count += 1, "Increment" }
//! button { onclick: move |_| count -= 1, "Decrement" }
//! ))
//! fn app(cx: Scope<()>) -> Element {
//! cx.render(rsx!("hello world!"))
//! }
//! ```
//!
@@ -59,7 +57,7 @@
//! For components with no explicit properties, we can use the `()` type. In Dioxus, all properties are memoized by default!
//!
//! ```rust
//! fn App(cx: Scope, props &()) -> Element {
//! fn App(cx: Scope<()>) -> Element {
//! cx.render(rsx!(
//! Header {
//! title: "My App",
@@ -78,11 +76,11 @@
//! color: String,
//! }
//!
//! fn Header(cx: Scope, props: &HeaderProps) -> Element {
//! fn Header(cx: Scope<HeaderProps>) -> Element {
//! cx.render(rsx!(
//! div {
//! background_color: "{props.color}"
//! h1 { "{props.title}" }
//! background_color: "{cx.props.color}"
//! h1 { "{cx.props.title}" }
//! }
//! ))
//! }
@@ -90,21 +88,65 @@
//!
//! ## Hooks
//!
//! While components are reusable forms of UI elements, hooks are reusable forms of logic. The details of hooks are
//! somewhat complicated. In essence, hooks let us save state between renders of our components and reuse the accompanying
//! logic across different apps.
//!
//! Hooks are simply composition of other hooks. To create our first hook we can create a simple function that takes in
//! an Scope. We can then call `use_hook` on the `Scope` to get a mutable reference to the stored value.
//! While components are reusable forms of UI elements, hooks are reusable forms of logic. All hooks start with `use_`. We can use hooks to declare state.
//!
//! ```rust
//! fn use_say_hello(cx: Scope) -> &mut String {
//! fn app(cx: Scope<()>) -> Element {
//! let name = use_state(&cx, || "world");
//!
//! rsx!(cx, "hello {name}!")
//! }
//! ```
//!
//! Hooks are sensitive to how they are used. To use hooks, you must abide by the ["rules of hooks" (borrowed from react)](https://reactjs.org/docs/hooks-rules.html):
//! - Hooks should not be called in callbacks
//! - Hooks should not be called in out of order
//! - Hooks should not be called in loops or conditionals
//!
//! In a sense, hooks let us add a field of state to our component without declaring
//! an explicit struct. However, this means we need to "load" the struct in the right
//! order. If that order is wrong, then the hook will pick the wrong state and panic.
//!
//! Most hooks you'll write are simply composition of other hooks:
//!
//! ```rust
//! fn use_username(cx: &ScopeState, id: Uuid) -> bool {
//! let users = use_context::<Users>(cx);
//! users.get(&id).is_some().map(|user| user.logged_in).ok_or(false)
//! }
//! ```
//!
//! To create entirely new foundational hooks, we can use the `use_hook` method on ScopeState.
//!
//! ```rust
//! fn use_mut_string(cx: &ScopeState) -> &mut String {
//! cx.use_hook(|_| "Hello".to_string(), |hook| hook)
//! }
//! ```
//!
//! If you want to extend Dioxus with some new functionality, you'll probably want to implement a new hook.
//! If you want to extend Dioxus with some new functionality, you'll probably want to implement a new hook from scratch.
//!
//! ## Putting it all together
//!
//! Using components, templates, and hooks, we can build a simple app.
//!
//! ```rust
//! use dioxus::prelude::*;
//!
//! fn main() {
//! dioxus::desktop::launch(App);
//! }
//!
//! fn App(cx: Scope<()>) -> Element {
//! let mut count = use_state(&cx, || 0);
//!
//! cx.render(rsx!(
//! div { "Count: {count}" }
//! button { onclick: move |_| count += 1, "Increment" }
//! button { onclick: move |_| count -= 1, "Decrement" }
//! ))
//! }
//! ```
//!
//! ## Features
//!
@@ -122,6 +164,23 @@
//! - Custom elements
//! - Basic fine-grained reactivity (IE SolidJS/Svelte)
//! - and more!
//!
//! Good luck!
//!
//! ## Inspiration, Resources, Alternatives and Credits
//!
//! Dioxus is inspired by:
//! - React: for its hooks, concurrency, suspense
//! - Dodrio: for its research in bump allocation, double buffering, and diffing architecture
//!
//! Alternatives to Dioxus include:
//! - Yew: supports function components and web, but no SSR, borrowed data, or bump allocation. Rather slow at times.
//! - Percy: supports function components, web, ssr, but lacks in state management
//! - Sycamore: supports function components, web, ssr, but closer to SolidJS than React
//! - MoonZoom/Seed: opionated in the Elm model (message, update) - no hooks
//!
//! We've put a lot of work into making Dioxus ergonomic and *familiar*.
//! Our target audience is TypeSrcipt developers looking to switch to Rust for the web - so we need to be comparabale to React.
// Just a heads-up, the core functionality of dioxus rests in Dioxus-Core. This crate just wraps a bunch of utilities
// together and exports their namespaces to something predicatble.