UI Configuration Settings

            
              # ZLPlayer v3.3.5

ZLPlayer is a javascript class used to create ZOOMLOOK experiences. It allows you to embed an interactive ZOOMLOOK experience with a set of configurable options and interactivity.

## Features

* Easily embed a 360 object in just a few lines of code
* Set up configurable settings for the player
* Control user interaction with touch events
* Get information on zoom level and state
* Hooks for custom callbacks such as entering or leaving full screen, spin to, and more

## Usage

The following is an example of using the ZLPlayer:  

### Add the player scripts to the page

    <script src="/zoomlook/assets/ZLWebGL.js"></script>
    <script src="/zoomlook/assets/ZLPlayer.min.js"></script>

### Instantiate the ZLPlayer

* ZLPlayer(config)
  
  **config**
  * basePath: The base path of the assets directory.
  * clickLoad: If true, user need to click to start loading; Otherwise, it will load automatically. Default: false.
  * fps: Spin speed, the default value is 25, representing 25 frames per second.
  * type: Type of content. Default: "animation". Available values: ["photo", "animation", "ZLVideo", "iframe"]
  * buttons:
    * enabled: Show/hide all buttons. Default: true.
    * fullscreenButton: Show/hide fullscreen button. "desktop" mean only show on desktop. "mobile" is the same. Default: true. Available values: ["desktop", "mobile", true, false].
    * directionButton: Show/hide direction buttons. Default: true.
    * playButton: Show/hide play button. Default: true.
    * controlMoveButton: Show/hide the control move button. Default: true.

  * fullscreenMode: Fullscreen mode. Default: "page". Available values: ["device", "page"]. Device full screen is not supported on iPhone, full page as fallback is used. [Browser compatibility of device fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API#browser_compatibility)
  * bounce: Enable/disable bounce effect. Default: false.
  * spinReverse: Reverse spin direction. Default: false.
  * inertia: Enable/disable inertia effect. Default: false.
  * autoplay: Enable/disable autoplay. Default: false.
  * maxZoom: The max percentage of zoom. '100%' is min value, means no zoom. Default: "200%". Range: 100% ~ 1000%.
  * limitRange: Limit the range of the view.
    * level: The zoom level of trigger limit. Default: "130%".
    * top: Top area range. Default: 1.0. Value range: 0.1 ~ 1.0.
    * bottom: Bottom area range. Default: 1.0. Value range: 0.1 ~ 1.0.
    * left: Left area range. Default: 1.0. Value range: 0.1 ~ 1.0.
    * right: Right area range. Default: 1.0. Value range: 0.1 ~ 1.0.
  * expandButton: Expand button.
    * enabled: Whether to enable or disable the expand button. Default: true.
    * showColor: The color of the show state. Default: '#000000'.
    * hideColor: The color of the hide state. Default: '#000000'.
    * invert: Whether invert the icon. Default: false.
  * pageScroll:
    * enabled: Enable scroll page with mouse wheel + Shift key. Default false. Note that if use an iframe, pageScroll will only work in the same domain.
    * invert: If true, scroll page when Shift key down + mouse wheel. If true, scroll page by mouse wheel. Default: false.
    * touch: Whether to support it on touch device. Default: false.
  * background:
    * color: The background color. Default: '#FFFFFF'.
  * startFrame: Initial frame. Default: 1.
  * autoChangeControl: Whether to automatically change the control type when zoom level at 200. Default: true.
  * limitMemory: Reduce the size and number of images when memory is limited. Default: true.
  * limitMemorySpeedMode: Absolute or relative speed using frames/fps. The relative speed may be faster than normal. Default: "relative". Available values: ["absolute", "relative"].
  * swipeGallery: Enable or disable swipe gallery. Default: false.
  * track: Enable or disable track. This will cause all hooks to output logs to the console. Default: true.
  * crossCursor: Enable or disable cross cursor. Default: false.
  * ga4: Enable or disable ga4. Default: false.
  * metadata: Metadata information. Default: { productName: null }.
  * configVersion: The version number of configuration json file . Default: null.
  * compare: The configuration of the compare function.
    * beforeUuid: The uuid of the previous view. Default: undefined.
    * afterUuid: The uuid of the next view. Default: undefined.
    * vertical: Enable or disable vertical layout. Default: false.
    * dividerWidth: The width of the divider. Default: 2.
    * dividerColor: The color of the divider line. Default: "#000000".
    * handlerBgcolor: The color of the handler. Default: "#FFFFFF".
    * handlerActiveBgcolor: The color of the handler when active. Default: "#00AAFF".
  * previewMode: The mode of preview layer. Available values: ["auto","image", "video"]. Default: "auto".
  * previewVideo: This configuration is not recommended to be modified. It is automatically generated by DAM and modifications may cause ZLVideo to not work properly.
    * fps: The fps of the video. Default: 25.
    * filename: Specifies the video name to use. Default: null.
    * desktopResolution: Specifies the video resolution for desktop. Default: "2500".
    * mobileResolution: Specifies the video resolution for mobile. Default: "900".
  * doubleClickAction: Define a double click action. Available values: ["play", "zoom", false]. Default: "zoom".
  * iframe:
    * url: Specifies the address of the document to embed in an iframe.
    * thumbImage: Specifies the thumbnail image of the iframe. Base64 Encoded Image or URL. Default: null, which means display a default placeholder image.

---

    const ZL = new ZLPlayer({
      basePath: "/zoomlook/pix/ZLGL360/",
      clickLoad: true,
      fps: 25,
      type: "ZLVideo",
      buttons: {
          enabled: true,
          fullscreenButton:true,
          directionButton: true,
          playButton: true,
          controlMoveButton: true
      },
      fullscreenMode: 'page',
      bounce: true,
      spinReverse: true,
      inertia: true,
      autoplay: true,
      maxZoom: "170%",
      limitRange: {
        level:"130%",
        top:0.5,
        bottom:0.5,
      },
      expandButton: {
        enabled: true,
        showColor: "#000000",
        hideColor: "#000000",
        invert: false
      },
      pageScroll: {
        enabled: true,
        invert: false,
        touch: true
      },
      background: {
        color: "#000000",
      },
      crossCursor: true
    });

### load view

* loadZLView(uuid, target) or loadZLView({...configs})
  * uuid: The id of the product, which must be unique.
  * target: The container id of the view.
  
---
    ZL.loadZLView("AP5U8BMIJB", "zoom1");

### load gallery

* ZL.loadZLGallery(config, target, configList);
  * config: gallery configuration.
    * showThumb: Show thumbnails. Available values: ["all", "desktop", "mobile", false]. Default: "all".
    * thumbFit: It's used to specify how an image should be resized to fit its container. Available values: ["fill", "contain", "cover"]. Default: "contain".
    * startItem: The first gallery item to be displayed on start. Default: 0. 0 is the first one in the configList, and so on.
  * target: The container id of the gallery.
  * configList: List of contents configuration.
    * [config, config, ...].
    * config items same as ZLPlayer.
  * galleryThumbs：Customize thumbnails styles.
    * align:
      * On desktop: Available values: ["left", "right", "top", "bottom"]. Default: "right".
      * On mobile: Available values: ["top", "bottom"]. Default: "bottom".
    * scale: Set the thumbnail size. Default: 1.0.
    * roundEdge: The rounded value of the thumbnail. Default: 0.
    * bgColor: The background color of the thumbnails. Default: "#ffffff".
    * activeOutlineWidth: The width of the active outline. Default: 1. 0 is disabled.
    * activeOutlineColor: The color of the active outline. Default: "#000000".
  
---
    const config = {
        showThumb: "desktop",
        startItem: 2,
        galleryThumbs: {
          align: "right",
          scale: 1,
          roundEdge: 0,
          bgcolor: "#ffffff",
          activeOutlineWidth: 1,
          activeOutlineColor: "#000000",
        }
       };
    const configList = [{
      basePath: "/zoomlook/pix/ZLGLAnimation/",
      clickLoad: false,
      type: "animation",
      fps: 8,
      uuid: "LOOK06",
      fullscreenMode: "page"
    },
    {
      basePath: "/zoomlook/pix/ZLGLGallery/",
      clickLoad: false,
      type: "photo",
      uuid: "LOOK01",
    },
    {
      basePath: "/zoomlook/pix/ZLGLGallery/",
      clickLoad: false,
      type: "photo",
      uuid: "LOOK02",
    },
    {
      basePath: "/zoomlook/pix/ZLGLGallery/",
      clickLoad: false,
      type: "photo",
      uuid: "LOOK03",
    },
    {
      basePath: "/zoomlook/pix/ZLGLGallery/",
      clickLoad: false,
      type: "photo",
      uuid: "LOOK04",
    }];
    const ZL = new ZLPlayer();
    ZL.loadZLGallery(config, "zoom", configList);

### unload player

    ZL.unload();

### load compare 

* loadCompare(leftUuid, rightUuid, config?)
  * leftUuid: left view uuid.
  * rightUuid: right view uuid.
  * config:
    * target: The container id of the view.
    * basePath: The base path of the assets directory.
  
---
    const ZL = new ZLPlayer({
            basePath: "https://zoomlook.comdia/zl/zoomlook/pix/ZLGL2d",
            target: "zoom",
            compare: {
              beforeUuid: "BlhLpN-337653",
              afterUuid: "LDZFT-999190",
              vertical: true
            }
          });
    ZL.loadCompare();

    ---OR---

    const ZL = new ZLPlayer();
      ZL.loadCompare("BlhLpN-337653",  "LDZFT-999190", {
              basePath: "https://zoomlook.comdia/zl/zoomlook/pix/ZLGL2d",
              target: "zoom",
              compare: {
                vertical: true
              }
            } );

### use hooks

    ZL.PreloadEnd = ()=>{
        ...
        do something
        ...
    }

## States

    state = {
      gallery_count: 0,
      gallery_index: 0,
      object_playing: false,
      frame: 0,
      frames: 0,
      x: 0,
      y: 0,
      fullscreen: false,
      popup: false,
      buttons: false,
      control_type: "spin",
    }

* gallery_count: The total number of items in the gallery.
* gallery_index: The index of activation items in the gallery.
* object_playing: The playback state of an object, which usually indicates whether it is spinning.
* frame: Current frame.
* frames: Total frames.
* x/y: Current focus coordinates.
* fullscreen: Whether it is in full-screen mode.
* popup: Whether it is in popup mode.
* buttons: Whether buttons are displayed.
* control_type: Current control type. ("spin" or "pan")

## Actions

* spinTo(frame, shortestWay)
  * frame: Target frame number. Default: 1.
  * shortestWay: The use the shortest possible way from the current to the target frame. Default: true.
* getZoomLevel()
* setZoomLevel(level)
  * level: Number OR percentage.
* openPopup(config, configList?)
  * config: Same as loadZLGallery().  
  * configList: Same as loadZLGallery().
  
  Normal-View usage:

        const ZL = new ZLPlayer();
        ZL.openPopup({
          uuid: "ixIHVi-177212",
          basePath: "https://storage.googleapis.com/zoomlook/pix/ZLGLAnimation/",
          fullscreenMode: type,
        });
  
  Compare-View usage:

        const ZL = new ZLPlayer();
        ZL.openPopup({
          basePath: "https://zoomlook.comdia/zl/zoomlook/pix/ZLGL2d",
          compare:["BlhLpN-337653","aLDZFT-999190"]
        });

  Gallery usage:

        const ZL = new ZLPlayer();
        const config = {
          showThumb: "all",
          fullscreenMode: type,
        };
        const configList = [
          {
          basePath: "https://storage.googleapis.com/zoomlook/pix/ZLGLAnimation/",
          clickLoad: false,
          type: "animation",
          fps: 8,
          uuid: "LOOK06",
          },
          {
          basePath: "https://storage.googleapis.com/zoomlook/pix/ZLGLVideo/",
          clickLoad: false,
          type: "ZLVideo",
          inertia: true,
          fps: 24,
          uuid: "ZLV-ixIHVi-177212",
          },
          {
          basePath: "https://storage.googleapis.com/zoomlook/pix/ZLGLGallery/",
          clickLoad: false,
          type: "photo",
          uuid: "LOOK01",
          },
        ];
        ZL.openPopup(config, configList);
  
* closePopup()
* fullView(state?)
  * state: Boolean. Full screen or not. When no value is passed, it switches between true and false.
* showButtons(buttons)
  * buttons: Boolean or Array.
    * True/False: Whether to display buttons.
    * Array: Specify which buttons to display. Value range: ["fullscreen", "direction", "play",  "control"].

## Hooks

* onZoomMin(callback)
  * callback = (zoomLevel) => void
* onZoomMax(callback)
  * callback =  (zoomLevel) => void
* onZoom(callback)
  * callback =  (zoomLevel) => void
* onAnimateStart(callback)
  * callback =  (frame, frames) => void
* onAnimateEnd(callback)
  * callback =  (frame, frames) => void
* onPanStart(callback)
  * callback =  (x, y) => void
* onPanEnd(callback)
  * callback =  (x, y) => void
* onPreloadStart(callback)
  * callback =  () => void
* onPreloadEnd(callback)
  * callback =  () => void
* onEnterFullScreen(callback)
  * callback =  () => void
* onExitFullScreen(callback)
  * callback =  () => void
  
## Global action

* setInfo:  Set the text information.
  * Multilingual:
  
        setInfo({
          "cn": { 
            "clickLoad": "点击加载", 
            "wheelInfo": "使用Shfit+鼠标滚轮进行缩放" },
          "de": {
            "clickLoad": "Klicken Sie zum Laden",
            "wheelInfo": "Verwenden Sie Shift+Mausrad zum Zoomen"
          },
          "en": {
            "clickLoad": "Click to load",
            "wheelInfo": "Use Shift+mouse wheel to zoom"
          },
        })

  * Monolingual:

        setInfo({
          "clickLoad": "Click to load",
          "wheelInfo": "Use Shift+mouse wheel to zoom"
        })
  
## Url query parameters

* uuid
* basePath: The base path of the assets directory.
* clickLoad: If true, user need to click to start loading; Otherwise, it will load automatically. Default: false.
* fps: Spin speed, the default value is 25, representing 25 frames per second.
* type: Type of content. Default: "animation". Available values: ["photo", "animation", "ZLVideo"]
* buttons:
  * enabled: Show/hide all buttons. Default: true.
  * fullscreenButton: Show/hide fullscreen button. "desktop" mean only show on desktop. "mobile" is the same. Default: true. Available values: ["desktop", "mobile", true, false].
  * directionButton: Show/hide direction buttons. Default: true.
  * playButton: Show/hide play button. Default: true.
  * controlMoveButton: Show/hide the control move button. Default: true.
* fullscreenMode: Fullscreen mode. Default: "device". Available values: ["device", "page"]. Device full screen is not supported on iPhone, full page as fallback is used. [Browser compatibility of device fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API#browser_compatibility)
* bounce: Enable/disable bounce effect. Default: false.
* spinReverse: Reverse spin direction. Default: false.
* inertia: Enable/disable inertia effect. Default: false.
* autoplay: Enable/disable autoplay. Default: false.
* maxZoom: The max percentage of zoom. '100%' is min value, means no zoom. Default: "200%". Range: 100% ~ 1000%.
* limitRange: Limit the range of the view.
  * Default:
    `{ "level":"130%", "top":1, "bottom":1, "left":1, "right":1 }`

* expandButton: Expand button.
  * Default:
    `{ "enabled": true, "showColor": "#000000", "hideColor": "#000000", invert: false }`
* pageScroll:
  * enabled: Enable scroll page with mouse wheel + Shift key. Default false. Note that if use an iframe, pageScroll will only work in the same domain.
  * invert: If true, scroll page when Shift key down + mouse wheel. If true, scroll page by mouse wheel. Default: false.
  * touch: Whether to support it on touch device. Default: false.
* background:
  * color: The background color. Default: '#FFFFFF'.
* startFrame: Initial frame. Default: 1.
* autoChangeControl: Whether to automatically change the control type when zoom level at 200. Default: true.
* limitMemory: Reduce the size and number of images when memory is limited. Default: true.
* limitMemorySpeedMode: Absolute or relative speed using frames/fps. The relative speed may be faster than normal. Default: "relative". Available values: ["absolute", "relative"].
* track: Enable or disable track. This will cause all hooks to output logs to the console. Default: true.
* crossCursor: Enable or disable cross cursor. Default: false.
* ga4: Enable or disable ga4. Default: false.
* metadata: Metadata information. Default: { productName: null }.
* configVersion: Config version. Default: null.

## Notes

* When using json objects as url query parameters, all keys must be quoted.

* Url query parameters need to be url encoded. Otherwise special symbols may cause errors, such as # $ *.

### Examples

  <https://zoomlook.io/zoomlook/?clickLoad=false&autoplay=true>
  
  <https://zoomlook.io/zoomlook/?basePath=https://zoomlook.comdia/zl/zoomlook/pix/ZLGL360&uuid=VOGxhm-170300&clickLoad=false&autoplay=true&spinReverse=true&buttons=false&bounce=true&inertia=true>
  
  <https://zoomlook.io/zoomlook/accessibility/expand-button.html?expandButton={"enabled":true,"showColor":"%25230000ff","hideColor":"%2523aa0000"}>

  <https://zoomlook.io/zoomlook/accessibility/expand-button.html?buttons={"playButton":false,"directionButton":false}>

## Shortcut key

* P  to toggles Play/Pause
* S  toggles Spin/Move
* F/Spacebar  activates fullScreen
* '+' zooms in
* '-' zooms out
* → pan photo right
* → pan object right at fullScreen
* →  spin object right 100 - 199
* ← pan photo left
* ←  pan object left at fullScreen
* ←   spin object left 100 - 199
* ↑ pan photo up
* ↓ pan photo down
* ? and i toggle info window (future)