Interactive Image is a jQuery plugin to embed interactive images on your website.Features:Interactive texts and images over large picturesFlexible configuration of markers and itemsEasily customizable with CSSInstallable via package managers

Image Effects Plugins

Documentation

Interactive Image npm version Build Status Code Climate

A jQuery plugin to embed interactive images on your website.

Demo

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

Chrome Safari Firefox Edge Opera
Latest ✔ Latest ✔ Latest ✔ Latest ✔ Latest ✔

Requirements

jQuery 1.7.2+ is required.

Dependencies

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

License

Copyright (c) 2015-2019 Jean-Philippe Chateau.
This content is released under the MIT license.


You May Also Like