Interactive Image
A jQuery plugin to embed interactive images on your website.
See it in action on the demo page.
Features
- Interactive videos, sounds, images and texts over large pictures
- Support for popular content providers
- Social media sharing capabilities
- Flexible configuration of markers and items
- Easily customizable with CSS
- Unit tested with Mocha
- Installable via package managers
- No restriction on commercial use
Installation
npm
$ npm install --save interactiveimagejs
Yarn
$ yarn add interactiveimagejs
Download
Download the production or the development version from GitHub.
All the plugin files (.js, .css and fonts) are located in the dist
directory.
Usage
How to use it
Edit the source code of your web page:
HTML
<head> <!-- Include Interactive Image jQuery plugin Styles --> <link rel="stylesheet" href="interactive-image.min.css" /> <!-- Specific styles of a scene --> <style> .interactive-image { width: 900px; height: 600px; background: url("/path/to/main-image.png"); } </style> </head> <body> <!-- Main container of a scene --> <div id="my-interactive-image"></div> <!-- Include jQuery --> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script> <!-- Include Interactive Image jQuery plugin JavaScript --> <script src="interactive-image.min.js"></script> </body>
Note regarding the css file: You may have to rewrite the relative paths of the fonts.
JavaScript
// Items collection var items = [ { type: "text", title: "Fur", description: "The fur of clouded leopards is...", position: { left: 100, top: 50 } }, { type: "picture", path: "/path/to/picture.png", caption: "A baby clouded leopard", position: { left: 200, top: 300 } }, { type: "audio", path: "/path/to/sound.mp3", caption: "A clouded leopard growl", position: { left: 300, top: 500 } }, { type: "video", path: "/path/to/video.mp4", caption: "A clouded leopard walking", poster: "/path/to/poster.png", position: { left: 400, top: 550 } }, { type: "provider", providerName: "youtube", parameters: { videoId: "iPRiQ6SBntQ" }, position: { left: 600, top: 550 }, sticky: true } ]; // Plugin activation $(document).ready(function() { $("#my-interactive-image").interactiveImage(items); });
More examples can be found in the examples
directory.
Social Media Share
By default, a social media share box is displayed.
You can prevent this behavior before activating the plugin:
var options = { shareBox: false }; $("#my-interactive-image").interactiveImage(items, options);
You can customize the social media share properties of your Interactive Image:
var options = { socialMedia: { url: "https://www.jpchateau.com/demo/interactive-image", text: "Clouded Leopard", hashtags: ["jQuery", "cloudedLeopard"], twitterUsername: "my_twitter_account", } } $("#my-interactive-image").interactiveImage(items, options);
Supported social media: email, Twitter and Facebook.
In case of email share, the subject of the email is the webpage title.
Sticky elements
Make some elements to have a sticky behavior:
// item object { //... sticky: true }
Debugging
In order to display some console messages to see the different steps of the processing, you can enable the debug mode before activating the plugin:
var options = { debug: true }; $("#my-interactive-image").interactiveImage(items, options);
Configuration
Plugin configuration options
Options
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
debug | boolean | true | No | false | Enable logs in console |
shareBox | boolean | false | No | true | Enable social media share |
socialMedia | object | See SocialMedia object | No | Social media configuration |
SocialMedia
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
url | string | "http://www.example.com" | No | Document URL | URL to share |
text | string | "Text" | No | Page title | Text |
hashtags | array | ["jQuery", "cloudedLeopard"] | No | Hashtags | |
twitterUsername | string | "my_twitter_account" | No | Twitter account |
You do not need to prefix your Twitter account by "@".
Items
Each item has several possibilities of configuration.
You can add a link and/or a picture to your text
items, or a caption to your picture
, audio
or video
items.
Text Item
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
type | string | "text" | Yes | Item type | |
position | object | See Position object | No | {left:0, top:0} | Hotspot position on the scene |
title | string | "My title" | Yes | Title | |
description | string | "My description" | Yes | Descriptive text | |
picturePath | string | "/path/to/picture.png" | No | Illustration source path | |
link | object | See Link object | No | HTTP Link | |
sticky | boolean | true | No | false | Sticky behavior |
Picture Item
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
type | string | "picture" | Yes | Item type | |
position | object | See Position object | No | {left:0, top:0} | Hotspot position on the scene |
path | string | "/path/to/picture.png" | Yes | Illustration source path | |
caption | string | "My caption" | No | Illustration short description | |
sticky | boolean | true | No | false | Sticky behavior |
Audio Item
Supported audio formats: mp3, ogg, wav.
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
type | string | "audio" | Yes | Item type | |
position | object | See Position object | No | {left:0, top:0} | Hotspot position on the scene |
path | string | "/path/to/sound.mp3" | Yes | Sound source path | |
caption | string | "My caption" | No | Sound short description | |
sticky | boolean | true | No | false | Sticky behavior |
Video Item
Supported video formats: mp4, webm.
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
type | string | "video" | Yes | Item type | |
position | object | See Position object | No | {left:0, top:0} | Hotspot position on the scene |
path | string | "/path/to/video.mp4" | Yes | Video source path | |
caption | string | "My caption" | No | Video short description | |
poster | string | "path/to/poster.png" | No | An image to be shown while the video is downloading | |
sticky | boolean | true | No | false | Sticky behavior |
Provider Item
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
type | string | "provider" | Yes | Item type | |
position | object | See Position object | No | {left:0, top:0} | Hotspot position on the scene |
providerName | string | "youtube|dailymotion" | Yes | Content provider name | |
parameters | object | See Parameters object | Yes | Content parameters | |
sticky | boolean | true | No | false | Sticky behavior |
Other objects
Position
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
left | integer | 200 | Yes | X absolute value | |
top | integer | 50 | Yes | Y absolute value |
Link
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
url | string | "https://www.github.com" | Yes | href attribute | |
label | string | "My webpage" | No | url value | Name of the webpage |
Parameters
Property | Type | Example | Required | Default | Purpose |
---|---|---|---|---|---|
videoId | string | "xxxYYY123" | Yes | Video identifier |
Please note that only Youtube and Dailymotion videos are supported.
Style customization
You may want to change the rendering of an item, as for example the background and the front color of text items.
Adapt this CSS snippet to your needs and add it after the interactive-image
css file is loaded:
.interactive-image .text-item { background-color: blue; color: yellow; }
Tests
All builds are unit tested with Mocha and Chai. Check it out on Travis CI!
Run all unit tests
$ npm run test
Run all unit tests and display code coverage
$ npm run test-with-coverage
Browser Support
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ |
Requirements
jQuery 1.7.2+ is required.
Dependencies
- imagesloaded to detect when images have been loaded
Philosophy
This tool is not just a means to create rich media contents. It focuses on code quality and cares about web performances.
A good code base, following the language good pratices, reduces maintainability issues and could be used as example.
Contribute
Feel free to contribute and open some issues or pull requests.
This jQuery plugin uses npm to manage dependencies and webpack as bundler.
See the complete contributing guidelines here.
Alternatives
- For business:
- Premium:
- Free:
License
Copyright (c) 2015-2019 Jean-Philippe Chateau.
This content is released under the MIT license.