add english website documentation

yewstack · Nov 16, 2021 · 1d53284 · 1d53284
1 parent 21ce197
commit 1d53284
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 0 deletions.
diff --git a/packages/website-test/Cargo.toml b/packages/website-test/Cargo.toml
@@ -23,6 +23,7 @@ yew-router = { path = "../../packages/yew-router/" }
 [dev-dependencies.web-sys]
 version = "0.3"
 features = [
+    "Document",
     "Element",
     "EventTarget",
     "HtmlElement",

diff --git a/packages/website-test/build.rs b/packages/website-test/build.rs
@@ -16,12 +16,17 @@ fn main() {
     let pattern = format!("{}/../../website/docs/**/*.md", home);
     let base = format!("{}/../../website", home);
     let base = Path::new(&base).canonicalize().unwrap();
+    let dir_pattern = format!("{}/../../website/docs/**", home);
+    for dir in glob(&dir_pattern).unwrap() {
+        println!("cargo:rerun-if-changed={}", dir.unwrap().display());
+    }
 
     let mut level = Level::default();
 
     for entry in glob(&pattern).unwrap() {
         let path = entry.unwrap();
         let path = Path::new(&path).canonicalize().unwrap();
+        println!("cargo:rerun-if-changed={}", path.display());
         let rel = path.strip_prefix(&base).unwrap();
 
         let mut parts = vec![];

diff --git a/website/docs/advanced-topics/portals.md b/website/docs/advanced-topics/portals.md
@@ -0,0 +1,35 @@
+---
+title: "Portals"
+description: "Rendering into out-of-tree DOM nodes"
+---
+
+## How to think about portals?
+
+Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+`create_portal(child, host)` returns a `Html` value that renders `child` not hierarchically under its parent component,
+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>`.
+
+```rust
+use yew::{html, create_portal, function_component};
+
+#[function_component(Modal)]
+fn modal() -> Html {
+    let modal_host = gloo_utils::document()
+        .get_element_by_id("modal_host")
+        .expect("a #modal_host element");
+
+    create_portal(
+        html! {
+            <div>{"Modal dialog mounted into another element"}</div>
+        },
+        modal_host.into(),
+    )
+}
+```
+
+## Further reading
+- [Portals example](https://github.com/yewstack/yew/tree/master/examples/portals)
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -91,6 +91,7 @@ module.exports = {
             items: [
                 "advanced-topics/how-it-works",
                 "advanced-topics/optimizations",
+                "advanced-topics/portals",
             ]
         },
         {