Add Codepen or Codesandbox examples to the docs

[gotjoshua]

I am a huge fan of how antd is provding examples: https://ant.design/components/auto-complete/ When you click to see the code, then hover over the code you get options to open it in codepen or codesandbox.... very helpful!

Would you find it a relevant / meaningful / desired contribution to create a set of such example codepens for ObjectModel?

[sylvainpolletvillard]

I usually have DevTools opened next to the docs website. The development build of the library is loaded as global so you can try directly all the code examples just by pressing F12. I don't think Codepens would be an improvement compared to Dev Tools, since HTML/CSS and Preview panels of Codepen are useless and Codepens don't show and format JS runtime exceptions unless you open the dev tools anyway. This is very different from documenting a UI library, where HTML and preview are very important. Also, I find Codepen to be quite slow to open and not very convenient to use as a debug tool.

My other concern is that moving on Codepen would imply additional maintenance out of the website, unless there is a way to generate codepens on the fly. I like how everything is in one place currently, and would like to keep it that way.

It is not possible to programatically open the dev tools, so if this is not a reflex for new comers, then we still need a way for people to run and hack the examples easily. A better option in my opinion would be to have a REPL right inside the website that mimic a JS console, and that would let you run the examples just by clicking a button. Do you know a lightweight component like that ? We could also implement this from scratch, it shouldn't be that hard.

[gotjoshua]

Ok, good point about devtools and outside maintenance, and big bummer that we can't send devtools a snippet with a single click... Lets see if someone shows up with a great idea at some point...

[sylvainpolletvillard]

I made some experiments with Codeblock.js but I'm not really convinced:

• some examples in ObjectModel docs have no real purpose of being evaluated, it's just model instanciation. That means nothing happens when you run the code, you can only log objects in console, and the user has to open his devtools and see the console. Also, there is 99% change it doesn't have custom dev formatters turned on, so he will just see a ugly Proxy signature log. This is not very sexy for a first contact with the library.
• when examples intend to throw TypeError exceptions, these exceptions are blocking, so I can't show several exceptions in one snippet ; I need to split them in several snippets
• the user has to click on "run" to see the exception thrown, so he can't understand the purpose of the library feature if he doesn't run the snippet, or if the code editor fails to load or run for any reason.
• when an embedded code editor throws an exception, it's not clear if the error is intended or is a bug. Directly showing the error in plain text makes the intention clearer.

A better option could be to replace the code snippets by little animations running the code line by line, with custom tooltips. I didn't find a plug-in solution for this at the moment. Maybe video could also do it.

[gotjoshua]

Actually I quite like the clarity that your examples show... and just copy paste into the console is already great... Maybe you could make all of the code from the left side of the examples (and all of the common.js) already loaded globally, so people could try the right side instantiation stuff in the devtools more easily..

There we could also provide a section with a screenshot and or video(s)... but even just a simple example of how to run the test code/examples could be enough

[sylvainpolletvillard]

I don't really want to evaluate the examples, this slows down the page load and prevents people from evaluating themselves the models (because of const). Also, some examples would not work together because some names are reused.

For now I'll just add a sentence to encourage the users to try the examples in their JS console.

[gotjoshua]

fair enough!

[sylvainpolletvillard]

Didn't find a better option so far, so I'm going to close this issue. Feel free to comment if you have a new idea

[gotjoshua]

I made a codepen that actually shows whats happening in a very simple case:

I am also not a huge fan of codepen, per se, but I like the idea that users can at least start to play with a bit more flexibility than the browser DevTools console.

I still agree that maintaining all of the codepens externally is not a good idea, but you could consider to make one or two examples and link to them. The above pen could serve as a starting point, or at least people can find it here in this thread...

[sylvainpolletvillard]

I recently tried Codesandbox and found it to be much superior to Codepen. See for yourself:

It has proper exception formatting in result view, full VSCode experience, npm package handling, and exceptions are remembered and displayed statically in the code itself as shown above. Also, it can link to a Github repository, so it would be possible to link it to a "demo" folder of this repo and there will be no external maintenance needed.

https://codesandbox.io/s/objectmodel-demo-cob1g

[gotjoshua]

Looks great... I am rather agnostic... And the possibility to keep the demo code in the repo is very appealing. Let me know if I can assist with that somehow.

[sylvainpolletvillard]

I added all the documentation examples as separate pages that can run on CodeSandbox: https://codesandbox.io/s/github/sylvainpolletvillard/ObjectModel/tree/master/docs/examples

Could you play with it a little, see if there are some issues ? I already noticed that ES6 classes examples do not work properly because of some Babel configuration used by Codesandbox.

[gotjoshua]

So, I can confirm that the classes examples fail with a remarkably cryptic message: TypeError: (0 , _getPrototypeOf2.default)(...).call is not a function

I can't find any babel settings in the settings, but I found that there is a sort of environment system that seems to default to parceljs. I imagine somewhere in there is the issue.

Shouldn't it be possible to run the code in a modern browser without babel at all?

[gotjoshua]

Anyway, I found a way to add and edit the .babelrc in codesandbox(have a look at my fork) I just replaced the presets entry with this:

"presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "esmodules": true
        }
      }
    ]
  ],

Class files run now.

[sylvainpolletvillard]

Nice, thanks ! Can you push a PR ? You can do this from Codesandbox with the Github icon on the left

Shouldn't it be possible to run the code in a modern browser without babel at all?

Yes it is, but not everyone uses an up-to-date browser. Babel makes it possible to run the examples on a ~3 years old browser

[sylvainpolletvillard]

Okay, it has been a month so I added the changes myself.

All the examples now run on Codesandbox, so I think we can close this issue. Thanks for your help !

[gotjoshua]

sorry, i must have missed that request to do the PR via codesandbox... i was traveling at that time. Wait now i am confused, it looks like you merged a PR from me... which changes did you do yourself?

Cheers!

[sylvainpolletvillard]

Oh so you actually did a PR :laughing: I thought I did it myself because this issue was still open after a month but the examples were working. Nevermind, thanks again :blush: