React-krpano-hooks NPM

React-krpano-hooks

A package migrates KRPano into React as a hook

Prerequisite

react >= 16.8
krpano script >= 1.20.7

Installation

npm install react-krpano-hooks

yarn

yarn add react-krpano-hooks

Demo & Example

React-krpano-hooks (Source from KRPano's official example demotour-winecellar)

Usage

Recommend project folder structure

root
│   package.json    
|   ...
└───public
│   │   index.html
│   │   ...
│   └───krpano
│       │   krpano.js
│       │   tour.xml
|       |   (plugins, panos, ...)
...

In tour.xml, put onstart="jscall(reactKrpano.onStart())" in to enable react-krpano-hooks (In some cases, you may need to change your url in xml if you get xml parsing failed from KRPano, see placeholder for more information)

<krpano ... onstart="jscall(reactKrpano.onStart())">
  ...
</krpano>

Create container dom with ref from useKrpano

import React from 'react'
import useKrpano from 'react-krpano-hooks'

const KrpanoExample = () => {
  const { containerRef } = useKrpano()

  return <div ref={containerRef} />
}

Example 1

Log scene name when a new scene will be loaded

example.js

const Example = () => {
  const { containerRef } = useKrpano({
    globalFunctions: {
      logNewScene: (scene) => {
        console.log('New scene: ', scene)
      },
    },
  })

  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />
}

tour.xml

<krpano>
  ...
  <events onnewscene="jscall(calc('reactKrpano.logNewScene(`' + get(xml.scene) + '`)'))" />
  ...
</krpano>

Example 2

Call krpano built-in action to reset lookat

example.js

const Example = () => {
  const { containerRef, callKrpano } = useKrpano()

  const resetLookat = () => {
    callKrpano('lookto(0, 0)')
  }

  return (
    <>
      <button
        onClick={resetLookat}
        style={{ top: '10px', left: '10px', position: 'fixed' }}
      >
        Reset
      </button>
      <div ref={containerRef} style={{ width: '100%', height: '100%' }} />
    </>
  )
}

APIs

const {
  krpanoState: {
    scriptLoaded,
    isEmbedded,
    isLoaded,
    error
  },
  setKrpano,
  getKrpano,
  callKrpano,
  spheretoscreenKrpano,
  screentosphereKrpano,
  lockView,
  unlockView,
  containerRef
} = useKrpano(options)

Returns

Name	Type	Description
krpanoState.scriptLoaded	Boolean	`True` when the krpano script is loaded
krpanoState.isEmbedded	Boolean	`True` when the embedding is done,but the xml haven't finished yet
krpanoState.isLoaded	Boolean	`True` after the xml loaded and parsed
krpanoState.error	String	Error message from krpano xml,will be `null` when no error
setKrpano(variable, value)	Function	Set the given krpano variable to the given value (return `false` when krpano not loaded yet)
getKrpano(variable)	Function	Return the value of the given krpano variable (return `false` when krpano not loaded yet)
callKrpano(action)	Function	Call and execute any krpano action code (return `false` when krpano not loaded yet)
spheretoscreenKrpano	Function	Directly call the spheretoscreen action
screentosphereKrpano	Function	Directly call the screentosphere action
lockView	Function	Lock whole view
unlockView	Function	Unlock whole view
containerRef	Ref	Used to reference a React node

Option Props

Name	Type	Description
scriptPath	String	Path of script provided by krpano, default is `'krpano/krpano.js'`
embeddingParams	Object	Krpano embedding params, the script will embed again when these params change, default is `{xml: 'krpano/tour.xml', target: 'react-krpano', html: 'prefer'}`Note: `react-krpano-hooks` have `onready` param already, so set `onready` into hooks will not work, you can set `handleLoaded` in option to execute function after embedding completed
scriptOptions	Object	Script options, default is `{async: true}`
handleLoaded	Function	Execute when embedding finished
globalFunctions	Object	Functions in this object will be registered as `js global variables`,you can call `jscall(reactKrpano.customFnc())` (or other name you assign in `globalVarName`) in xml to execute global functionNote: `react-krpano-hooks` have `onStart` global function already, so set `onStart` into hooks will not work
globalVarName	String	Variable name used for global functions,default is `'reactKrpano'`
height	String	KRPano container's height, default is `100vh`
width	String	KRPano container's width, default is `100vw`

Appendix and FAQ

Krpano module load failed

Please check the url in xml, you can use krpano's placeholders to set the correct url, according to your folder structure in /public, for example:

root
│   package.json    
|   ...
└───public
│   │   index.html
│   │   ...
│   └───krpano
│       │   krpano.js
│       │   tour.xml
│       │   ...
|       └───plugins
|           |    webvr.xml
|           |    ...
...

%HTMLPATH%: Path to the folder of the html file. eg. url="%HTMLPATH%/krpano/plugins/webvr.xml"
%VIEWER%: Path to the folder of the core krpano viewer file. eg. url="%VIEWER%/plugins/webvr.xml"

For the completed url attributes list, you can follow here

Get global javascript function & variable from `xml`

Please ref jscall and jsget

Prefer load krpano script at the beginning

react-krpano-hooks will load krpano.js when the hook start, if you want to load at the beginning, you can put the code below in your public/index.html

...
<body>
  <script src="krpano/krpano.js"></script>
  ...
  ...
</body>

Pass krpano's variables into js function arguments

Use the calc() action to build the Javascript call and pass krpano variables, for example:

<action>
  ...
  jscall(calc("reactKrpano.logNewScene(`' + get(xml.scene) + '`)"))
  ...
</action>

Custom styles

In addition to passing height & width into options, you can directly set inline style and classes in your jsx dom, for example:

const KrpanoExample = () => {
  const { containerRef } = useKrpano({
    height: '50vh',
    width: '50vw'
  })

  return <div ref={containerRef} style={{ position: 'relative', top: '10px' }} className="custom-styles" />
}