yewstack/docs

docs's Issues

I think it's batch_callback, not send_message_batch.

The reason is that it writes "a Callback<IN> is returned".

docs/src/concepts/components/callbacks.md

Lines 23 to 27 in 2bdbafc

	### send\_message\_batch
	Registers a callback that sends a batch of many messages at once when it is executed. If any of the
	messages cause the component to re-render, the component will re-render after all messages in the
	batch have been processed. A `Fn(IN) -> COMP::Message` is provided and a `Callback<IN>` is returned.

send_message_batch does not return Callback<IN> , but batch_callback return Callback<IN>.

If it's correct, I create a pull request.

Add an explanation of the WebSocket service.

The Websocket service is only documented in the API documentation. An explanation of how it works and how to use it should be included here.

Add a diagram of the Agent lifecycle

DOC TODO: https://yew.rs/docs/concepts/agents#lifecycle

Describe the lifecycle methods of an Agent and the lifetime of each type of Agent (Job, Context, Private, Public)

    /// Creates an instance of an agent.
    fn create(link: AgentLink<Self>) -> Self;

    /// This method called on every update message.
    fn update(&mut self, msg: Self::Message);

    /// This method called on when a new bridge created.
    fn connected(&mut self, _id: HandlerId) {}

    /// This method called on every incoming message.
    fn handle_input(&mut self, msg: Self::Input, id: HandlerId);

    /// This method called on when a new bridge destroyed.
    fn disconnected(&mut self, _id: HandlerId) {}

    /// This method called when the agent is destroyed.
    fn destroy(&mut self) {}

Add a diagram of the component lifecycle

Something like:

Render Cycle

1. create()
2. view()
3. (yew renders to page)
4. mounted()

Note: should explain how children components are rendered... (Parent view -> Child view -> Child mount -> Parent mount)

Update Cycle

1. (trigger event / callback / send message)
2. update()
3. (optional) view()
4. (yew renders to page)

Change Cycle

1. (render component with new props)
2. update()
3. (optional) view()
4. (yew renders to page)

DOC TODO: https://yew.rs/docs/concepts/components#lifecycle

Duplicate entry in Examples

The Examples page for the docs has a duplicate entry for one of the examples:

• Todo App
• Custom Components
• Multi-threading (Agents)
• Nested Components <--
• Timer Service
• Nested Components <--

Home page in chinese

I can't read the English homepage anymore because it changed to Chinese 😢

Was this commit intended?

Document dynamic tags in html section

See yewstack/yew#1266.

Add instructions for how to produce small release binaries

Improve documentation around ComponentLink usage

We have a page describing callbacks but it's lacking examples and a clear explanation of how to properly use ComponentLink beyond creating callbacks.

Use doc-comment to check code snippets

Not sure what the CI story is for this yet but it would be nice to verify all the code snippets with this tool: https://github.com/guillaumegomez/doc-comment

Build a Sample App code in the getting started section does not compile

The code in the Build a Sample App page in the getting started section does not compile.

If the App struct is changed from:
struct App { clicked: bool, onclick: Callback<()>, }

To (also updating the use yew:: to include ClickEvent):
struct App { clicked: bool, onclick: Callback<ClickEvent>, }

The sample app compiles.

Explain the format module in depth

DOC TODO: https://yew.rs/docs/concepts/services/format

The Format API is not very user-friendly at the moment and needs better documentation.

1. Explain the difference between text and binary formats
2. Explain how format is used for the storage, websocket, and fetch services
3. Provide examples on how to destructure format results

Adoptation of a formal style guide

To standardise the documentation and give a coherent and consistent reading for all readers, I think we should adopt a style guide (on a very informal basis – i.e. this is ideally what we want our documentation to look like but we'd rather have documentation not in keeping with the style guide than no documentation).
Something like The Chicago Manual of Style or Hart's Rules would do the trick.

Sample code error .

In "Use html!", Elements -> Listeners -> Component Handler

struct MyComponent {
    link: ComponentLink<Self>,
}

enum Msg {
    Click,
}

impl Component for MyComponent {
    type Message = Msg;
    type Properties = ();

    fn create(_: Self::Properties, link: ComponentLink<Self>) -> Self {
        MyComponent { link }
    }

    fn update(&mut self, msg: Self::Message) -> ShouldRender {
        match msg {
            Msg::Click => {
                // Handle Click
            }
        }
    }

    fn view(&self) -> Html<Self> {
        // Create a callback from a component link to handle it in a component
        let click_callback = self.link.send_back(|_: ClickEvent| Msg::Click);
        html! {
            <button onclick=click_callback>
                { "Click me!" }
            </button>
        }
    }
}

will report 2 errors

• 
• 

The first error was very obvious, but I couldn't just &mut self. Because this will directly disrupt the library code.

The second error is contained in the macro, so I can't understand it.

By the way , sample code in the second tab Agent Handler seems have the same issue.

The instructions at “Getting Started/Project Setup/Using wasm-pack” are extremely unclear

I’ve been trying and failing for a while to apply the instructions to the web-sys examples in the yew repository. I’ll take todomvc as an example. Everything up to and including wasm-pack build is fine. The problems start at the next line:

rollup ./main.js --format iife --file ./pkg/bundle.js

Ok, there is no main.js, so maybe I should put pkg/todomvc.js? Well,

> rollup pkg/todomvc.js --file ./pkg/bundle.js

pkg/todomvc.js → ./pkg/bundle.js...
[!] Error: Unexpected character '' (Note that you need plugins to import files that are not JavaScript)
pkg/todomvc_bg.wasm (1:0)
1: asm
…

Ok, so I need to install a wasm plugin for rollup with npm install @rollup/plugin-wasm --save-dev and add a file rollup.config.js containing

import wasm from '@rollup/plugin-wasm';

export default {
  plugins: [wasm()]
};

Now I can run rollup -c rollup.config.js pkg/todomvc.js --file pkg/bundle.js. Cool. The next step is

python -m http.server 8000

(or any other server, as the tutorial notes). Running this and visiting localhost:8000 in my browser shows me the contents of the todomvc directory. Ok, not exactly what I wanted, so I run

python -m http.server 8000 --directory static

because index.html is in the static directory. This time I get a page with the title Yew • TodoMVC, which is good, but the page is entirely blank. The console shows the error message Loading failed for the <script> with source “http://localhost:8000/todomvc.js”., which makes sense to me because todomvc.js resides in pkg. Also, I am now unsure whether using rollup even accomplished anything because I haven’t interacted with bundle.js in any way.

Maybe I’m going about this very stupidly. After all, I am a complete beginner when it comes to any sort of web development.

How do we build examples?

I've tried guessing at this at least 10 ways.

How about a guide on how to actually build the examples/. I can't get the todomvc example to even run.

Cargo web instructions are over-simplified

Turns out cargo web will not auto-install emscripten on windows and macos: koute/cargo-web#207

Error in one of pages about Properties

Samples in https://yew.rs/docs/concepts/html/components has examples of creating properties struct:

#[derive(Properties)]
pub struct Props {
    pub children: Children,
}
...
#[derive(Properties)]
pub struct Props {
    pub children: ChildrenWithProps<ListItem>,
}

But https://yew.rs/docs/concepts/components/properties states, that Props struct must implement Clone. In one of there pages are error

Hi, I wonder how you deploy the documents in different languages by gitbook

As I want to translate the remaining documents into Chinese, there is a zh_cn branch whose directory structure is different from the master branch, which makes sync documents difficult. Why not just use a zh-CN folder under src like this, thank you!

Update wasm-bindgen / wasm-pack description

In https://yew.rs/docs/getting-started/project-setup is written: We don't recommend using wasm-bindgen directly because it requires hand-writing some JavaScript to bootstrap you WebAssembly binary.

But wasm-pack and wasm-bindgen both can use same /examples/static/index.html file. No other steps are needed. Neither of them needs to use bundler when compiled with --target web

Context: yewstack/yew#1165 (comment)

cc @fbucek

'Events' vs 'Callbacks' in the documentation

'Callback' word could be confusing and is used for different concepts in Yew,
Events seems to be easier to understand in the domain of HTML component interaction

The documentation may be improved with a structure inspired by the one of StencilJS.com ( there is some similarity between the projects)

Could be something like:

...

Components

• Component: overview and basic example

• Life cycle: more details on all the steps

• properties: overview

  1. optional property with default value (basic example)
  2. optional property with a specific value (basic example)
  3. mandatory property (basic example)
  4. good to know
     • derive macro
     • PartialEq
     • Memory Speed

Events:

• emit event and trap it is parent
• events with value

Nested components

i feel this subject should be extracted from html! section

• Nested component
• Nested components with properties

Styling

i feel this subject should be extracted from more section even if there is not a lot to say for now.

• static CSS file
• dev feedbacks; use of CSSinRust
• official support in Yew under analysis ... #533

Explain how to setup a wasm-bindgen build environment

Sample app does not work with web-sys

I'm talking about the code on this page: https://yew.rs/docs/getting-started/build-a-sample-app

I know the Cargo.toml there says to install yew with the std-web feature, but I thought I could copy the code and it would work in web-sys too. When I tried that I got:

error[E0432]: unresolved import `yew::ClickEvent`
--> src/lib.rs:4:27
  |
4 | use yew::{html, Callback, ClickEvent, Component, ComponentLink, Html, ShouldRender};
  |                           ^^^^^^^^^^ no `ClickEvent` in the root
error[E0282]: type annotations needed
--> src/lib.rs:30:37
   |
30 |             onclick: link.callback(|_| Msg::Click),
   |                                     ^ consider giving this closure parameter a type
error: aborting due to 2 previous errors

I was able to fix it by replacing every reference to ClickEvent with MouseEvent.

I think it would be great to either add a version of the code that works in web-sys on that page or make a separate "Sample app" page for web-sys.

Build Environment instructions for wasm-pack leads to error

When using rollup following the instructions found here, I get the following error in the command line:

$ rollup ./main.js --format iife --file ./pkg/bundle.js

./main.js → ./pkg/bundle.js...
[!] Error: Could not resolve entry module (./main.js).
Error: Could not resolve entry module (./main.js).
    at error (/Users/charlesjohnson/.nvm/versions/node/v10.15.3/lib/node_modules/rollup/dist/rollup.js:5363:30)
    at pluginDriver.hookFirst.then.resolveIdResult (/Users/charlesjohnson/.nvm/versions/node/v10.15.3/lib/node_modules/rollup/dist/rollup.js:12034:20)
    at process._tickCallback (internal/process/next_tick.js:68:7)
    at Function.Module.runMain (internal/modules/cjs/loader.js:757:11)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)

Before I that I ran wasm-pack build but it didn't produce a main.js file

Cant build

Hi

I just installed rust and did a

cargo install mdbook

but the build failed:

Custom website.

I think it would be cool for Yew to have a custom website instead of using Gitbook. The advantage to this is that it would help improve the image (which is already good) of the project to make it appear more established.

I think that this would best be done by designing a custom mdbook template.

I'd be happy to work on this.

Should explain how to build

I just wanted to implement a proposal for this issue but I had trouble building the documentation. Neither

• mdbook serve
• gitbook serve

ran out of the box from the top-level path. Then I gave up. It would be nice if there were a BUILDING.md or so (the README.md seems to be already Yew's main documentation) explaining how to build and serve this locally.

Spellchecker script.

For another project I've undertaken, I've produced a spellchecker which looks through all the markdown files in a directory and reports spelling mistakes (and provides suggestions for how they could be corrected).
I thought that this could be something interesting to incorporate as part of the doctests (which currently just test Rust code).

[doc] toml config make an error.

[package]
name = "yew-app"
version = "0.1.0"
authors = ["Yew App Developer <[email protected]>"]
edition = "2018"

[dependencies]
yew = { version = "0.13.0", features = "std_web" }

yew = { version = "0.13.0", features = "std_web" } should be replace as yew = { version = "0.13.0", features = ["std_web"] }.

if use features = "std_web", I got error below in linux(deepin):

Caused by:
  invalid type: string "std_web", expected a sequence for key `dependencies.yew.features`

this will work instead

[package]
name = "yew-app"
version = "0.1.0"
authors = ["Yew App Developer <[email protected]>"]
edition = "2018"

[dependencies]
yew = { version = "0.13.0", features = ["std_web"] }

Introduce a max line length.

Having really long lines makes it hard to review changes being made to the documentation.

I intend to work on a PR to fix this.

Add a styling (CSS) section to the readme

The lack of a CSS section in the introduction (https://yew.rs/docs/, https://github.com/yewstack/docs) is an omission of the framework.

Related issues: yewstack/yew#533, yewstack/yew#448