React-krpano-hooks

A package migrates KRPano into React as a hook

Prerequisite

• react >= 16.8
• krpano script >= 1.20.7

Installation

• npm

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 function Note: 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" />
}

Change log

change log

Credits

react-krpano-hooks is mainly inspired by react-krpano

Keywords

React Hooks Krpano Custom hooks

License

MIT