Installations
npm install js-cloudimage-360-viewDeveloper Guide
Typescript
No
Module System
CommonJS, ESM
Node Version
20.16.0
NPM Version
10.8.1
Score
75.7
Supply Chain
99.4
Quality
90.3
Maintenance
100
Vulnerability
99.3
License
Releases
Contributors
Unable to fetch Contributors
Languages
JavaScript (90.52%)
CSS (9.48%)
Developer
scaleflex
Download Statistics
Total Downloads
143,802
Last Day
97
Last Week
916
Last Month
3,731
Last Year
46,320
GitHub Statistics
2,025 Stars
402 Commits
232 Forks
31 Watching
38 Branches
12 Contributors
Bundle Size
3.70 kB
Minified
1.17 kB
Minified + Gzipped
Maintainers
Package Meta Information
Latest Version
4.0.0
Package Id
js-cloudimage-360-view@4.0.0
Unpacked Size
107.67 kB
Size
32.10 kB
File Count
6
NPM Version
10.8.1
Node Version
20.16.0
Publised On
31 Oct 2024
Total Downloads
Cumulative downloads
Total Downloads
143,802
Last day
-55.5%
97
Compared to previous day
Last week
7.3%
916
Compared to previous week
Last month
-8.7%
3,731
Compared to previous month
Last year
22.2%
46,320
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
3
Dev Dependencies
28
JS Cloudimage 360 View
360 Views, Infinite Possibilities: Unleash the Power of js-cloudimage-360-view!
🔗 Table of Contents
- 📍 Overview
- 👾 Features
- 🚀 Getting Started
- 🗺️ Hotspots or Markers Configuration
- 🗺️ Cloudimage responsive integration
- 🔧 Methods
- 🔰 Contributing
- 🎗 License
📍 Overview
The js-cloudimage-360-view project revolutionizes interactive 360-degree image viewing experiences. With robust build and deployment scripts, it simplifies development processes. Key features include viewer initialization, hotspot functionality, and dynamic configuration utilities. Ideal for e-commerce platforms and virtual tours, it offers immersive and engaging user experiences.
👾 Features
| Feature | Summary | |
|---|---|---|
| ⚙️ | Image Viewing |
|
| 🔩 | Customization |
|
| 📄 | Documentation |
|
| 🔌 | Framework Support |
|
| ⚡️ | Performance |
|
| 📦 | Dependencies |
|
🚀 Getting Started
⚙️ Installation
You can install js-cloudimage-360-view using one of the following methods:
Option 1: Add via CDN
Include the CDN link to the js-cloudimage-360-view library at the end of your <body> tag. Additionally, make sure to include the corresponding CSS file for proper styling:
1<link rel="stylesheet" href="https://scaleflex.cloudimg.io/v7/plugins/js-cloudimage-360-view/latest/js-cloudimage-360-view.min.css"> 2<script src="https://scaleflex.cloudimg.io/v7/plugins/js-cloudimage-360-view/latest/js-cloudimage-360-view.min.js?func=proxy"></script>
Note:
To ensure the js-cloudimage-360-view functionality works correctly, you must also include the CSS file. This is crucial for proper styling and display of the plugin.
This is the quickest way to get started without additional setup.
Option 2: Install with Package Manager
You can add js-cloudimage-360-view to your project using either npm or Yarn:
For npm:
1npm install js-cloudimage-360-view
For Yarn:
1yarn add js-cloudimage-360-view
Then, import it in your JavaScript file:
1import CloudImage360 from 'js-cloudimage-360-view';
OR
1window.CI360
Choose the method that best suits your project setup, and refer to the documentation for configuration options and usage examples.
🛠️ Usage
To use js-cloudimage-360-view, you need to initialize an instance of the viewer. You can either initialize a specific view or initialize all instances with a common selector.
Initialize a Single View
To initialize a single 360-degree view, use the following code:
1const cloudimage360 = new CloudImage360(); 2 3const suvCarContainer = document.getElementById('gurkha-suv'); 4 5const config = { 6 folder: 'https://scaleflex.cloudimg.io/v7/demo/suv-orange-car-360/', 7 filenameX: 'orange-{index}.jpg', 8 amountX: 73, 9 responsive: 'scaleflex', 10}; 11 12instance.init(suvCarContainer, config);
Initialize All Instances
To initialize all instances with a common selector, use the following code:
1instance.initAll('.cloudimage-360');
This will apply the 360-degree viewer to all elements matching the specified selector.
⚙️ Configuration Options
When initializing the js-cloudimage-360-view, you can customize various configuration options. Below is a list of available options, their required status, default values, and the corresponding data attributes you can use in HTML.
Method 1: Initialization via JavaScript Code
To initialize a view programmatically, use the following configuration options:
Method 2: Initialization via Data Attributes
You can also initialize the view using HTML data attributes, which correspond to the configuration options listed below.
For example:
1<div id="gurkha-suv" 2 data-folder="/path/to/images/" 3 data-api-version="v7" 4 data-amount-x="73" 5 data-speed="80" 6 data-draggable="true"> 7</div>
| Option | Data Attribute | Required | Default Value | Description |
|---|---|---|---|---|
folder | data-folder | Yes | '/' | The path to the folder containing the images. |
apiVersion | data-api-version | No | 'v7' | The API version to use. |
filenameX | data-filename-x | Yes | 'image-{index}.jpg' | The filename pattern for the X-axis images. |
filenameY | data-filename-y | No | null | The filename pattern for the Y-axis images (optional). |
imageListX | data-image-list-x | No | null | An array of images for the X-axis (optional). |
imageListY | data-image-list-y | No | null | An array of images for the Y-axis (optional). |
indexZeroBase | data-index-zero-base | No | 0 | Whether the index starts from 0. |
amountX | data-amount-x | Yes | 0 | Total number of X-axis images. |
amountY | data-amount-y | No | 0 | Total number of Y-axis images (optional). |
speed | data-speed | No | 80 | The speed of the rotation in milliseconds. |
dragSpeed | data-drag-speed | No | 150 | The speed when dragging the image. |
draggable | data-draggable | No | true | Enables dragging functionality. |
swipeable | data-swipeable | No | true | Enables swipe functionality on touch devices. |
keys | data-keys | No | false | Enables keyboard navigation. |
keysReverse | data-keys-reverse | No | false | Reverses keyboard navigation controls. |
autoplay | data-autoplay | No | false | Automatically plays the rotation. |
autoplayBehavior | data-autoplay-behavior | No | AUTOPLAY_BEHAVIOR.SPIN_X | Defines how autoplay behaves. |
playOnce | data-play-once | No | false | Plays the animation only once. |
autoplayReverse | data-autoplay-reverse | No | false | Plays the autoplay in reverse. |
pointerZoom | data-pointer-zoom | No | 0 | Defines the zoom level on pointer hover. |
fullscreen | data-fullscreen | No | false | Enables fullscreen mode. |
magnifier | data-magnifier | No | null | Defines the magnification level (optional). |
bottomCircle | data-bottom-circle | No | true | Displays the bottom circle navigation. |
bottomCircleOffset | data-bottom-circle-offset | No | 5 | The offset of the bottom circle from the container. |
ciToken | data-responsive | No | null | Token for Cloudimage API authentication (optional). 🗺️ Cloudimage responsive integration |
ciFilters | data-filters | No | null | Filters applied to Cloudimage images (optional). |
ciTransformation | data-transformation | No | null | Transformations for Cloudimage images (optional). |
lazyload | data-lazyload | No | true | Enables lazy loading of images. |
dragReverse | data-drag-reverse | No | false | Reverses drag direction. |
stopAtEdges | data-stop-at-edges | No | false | Stops the rotation at the edges. |
imageInfo | data-info | No | false | Displays image information. |
initialIconShown | data-initial-icon | No | true | Shows the initial icon on load. |
The library will automatically read these attributes to configure the instance.
🗺️ Hotspots or Markers Configuration
An array defines the configuration for hotspots or markers that can be displayed on the 360 view. Each hotspot can provide additional information or interactivity.
Hotspot Configuration Structure
Each hotspot configuration consists of the following properties:
| Property | Required | Description |
|---|---|---|
id | Yes | A unique identifier for the hotspot. |
orientation | Yes | The orientation of the hotspot (e.g., 'x' for X-axis). |
containerSize | Yes | An array defining the width and height of the container in pixels (e.g., [width, height]). This size represents the dimensions of the container when you first start setting the hotspots. |
positions | Yes | An object where keys are indices (image indexes) representing the position of the hotspot for specific images. |
content | Yes | HTML content to display in the tooltip when the hotspot is hovered or clicked. |
onClick | No | A function that defines the behavior when the hotspot is clicked (optional). |
Positions
The positions property is an object where:
- The key is the index of the image in the 360 view (e.g., 6, 7, 8, ...).
- The value is an object with
xandyproperties, representing the coordinates of the hotspot on the image.
If either the x or y value is null, it means that the hotspot will take the coordinates from the previous defined position for that index.
For example:
1positions: { 2 6: { x: 607, y: 246 }, 3 7: { x: 619, y: null }, // y is null, so it takes the previous y (246) 4 8: { x: 630, y: null }, // y is null, so it takes the previous y (246) 5 9: { x: 637, y: null }, // y is null, so it takes the previous y (246) 6 10: { x: 642, y: null }, // y is null, so it takes the previous y (246) 7},
Example Hotspot Configuration
Here's an example configuration for multiple hotspots:
1const GURKHA_SUV_HOTSPOTS_CONFIG = [ 2 { 3 id: 'hotspot-1', 4 orientation: 'x', 5 containerSize: [1170, 663], 6 positions: { 7 0: { x: 527, y: 319 }, 8 1: { x: 527, y: 319 }, 9 2: { x: 527, y: null }, // Takes the previous position 10 3: { x: 498, y: null }, // Takes the previous y (319) 11 4: { x: 470, y: null }, // Takes the previous y (319) 12 // Additional positions... 13 }, 14 content: '<div class="tooltip">Info about Hotspot 1</div>', 15 }, 16 // Additional hotspots... 17];
In the example above, the keys (0, 1, 2, 3, 4, ...) represent image indexes. If the y value is null, it inherits the y coordinate from the previous defined position. This allows for easier configuration and reduces redundancy.
🎨 Styling
The following class names are used for styling various elements within the 360-degree viewer and hotspot functionality. Each class serves a specific purpose in controlling the appearance and behavior of the component.
| Class Name | Description |
|---|---|
cloudimage-360-transition-overlay | Applies styling for the overlay that appears during transitions. |
cloudimage-360-button | Styles the main button for interacting with the 360 view. |
cloudimage-360-magnifier-button | Styles the button that activates the magnifier feature within the 360 view. |
cloudimage-loading-spinner | Styles the loading spinner displayed while the images are being loaded. |
cloudimage-initial-icon | Styles the initial icon displayed before the 360 view is fully loaded. |
cloudimage-360-icons-container | Styles the container for all icons associated with the 360 view (e.g., buttons, overlays). |
cloudimage-360-hotspot-container | Styles the container that holds the hotspots or markers in the 360 view. |
cloudimage-360-fullscreen-modal | Styles the modal that appears when the 360 view is in fullscreen mode. |
cloudimage-360-fullscreen-button | Styles the button that toggles the fullscreen mode of the 360 view. |
cloudimage-360-close-icon | Styles the close icon used to exit the fullscreen view. |
cloudimage-360-view-360-circle | Styles the circular view area of the 360 images. |
cloudimage-360-popper | Styles the popper element for displaying tooltips or additional information on hover or click. |
cloudimage-360-hotspot | Styles individual hotspots within the 360 view, allowing for customizable appearance and behavior. |
Customize these class names in your CSS files to match your application's design requirements.
Methods
getViewById(id)
Returns the view object associated with the specified ID.
1getViewById(id)
getViews()
Returns an array of all the view objects currently available.
1getViews()
updateView(id, config)
Updates the configuration of an existing view identified by its ID. If the configuration has changed significantly, the view will be destroyed and reinitialized; otherwise, it will simply be updated.
1updateView(id, config)
View Methods
onMoveHandler(movingDirection, itemsSkippedX = 1, itemsSkippedY = 1)
Handles the movement of items in the view. It takes a direction and the number of items to skip horizontally and vertically.
1onMoveHandler(movingDirection, itemsSkippedX = 1, itemsSkippedY = 1)
Parameters:
movingDirection: A string indicating the direction of movement ('right','left','top', or'bottom').itemsSkippedX: The number of items to skip in the horizontal direction (default is 1).itemsSkippedY: The number of items to skip in the vertical direction (default is 1).
Cloudimage Responsive Integration
Overview
Integrating Cloudimage for responsive images enhances the loading speed and performance of your website. This service delivers optimized images over a Content Delivery Network (CDN), ensuring that your images are served quickly and efficiently, regardless of the user's location.
How It Works
To see how Cloudimage transforms image delivery for responsive design, check out the full article on Medium. The article details the importance of responsive images in modern web development and how Cloudimage simplifies the process.
Requirements
Before you start using the Cloudimage Responsive plugin, make sure you have the following:
-
Cloudimage Token: You'll need a unique Cloudimage token to deliver your images over their CDN.
Getting Your Token:
- Register at the Cloudimage website.
- After registration, you'll receive a token that allows you to access their services.
The token grants you 25GB of image cache and 25GB of worldwide CDN traffic per month for free. This is perfect for startups and small projects looking to enhance their website's performance without incurring costs.
🔰 Contributing
- 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
- 🐛 Report Issues: Submit bugs found or log feature requests for the
js-cloudimage-360-viewproject. - 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.
Contributing Guidelines
- Fork the Repository: Start by forking the project repository to your github account.
- Clone Locally: Clone the forked repository to your local machine using a git client.
1git clone https://github.com/Scaleflex/js-cloudimage-360-view - Create a New Branch: Always work on a new branch, giving it a descriptive name.
1git checkout -b new-feature-x - Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear message describing your updates.
1git commit -m 'Implemented new feature x.' - Push to github: Push the changes to your forked repository.
1git push origin new-feature-x - Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
- Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
Contributor Graph
🎗 License
JS Cloudimage 360 View is provided under the MIT License
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
0 existing vulnerabilities detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Warn: project license file does not contain an FSF or OSI license.
Reason
Found 0/29 approved changesets -- score normalized to 0
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 2 are checked with a SAST tool
Score
3
/10
Last Scanned on 2024-12-16
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn MoreOther packages similar to js-cloudimage-360-view
js-cloudimage-360-view-utils
cloudimage responsive utils
mmc-js-cloudimage-360-view
[](https://github.com/scaleflex/js-cloudimage-360-view/releases) [](#contributing) [](https://github.com/scaleflex/js-cloudimage-360-view/releases) [](https://img.shields.io/bundlepho