@nimblestory/perspective-viewer

This is an NPM package of Nimblestory for viewing data in external applications.

Prerequisites

• Data file containing the Perspective/Journey and Visual data
• Folder with Visual tiles
• Folder with Waypoint Icons

Getting Started

First, we need to get the latest version of the package to the project

npm install @nimblestory/nimblestory-player@latest

Before we start importing the package we have to make sure that the styles are included in the application.

import '@nimblestory/nimblestory-player/lib/styles/index.css';

This imports styles for the components, leaflet map and also for the Ant Design library that is used internally for styling. Now that we have the styles ready we can import the player. To make things easier we have included a Loader that allows you to customise base paths for files as well as adjusting the theme for basic styling of waypoints.

import NimblestoryLoader from '@nimblestory/nimlestory-player' // this will work depending on the framework usage
// OR
const NimblestoryLoader = dynamic(() => import('@nimblestory/nimblestory-player'), { ssr: false }); // next/dynamic

Now that we have the package imported we can create a confing to supply the Loader with. The NimblestoryLoader is accepting these values:

visualBaseURL: string; // base URL for the location of visual tiles (https://domain.com/path/to/visual/)
iconBaseURL: string; // base URL for the location of icons used for waypoints (https://domain.com/path/to/icons/)
perspectiveData: Perspective | undefined; // the Perspective/Journey data - can be undefined due to async loading of data
visualsData: Visual[] | undefined; // the Visual(s) data - can be undefined due to async loading of data
defaultThemeColors?: ThemeSettings; // not required - used for basic styling of waypoints

Now that we know what values the config accepts we can populate it and pass it to the player. All the needed data/files should be provided to you by Bruce Kibbey. The data files should be something like this:

• one json file containing the Perspective + Visual data
  • this json has two objects, one for perspective and the other for visuals
• one folder containing the visual files
  • in the folder can be multiple folders with names of the visuals
  • each visual has then its own source and many numbered folders with tiles
• one folder containing icons
  • icons are used for waypoints
  • make sure you have at least one plus-circle.svg which is the default

Learn More

SharePoint Web Part Usage Example

/*No framework template*/

// React and ReactDom imports
import * as React from 'react';
import * as ReactDom from 'react-dom';

// Component and Style imports
import NimbleStoryLoader from "@nimblestory/nimblestory-player";
import '@nimblestory/nimblestory-player/lib/styles/index.css';

export interface IMapImageWebPartProps {
    description: string;
}

export default class MapImageWebPart extends BaseClientSideWebPart<IMapImageWebPartProps> {
    
    public render(): void {
        // Set height of the webpart root element 
        this.domElement.style.setProperty('height', '600px');

        // Create a React Element from the imported component
        const element = React.createElement(NimbleStoryLoader, {
            // visualData is an array of {VisualObject} elements
            // {VisualObject} is a JS Object with data needed to render the Core Visual
            visualsData: [{VisualObject}],
            // {PerspectiveObject} in a JS Object with data needed to render the Perspective
            perspectiveData: {PerspectiveObject},
            // Path to the Core Visual Tile Set storage
            // The final path to the Tiles is {visualBaseURL}{tileSetPathTemplate}
            // {tileSetPathTemplate} is present in the {VisualObject} passed to the visualData prop
            visualBaseURL: 'https://domain.com/path/to/visual/storage/',
            // Path to Icons storage
            iconBaseURL: 'https://domain.com/path/to/icons/storage/',
        })
      
        //Render the created React Element to the root element
        ReactDom.render(element, this.domElement);
    }
}

Troubleshooting

Could not load "my-solution" in require. TypeError: Cannot read properties of undefined (reading 'id')

Make sure you are using the correct version of React. The package is using react 18.2.0 but also works on earlier versions 17.0.1 (for spfx applications)

Window is not defined

The package has been initialized too early. Try dynamic import or make a timeout to see if that helps (it is not recommended to keep that in, thi is just for testing purposes). The leaflet package is using window for map movements

The waypoint has no image/broken image

The icons are missing or the default icon is missing. You can adjust the path to the default icon in the config. The default icon is missing: plus-circle.svg

I can see nothing or only the player but nothing else

Make sure the parent element of the package has set height. The package is set to take 100% of the provided height so you need to give the parent element some height.

If you can see gray background it is likely that the player has correct height but the path to the visual files could not be resolved at all.

You can manually adjust the source used for loading visual tiles by modifying the json data. The data field used for adjusting the location is called tileSetPathTemplate and it should reflect the path from base url to the actual image file. For example if my base path is https://domain.com/base/path/ we can adjust the apppending path by specifying the folder structure within the data. By default the template is visuals/m44/{z}/{x}/{y}.png where "visuals" is the parent folder for any amount of visuals and "m44" is name of the visual. The zxy should stay the same and should not be changed.