aframe-presentation-component v1.1.0
AFrame Presentation Component
This presentation component will let you setup an AFrame scene to work like a slidedeck. By using the presentation and slide components, you can move the camera and trigger animations when moving back and forth through the slides.
Note: This documentation will only cover the primitives that are needed to setup the presentation. If you're interested in learning more about the components running them and an alternate way to setup a presentation via <a-entity> elements instead, please read the DEVELOPMENT.md file.
Example
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Example project</title>
<meta name="description" content="Example project">
<script src="https://aframe.io/releases/0.9.2/aframe.min.js"></script>
<script src="https://unpkg.com/aframe-presentation-component/dist/aframe-presentation-component.min.js"></script>
</head>
<body>
<a-scene vr-mode-ui="enabled: false">
<a-box color="red" position="0 3 -3">
<a-text position="0 -1 0" align="center" value="Box"></a-text>
</a-box>
<a-sphere color="blue" position="6 3 -3" scale=".75 .75 .75">
<a-text position="0 -1.333 0" scale="1.333 1.333 1.333" align="center" value="Sphere"></a-text>
</a-sphere>
<a-triangle color="green" position="12 3 -3">
<a-text position="0 -1 0" align="center" value="Triangle"></a-text>
</a-triangle>
<a-cylinder color="gray" position="6 3 3">
<a-text position="0 -1 0" rotation="0 -180 0" align="center" value="Cylinder"></a-text>
</a-cylinder>
<a-entity position="0 3 0" camera>
<a-text position="0 1.5 -3" align="center" value="Press <- and -> to move back and forth"></a-text>
</a-entity>
<a-presentation aspect-ratio="16:9">
<a-slide>
<a-slide-camera position="0 3 0"></a-slide-camera>
</a-slide>
<a-slide>
<a-slide-camera position="6 3 0"></a-slide-camera>
</a-slide>
<a-slide>
<a-slide-camera position="12 3 0"></a-slide-camera>
</a-slide>
<a-slide>
<a-slide-camera position="6 3 0" rotation="0 -180 0" duration="2500"></a-slide-camera>
</a-slide>
</a-presentation>
</a-scene>
</body>
</html>Setup
After setting up your AFrame scene, first setup an entity with only a camera element.
<a-entity camera></a-entity>Then add a <a-presentation> element.
<a-entity camera></a-entity>
<a-presentation>
</a-presentation>Next, add an <a-slide> element for every slide you need.
<a-entity camera></a-entity>
<a-presentation>
<a-slide>
</a-slide>
<a-slide>
</a-slide>
<a-slide>
</a-slide>
</a-presentation>Finally, you can add actions to every a-slide to indicate what actions should be triggered once you get to that slide. This could mean moving the camera, triggering animations or making entities appear or disappear.
<a-entity camera></a-entity>
<a-presentation>
<a-slide>
<a-slide-camera position="0 3 0"></a-slide-camera>
</a-slide>
<a-slide-camera position="2 3 0"></a-slide-camera>
<a-slide-visibility selector="#background" visibility="false"></a-slide-visibility>
<a-slide>
<a-slide-visibility selector="#hello" visibility="true"></a-slide-visibility>
</a-slide>
<a-slide>
<a-slide-camera position="10 20 10" rotation="0 -180 0" duration="3000"></a-slide-camera>
<a-slide-animation selector="#model" animations="appear,position,rotation"></a-slide-animation>
</a-slide>
</a-presentation>To get a full idea of every element, read on...
Primitives
a-presentation
<a-presentation progress-bar="true" shortcuts="false" use-hash="true"></a-presentation>Description
The a-presentation primitive contains all elements makes up the slide deck.
Parameters
| Parameter | Default | Description |
|---|---|---|
| aspect-ratio | null | Sets an aspect ratio for the canvas. The format is width:height. For example: 16:9. |
| progress-bar | true | Adds a progress bar to the bottom of the document that will update every time you change slides. If you want to style it, the div element gets an id named aframe-presentation-progress-bar. |
| shortcuts | true | Whether the user can move back and forth through the slides by using the arrow keys on the keyboard or by swiping the screen (for touch device). |
| use-hash | true | Will use the URL's hash to store the current slide and move to that slide when the user enters the page. |
Events
Whenever the user changes slides, events are fired off on the presentation primitive, the new slide and the previous slide. Each event gets the following details...
| Key | Description |
|---|---|
| currentSlide | The a-slide that is getting activated. |
| direction | In which direction the user moved. -1 if the user went to a previous slide, 1 if to the next. |
| instant | If the slide-action should move to the end. |
| previousSlide | The previous slide that was active |
a-presentation.slide-change
The a-presentation.slide-change is fired on the a-presentation element whenever a slide changes.
a-presentation.slide-inactive
Is fired on the previous active a-slide.
a-presentation.slide-active
Is fired on the current active a-slide.
a-slide
<a-slide></a-slide>Description
The a-slide is a container for all slide actions. It will pass all events to its children.
Slide actions
a-slide-animation
<a-gltf-model
id="phone"
src="#phone-gltf"
animation__position="property: position; from: 0 0 0; to: 0 0 3; autoplay: false"
animation__rotation="property: position; from: 360 720 0; to: 0 0 3; autoplay: false"
animation__scale="property: scale; from: 0.25 0.25 0.25; to: 3 3 3; autoplay: false"
></a-gltf-model>
...
<a-slide-animation selector="#phone" animations="position,rotation,scale"></a-slide>Description
The a-slide-animation will automatically trigger AFrame animations to play.
Note: Each animation should have its own namespace, and autoplay should be set to false. There is also no proper support yet for looping animations.
Parameters
| Parameter | Default | Description |
|---|---|---|
| animations | [] | Which animation namespaces need to be trigger. |
| selector | What selector is used to find all elements with animations to trigger. |
a-slide-camera
<a-slide-camera position="1 2 0" rotation="90 180 0"></a-slide-camera>The a-slide-camera will move the camera to a new position.
Parameters
| Parameter | Default | Description |
|---|---|---|
| duration | 1000 | How long the animation will last in miliseconds |
| easing | linear | Easings define the accelerations and speed throughout the cycle of the animation. See a list of possible values here. |
| position | 0 0 0 | The new position |
| rotation | 0 0 0 | The new rotation |
a-slide-visibility
<a-box id="red-box"></a-box>
...
<a-slide-visibility selector="red-box" visibility="true"></a-slide-visibility>Description
The a-slide-visibility will change an entity's visibility by changing its visible attribute.
Note: When moving back one slide, the entities' visibility will be set to the opposite value.
Parameters
| Parameter | Default | Description |
|---|---|---|
| selector | What selector is used to find all elements whose visibility needs to be changed. | |
| visibility | false | Whether the entity should become visibile or not |
Creating your own slide action
By making use of the a-presentation.slide-inactive and a-presentation.slide-active events, it is possible to create your own custom actions that can be easily reused per slide.
As seen in the examples/overview.html, here is an action that will change an aframe-environment whenever a slide becomes active.
AFRAME.registerComponent('slide-environment', {
schema: {
settings: { type: 'string', default: 'preset: default' },
},
init: function() {
this.el.addEventListener('a-presentation.slide-active', () => {
const { settings } = this.data;
if (this.el.sceneEl.getAttribute('environment') === settings) {
return;
}
const elements = [].slice.call(document.querySelectorAll('.environment'));
elements.forEach((element) => {
element.parentNode.removeChild(element);
});
this.el.sceneEl.removeAttribute('environment');
this.el.sceneEl.setAttribute('environment', settings);
});
}
});
AFRAME.registerPrimitive('a-slide-environment', {
defaultComponents: {
'slide-environment': {},
},
mappings: {
'settings': 'slide-environment.settings',
}
});Which can then be followed as follows...
<a-slide>
<a-slide-environment settings="preset: tron"></a-slide-environment>
</a-slide>If you've created a slide-action that you think could be easily reusable, then feel free to create a pull request.