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

Bring "Community components" example into A-Frame Examples. #5211

Merged
merged 14 commits into from
Mar 28, 2023
Merged

Bring "Community components" example into A-Frame Examples. #5211

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c2d4760
Copy example from glitch
diarmidmackenzie Jan 11, 2023
3144b8e
Update example to use latest working code
diarmidmackenzie Jan 11, 2023
e1d065b
Add link to Community Components example
diarmidmackenzie Jan 11, 2023
f739cf8
Consistently use jsdelivr for CDN
diarmidmackenzie Jan 11, 2023
9976d7b
Update Title
diarmidmackenzie Jan 11, 2023
9b7daf5
Update documentation of community components example
diarmidmackenzie Jan 11, 2023
ec1e2b0
Fix docs lint error
diarmidmackenzie Jan 12, 2023
e758261
Add comment explaining what to do if copy/pasting code.
diarmidmackenzie Jan 13, 2023
ef97760
Tidy up.
diarmidmackenzie Jan 13, 2023
5a0f611
Merge remote-tracking branch 'upstream/master' into community-compone…
diarmidmackenzie Jan 19, 2023
7d5b735
Move community components from "showcase" to "docs"
diarmidmackenzie Jan 19, 2023
b045d0e
Fix some bad links left over from #5215
diarmidmackenzie Jan 19, 2023
80a8934
Merge remote-tracking branch 'upstream/master' into community-compone…
diarmidmackenzie Mar 27, 2023
dc0113f
Use versioned release here
diarmidmackenzie Mar 28, 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
38 changes: 23 additions & 15 deletions docs/introduction/entity-component-system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -451,27 +451,37 @@ Now we can include it into our HTML:
</html>
```

### Using jsdelivr for CDN

[jsdelivr]: https://www.jsdelivr.com/

[JSDELIVR][jsdelivr] is an alternative CDN to unpkg. One benefit of JSDELIVR is that it can download files from GitHub as well as NPM.

You can convert unpkg URLs to JSDELIVR URLs using this link: https://www.jsdelivr.com/unpkg

You can convert GitHub URLs to JSDELIVR URLs using this link: https://www.jsdelivr.com/github

### Example

[glitch]: http://glitch.com/~aframe-registry
[community-example]: https://aframe.io/examples/showcase/community-components

![Registry Example](https://cloud.githubusercontent.com/assets/674727/25502318/0f76ceec-2b4b-11e7-9829-cb3784b20dc1.gif)
![Community Components Example](https://cloud.githubusercontent.com/assets/674727/25502318/0f76ceec-2b4b-11e7-9829-cb3784b20dc1.gif)

Below is a complete example of using various community components from the
Registry and using the unpkg CDN. We can [remix or check out this example on
Glitch][glitch].
Registry and using the JSDELIVR CDN. This example can also be viewed in the [A-Frame Examples][community-example].

```html
<html>
<head>
<script src="https://aframe.io/releases/1.4.0/aframe.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-animation-component.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-particle-system-component.min.js"></script>
<script src="https://unpkg.com/aframe-extras.ocean@%5E3.5.x/dist/aframe-extras.ocean.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/gradientsky.min.js"></script>
<title>Community Components Example</title>
Copy link
Member

Choose a reason for hiding this comment

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

We now have duplicated code here and the example that have to be in sync. It would be cool if there's a markdown way to display html from the file hosted on gihub

Copy link
Contributor Author

@diarmidmackenzie diarmidmackenzie Jan 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

One option:
https://github.com/zakhenry/embedme

A limitation is that code fragments are indexable only by line number. If line numbers change, extracts will get out of sync. That's discussed (together with some possible solutions) here but there doesn't seem to be a good solution yet (and momentum has stalled since 2020).

How widespread an issue do you think this is in the docs? Is there enough benefit to be worth the overhead of adding new tools like embedme to the pipeline? Is it worth doing if snippets have to be by line number, rather than tag-based as #48 will enable?

<meta name="description" content="Community Components Example">
<script src="../../../dist/aframe-master.js"></script>
Copy link
Member

Choose a reason for hiding this comment

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

For embedded code in docs we can point to the A-Frame version. That gets updated automatically. If we point to dist/aframe-master once cannot copy / paste the code.

One of the features I once requested to glitch is having a glitch backed up by a git directory. These way we could have all the glitches in a single repo and update them all on a new release.

Copy link
Contributor

Choose a reason for hiding this comment

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

FYI for networked-aframe, I update the naf-examples glitch by opening the glitch terminal and git pull from github, see my procedure https://github.com/networked-aframe/networked-aframe/blob/master/docs/release-instructions.md
Each glitch is actually a git repository where it autocommit the changes.

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'm proposing these lines in each example:

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

Not perfect, but feels like a reasonable compromise?

Same applies to #5213, #5214, #5215.

Copy link
Member

@dmarcos dmarcos Mar 28, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

I think this embedded code should point to the latest A-Frame version as it was before. The docs update script updates the version automatically upon publication. Does it make sense?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

OK, makes sense. Changed back to 1.4.0 version. Quoted code in the docs won't exactly match the code in the linked example, but the difference is hopefully not going to be too confusing to anyone...

<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-particle-system-component@a5a8449/dist/aframe-particle-system-component.js"></script>
<script src="https://cdn.jsdelivr.net/npm/aframe-simple-sun-sky@^1.2.2/simple-sun-sky.js"></script>
<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-extras@d5f3f8/dist/aframe-extras.min.js"></script>
</head>
<body>
<a-scene>
<a-scene>
<a-entity id="rain" particle-system="preset: rain; color: #24CAFF; particleCount: 5000"></a-entity>

<a-entity id="sphere" geometry="primitive: sphere"
Expand All @@ -483,11 +493,9 @@ Glitch][glitch].
<a-entity id="ocean" ocean="density: 20; width: 50; depth: 50; speed: 4"
material="color: #9CE3F9; opacity: 0.75; metalness: 0; roughness: 1"
rotation="-90 0 0"></a-entity>

<a-entity id="sky" geometry="primitive: sphere; radius: 5000"
material="shader: gradient; topColor: 235 235 245; bottomColor: 185 185 210"
scale="-1 1 1"></a-entity>


<a-simple-sun-sky sun-position="1 0.4 0"></a-simple-sun-sky>

<a-entity id="light" light="type: ambient; color: #888"></a-entity>
</a-scene>
</body>
Expand Down
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 @@ -137,6 +137,7 @@ <h2>Examples</h2>
<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>
<li><a href="showcase/community-components/">Community Components</a></li>
<li><a href="showcase/curved-mockups/">Curved Mockups</a></li>
<li><a href="showcase/dynamic-lights/">Dynamic Lights</a></li>
<li><a href="showcase/hand-tracking/">Hand Tracking</a></li>
Expand Down
30 changes: 30 additions & 0 deletions examples/showcase/community-components/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<!DOCTYPE html>
<html>
<head>
<title>Community Components Example</title>
<meta name="description" content="Community Components Example">
<script src="../../../dist/aframe-master.js"></script>
<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-particle-system-component@a5a8449/dist/aframe-particle-system-component.js"></script>
<script src="https://cdn.jsdelivr.net/npm/aframe-simple-sun-sky@^1.2.2/simple-sun-sky.js"></script>
<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-extras@d5f3f8/dist/aframe-extras.min.js"></script>
</head>
<body>
<a-scene>
<a-entity id="rain" particle-system="preset: rain; color: #24CAFF; particleCount: 5000"></a-entity>

<a-entity id="sphere" geometry="primitive: sphere"
material="color: #EFEFEF; shader: flat"
position="0 0.15 -5"
light="type: point; intensity: 5"
animation="property: position; easing: easeInOutQuad; dir: alternate; dur: 1000; to: 0 -0.10 -5; loop: true"></a-entity>

<a-entity id="ocean" ocean="density: 20; width: 50; depth: 50; speed: 4"
material="color: #9CE3F9; opacity: 0.75; metalness: 0; roughness: 1"
rotation="-90 0 0"></a-entity>

<a-simple-sun-sky sun-position="1 0.4 0"></a-simple-sun-sky>

<a-entity id="light" light="type: ambient; color: #888"></a-entity>
</a-scene>
</body>
</html>