Live samples: add a built-in console and reset button

[wbamberg]

In our live sample system (that is, the things that are built using EmbedLiveSample) writers often want to show some output. They use various things:

• alert(), which we don't like
• console.log(), which we also don't like (because it's not visible unless the user has the console open, and gets mixed in among page output
• their own handmade system (like for instance https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/progress_event#live_example) - this works but (a) gives us an inconsistent UI across pages (b) duplicates the code in lots of places (c) adds non-essential complexity to the example

It would be nice if live samples could have their own console attached to the output iframe, and console.log() calls showed up there (as we do currrently for interactive examples).

Relatedly, we often want the ability to reset a live sample so it can be run again. People again hand-craft this by adding a "Reset" button that reloads the iframe. For the same reasons it would be nice if we had a built-in button to do that.

Regarding the console.log() thing though, a few things:

• we could do an analysis of places we could benefit from this, to see if it's worth it
• at least some pages do weird things with live samples (especially in the learning area) and they would need a way to opt out. That would mean even more optionsfor live samples. Perhaps we should retire some of the other options first.
• as @schalkneethling said, it would be great to reuse the console from interactive examples for this.
• the interactive examples editor only patches console.log() and console.error(). Should this do the same?

[NiedziolkaMichal]

There are few things to consider, before working on this feature.

Should this console be added automatically under some conditions?

• It would work well for examples that have console.log as its only side effect.
• There are plenty of examples that don't output anything, they just write expected result in the comments.
• There are examples which will give different output than expected.
• There are examples causing side effects that may be annoying to the user.
• There may be examples causing infinite loops or other heavy operations, breaking page performance.

I think creating set of conditions that would activate this console automatically would be very challenging, so it is probably best to make it be activated explicitly.

Should it be optionally activated part of EmbedLiveSample macro or be a separate macro?

• Currently EmbedLiveSample has those parameters:

1. The ID of the header block containing the sample
2. The width of the iframe (optional)
3. The height of the iframe (optional)
4. The url of a screenshot of the sample working as intended (optional)
5. The slug from which to load the sample (optional; current page used if not provided)
6. The class name of the frame; defaults to "sample-code-frame".
7. Allowed features, separated by semicolons (optional)

• Activating console would need to be parameter 8.
• Some examples wouldn't need console, some of them would need just console, while others may need console + html output.

I think it might be best to do separate macro for just the console and later make new macro that would contain console + html output.

Should there be a Play button?

• There are examples printing output after a delay.
• There are examples causing side effects that may be annoying to the user.

Other things to consider

• Just like in interactive examples, exceptions should be properly displayed. Second example on this section throws an exception as an expected result.

[rubiesonthesky]

I'm not sure is it achievable, but I think if reworking existing system or creating new, there should be some way to mark the expected output and this would be done so, that in PR phase, incorrect results would be flagged as flaws. If not as automatic flaw system, then it would help to have live example that would show error when the expected result was not met. This is not possible for all examples, but it would help in many situations.

Sometimes is more of documentation issue, that is not clear after years, what the function should do or return. There have been those kind of examples when trying to modernize code examples. Sometimes it's little bit hard to see what is the expected output and that maybe the expected output is "wrong".

[wbamberg]

This is (at the moment at least) a much more narrowly-scoped proposal, just to add a console, and just to add it to live samples. For instance the examples listed:

There are few things to consider, before working on this feature.

Should this console be added automatically under some conditions?

• It would work well for examples that have console.log as its only side effect.

• There are plenty of examples that don't output anything, they just write expected result in the comments.

• There are examples which will give different output than expected.

• There are examples causing side effects that may be annoying to the user.

• There may be examples causing infinite loops or other heavy operations, breaking page performance.

...none of these are currently live samples, and in some cases for good reasons. Our JS docs hardly use live samples at all.

The whole question of "which example systems should we have and what should they support" is massive really.