Improve inline docs (#2460)

Improve inline docs

* improve incorrect event handler return error message

* Improve event handler docs

* document the eval functions

* document spawn and common spawn errors

* fix event handler docs

* add notes about how you use attributes and elements in rsx

* add doc aliases for attributes and events we rename

* add some more aliases for common search terms

* don't doc ignore any public examples in core

* don't ignore public doc examples in ssr

* don't ignore examples in the dioxus package readme

* add a warning when you launch without a renderer enabled

* fix some outdated element docs

* add a bunch of examples to resource

* add notes about desktop events

* add more docs for use_resource

* add on_unimplemented hint to Dependency

* fix some unresolved links

* add examples to each of the router traits

* add not implemented errors for router traits

* add an example to the routable trait

* expand rsx macro docs

* improve memo docs

* update the dioxus readme

* mention dioxus crate features in the docs

* fix a bunch of doc tests

* fix html doc tests

* fix router doc tests

* fix dioxus signals doc tests

* fix dioxus ssr doc tests

* fix use_future example in the hooks cheat sheet

* add a javascript alias for eval

* fix hook explanation values

* remove unused embed-doc-image dependency
This commit is contained in:
Evan Almloff authored and GitHub committed 2024-06-06 18:15:17 -07:00
1 parent 054351139f
commit 0127501dbf
71 files changed
+4132 -1162

No files matched your search

+24 -25
View File
@@ -17,8 +17,13 @@ This crate is a part of the broader Dioxus ecosystem. For more resources about D
Dioxus SSR provides utilities to render Dioxus components to valid HTML. Once rendered, the HTML can be rehydrated client-side or served from your web server of choice.
```rust, ignore
let app: Component = |cx| rsx!(div {"hello world!"});
```rust
# use dioxus::prelude::*;
fn app() -> Element {
rsx!{
div {"hello world!"}
}
}
let mut vdom = VirtualDom::new(app);
vdom.rebuild_in_place();
@@ -31,19 +36,22 @@ assert_eq!(text, "<div>hello world!</div>")
The simplest example is to simply render some `rsx!` nodes to HTML. This can be done with the [`render_element`] API.
```rust, ignore
```rust, no_run
# use dioxus::prelude::*;
let content = dioxus_ssr::render_element(rsx!{
div {
(0..5).map(|i| rsx!(
for i in 0..5 {
"Number: {i}"
))
}
}
});
```
## Rendering a VirtualDom
```rust, ignore
```rust, no_run
# use dioxus::prelude::*;
# fn app() -> Element { todo!() }
let mut vdom = VirtualDom::new(app);
vdom.rebuild_in_place();
@@ -60,7 +68,9 @@ With pre-rendering enabled, this crate will generate element nodes with Element
To enable pre-rendering, simply set the pre-rendering flag to true.
```rust, ignore
```rust, no_run
# use dioxus::prelude::*;
# fn App() -> Element { todo!() }
let mut vdom = VirtualDom::new(App);
vdom.rebuild_in_place();
@@ -75,30 +85,19 @@ let text = renderer.render(&vdom);
Dioxus SSR can also be used to render on the server. You can just render the VirtualDOM to a string and send that to the client.
```rust, ignore
```rust
# use dioxus::prelude::*;
fn App() -> Element {
rsx! { div { "hello world!" } }
}
let mut vdom = VirtualDom::new(App);
vdom.rebuild_in_place();
let text = dioxus_ssr::render(&vdom);
assert_eq!(text, "<div>hello world!</div>")
```
The rest of the space - IE doing this more efficiently, caching the VirtualDom, etc, will all need to be a custom implementation for now.
## Usage without a VirtualDom
Dioxus SSR needs an arena to allocate from - whether it be the VirtualDom or a dedicated Bump allocator. To render `rsx!` directly to a string, you'll want to create a `Renderer` and call `render_element`.
```rust, ignore
let text = dioxus_ssr::Renderer::new().render_element(rsx!{
div { "hello world" }
});
assert_eq!(text, "<div>hello world!</div>")
```
This can be automated with the `render_element!` macro:
```rust, ignore
let text = render_element!(rsx!( div { "hello world" } ));
```
## Usage in static site generation
Dioxus SSR is a powerful tool to generate static sites. Using Dioxus for static site generation _is_ a bit overkill, however. The new documentation generation library, Doxie, is essentially Dioxus SSR on steroids designed for static site generation with client-side hydration.