@v360-tech/v360-classic-player

v1.0.3

Published

a month ago

A web component wrapper for Vision360 diamond viewer with 360° interactive viewing and customizable controls

Downloads

0High
0Medium
0Low

v360

diamond-player 360-viewer web-component custom-element lit vision360 diamond-viewer jewelry-viewer

Diamond Player Web Component

A modern web component wrapper for the Vision360 diamond viewer. Built with Lit, this component provides a simple, reusable way to integrate 360-degree diamond viewing functionality into any web project.

Features

🎯 Web Component Standard: Works with any framework or vanilla JavaScript
🔄 360° Interactive Viewing: Smooth diamond rotation and viewing
💧 Watermark Support: Customizable watermark with positioning options
⚡ Auto-play: Optional automatic rotation on load
🔍 Zoom Controls: Enable/disable zoom with slider support
🎨 Highly Customizable: Control speed, scale, views, buttons, and more
📦 Self-contained: All dependencies bundled (jQuery, Vision360)
🎭 Light DOM: Direct DOM access for Vision360 compatibility

Installation

NPM

npm install @v360-tech/v360-classic-player

CDN

ES Module (Recommended)

<script type="module">
  import "@v360-tech/v360-classic-player";
</script>

Or use unpkg:

<script
  type="module"
  src="https://unpkg.com/@v360-tech/v360-classic-player/dist/v360-classic-player.js"
></script>

UMD (Browser Global)

<script src="https://unpkg.com/@v360-tech/v360-classic-player/dist/v360-classic-player.browser.js"></script>

Usage

Basic Example

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import "@v360-tech/v360-classic-player";
    </script>
  </head>
  <body>
    <v360-classic-player
      asset-name="Beautiful Diamond"
      path="https://your-cdn.com/360-images/"
      auto-play
    ></v360-classic-player>
  </body>
</html>

Advanced Example

<v360-classic-player
  asset-id="diamond-123"
  asset-name="Premium Diamond"
  path="https://cdn.example.com/diamonds/premium/"
  watermark="Your Brand"
  watermark-link="https://yourwebsite.com"
  watermark-position="9"
  scale-ratio="-25"
  small-viewer="0"
  speed="0"
  zoom="1"
  auto-play
></v360-classic-player>

JavaScript Integration

// Import the component
import "@v360-tech/v360-classic-player";

// Create element programmatically
const player = document.createElement("v360-classic-player");
player.setAttribute("asset-name", "My Diamond");
player.setAttribute("path", "https://example.com/images/");
player.setAttribute("auto-play", "");
document.body.appendChild(player);

Properties/Attributes

| Property | Attribute | Type | Default | Description | | ------------------- | -------------------- | ------- | -------------- | -------------------------------------------------------------------------------------------------------- | | assetId | asset-id | String | auto-generated | Unique identifier for the player instance | | assetName | asset-name | String | "" | Name of the asset, should match the folder name in the path | | path | path | String | "" | Path to the asset folder containing 360° image frames | | watermark | watermark | String | default image | Base64 of watermark PNG image | | watermarkLink | watermark-link | String | "" | Watermark link URL, triggered on click of watermark | | watermarkPosition | watermark-position | Number | 9 | Position of watermark (1-9, like numpad layout) | | scaleRatio | scale-ratio | Number | 0 | Decrease/increase size of viewer: -1 to -100 to decrease, 1 to 100 to increase | | smallViewer | sm-viewer | Boolean | false | Whether to use small viewer mode | | speed | speed | Number | 0 | Speed of rotation: decrease 1 to 200, increase -1 to -200 | | zoom | zoom | Boolean | false | Disable/enable zoom button | | autoPlay | auto-play | Boolean | true | Whether to autoplay after mouse interaction | | isFullLoad | is-full-load | Boolean | false | Whether to load full set of images at once | | isBorderRadius | is-border-radius | Boolean | false | Whether to apply border radius to viewer | | sideView | side-view | String | "" | Different views: 1-Front, 2-Right, 3-Left, 4-Back, 5-Faceup. Comma-separated combinations (e.g., "1,2") | | buttons | buttons | String | "" | Control buttons: 0-None, 1-Next/Previous, 2-Play/Pause, 3-Reverse, 4-Info. Comma-separated (e.g., "1,2") | | infoURL | info-url | String | "" | URL to open when info button is clicked | | quality | quality | String | "1" | Quality of images: ranges from 1 (normal) to 6 (excellent) |

Watermark Positions

The watermark-position attribute uses a numpad-style positioning:

1 2 3    (top-left, top-center, top-right)
4 5 6    (middle-left, center, middle-right)
7 8 9    (bottom-left, bottom-center, bottom-right)

Side Views

The side-view attribute supports multiple views that can be combined:

1 - Front view
2 - Right view
3 - Left view
4 - Back view
5 - Face-up view

Examples:
"1"     - Front view only
"1,2"   - Front + Right views
"1,2,3" - Front + Right + Left views

Control Buttons

The buttons attribute configures which control buttons to display:

0 - None (no buttons)
1 - Next/Previous buttons
2 - Play/Pause button
3 - Reverse button
4 - Info button

Examples:
"1"     - Next/Previous only
"1,2"   - Next/Previous + Play/Pause
"1,2,4" - Next/Previous + Play/Pause + Info

Scale Ratio

The scale-ratio property controls viewer sizing:

Use negative values (-1 to -100) to decrease size
Use positive values (1 to 100) to increase size
Use 0 for default size

Speed Control

The speed property controls rotation speed:

Use positive values (1 to 200) to decrease speed
Use negative values (-1 to -200) to increase speed
Use 0 for default speed

Requirements

Image Assets Structure

The Vision360 plugin expects your 360° image frames to be organized in a specific directory structure. The path attribute should point to a base URL that contains:

UI Icons (if using custom controls):
- images/icon/info.png - Information icon
- images/icon/play.png - Play/pause icon
- Other control icons as needed

Example Directory Structure:

https://your-cdn.com/diamonds/premium/
└── images/
    └── icon/
        ├── info.png
        ├── play.png
        └── ...

Note: If you encounter missing icon errors in the browser console, it means the Vision360 plugin is trying to load UI control icons. You can either:

Provide these icons in your image path at images/icon/
Use the component without custom controls (icons are optional for basic 360° viewing)
The 360° diamond viewing functionality will work even without these icons

Development

Prerequisites

Node.js 16+
npm or yarn

Setup

# Clone the repository
git clone https://github.com/v360tech/classic-movie-player.git
cd classic-movie-player

# Install dependencies
npm install

# Start development server
npm run dev

Build

# Build for production
npm run build

# Output will be in the dist/ directory

Architecture

This component uses light DOM instead of shadow DOM due to Vision360's requirements:

Light DOM Rendering: Uses createRenderRoot() { return this; } to disable shadow DOM
Global Styles: Styles are injected into document head (required for Vision360)
Direct DOM Access: Vision360 jQuery plugin requires direct access to DOM elements
Simple Initialization: No queuing or complex timing - Vision360 initializes directly in updated() lifecycle

For detailed architecture information, see ARCHITECTURE.md.

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Modern browsers with Web Components support

Legacy Browser Support

For older browsers, include the Web Components polyfill:

<script src="https://unpkg.com/@webcomponents/webcomponentsjs@latest/webcomponents-loader.js"></script>
<script src="https://unpkg.com/@v360-tech/v360-classic-player/dist/v360-classic-player.browser.js"></script>

Examples

React

import "@v360-tech/v360-classic-player";

function App() {
  return (
    <v360-classic-player
      asset-name="Diamond"
      path="https://example.com/images/"
      auto-play
    />
  );
}

Vue

<template>
  <v360-classic-player
    asset-name="Diamond"
    path="https://example.com/images/"
    auto-play
  />
</template>

<script>
import "@v360-tech/v360-classic-player";

export default {
  name: "DiamondViewer",
};
</script>

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@v360-tech/v360-classic-player";

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- component.html -->
<v360-classic-player
  asset-name="Diamond"
  path="https://example.com/images/"
  [attr.auto-play]="true"
></v360-classic-player>

Technical Notes

Light DOM Implementation

This component uses light DOM (not shadow DOM) for Vision360 compatibility:

class V360ClassicPlayer extends LitElement {
  // Disable shadow DOM - required for Vision360
  createRenderRoot() {
    return this;
  }
}

Why Light DOM?

Vision360 is a legacy jQuery plugin that requires direct DOM access
Cannot work with shadow DOM's encapsulation
Needs global CSS styles for proper rendering
Uses $(document).ready() and checks image.complete on DOM elements

Trade-offs:

❌ No style encapsulation (styles are global)
❌ No DOM encapsulation
✅ Full Vision360 functionality
✅ Works reliably across all scenarios
✅ Simple, maintainable implementation

Single Instance

This component is designed for single instance usage per page:

No initialization queue needed
Direct Vision360 initialization
Simplified lifecycle management

For multiple viewers, consider instantiating separate pages or using framework-level routing.

License

MIT License - see LICENSE file for details

Author

ymkapuriya (Yogesh Kapuriya)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

For issues and questions, please open an issue on GitHub.