Documentation: Guide update: 360 image gallery

[diarmidmackenzie]

Description:

3rd of 4 updates to bring external glitch examples up-to-date & into the A-Frame repo, per #5207.

This one addresses the 360 Image Galley Guide.

• Bring code from Glitch into A-Frame Examples
• Code up-to-date with latest versions
• Code and documentation match

[dmarcos]

link to master build instead of hardcoded version like other examples

[diarmidmackenzie]

Can do. Reason I did it this way was so that the HTML could easily be copy/pasted to another context (e.g. Glitch) and still work.

A small helping hand for beginners who might want to play with the example code, without cloning the A-Frame repo.

But if you prefer consistency with the other examples, that's - just wanted to share this consideration...

[dmarcos]

I wish we could have both from both worlds for the docs. Easy forkability of glich + easier maintenance of a github repo. Is there any solution out there we can look at?

[vincentfretin]

If each example is it's own github repo, you can push to glitch git repo:
https://dev.to/elvezpablo/using-git-with-glitch-5832
You could also do it automatically with a GitHub Action https://github.com/marketplace/actions/glitch-project-sync
I personally do it the other way, from the glitch console I'm git pull to sync from the github repo:
https://github.com/networked-aframe/networked-aframe/blob/master/docs/release-instructions.md

With an alternate solution like codesandbox, you can start a project from a folder in a github repo, example this url:
https://codesandbox.io/s/github/LXSMNSYC/solid-headless/tree/main/examples/accordion-example
takes the code directly from github:
https://github.com/lxsmnsyc/solid-headless/tree/main/examples/accordion-example

[diarmidmackenzie]

You can sync to glitch from a sub-path within a repo too.

I created this one by:

• In Glitch: Tools / Import & Export / Import from GithHUb
• Entering this path: aframevr/aframe:/examples/docs/aincraft
• After the code is loaded, modifying the A-Frame path to https://aframe.io/releases/1.4.1/aframe.min.js

See screenshot for steps...

[diarmidmackenzie]

For codesandbox.io, the following URL will automatically clone from GitHub nto codesandbox.

https://githubbox.com/aframevr/aframe/tree/master/examples/docs/aincraft

To make it work, you need to fork the sandbox & modify the A-Frame path to https://aframe.io/releases/1.4.1/aframe.min.js

IMO it would be nice to update the code to use a CDN URL already, to avoid users having to do that.

[diarmidmackenzie]

Codesandbox is the lowest maintenance solution, just requires that we:

• update the examples to use a CDN URL for A-Frame, rather than using the local copy
• include the relevant githubbox URL in the documentation (maybe also in a corner overlay in the experience itself)

Suggest we also update the npm run prerelease command to update A-Frame version strings in HTML files in the examples\docs folder.
#5213 (comment)

I think that could be a one-liner here like this:

glob.sync('examples/docs/**/*.html').forEach(updateDoc);

[diarmidmackenzie]

Proposal: let's get to a stable state with consistent up-to-date working code for all examples in examples/docs.

Then drive the sync to glitch and/or codesandbox as a separate issue/PR.

Now that #5215 is merged I'll update the remaining PRs to refer to examples/docs, which will get us to a consistent stable position, and we can move forwards from there.

[diarmidmackenzie]

One more lead - https://glitch.new/
"Just type glitch.new in front of any GitHub repo URL to import it directly to Glitch, like glitch.new/github.com/11ty/eleventy-base-blog."

Unfortunately this only seems to work with a whole repo (aframevr/aframe), not a sub-part of that repo. That would be a nice enhancement to get from glitch.

[diarmidmackenzie]

I raised an enhancement request in glitch support forum.
https://support.glitch.com/t/glitch-new-for-sub-trees-of-github-repos/59049

[dmarcos]

glitch design looks cleaner and it's what the community is used to. It will take time to reeducate and there's so much stuff on glitch already. Not sure I understand the drawback with glitch if we can sync directly from the repo.

About pointing examples/docs to a release. It will make harder to test locally those examples.

[diarmidmackenzie]

Moving discussion to #5222

Looks like a solution base on https://github.com/javierarce/glitchub is going to be the best way forwards.

[diarmidmackenzie]

Moved from examples/showcase to examples/docs.

Regarding this discussion, I'm proposing we merge as is, so we have a stable base of working examples & then handle the ability to fork to glitch / codesandbox as a separate issue.

[dmarcos]

Thanks