Skip to content

shinenic/react-krpano-hooks

Repository files navigation

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