Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/NUKnightLab/juxtapose

JuxtaposeJS is a JavaScript library for making before/after image sliders
https://github.com/NUKnightLab/juxtapose

Last synced: about 2 months ago
JSON representation

JuxtaposeJS is a JavaScript library for making before/after image sliders

Awesome Lists containing this project

README 

        
# JuxtaposeJS



[JuxtaposeJS][https://juxtapose.knightlab.com] is a simple, open source tool for creating before/after image sliders. Just provide two image URLs and Juxtapose will do the rest of the work for you. Below are instructions for implementing Juxtapose with HTML and Javascript but we also have a [tool that lets you make a slider without needing to know any code](https://juxtapose.knightlab.com#create-new).



If you want to contribute to Juxtapose, check out the `DEVELOPERS.md` file for installation instructions. Fork the project, create a new branch with your features, and submit a pull request. Thanks for your help!



#### Contents

* [Installation](#installation)

* [Create a Juxtapose Slider](#create-a-juxtapose-slider)

    * [Create an iFrame](#create-an-iframe)

    * [HTML Implementation](#html-implementation)

    * [Javascript Implementation](#javascript-implementation)

* [Modifications and Custom Behavior](#modifications-and-custom-behavior)

* [Security Information](#security-information)



### Installation

The easiest way to create a Juxtapose slider is to go to to [https://juxtapose.knightlab.com][1] and use the tool to generate an embedable code snippet that you can use on any website. There are a number of other ways to install Juxtapose on your website.



**CDN** — Juxtapose is available on the Knight Lab CDN. Just add this code to the `` of your HTML page:

```html



```



**Package Managers** — Juxtapose is available on both the [npm](https://www.npmjs.com/package/juxtaposejs) and [Bower](https://bower.io/) package registries. The following commands will, respectively, save Juxtapose to your package.json and bower.json requirements files.



```bash

npm install --save juxtaposejs

bower install --save juxtapose

```



There is also a [Meteor package](https://atmospherejs.com/kyleking/juxtapose-js) available.



### Create a Juxtapose Slider



#### Create an iFrame

The easiest way to create a Juxtapose slider is to go to to [https://juxtapose.knightlab.com][1] and use the tool to generate an embedable code snippet that you can use on any website. The tool is easy to use and requires no coding knowledge whatsoever. If you want to use JuxtaposeJS without using the embed generator, keep reading to learn about different implementation methods.



#### HTML Implementation

The easiest way to implement the image slider is to add this code to your markup:



```html



    

    




```



Each `img` can also take additional attributes like so:



```html



```



If each image has an `data-label` attribute defined, the slider will display a label on each image. If each image has a `data-credit` attribute defined, the slider will display a credit for each image.



The slider wrapper can also take some additional attributes as well to specify a few options:



```html

...


```



Specifying a starting position with `data-startingposition` lets you focus the users attention on the part of the image where the change is most noticeable. To toggle the visibility of the labels and the credits respectively, set `data-showlabels` and `data-showcredits` to false. And to disable the animation, set `data-animate` to false.



If you are using Juxtapose in an existing responsive iFrame solution like [pym.js](https://blog.apps.npr.org/pym.js/) and don't want to use Juxtapose's built in (but faily opinionated) responsive iFrame solution, you can set `data-makeresponsive` to false.



#### Javascript Implementation

The `JXSlider` class takes three arguments. First, is the string of the ID of the element you want to turn into a slider. Second is an array of two objects. Each object *must* have `src` defined and can optionally define a `label` and a `credit`. The third argument lets you set additional options for the image slider.



```js




slider = new juxtapose.JXSlider('#foo',

    [

        {

            src: 'https://example.com/firstimage.jpg',

            label: '2009',

            credit: 'Image Credit'

        },

        {

            src: 'https://example.com/secondimage.jpg',

            label: '2014',

            credit: "Image Credit"

        }

    ],

    {

        animate: true,

        showLabels: true,

        showCredits: true,

        startingPosition: "50%",

        makeResponsive: true

    });



```



### Modifications and Custom Behavior

#### CSS

You can customize how JuxtaposeJS looks by modifying its CSS. For instructions, [click here](https://github.com/NUKnightLab/juxtapose/wiki/Styling-the-Slider).



#### JavaScript



The JXSlider class contains a few methods you can use to modify your sliders.



If you instantiated your sliders with the HTML method but still want to access one of your sliders programmatically, JuxtaposeJS creates an array of the JXSliders on your page that you can access with `juxtapose.sliders`.

```javascript

JXSlider.updateSlider(percentage, animate);

```



*Percentage* indicates where you want to set the handle relative to the left side of the slider. If you set *animate* to `true`, the handle will animate to the new location; if animate is set to `false`, the handle will not.



### Security Information



As part of rendering a juxtapose instance, this library renders a "credit" as HTML. Juxtapose passes this string directly through from the `data-credit` attribute, or from the `credit` property of the configuration object for either of the images.



In the strictest sense, this exposes an XSS vulnerability; however, we believe that for JuxtaposeJS to exist as a tool in a toolkit, it is both responsible and optimal to leave any HTML sanitizing as the responsibility of integrators, who may have their own ideas about what is appropriate. Therefore, take note: if you are providing a service which helps people to create juxtapose instances, you should take appropriate responsibility for preventing the injection of malicious code.