[Website] add playground section by bullet03 · Pull Request #21959 · apache/beam

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

+ </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

- 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

+ <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

-</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

 ## 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

+ 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

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

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

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

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

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

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-actionsBot added the website label Jun 21, 2022

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

bullet03 force-pushed the website-add-playground-without-autofocus branch 3 times, most recently from d3a8b6e to 3723b77Compare 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 51be88dCompare 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 2692f9dCompare 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 3dfa455Compare 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 d9f3fdfCompare 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 87bced5Compare 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 62a0d0aCompare July 15, 2022 17:12

damondouglas approved these changes Jul 15, 2022
View reviewed changes

pabloem merged commit 29b26be into apache:masterJul 15, 2022

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!

alexeyinkinJul 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!

bullet03Jul 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

Uh oh!

alexeyinkin left a comment

bullet03 commented Jun 21, 2022•
edited
Loading

alexeyinkinJul 8, 2022•
edited
Loading

bullet03Jul 14, 2022•
edited
Loading

alexeyinkin commented Jul 15, 2022•
edited
Loading