[Website] add playground section #21959

bullet03 · 2022-06-21T13:09:04Z

Resolves #22301

add playground section with no autofocus set in playground iframe on page loading
update playground shortcode
move fix-playground-nested-scroll.js to head.html/head_homepage.html from body-end.html, since soon playground will be used on many pages
wrap fix-playground-nested-scroll.js in jQuery.ready, so func works only when DOM is ready

Thank you for your contribution! Follow this checklist to help us incorporate your contribution quickly and easily:

Choose reviewer(s) and mention them in a comment (R: @username).
Mention the appropriate issue in your description (for example: addresses #123), if applicable. This will automatically add a link to the pull request in the issue. If you would like the issue to automatically close on merging the pull request, comment fixes #<ISSUE NUMBER> instead.
Update CHANGES.md with noteworthy changes.
If this contribution is large, please file an Apache Individual Contributor License Agreement.

See the Contributor Guide for more tips on how to make review process smoother.

To check the build health, please visit https://github.com/apache/beam/blob/master/.test-infra/BUILD_STATUS.md

GitHub Actions Tests Status (on master branch)

See CI.md for more information about GitHub Actions CI.

asf-ci · 2022-06-21T13:09:08Z

Can one of the admins verify this patch?

asf-ci · 2022-06-21T13:09:08Z

Can one of the admins verify this patch?

asf-ci · 2022-06-21T13:09:08Z

Can one of the admins verify this patch?

asf-ci · 2022-06-21T13:09:08Z

Can one of the admins verify this patch?

asf-ci · 2022-06-21T13:09:08Z

Can one of the admins verify this patch?

alexeyinkin · 2022-07-08T12:28:43Z

website/www/site/layouts/index.html

+  </a>
+  <div id="playgroundIframeContainer">
+    <iframe
+            src="https://play.beam.apache.org/embedded?enabled=true&example=SDK_JAVA/PRECOMPILED_OBJECT_TYPE_EXAMPLE/MinimalWordCount&code="


No need to pass code if it's empty.

alexeyinkin · 2022-07-08T12:31:58Z

website/www/site/layouts/shortcodes/playground.html

-    class="code-snippet playground"
-    allow="clipboard-write">
-</iframe>
+<div id="playgroundIframeContainer">


id should not be used in shortcode because the shortcode can be used multiple times on a page. It actually will be used many times since we need to convert many doc highlighted examples to playground instances.

alexeyinkin · 2022-07-08T12:33:15Z

website/www/site/layouts/index.html

+  <a class="playground__mobile" href="https://play.beam.apache.org/">
+    <img src="images/playground.png" alt="beam playground">
+  </a>
+  <div id="playgroundIframeContainer">


Why not use a shortcode here?

as far as I understood according to the answer, we are not able to use shortcodes: https://discourse.gohugo.io/t/shortcode-inside-define-block/39410

alexeyinkin · 2022-07-08T12:36:34Z

website/www/site/layouts/shortcodes/playground.html

-</iframe>
+<div id="playgroundIframeContainer">
+    <iframe
+        src="https://frontend-beta-dot-apache-beam-testing.appspot.com/embedded?enabled={{ .Get 0 }}&example={{ .Get 1 }}&code={{ .Get 2 }}"


Better use named parameters in this shortcode since we already have 5. They will only be adding up.

Opportunity to update embedded playground source to https://play.beam.apache.org/

alexeyinkin · 2022-07-08T12:41:44Z

website/www/site/content/en/get-started/try-beam-playground.md

 ## Beam Playground WordCount Example

-{{< playground "true" "SDK_JAVA/PRECOMPILED_OBJECT_TYPE_EXAMPLE/MinimalWordCount" "" "700px">}}
+{{< playground "true" "SDK_JAVA/PRECOMPILED_OBJECT_TYPE_EXAMPLE/MinimalWordCount" "" "700px" "playgroundIframe">}}


I have another vision for this. We often will need Playground with tabs for multiple languages. A shortcode should be like

{{< playground height="700px" >}} {{< playground_snippet sdk="java" example="SDK_JAVA/PRECOMPILEDOBJECT_TYPE_EXAMPLE/MinimalWordCount" ... >}} {{< playground_snippet sdk="python" ... >}} {{< /playground >}}

The idea is that playground_snippet inserts a div with data-xxx attributes or something like this.
playground shortcode then inserts a JS that looks for these nested dives. If only one is given, it renders a single iframe. If multiple are given, it creates tabs.

If you need to push this fast, can you rename playground shortcode to playground_iframe or something like so we can reserve playground shortcode for the above solution?

renamed playground shortcode to playground_iframe

alexeyinkin · 2022-07-08T12:49:20Z

website/www/site/layouts/shortcodes/playground.html

+        src="https://frontend-beta-dot-apache-beam-testing.appspot.com/embedded?enabled={{ .Get 0 }}&example={{ .Get 1 }}&code={{ .Get 2 }}"
+        width="100%"
+        height="{{ .Get 3 }}"
+        id="{{ .Get 4 }}"


What is the use for this ID? Is it used outside of the shortcode? If not, can it be generated here or omitted?

Playground now has subdomain https://play.beam.apache.org/ - would be nice to update

alexeyinkin · 2022-07-11T15:18:24Z

website/www/site/assets/js/fix-playground-nested-scroll.js

I think it's better to add and remove classes to the div instead if tweaking styles at runtime. I suggest to:

Rename this class to playground-iframe-wrapper-no-scroll so it is self-descriptive. (Dashes are for this to go in line with my parallel work on embedding).

On click, add another class playground-iframe-wrapper-scroll that sets pointer-events: auto on iframe so it takes over.

On mouse leave, remove playground-iframe-wrapper-scroll class.

alexeyinkin · 2022-07-11T15:21:58Z

playground/frontend/README.md

This is hard to read without an example. I think I will add it myself when I'm done on my part.
Sorry for the overhead.

removed Embedding note from README

alexeyinkin · 2022-07-11T17:04:20Z

I renamed enabled param to editable. enabled was vague, it gives an impression that disabled playground is unable to run the code. editable is more precise.

I did it in this branch because it is likely the fastest way to deploy it, and we want this change before URLs start to spread.

alexeyinkin · 2022-07-13T12:50:30Z

website/www/site/assets/js/fix-playground-nested-scroll.js

This should be done on $(this), otherwise we affect all Playground instances on the page.

alexeyinkin · 2022-07-13T13:03:47Z

website/www/site/layouts/get-started/playground_template.html

Do we need to include this on each page where this scrolling trick is used? If so, it is inconvenient.

I see the following options to avoid it:

There seems to be a technique to check if a shortcode is used anywhere in the page to include scripts in that case:
https://gohugo.io/templates/shortcode-templates/#checking-for-existence

Inline JS in the shortcode. It may be non-trivial if we want to avoid IDs on iframes and divs.

Include this JS unconditionally on all pages as the last resort, since Playground will likely be used on most of them.

Thank you, used approach #1.
Made a partial from this code, so it could be reusable in future, since playground will be used on many pages.

{{ if .HasShortcode "playground_iframe" }} {{ $fixPlaygroundNestedScroll := resources.Get "js/fix-playground-nested-scroll.js" | minify | fingerprint }} <script type="text/javascript" src="{{ $fixPlaygroundNestedScroll.RelPermalink }}" defer></script> {{ end }}

alexeyinkin · 2022-07-14T10:03:41Z

website/www/site/layouts/get-started/baseof.html

This only adds this check to get-started, but not the home page. Maybe better add this to footer.html? That will cover all pages on the website.

added to head.html/head_homepage.html

alexeyinkin

LGTM.

alexeyinkin

LGTM.

apache#22301

alexeyinkin · 2022-07-15T17:24:40Z

Known limitations:

Mid impact: To avoid text editor inside embedded Playground take over focus and scrolling while user intends to scroll web page and bring mouse over iframe, implemented an overlay container over embedded Playground leaving only top buttons bar (Run, theme, copy, Try Playground) buttons react to the first user click. If user wants to interact with the code example, Result, Graph – user will first need to click (on the overlay container) that will hide the overlay container, and user will be able to interact with Playground code editor (scroll, edit, etc.). When mouse pointer leaves iframe (user navigates away), the overlay container displayed again so user scrolls web page, as intended
Low impact: On Beam staging, copy button scrolls user to the top of web not reproduced on a local environment or in the current production environment. Do not expect most users to copy in the scenarios we have for home page and try Playground page. Needs more investigate to understand difference between local and staging behavior. http://apache-beam-website-pull-requests.storage.googleapis.com/21959/index.html
Low impact: Firefox browser only – selected text from Results does not loose selection when user clicks outside of Result edit box
Low impact: When selecting text in Output window and dragging mouse pointer below the field, the selection is lost because the pointer leaves the iframe. This is a side effect of the workaround to release the focus.

This PR will also expose the trade-off from #22154 (comment) that was chosen to fix #22153. It was not visible before because the embedded Playground was read-only since the last deployment and will become editable again in this PR.

AKosolapov · 2022-07-15T18:02:07Z

@alexeyinkin Thank you for adding notes from our testing and triage with @alevtinaboiko and @bullet03

damondouglas

@pabloem LGTM

github-actions bot added the website label Jun 21, 2022

bullet03 force-pushed the website-add-playground-without-autofocus branch 3 times, most recently from d2940d0 to 9d1bc9f Compare June 27, 2022 09:34

bullet03 force-pushed the website-add-playground-without-autofocus branch 3 times, most recently from d3a8b6e to 3723b77 Compare July 8, 2022 11:51

alexeyinkin reviewed Jul 8, 2022

View reviewed changes

bullet03 force-pushed the website-add-playground-without-autofocus branch 4 times, most recently from e6b7c47 to 51be88d Compare July 11, 2022 09:55

alexeyinkin reviewed Jul 11, 2022

View reviewed changes

bullet03 force-pushed the website-add-playground-without-autofocus branch 3 times, most recently from 1e197af to 2692f9d Compare July 13, 2022 11:16

alexeyinkin reviewed Jul 13, 2022

View reviewed changes

bullet03 force-pushed the website-add-playground-without-autofocus branch 3 times, most recently from 10ae5c0 to 3dfa455 Compare July 14, 2022 08:53

alexeyinkin reviewed Jul 14, 2022

View reviewed changes

bullet03 force-pushed the website-add-playground-without-autofocus branch 2 times, most recently from 5ad7835 to d9f3fdf Compare July 15, 2022 08:16

alexeyinkin approved these changes Jul 15, 2022

View reviewed changes

bullet03 force-pushed the website-add-playground-without-autofocus branch from d9f3fdf to 87bced5 Compare July 15, 2022 12:47

alexeyinkin approved these changes Jul 15, 2022

View reviewed changes

bullet03 marked this pull request as ready for review July 15, 2022 16:55

[Website] add playground section, update playground, update get-started

62a0d0a

apache#22301

bullet03 force-pushed the website-add-playground-without-autofocus branch from 87bced5 to 62a0d0a Compare July 15, 2022 17:12

damondouglas approved these changes Jul 15, 2022

View reviewed changes

pabloem merged commit 29b26be into apache:master Jul 15, 2022

[Website] add playground section #21959

[Website] add playground section #21959

Uh oh!

Conversation

bullet03 commented Jun 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

GitHub Actions Tests Status (on master branch)

Uh oh!

asf-ci commented Jun 21, 2022

Uh oh!

asf-ci commented Jun 21, 2022

Uh oh!

asf-ci commented Jun 21, 2022

Uh oh!

asf-ci commented Jun 21, 2022

Uh oh!

asf-ci commented Jun 21, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexeyinkin Jul 8, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexeyinkin commented Jul 11, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bullet03 Jul 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexeyinkin left a comment

Choose a reason for hiding this comment

bullet03 commented Jun 21, 2022 •

edited

Loading

alexeyinkin Jul 8, 2022 •

edited

Loading

bullet03 Jul 14, 2022 •

edited

Loading

alexeyinkin commented Jul 15, 2022 •

edited

Loading