Skip to content

Commit

Permalink
Overhaul examples (#1559)
Browse files Browse the repository at this point in the history
* remove old files

* update counter

* update crm example

* Add readme for counter

* update custom_components

* update webgl example

* update two_apps

* update todomvc

* mark special case multithread

* update dashboard

* update examples readme

* file_upload example

* fragments example

* futures example

* game_of_life example

* inner_html example

* js_callback example

* keyed_list example

* remove large_table

* remove minimal

* mount_point example

* I can't count apparently

* nested_list example

* node_refs example

* timer example

* store example

* pub_sub example

* rip npm_and_my_sanity

* use a title:tm:

* clean up multi_thread

* fix format

* boids part 1

* boids part 2

* add workflow

See: <siku2#13>

* remove my little scratchpad again

* add boids to examples table

* runtime-generated list in  nested_list example

* update workflow

* first batch of yewtil examples

* clippy "futures"

* remove old yew-router examples

* add a new router example to the main examples

* remove remaining yewtil examples

* more progress

* update for testing purposes

* author list

* improve content generation

* revert this mistake

I thought it would be great to use `unimplemented!()` in case the component doesn't have any properties.
This helps avoid the mistake of forgetting to update the change method when adding props later on.
What I didn't consider is that just because the props are () that doesn't mean that Yew isn't going to call it...
So yeah, it's still a good idea for update, but certainly not for change.

* missed a few

* turn router switch example into test

* seems to be working

* make it possible to host the router example on a sub-path

* create a 404 file for SPA

* remove the three examples and update table

* remove the 404 file because it isn't working anyway

* fix small router issue relating to the sub-path hack
  • Loading branch information
siku2 authored Sep 21, 2020
1 parent 1ed78fa commit c946b99
Show file tree
Hide file tree
Showing 247 changed files with 6,315 additions and 6,110 deletions.
65 changes: 65 additions & 0 deletions .github/workflows/publish-examples.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: Publish Examples
on:
push:
branches: [master]

jobs:
publish:
runs-on: ubuntu-latest
env:
# leave empty for /
PUBLIC_URL_PREFIX: ""

steps:
- uses: actions/checkout@v2
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
target: wasm32-unknown-unknown
override: true
profile: minimal

- uses: actions/cache@v2
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.toml') }}
restore-keys: |
cargo-${{ runner.os }}-
- name: Install trunk
run: cargo install trunk wasm-bindgen-cli

- name: Build examples
run: |
output="$(pwd)/dist"
for path in examples/*; do
if [[ ! -d $path ]]; then
continue
fi
example=$(basename "$path")
# multi_thread doesn't work yet. See <https://github.com/thedodd/trunk/issues/40>.
if [[ "$example" == "multi_thread" ]]; then
continue
fi
echo "building: $example"
(
cd "$path"
dist_dir="$output/$example"
export PUBLIC_URL="$PUBLIC_URL_PREFIX/$example"
trunk build --release --dist "$dist_dir" --public-url "$PUBLIC_URL"
)
done
- name: Deploy
uses: peaceiris/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
22 changes: 2 additions & 20 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,49 +10,31 @@ members = [
"yew-router",
"yew-router-macro",
"yew-router-route-parser",
"yew-router/examples/minimal",
"yew-router/examples/router_component",
"yew-router/examples/switch",

# Utilities
"yewtil",
"yewtil-macro",
"yewtil/examples/pure_component",
# "yewtil/examples/dsl",
"yewtil/examples/lrc",
"yewtil/examples/history",
"yewtil/examples/mrc_irc",
"yewtil/examples/effect",
"yewtil/examples/fetch",
"yewtil/examples/futures",
"yewtil/examples/function_component",

# dsl
"yew-dsl",

# Examples
"examples/counter",
"examples/crm",
"examples/custom_components",
"examples/dashboard",
"examples/file_upload",
"examples/fragments",
"examples/futures_wp",
"examples/futures",
"examples/game_of_life",
"examples/inner_html",
"examples/js_callback",
"examples/keyed_list",
"examples/large_table",
"examples/minimal",
"examples/minimal_wp",
"examples/mount_point",
"examples/multi_thread",
"examples/nested_list",
"examples/node_refs",
"examples/npm_and_rest",
"examples/pub_sub",
"examples/router",
"examples/store",
"examples/textarea",
"examples/timer",
"examples/todomvc",
"examples/two_apps",
Expand Down
6 changes: 1 addition & 5 deletions examples/.gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1 @@
*/static/package.json
*/static/wasm_bg.wasm
*/static/wasm_bg.d.ts
*/static/wasm.d.ts
*/static/wasm.js
*/dist/
111 changes: 37 additions & 74 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,15 @@
# Yew Examples

In order to run the examples, we provide the `run_example.sh` script.
This script takes care of compiling the example and runs a web server for you.
All that's left is for you to play around with the examples :).

> **A note for Windows users:**<br>
> Depending on how you installed `git` you will already have a bash emulator at your disposal. This allows you to run the `run_example.sh` script (and any other bash script) normally.<br>
> See <https://gitforwindows.org/#bash> for more information.
>
> We're always trying to improve the developer experience for developers across all platforms.
> There's an ongoing effort to replace the bash scripts with a Rust command line tool ([#1418](https://github.com/yewstack/yew/issues/1418)).
> If at any point you encounter an issue, don't hesitate to ask a question or open an issue.
## Dependencies

Before we can run the examples we need to get a few things ready.

Some examples currently use `wasm-bindgen` and others use `wasm-pack`.
You can install them both using the following command:
The examples are built with [trunk](https://github.com/thedodd/trunk).
You can install it with the following command:

```bash
cargo install wasm-pack wasm-bindgen-cli
# at some point in the future, trunk should automatically download wasm-bindgen for you
cargo install trunk wasm-bindgen-cli
```

### Optional dependencies

We've written a small web server which you can use to serve the built examples. In order to
use it, you'll need to have installed Python (3.6 or greater).
You can also use a different web server, provided that it can serve static files from a directory.

> **Note:**<br>
> Some examples don't have an `index.html` file in their static directory.
> The python web server handles this by serving a default index file.
> If you aren't using it, you will need to create the index file manually.
One alternative to the built-in web server there is an extension for [Visual Studio Code](https://code.visualstudio.com/) called [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer).
This extension is used to serve static files.
To do so, open the `index.html` file in the static directory of the example you wish to run and press "Open with Live Server" in the context menu.

## Run an example

```bash
Expand All @@ -48,54 +20,45 @@ git clone https://github.com/yewstack/yew.git
cd yew/examples

# run the "todomvc" example
./run_example.sh todomvc
cd todomvc
trunk serve --release
```

## Script options

The general structure of the command looks like this:<br>
`./run_example.sh <example> [OPTIONS]`

`<example>` is the name of the example (i.e. the name of the directory).

The following table describes all possible options:

| Option | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `--debug`<br>`--release` | Specifies which profile to use for `cargo build`. Defaults to `--debug`. |
| `--build-only` | Disables the built-in server.<br>Use this if you don't have Python installed or if you want to use your own server. |
Some examples might require additional steps.
In this case, instructions can be found in the example's `README` file.

## List of examples

| Example | Description | Has README |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | :--------: |
| [counter](counter) | A single component which displays a stateful number. The number can be incremented and decremented using buttons ||
| [crm](crm) | See the `README` file for details ||
| [custom_components](custom_components) | Demonstrates the use of components ||
| [dashboard](dashboard) | Uses the `fetch` and `websocket` services to load external data ||
| [file_upload](file_upload) | Uses the `reader` service to read the content of user uploaded files ||
| [fragments](fragments) | Similar to the counter example but demonstrating the use of [fragments](https://yew.rs/docs/concepts/html/lists#fragments) ||
| [futures_wp](futures_wp) | Demonstrates how you can use futures and async code with Yew. Features a Markdown renderer. ||
| [game_of_life](game_of_life) | Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) ||
| [inner_html](inner_html) | Embeds an external document as raw HTML by manually managing the element ||
| [js_callback](js_callback) | Interacts with JavaScript code ||
| [keyed_list](keyed_list) | Demonstrates how to use keys to improve the performance of lists ||
| [large_table](large_table) | Renders a big table which highlights the selected cell ||
| [minimal](minimal) | A simple button that listens to click events ||
| [minimal_wp](minimal) | Same as the minimal example but using `wasm-pack` ||
| [mount_point](mount_point) | Shows how to mount the root component to a custom element ||
| [multi_thread](multi_thread) | Demonstrates the use of Web Workers to offload computation to the background ||
| [nested_list](nested_list) | Renders a styled list which tracks hover events ||
| [node_refs](node_refs) | Uses a [`NodeRef`](https://yew.rs/docs/concepts/components/refs) to focus the input element under the cursor ||
| [npm_and_rest](npm_and_rest) | A more elaborate demonstration of the `fetch` service ||
| [pub_sub](pub_sub) | Cross-component communication using [Agents](https://yew.rs/docs/concepts/agents) ||
| [store](store) | Showcases the `yewtil::store` API ||
| [textarea](textarea) | Shows how to use the value of a textarea or input tag ||
| [timer](timer) | Demonstrates the use of the interval and timeout services ||
| [todomvc](todomvc) | Implementation of the [TodoMVC](http://todomvc.com/) app ||
| [two_apps](two_apps) | Runs two separate Yew apps at the same time ||
| [webgl](webgl) | Controls a [WebGL canvas](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL) from Yew ||
| Example | Description |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [boids](boids) | Yew port of [Boids](https://en.wikipedia.org/wiki/Boids) |
| [counter](counter) | Simple counter which can be incremented and decremented |
| [crm](crm) | Shallow customer relationship management tool |
| [dashboard](dashboard) | Uses the `fetch` and `websocket` services to load external data |
| [file_upload](file_upload) | Uses the `reader` service to read the content of user uploaded files |
| [futures](futures) | Demonstrates how you can use futures and async code with Yew. Features a Markdown renderer. |
| [game_of_life](game_of_life) | Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) |
| [inner_html](inner_html) | Embeds an external document as raw HTML by manually managing the element |
| [js_callback](js_callback) | Interacts with JavaScript code |
| [keyed_list](keyed_list) | Demonstrates how to use keys to improve the performance of lists |
| [mount_point](mount_point) | Shows how to mount the root component to a custom element |
| [multi_thread](multi_thread) | Demonstrates the use of Web Workers to offload computation to the background |
| [nested_list](nested_list) | Renders a styled list which tracks hover events |
| [node_refs](node_refs) | Uses a [`NodeRef`](https://yew.rs/docs/concepts/components/refs) to focus the input element under the cursor |
| [pub_sub](pub_sub) | Cross-component communication using [Agents](https://yew.rs/docs/concepts/agents) |
| [router](router) | The best yew blog built with `yew-router` |
| [store](store) | Showcases the `yewtil::store` API |
| [timer](timer) | Demonstrates the use of the interval and timeout services |
| [todomvc](todomvc) | Implementation of [TodoMVC](http://todomvc.com/) |
| [two_apps](two_apps) | Runs two separate Yew apps which can communicate with each other |
| [webgl](webgl) | Controls a [WebGL canvas](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL) from Yew |

## Next steps

Have a look at Yew's [starter templates](https://yew.rs/docs/getting-started/starter-templates) when starting a project using Yew – they can significantly simplify things.

## Help out

Most examples have an "improvements" section in their README.md which lists ways to improve the example.

The biggest point of improvement is the presentation of the examples (ex. styling).
2 changes: 0 additions & 2 deletions examples/boids/.gitignore

This file was deleted.

8 changes: 3 additions & 5 deletions examples/boids/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,8 @@ authors = ["motoki saito <[email protected]>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
rand = { version = "0.7.3", features = ["wasm-bindgen"] }
anyhow = "1.0"
rand = { version = "0.7", features = ["wasm-bindgen"] }
serde = { version = "1.0", features = ["derive"] }
yew = { path = "../../yew" }
31 changes: 31 additions & 0 deletions examples/boids/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Boids Example

A version of [Boids](https://en.wikipedia.org/wiki/Boids) implemented in Yew.

This example doesn't make use of a [Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API),
instead, each boid has its own element demonstrating the performance of Yew's virtual DOM.

## Running

You should run this example with the `--release` flag:

```bash
trunk serve --release
```

## Concepts

The example uses [`IntervalService`] to drive the game loop.

## Improvements

- Add the possibility to switch the behaviour from flocking to scattering by inverting the cohesion rule so that boids avoid each other.
This should also invert the color adaption to restore some variety.
- Add keyboard shortcuts (using the `KeyboardService`) for the actions.
- Make it possible to hide the settings panel entirely
- Bigger boids should accelerate slower than smaller ones
- Share settings by encoding them into the URL
- Resize the boids when "Spacing" is changed.
The setting should then also be renamed to something like "Size".

[`intervalservice`]: https://docs.rs/yew/latest/yew/services/struct.IntervalService.html
11 changes: 11 additions & 0 deletions examples/boids/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Yew • Boids</title>

<link rel="stylesheet" href="index.scss" />
</head>

<body></body>
</html>
Loading

0 comments on commit c946b99

Please sign in to comment.