Codepen based API interactive example prototype

[schalkneethling]

User story

As a product owner, I want a user testable basic prototype of the API interactive examples using the Codepen API live on Kuma.

Acceptance criteria

• [ ] A user testable demo page, showing the UI/UX of an interactive API example using Codepen deployed on Kuma

Tasks

1. • [ ] Write EnableCodePenEmbed macro with example code hard coded
2. • [ ] JavaScript and CSS to style the static example, and enable the interaction to switch from static example, to live Codepen embed

Relevant Bugzilla bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1521135

[schalkneethling]

I had a more detailed look at the current EmbedLiveSample macro and how it is used. While it can take a couple of parameters, I see that essentially it outputs either:

1. A table with a screenshot on the left and a live sample(inside an iframe) on the right,
2. Just the live sample iframe

The first parameter that is passed is the sample ID(for example Without_changing_the_origin), which I notice matches two things:

1. The name of the live example that lives at say https://mdn.mozillademos.org/en-US/docs/Web/CSS/transform-function/scale3d$samples/Without_changing_the_origin?revision=1448037
2. A DOM id - https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale3d#Without_changing_the_origin

Using this DOM id, the JavaScipt build up a URL such as this: /en-US/docs/Web/CSS/transform-function/scale3d?section=Without_changing_the_origin&raw=1

which it loads via Ajax. Looking at the URL, it returns the raw HTML of just the section identified by the id: https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale3d?section=Without_changing_the_origin&raw=1

From this, it then extracts the HTML, CSS and JavaScript: https://github.com/mozilla/kuma/blob/master/kuma/static/js/wiki-samples.js#L80

That is then passed to the openSample function when one of the buttons is clicked: https://github.com/mozilla/kuma/blob/master/kuma/static/js/wiki-samples.js#L55

Conclusion

I doubt that we need to duplicate all of this for our purposes.

The code will be added via CKEditor(for now?) and not via a mechanism within the macro i.e. loading an interactive example via the IEx npm module The sample code will be in a format like:

div#iex-sample-code
  pre#iex-sample-html
  pre#iex-sample-css
  pre#iex-sample-js

As we will only have one per page, those ids will be safe. Of the above, only pre#iex-sample-js will be visible initially, the rest hidden.

The above format makes it simple to get at the individual pieces of code so, there should be no reason to load the raw HTML via Ajax and then extract it from there(might there be a caching benefit to this(loading the page fragment via Ajax I mean)? Not sure).

So the macro only needs to add:

1. a hidden iframe with no source, that will become the host of the Codepen example,
2. A "Try it now" button

When the "Try it now" button is clicked, div#iex-sample-code is hidden, the source of the iframe is set and made visible. This will then load the Codepen example, replacing the static JS.

I am guessing the "Try it now" button will also be hidden at this stage. Should we have a mechanism to get back to the previous state i.e. no Codepen with static JS code?

[jwhitlock]

Bug was closed on January 28, and marked complete in mid-sprint review.