@fiveid/scenes NPM

Scenes

Minimalist scene-switcher module in vanilla JS.

Basic usage

Scenes toggles the active classname of elements. In the simple example below, clicking the "Next" or "Previous" buttons will switch visibility between the two scenes.

index.html

<div class="scene active">
  <p>This is scene 1</p>
  <button class="scene__next">Next</button>
</div>
<div class="scene">
  <p>This is scene 2</p>
  <button class="scene__prev">Previous</button>
</div>

style.css

.scene {
  display: none;
}

.scene {
  display: block;
}

main.js

import { Scenes } from "@fiveid/scenes";

const scenes = new Scenes();

Options

Customise Scenes behaviour by passing an options object on initialisation.

Option key	Description
`selectors`	An object containing the DOM selectors that trigger certain actions (see below)
`activeClass`	The classname that designates a scene element as "active" (default: `active`)
`dataKey`	The HTML data attribute used to identify which scene index to set as active, in JS format (default: `sceneIndex`)
`initialIndex`	The index of the active scene on load (default: `0`)
`preTransition`	A function that is called before changing active state. This can be used to alter the next active scene (see full example below)
`postTransition`	A function that is called after changing active state (see full example below)

Selectors

Override default DOM selectors in options.

State changes are triggered when users click on DOM elements. The selectors that trigger these actions can be configured (or you can keep the default values).

Key	Description	Default
scene	The element that will be set as active or not	`.scene`
next	Sets the subsequent adjacent scene element to active	`.scene__next`
prev	Sets the previous adjacent scene element to active	`.scene_prev`
reset	Sets the scene element at the initial index to active	`.scene__reset`
goto	Goes to a scene element at an index specified by a HTML data attribute (e.g. `data-scene-index`)	`.scene__goto`
pop	Sets the previously active scene element as active	`.scene__pop`

Example custom selectors:

const mySelectors = {
  scene: ".block",
  next: ".block__next",
  prev: ".block__prev",
  reset: ".block__reset",
  goto: ".block__goto",
  pop: ".block__pop"
};

Pre-transition

You can trigger a side effect or alter the typical state change behaviour by passing a function to the preTransition option.

The function has three parameters:

state: an object containing currentIndex and nextIndex
callback: a function that needs to be called to trigger the state change. You can optionally pass a nextIndex value to the callback to determine which scene will next be set as active
event: if the transition was triggered by a JS event, the event object will be passed to the preTransition function

Example:

const preTransition = (state, callback, event) => {
  if (
    state.nextIndex === RESTRICTED_SCENE &&
    userIsAllowedRestrictedScene === false
  ) {
    return callback(state.currentIndex);
  }

  callback();
};

Post-transition

You can trigger a side effect after changing active state by passing a function to the postTransition option.

The function has two parameters:

state: an object containing currentIndex and prevIndex
event: if the transition was triggered by a JS event, the event object will be passed to the preTransition function

Example:

const postTransition = (state, event) => {
  lazyLoadContentOfActiveScene(state.currentIndex);
  disableMediaContentOfPreviousScene(state.prevIndex);
};

Instance properties and methods

Some potentially useful instance methods and properties are exposed.

`activeIndex`

The index of the currently active scene.

Returns:

: number

`transitionTo`

A function that sets the scene at index as active. (Note: calling transitionTo will still trigger the preTransition and postTransition functions).

Parameters:

index: number - the target scene index (default: 0)

Example:

const scenes = new Scenes();

fetchDataFromSomewhere().then(done => {
  if (done.ok) {
    scenes.transitionTo(1); // success scene
  } else {
    scenes.transitionTo(2); // error scene
  }
});

@everything-registry/sub-chunk-326

6 years ago

6 years ago

6 years ago

6 years ago