mirror of https://github.com/yewstack/yew
Tidy up the documentation. (#2404)
- fix a number of typos/grammatical errors - also includes some stylistic changes
This commit is contained in:
parent
4580d94c59
commit
c7599c54d8
|
@ -23,16 +23,18 @@ Using the `html!` macro can feel pretty magic, but it has nothing to hide. If yo
|
|||
how it works, try expanding the `html!` macro calls in your program. There's a useful command called
|
||||
`cargo expand` which allows you to see the expansion of Rust macros. `cargo expand` isn't shipped with
|
||||
`cargo` by default so you'll need to install it with `cargo install cargo-expand` if you haven't
|
||||
already.
|
||||
already. [Rust-Analyzer](https://rust-analyzer.github.io/) also provides a mechanism for
|
||||
[obtaining macro output from within an IDE](https://rust-analyzer.github.io/manual.html#expand-macro-recursively).
|
||||
|
||||
Note that when viewing expanded macro code, you're likely to encounter unusually verbose code. The
|
||||
reason is because generated code can sometimes clash with other code in an application. In order
|
||||
to prevent issues, `proc_macro` "hygiene" is adhered to. Some examples include:
|
||||
Output from the `html!` macro is often pretty terse! This is a feature: machine-generated code can
|
||||
sometimes clash with other code in an application. In order to prevent issues, `proc_macro`
|
||||
"hygiene" is adhered to. Some examples include:
|
||||
|
||||
1. Instead of using `yew::<module>` the macro generates `::yew::<module>` to make sure that the
|
||||
Yew package is referenced correctly. This is also why `::alloc::vec::Vec::new()` is called instead
|
||||
of just `Vec::new()`.
|
||||
2. Due to potential trait method name collisions, `<Type as Trait>` is used to make sure that we're using items from the right trait.
|
||||
2. Due to potential trait method name collisions, `<Type as Trait>` is used to make sure that we're
|
||||
using members from the correct trait.
|
||||
|
||||
## What is a virtual DOM?
|
||||
|
||||
|
|
|
@ -3,7 +3,7 @@ title: "Portals"
|
|||
description: "Rendering into out-of-tree DOM nodes"
|
||||
---
|
||||
|
||||
## How to think about portals?
|
||||
## What is a portal?
|
||||
|
||||
Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
|
||||
`yew::create_portal(child, host)` returns a `Html` value that renders `child` not hierarchically under its parent component,
|
||||
|
@ -11,9 +11,16 @@ but as a child of the `host` element.
|
|||
|
||||
## Usage
|
||||
|
||||
Typical uses of portals can include modal dialogs and hovercards, as well as more technical applications such as controlling the contents of an element's [`shadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot), appending stylesheets to the surrounding document's `<head>` and collecting referenced elements inside a central `<defs>` element of an `<svg>`.
|
||||
Typical uses of portals can include modal dialogs and hovercards, as well as more technical applications
|
||||
such as controlling the contents of an element's
|
||||
[`shadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot), appending
|
||||
stylesheets to the surrounding document's `<head>` and collecting referenced elements inside a
|
||||
central `<defs>` element of an `<svg>`.
|
||||
|
||||
Note that `yew::create_portal` is a rather low-level building block, on which other components should be built that provide the interface for your specific use case. As an example, here is a simple modal dialogue that renders its `children` into an element outside `yew`'s control, identified by the `id="modal_host"`.
|
||||
Note that `yew::create_portal` is a low-level building block. Libraries should use it to implement
|
||||
higher-level APIs which can then be consumed by applications. For example, here is a
|
||||
simple modal dialogue that renders its `children` into an element outside `yew`'s control,
|
||||
identified by the `id="modal_host"`.
|
||||
|
||||
```rust
|
||||
use yew::{html, create_portal, function_component, Children, Properties, Html};
|
||||
|
|
|
@ -289,8 +289,8 @@ for the behaviour of `JsCast` but with the smaller scope of events and their tar
|
|||
similar to what you would using `JsCast`.
|
||||
:::
|
||||
|
||||
The `TargetCast` trait builds off of `JsCast` and is specialized towards getting typed event targets
|
||||
from events.
|
||||
The `TargetCast` trait is built on top of `JsCast` and is specialized towards getting typed event
|
||||
targets from events.
|
||||
|
||||
`TargetCast` comes with Yew so no need to add a dependency in order to use the trait methods on events
|
||||
but it works in a very similar way to `JsCast`.
|
||||
|
|
|
@ -7,7 +7,7 @@ sidebar_label: wasm-bindgen
|
|||
high-level interactions between Wasm modules and JavaScript; it is built with Rust by
|
||||
[The Rust and WebAssembly Working Group](https://rustwasm.github.io/).
|
||||
|
||||
Yew builds off `wasm-bindgen` and specifically uses the following of its crates:
|
||||
Yew uses `wasm-bindgen` to interact with the browser through a number of crates:
|
||||
|
||||
- [`js-sys`](https://crates.io/crates/js-sys)
|
||||
- [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen)
|
||||
|
@ -15,7 +15,7 @@ Yew builds off `wasm-bindgen` and specifically uses the following of its crates:
|
|||
- [`web-sys`](https://crates.io/crates/web-sys)
|
||||
|
||||
This section will explore some of these crates in a high level in order to make it easier to understand
|
||||
and use `wasm-bindgen` APIs with Yew. For a more in-depth guide into `wasm-bindgen` and it's associated
|
||||
and use `wasm-bindgen` APIs with Yew. For a more in-depth guide to `wasm-bindgen` and its associated
|
||||
crates then check out [The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/wasm-bindgen/).
|
||||
|
||||
For documentation on the above crates check out [`wasm-bindgen docs.rs`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/index.html).
|
||||
|
@ -33,14 +33,13 @@ types / traits you will see pop up again and again.
|
|||
|
||||
### `#[wasm_bindgen]` macro
|
||||
|
||||
The `#[wasm_bindgen]` macro, in a high level view, is your translator between Rust and JavaScript, it
|
||||
allows you to describe imported JavaScript types in terms of Rust and vice versa. Using this macro
|
||||
is more advanced, and you shouldn't need to reach for it unless you are trying to interop with an
|
||||
external JavaScript library. The `js-sys` and `web-sys` crates are essentially imported types using
|
||||
this macro for JavaScript types and the browser API respectively.
|
||||
The `#[wasm_bindgen]` macro provides an interface between Rust and JavaScript, providing a system
|
||||
for translating between the two. Using this macro is more advanced, and you shouldn't need to reach
|
||||
for it unless you are trying to use an external JavaScript library. The `js-sys` and `web-sys`
|
||||
crates expose `wasm-bindgen` definitions for built-in Javascript types and browser APIs.
|
||||
|
||||
Let's go over a simple example of using the `#[wasm-bindgen]` macro to import some specific flavours
|
||||
of the [`console.log`](https://developer.mozilla.org/en-US/docs/Web/API/Console/log).
|
||||
of the [`console.log`](https://developer.mozilla.org/en-US/docs/Web/API/Console/log) function.
|
||||
|
||||
```rust ,no_run
|
||||
use wasm_bindgen::prelude::*;
|
||||
|
@ -78,14 +77,15 @@ _This example was adapted from [1.2 Using console.log of The `wasm-bindgen` Guid
|
|||
|
||||
### Simulating inheritance
|
||||
|
||||
Inheritance between JavaScript classes is a big part of the language and is a major part of how the
|
||||
Document Object Model (DOM). When types are imported using `wasm-bindgen` you can
|
||||
also add attributes that describe its inheritance.
|
||||
Inheritance between JavaScript classes is a core feature of the Javascript language, and the DOM
|
||||
(Document Object Model) is designed around it. When types are imported using `wasm-bindgen` you can
|
||||
also add attributes that describe their inheritance.
|
||||
|
||||
In Rust this inheritance is simulated using the [`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html)
|
||||
In Rust this inheritance is represented using the [`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html)
|
||||
and [`AsRef`](https://doc.rust-lang.org/std/convert/trait.AsRef.html) traits. An example of this
|
||||
might help; so say you have three types `A`, `B`, and `C` where `C` extends `B` which in turn
|
||||
extends `A`.
|
||||
|
||||
When importing these types the `#[wasm-bindgen]` macro will implement the `Deref` and `AsRef`
|
||||
traits in the following way:
|
||||
|
||||
|
@ -99,8 +99,7 @@ it was `&B` or `&A`.
|
|||
|
||||
Its important to note that every single type imported using `#[wasm-bindgen]` has the same root type,
|
||||
you can think of it as the `A` in the example above, this type is [`JsValue`](#jsvalue) which has
|
||||
its own section
|
||||
below.
|
||||
its own section below.
|
||||
|
||||
_[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/extends.html)_
|
||||
|
||||
|
@ -109,19 +108,19 @@ _[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/w
|
|||
This is a representation of an object owned by JavaScript, this is a root catch-all type for `wasm-bindgen`.
|
||||
Any type that comes from `wasm-bindgen` is a `JsValue` and this is because JavaScript doesn't have
|
||||
a strong type system so any function that accepts a variable `x` doesn't define its type so `x` can be
|
||||
a valid JavaScript value; hence `JsValue`. So when you are working with imported functions or types that
|
||||
a valid JavaScript value; hence `JsValue`. If you are working with imported functions or types that
|
||||
accept a `JsValue`, then any imported value is _technically_ valid.
|
||||
|
||||
`JsValue` can be accepted by a function but that function may still only expect certain types and this
|
||||
`JsValue` can be accepted by a function but that function may still only accept certain types and this
|
||||
can lead to panics - so when using raw `wasm-bindgen` APIs check the documentation of the JavaScript
|
||||
being imported whether an exception will be caused if that value is not a certain type.
|
||||
being imported as to whether an exception (panic) will be raised if that value is not a certain type.
|
||||
|
||||
_[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)._
|
||||
|
||||
### [`JsCast`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html)
|
||||
|
||||
Rust has a strong type system and JavaScript...doesn't 😞 So in order for Rust to maintain these
|
||||
strong types but still be convenient the web assembly group came up with a pretty neat trait `JsCast`.
|
||||
Rust has a strong type system and JavaScript...doesn't 😞. In order for Rust to maintain these
|
||||
strong types but still be convenient the WebAssembly group came up with a pretty neat trait `JsCast`.
|
||||
Its job is to help you move from one JavaScript "type" to another, which sounds vague, but it means
|
||||
that if you have one type which you know is really another then you can use the functions of `JsCast`
|
||||
to jump from one type to the other. It's a nice trait to get to know when working with `web-sys`,
|
||||
|
@ -195,9 +194,10 @@ _[`js-sys` documentation](https://rustwasm.github.io/wasm-bindgen/api/js_sys/ind
|
|||
## [`wasm-bindgen-futures`](https://crates.io/crates/wasm-bindgen-futures)
|
||||
|
||||
The `wasm-bindgen-futures` crate provides a bridge for working with JavaScript Promise types as a
|
||||
Rust Future, and similarly contains utilities to turn a rust Future into a JavaScript Promise.
|
||||
This can be useful when working with asynchronous or otherwise blocking work in Rust (wasm),
|
||||
and provides the ability to interoperate with JavaScript events and JavaScript I/O primitives.
|
||||
Rust [`Future`](https://doc.rust-lang.org/stable/std/future/trait.Future.html), and contains
|
||||
utilities to turn a rust Future into a JavaScript Promise. This can be useful when working with
|
||||
asynchronous or otherwise blocking work in Rust (wasm), and provides the ability to interoperate
|
||||
with JavaScript events and JavaScript I/O primitives.
|
||||
|
||||
There are three main interfaces in this crate currently:
|
||||
|
||||
|
|
|
@ -31,13 +31,15 @@ cd yew-app
|
|||
|
||||
### Run a hello world example
|
||||
|
||||
To verify the Rust environment is setup, run the initial project using the cargo build tool. After output about the build process, you should see the expected "Hello World" message.
|
||||
To verify the Rust environment is setup, run the initial project using `cargo run`. You should see
|
||||
a "Hello World!" message.
|
||||
|
||||
```bash
|
||||
cargo run
|
||||
# output: Hello World!
|
||||
```
|
||||
|
||||
### Converting the project into a Yew web application
|
||||
### Setting up the project as a Yew web application
|
||||
|
||||
To convert this simple command line application to a basic Yew web application, a few changes are needed.
|
||||
|
||||
|
@ -58,12 +60,13 @@ yew = "0.19"
|
|||
|
||||
#### Update main.rs
|
||||
|
||||
We need to generate a template which sets up a root Component called `App` which renders a button that updates its value when clicked.
|
||||
Replace the contents of `src/main.rs` with the following code.
|
||||
We need to generate a template which sets up a root Component called `App` which renders a button
|
||||
that updates its value when clicked. Replace the contents of `src/main.rs` with the following code.
|
||||
|
||||
:::note
|
||||
The line `yew::start_app::<App>()` inside `main()` starts your application and mounts it to the page's `<body>` tag.
|
||||
If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::<App>(..)`.
|
||||
The call to `yew::start_app::<App>()` inside the `main` function starts your application and mounts
|
||||
it to the page's `<body>` tag. If you would like to start your application with any dynamic
|
||||
properties, you can instead use `yew::start_app_with_props::<App>(..)`.
|
||||
:::
|
||||
|
||||
```rust ,no_run, title=main.rs
|
||||
|
@ -115,7 +118,7 @@ Run the following command to build and serve the application locally.
|
|||
trunk serve
|
||||
```
|
||||
|
||||
Trunk will helpfully rebuild your application if you modify any of its files.
|
||||
Trunk will rebuild your application if you modify any of its source code files.
|
||||
|
||||
## Congratulations
|
||||
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
title: "Examples"
|
||||
---
|
||||
|
||||
The Yew repository is chock-full of [examples] (in various states of maintenance).
|
||||
The Yew repository is contains many [examples] (in various states of maintenance).
|
||||
We recommend perusing them to get a feel for how to use different features of the framework.
|
||||
We also welcome Pull Requests and issues for when they inevitably get neglected and need some ♥️
|
||||
|
||||
|
|
|
@ -5,7 +5,7 @@ description: "Set yourself up for success"
|
|||
---
|
||||
|
||||
|
||||
Your local development environment will need a couple of tools to compile, build, package and debug your Yew application.
|
||||
You will need a couple of tools to compile, build, package and debug your Yew application.
|
||||
When getting started, we recommend using [Trunk](https://trunkrs.dev/). Trunk is a WASM web application
|
||||
bundler for Rust.
|
||||
|
||||
|
@ -14,16 +14,17 @@ bundler for Rust.
|
|||
To install Rust, follow the [official instructions](https://www.rust-lang.org/tools/install).
|
||||
|
||||
:::important
|
||||
The minimum supported Rust version (MSRV) for Yew is `1.49.0`. Older versions can cause unexpected issues accompanied
|
||||
by incomprehensible error messages. You can check your toolchain version using `rustup show` (under "active toolchain")
|
||||
or alternatively `rustc --version`. To update your toolchain, run `rustup update`.
|
||||
The minimum supported Rust version (MSRV) for Yew is `1.56.0`. Older versions can cause unexpected
|
||||
issues accompanied by incomprehensible error messages. You can check your toolchain version using
|
||||
`rustup show` (under "active toolchain") or alternatively `rustc --version`. To update your
|
||||
toolchain, run `rustup update`.
|
||||
:::
|
||||
|
||||
## Install WebAssembly target
|
||||
|
||||
Rust can compile source codes for different "targets" (e.g. different processors). The compilation target for
|
||||
browser-based WebAssembly is called `wasm32-unknown-unknown`.
|
||||
The following command will add this target to your development environment.
|
||||
Rust can compile source codes for different "targets" (e.g. different processors). The compilation
|
||||
target for browser-based WebAssembly is called `wasm32-unknown-unknown`. The following command will
|
||||
add the WebAssembly target to your development environment.
|
||||
|
||||
```shell
|
||||
rustup target add wasm32-unknown-unknown
|
||||
|
@ -31,7 +32,8 @@ rustup target add wasm32-unknown-unknown
|
|||
|
||||
## Install Trunk
|
||||
|
||||
Trunk is the recommended tool for managing deployment and packaging, and will be used throughout the documentation and examples.
|
||||
Trunk is the recommended tool for managing deployment and packaging, and is used throughout the
|
||||
documentation and examples.
|
||||
|
||||
```shell
|
||||
# note that this might take a while to install, because it compiles everything from scratch
|
||||
|
|
|
@ -6,11 +6,12 @@ title: "From 0.1.0 to 0.2.0"
|
|||
|
||||
The `Context` and `Job` Agents have been removed in favour of Yew's Context API.
|
||||
|
||||
You can see the updated [`pub_sub`](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example about how to use Context API.
|
||||
You can see the updated [`pub_sub`](https://github.com/yewstack/yew/tree/master/examples/pub_sub)
|
||||
which demonstrate how to use the context API.
|
||||
|
||||
For users of `yew_agent::utils::store`, you may switch to third party solutions like: [Yewdux](https://github.com/intendednull/yewdux) or [Bounce](https://github.com/futursolo/bounce).
|
||||
|
||||
## `Threaded` is separated into `PublicAgent` and `PrivateAgent`
|
||||
## `Threaded` has been separated into `PublicAgent` and `PrivateAgent`
|
||||
|
||||
Replace `use yew_agent::Threaded;` with `use yew_agent::PublicAgent;`.
|
||||
|
||||
|
|
|
@ -2,6 +2,8 @@
|
|||
title: "From 0.15.0 to 0.16.0"
|
||||
---
|
||||
|
||||
The router API has been completely redone in `0.16.0`.
|
||||
The router API has been completely rewritten in `0.16.0`.
|
||||
|
||||
There would be to many things to list out here, so we highly recommend to read up on the [router documentation](./../../concepts/router) and adapt your app accordingly.
|
||||
Because it is such a radical change, there are too many things to list out here, so we highly
|
||||
recommend to read the updated [router documentation](./../../concepts/router) and adapt your app
|
||||
accordingly.
|
||||
|
|
|
@ -7,11 +7,12 @@ import TabItem from '@theme/TabItem';
|
|||
|
||||
`Yew 0.19.0` has changed a lot, thus this migration will not cover ALL of the changes.
|
||||
|
||||
Instead only the most impacting changes are mentioned and the rest should be picked up by cargo.
|
||||
Instead only the most impactful changes are mentioned and the rest should be picked up by `cargo`.
|
||||
|
||||
## html! requirement for braces around most props
|
||||
## `html!` requirement for braces around most props
|
||||
|
||||
Put it simply almost all the time you have to provide braces for props:
|
||||
The syntax of the `html!` macro has been updated, such that in most cases you will need to enclose
|
||||
props with braces.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Invalid" label="Invalid">
|
||||
|
@ -40,7 +41,7 @@ html!{
|
|||
</TabItem>
|
||||
<TabItem value="Shorthand" label="Shorthand">
|
||||
|
||||
Also now you can use a shorthand if prop and variable names are the same:
|
||||
Shorthand initialization has been added:
|
||||
|
||||
```rust {4}, ignore
|
||||
let age = 1;
|
||||
|
@ -54,9 +55,10 @@ html!{
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
There is a community provided regex to help with this change, though we cant promise it will work all the time.
|
||||
There is a community provided regex to help automate the update, though we can't promise it will work
|
||||
all the time.
|
||||
|
||||
It for sure breaks when it encounters closures, specifically `|_|` syntax.
|
||||
It breaks when it encounters closures (specifically the `|_|` syntax).
|
||||
|
||||
find with `=(?![{">=\s])([^\s></]*(\s!{0,1}[=|&]{2}\s[^\s></]*)*)`
|
||||
|
||||
|
@ -64,9 +66,10 @@ replace with `={$1}`
|
|||
|
||||
## Function components
|
||||
|
||||
[Function components](./../../concepts/function-components/introduction) are a brand new way to write components that require less boilerplate than their structural counter part.
|
||||
[Function components](./../../concepts/function-components/introduction) are a brand new way to write components that
|
||||
requires less boilerplate than their structural counterpart.
|
||||
|
||||
While this change does not force you to change your codebase, this migration time is a good opportunity to start using them in your codebase.
|
||||
While this change does not force you to change your codebase, as you migrate from `0.18` to `0.19`, this migration time might present a good opportunity to start using them in your codebase.
|
||||
|
||||
## Struct components lifecycle methods and ctx
|
||||
|
||||
|
@ -128,8 +131,9 @@ html! {
|
|||
|
||||
## New crate - yew-agent
|
||||
|
||||
Yew agents were removed to their separate crate, see [yew agents migration guide](./../yew-agent/from-0_0_0-to-0_1_0)
|
||||
Yew agents were removed to a separate crate, see [yew agents migration guide](./../yew-agent/from-0_0_0-to-0_1_0)
|
||||
|
||||
## Ending note
|
||||
|
||||
We are sorry if some things are not covered in this guide as it was truly a huge update and we hope that the uncovered issues will be clearly explained by cargo check/build/clippy.
|
||||
We are sorry if some things are not covered in this guide as it was truly a huge update and we hope
|
||||
that the uncovered issues will be clearly explained in error messages emitted by the Rust compiler.
|
||||
|
|
|
@ -41,6 +41,5 @@ Status of all major initiatives can be tracked on the Yew Github [project board]
|
|||
### Pain points
|
||||
|
||||
* [Component boilerplate](https://github.com/yewstack/yew/issues/830)
|
||||
* Fetch API
|
||||
* [Agents](https://github.com/yewstack/yew/projects/6)
|
||||
|
||||
|
|
|
@ -11,10 +11,10 @@ Support for [shallow rendering](https://github.com/yewstack/yew/issues/1413) can
|
|||
|
||||
## Snapshot testing
|
||||
|
||||
Yew exposes `yew::tests::layout_tests` module to facilitate with snapshot testing of components.
|
||||
Yew exposes the `yew::tests::layout_tests` module to facilitate with snapshot testing of components.
|
||||
|
||||
:::important contribute
|
||||
Help improve documentation for snapshot testing.
|
||||
Help improve the documentation for snapshot testing.
|
||||
:::
|
||||
|
||||
## wasm_bindgen_test
|
||||
|
|
|
@ -289,8 +289,8 @@ for the behaviour of `JsCast` but with the smaller scope of events and their tar
|
|||
similar to what you would using `JsCast`.
|
||||
:::
|
||||
|
||||
The `TargetCast` trait builds off of `JsCast` and is specialized towards getting typed event targets
|
||||
from events.
|
||||
The `TargetCast` trait is built on top of `JsCast` and is specialized towards getting typed event
|
||||
targets from events.
|
||||
|
||||
`TargetCast` comes with Yew so no need to add a dependency in order to use the trait methods on events
|
||||
but it works in a very similar way to `JsCast`.
|
||||
|
|
|
@ -8,7 +8,7 @@ slug: /concepts/wasm-bindgen
|
|||
high-level interactions between Wasm modules and JavaScript; it is built with Rust by
|
||||
[The Rust and WebAssembly Working Group](https://rustwasm.github.io/).
|
||||
|
||||
Yew builds off `wasm-bindgen` and specifically uses the following of its crates:
|
||||
Yew is built on `wasm-bindgen` and specifically uses the following of its crates:
|
||||
|
||||
- [`js-sys`](https://crates.io/crates/js-sys)
|
||||
- [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen)
|
||||
|
|
Loading…
Reference in New Issue