Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Developer experience: Not always clear how to init from JS #122

Open
cmditch opened this issue Apr 13, 2021 · 0 comments
Open

Developer experience: Not always clear how to init from JS #122

cmditch opened this issue Apr 13, 2021 · 0 comments

Comments

@cmditch
Copy link

cmditch commented Apr 13, 2021

I appreciate how much effort and focus the Elm community devotes to clear & thorough documentation. In an effort to continue improving the docs, I'll go over an experience I recently had trying to use Browser.sandbox for a SSCCE.

I found that it was not very clear from the Browser.element or Browser.sandbox docs how to initialize them within JS.

I spent quite a bit of time pouring over the package docs, elm guide, and elm guide examples to no avail.

I eventually happened upon https://guide.elm-lang.org/interop/ , which shows the use of the node field, but it's not clear when this field is relevant wrt sandbox, element, document, application. I also found https://guide.elm-lang.org/webapps/, but this only shows how to init a document.

Potential ways to ameliorate this confusion:

  1. Include js snipptes in the Browser docs.
  2. Include js/html snippets in the guides examples instead of only pure Elm.
  3. Include something like the table below as a quick and clear reference in the Browser docs and Elm guide (with help from @Janiczek).
+----------------------+-------------------+------------------------+
| entry point js param | uses `node` field | supports `flags` field |
+----------------------+-------------------+------------------------+
| Platform.worker      | no                | yes                    |
+----------------------+-------------------+------------------------+
| Browser.sandbox      | yes               | no                     |
+----------------------+-------------------+------------------------+
| Browser.element      | yes               | yes                    |
+----------------------+-------------------+------------------------+
| Browser.document     | no                | yes                    |
+----------------------+-------------------+------------------------+
| Browser.application  | no                | yes                    |
+----------------------+-------------------+------------------------+
  1. All of the above
  2. None of the above and something better?

Thanks!
Coury

@cmditch cmditch changed the title Developer experience: Not clear how to init element/sandbox from JS Developer experience: Not always clear how to init from JS Apr 13, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant