Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: Guide update: 360 image gallery #5214

Merged
merged 7 commits into from
Jan 20, 2023
Merged

Documentation: Guide update: 360 image gallery #5214

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8b22d12
Copy example from glitch
diarmidmackenzie Jan 12, 2023
168fca9
Align documentation & example
diarmidmackenzie Jan 12, 2023
6c4a216
Add 360 Gallery to showcase index
diarmidmackenzie Jan 12, 2023
d1ea53b
Remove reference to glitch
diarmidmackenzie Jan 12, 2023
526e567
Use master A-Frame
diarmidmackenzie Jan 13, 2023
75fbf2c
Merge remote-tracking branch 'upstream/master' into 360-image-gallery
diarmidmackenzie Jan 19, 2023
774208c
moved from examples/showcase to examples/docs
diarmidmackenzie Jan 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions docs/guides/building-a-360-image-gallery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ parent_section: guides
order: 3
examples:
- title: 360° Image Gallery
src: https://glitch.com/edit/#!/aframe-gallery?path=index.html
src: https://github.com/aframevr/aframe/tree/master/examples/showcase/360-gallery/index.html
---

[glitch]: https://glitch.com/edit/#!/aframe-gallery?path=index.html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@diarmidmackenzie diarmidmackenzie Jan 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...
image

Copy link
Contributor Author

@diarmidmackenzie diarmidmackenzie Jan 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@diarmidmackenzie diarmidmackenzie Jan 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving discussion to #5222

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

[live-example]: https://aframe.io/examples/showcase/360-gallery/

![360° Image Viewer](/images/docs/360-image-viewer.png)

Expand All @@ -32,7 +32,7 @@ for an easy example that has a lot of demand as an early use case on the Web.

## Skeleton

This is the starting point for our scene. We can also remix the [Glitch][glitch].
This is the starting point for our scene.

```html
<a-scene>
Expand Down Expand Up @@ -209,7 +209,7 @@ template and give it a name using an `id`:
```html
<head>
<!-- ... -->
<script id="plane" type="text/html">
<script id="link" type="text/html">
<a-entity class="link"
geometry="primitive: plane; height: 1; width: 1"
material="shader: flat; src: #cubes-thumb"
Expand All @@ -221,9 +221,9 @@ template and give it a name using an `id`:
Then we can use the template to create multiple planes without much work:

```html
<a-entity template="src: #plane"></a-entity>
<a-entity template="src: #plane"></a-entity>
<a-entity template="src: #plane"></a-entity>
<a-entity template="src: #link"></a-entity>
<a-entity template="src: #link"></a-entity>
<a-entity template="src: #link"></a-entity>
```

[templateliteral]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Template_literals
Expand All @@ -242,7 +242,7 @@ attributes][data]:
```html
<a-assets>
<!-- ... -->
<script id="plane" type="text/html">
<script id="link" type="text/html">
<a-entity class="link"
geometry="primitive: plane; height: 1; width: 1"
material="shader: flat; src: ${thumb}"
Expand All @@ -253,9 +253,9 @@ attributes][data]:
<!-- ... -->

<!-- Pass image sources to the template. -->
<a-entity template="src: #plane" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #plane" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #plane" data-thumb="#sechelt-thumb"></a-entity>
<a-entity template="src: #link" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #link" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #link" data-thumb="#sechelt-thumb"></a-entity>
```

The template component has allowed us to not have to repeat a lot of HTML,
Expand All @@ -274,10 +274,10 @@ We create a wrapper entity around our links and attach the layout component
using the `line` layout:

```html
<a-entity id="links" layout="type: line; margin: 1.5" position="-3 -1 -4">
<a-entity template="src: #plane" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #plane" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #plane" data-thumb="#sechelt-thumb"></a-entity>
<a-entity id="links" layout="type: line; margin: 1.5" position="-1.5 -1 -4">
<a-entity template="src: #link" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #link" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #link" data-thumb="#sechelt-thumb"></a-entity>
</a-entity>
```

Expand Down Expand Up @@ -309,7 +309,7 @@ the `setAttribute` calls. Notice that the event-set component can have
[multiple instances][multiple]:

```html
<script id="plane" type="text/html">
<script id="link" type="text/html">
<a-entity class="link"
geometry="primitive: plane; height: 1; width: 1"
material="shader: flat; src: ${thumb}"
Expand All @@ -323,9 +323,9 @@ the `setAttribute` calls. Notice that the event-set component can have
Remember to add `data-src` attributes to the link entities to load the full image on click:

```
<a-entity template="src: #plane" data-src="#city" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #plane" data-src="#cubes" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #plane" data-src="#sechelt" data-thumb="#sechelt-thumb"></a-entity>
<a-entity template="src: #link" data-src="#city" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #link" data-src="#cubes" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #link" data-src="#sechelt" data-thumb="#sechelt-thumb"></a-entity>
```

Next, we want to actually set the new background image. We'll add a nice fade-to-black effect.
Expand Down Expand Up @@ -378,4 +378,4 @@ to offer for common needs, non-trivial VR applications will require us to write
application-specific components. That is covered in [Writing a Component] and
hopefully in later guides.

> **[Try it out!](https://aframe-gallery.glitch.me)**
> **[Try it out!][live-example]**
1 change: 1 addition & 0 deletions examples/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ <h1>A-Frame Examples</h1>
<h2>Examples</h2>

<ul class="links">
<li><a href="showcase/360-gallery/">360 Gallery</a></li>
<li><a href="showcase/anime-UI/">Anime UI</a></li>
<li><a href="showcase/comicbook/">Comic Book</a></li>
<li><a href="showcase/composite/">Composite</a></li>
Expand Down
65 changes: 65 additions & 0 deletions examples/showcase/360-gallery/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>360&deg; Image Gallery</title>
<meta name="description" content="360&deg; Image Gallery - A-Frame">
<!-- If running this example without a local copy of A-Frame, replace this next line with:
<script src="https://aframe.io/releases/<release_number>/aframe.min.js"></script>
-->
<script src="../../../dist/aframe-master.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-template-component.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-layout-component.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-event-set-component.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-proxy-event-component.min.jss"></script>

<!-- Image link template to be reused. -->
<script id="link" type="text/html">
<a-entity class="link"
geometry="primitive: plane; height: 1; width: 1"
material="shader: flat; src: ${thumb}"
sound="on: click; src: #click-sound"
event-set__mouseenter="scale: 1.2 1.2 1"
event-set__mouseleave="scale: 1 1 1"
event-set__click="_target: #image-360; _delay: 300; material.src: ${src}"
proxy-event="event: click; to: #image-360; as: fade"></a-entity>
</script>
</head>
<body>
<a-scene>
<a-assets>
<img id="city" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/city.jpg">
<img id="city-thumb" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/thumb-city.jpg">
<img id="cubes-thumb" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/thumb-cubes.jpg">
<img id="sechelt-thumb" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/thumb-sechelt.jpg">
<audio id="click-sound" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/audio/click.ogg"></audio>
<img id="cubes" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/cubes.jpg">
<img id="sechelt" crossorigin="anonymous" src="https://cdn.aframe.io/360-image-gallery-boilerplate/img/sechelt.jpg">

</a-assets>

<!-- 360-degree image. -->
<a-sky id="image-360" radius="10" src="#city"
animation__fade="property: components.material.material.color; type: color; from: #FFF; to: #000; dur: 300; startEvents: fade"
animation__fadeback="property: components.material.material.color; type: color; from: #000; to: #FFF; dur: 300; startEvents: animationcomplete__fade"></a-sky>

<!-- Image links. -->
<a-entity id="links" layout="type: line; margin: 1.5" position="-1.5 -1 -4">
<a-entity template="src: #link" data-src="#city" data-thumb="#city-thumb"></a-entity>
<a-entity template="src: #link" data-src="#cubes" data-thumb="#cubes-thumb"></a-entity>
<a-entity template="src: #link" data-src="#sechelt" data-thumb="#sechelt-thumb"></a-entity>
</a-entity>

<!-- Camera + cursor. -->
<a-entity camera look-controls>
<a-cursor
id="cursor"
animation__click="property: scale; startEvents: click; from: 0.1 0.1 0.1; to: 1 1 1; dur: 150"
animation__fusing="property: fusing; startEvents: fusing; from: 1 1 1; to: 0.1 0.1 0.1; dur: 1500"
event-set__mouseenter="_event: mouseenter; color: springgreen"
event-set__mouseleave="_event: mouseleave; color: black"
raycaster="objects: .link"></a-cursor>
</a-entity>
</a-scene>
</body>
</html>