DOCSEARCHbyAlgolia
Submit Docs

JuxtaposeJS Documentation

repository·master·Indexed 21 days ago

https://github.com/nuknightlab/juxtapose

JuxtaposeJS is an open-source JavaScript library (version 1.2.5) for creating before/after image sliders. It allows developers to compare two images using a sliding handle via HTML markup or the JXSlider class API. The library supports custom labels, credits, and responsive configurations, and can be installed via CDN, npm, Bower, or Meteor.

Tokens
4.5K
Snippets
19
Records
21
Agent score
75%

What's inside JuxtaposeJS

  1. Understand the Juxtapose project structure

    master

    The repository is organized into two main functional areas:

    • juxtapose/ (inner directory): Contains the resources intended for deployment to the CDN.
    • website/: Contains files specific to the Juxtapose website.
    • config.json: A central configuration file used to control building, staging, and deployment processes.

  3. Install JuxtaposeJS via CDN, npm, or Bower

    master

    You can integrate JuxtaposeJS into your project using several methods:

    CDN

    Add the following tags to the <head> of your HTML page:

    npm

    Install via npm to save it to your package.json:

    Bower

    Install via Bower to save it to your bower.json:

    Meteor

    There is also a Meteor package available via Atmosphere.

    <script src="https://cdn.knightlab.com/libs/juxtapose/latest/js/juxtapose.min.js"></script>
<link rel="stylesheet" href="https://cdn.knightlab.com/libs/juxtapose/latest/css/juxtapose.css">
    npm install --save juxtaposejs
    bower install --save juxtapose

  4. Deploy the Juxtapose website

    master

    Website deployment is managed via git-deploy. The environment variables configured in git-deploy determine the CDN paths used for each environment:

    • Staging (juxtapose.knilab.com): Uses the current development version of the CDN.
    • Production (juxtapose.knightlab.com): Uses the latest version of the CDN.

    Use the following commands to deploy:

    git deploy stg
git deploy prd

  5. Install development requirements for Juxtapose

    master

    Before setting up the development environment, ensure you have Python 2.7.x, Node.js, and virtualenvwrapper installed. You also need to install less and uglify-js@1 globally via npm to handle CSS and JavaScript processing.

    npm install -g less
npm install -g uglify-js@1

  6. Create a Juxtapose slider using HTML markup

    master

    To implement a slider using only HTML, create a div with the class juxtapose and place two img tags inside it. Ensure you include the Juxtapose JS and CSS files in your page.

    Image Attributes

    Each img tag can include:

    • data-label: Displays a label on the image.
    • data-credit: Displays a credit for the image.

    Wrapper Attributes

    The container div can use the following data-* attributes to configure the slider:

    • data-startingposition: Sets the initial handle position (e.g., 35%).
    • data-showlabels: Set to false to hide labels.
    • data-showcredits: Set to false to hide credits.
    • data-animate: Set to false to disable animation.
    • data-makeresponsive: Set to false if using an external responsive solution like pym.js and you want to disable Juxtapose's built-in responsiveness.
    <div id="juxtapose-wrapper" class="juxtapose" data-startingposition="35%" data-showlabels="false" data-showcredits="false" data-animate="false">
    <img src="https://example.com/firstimage.jpg" data-label="2009" data-credit="Alex Duner/Northwestern Knight Lab" />
    <img src="https://example.com/secondimage.jpg" data-label="2014" data-credit="Alex Duner" />
</div>
<script src="https://cdn.knightlab.com/libs/juxtapose/latest/js/juxtapose.min.js"></script>
<link rel="stylesheet" href="https://cdn.knightlab.com/libs/juxtapose/latest/css/juxtapose.css">

  7. Set up the Juxtapose development environment

    master

    Follow these steps to clone the necessary repositories and configure the Python virtual environment:

    1. Navigate to your repositories root directory.
    2. Clone the required repositories (secrets, cdn.knightlab.com, and juxtapose).
    3. Enter the juxtapose directory.
    4. Create and activate a virtual environment named juxtapose using virtualenvwrapper.
    5. Install Python dependencies from requirements.txt.
    6. Copy env.sh.example to env.sh and configure it for your local environment.
    cd path_to_repos_root

git clone git@github.com:NUKnightLab/secrets.git
git clone git@github.com:NUKnightLab/cdn.knightlab.com.git
git clone git@github.com:NUKnightLab/juxtapose.git

cd juxtapose
mkvirtualenv juxtapose
workon juxtapose
pip install -r requirements.txt
cp env.sh.example env.sh

  8. Stage and deploy JavaScript changes to the CDN

    master

    To deploy updates to the JavaScript library, first ensure all changes are tested and the package.json version number is updated. Use the following npm scripts to stage releases to the cdn.knightlab.com repository:

    • npm run stage_latest: (Most common) Prompts for a version number (tag) matching package.json. Builds a ZIP archive and copies the distribution to both the versioned subdirectory and the /latest/ directory in the CDN repo.
    • npm run stage: Tags a version without updating the /latest/ directory.
    • npm run stage_dev: Stages a development version.

    Final Deployment Step: After running the npm scripts, commit the changes within the cdn.knightlab.com repository and execute the deployment script:

    ./deploy.sh
    npm run stage_latest

# Then in the cdn.knightlab.com repo:
./deploy.sh

  9. How third-party image links (Dropbox and Google Drive) are handled

    master

    The Juxtapose interface includes logic to automatically correct common mistakes when users paste links from Dropbox or Google Drive to ensure they function as direct image URLs.

    Dropbox

    • Share Links: If a link contains /home, it is flagged as an invalid image link. The system expects a 'share URL'.
    • Direct Links: The system appends ?raw=1 to Dropbox links to ensure they point to the raw image file rather than a preview page.
    • Picker Integration: When using the Dropbox picker, the domain www.dropbox.com is replaced with dl.dropboxusercontent.com to ensure a direct download link.

    Google Drive

    • Share Links: Standard Google Drive share links (e.g., https://drive.google.com/open?id=...) do not work as direct image sources. The system automatically converts them to the direct export format: https://drive.google.com/uc?export=view&id={FILE_ID}
    ```javascript
// Example of Google Drive link conversion logic
// Input: https://drive.google.com/open?id=0By5R-j9oQKMJQUlYRFVSQ1pWZWc
// Output: https://drive.google.com/uc?export=view&id=0By5R-j9oQKMJQUlYRFVSQ1pWZWc
```埋

  10. Configure the Flask application via environment variables

    master

    The backend application uses a settings module to configure its behavior. You can specify which module to load using the FLASK_SETTINGS_MODULE environment variable. If not provided, it defaults to core.settings.

    Additionally, the application can load configuration from a file path specified by the FLASK_SETTINGS_FILE environment variable.

    export FLASK_SETTINGS_MODULE='my_custom_settings'
export FLASK_SETTINGS_FILE='/path/to/config.py'
python app.py

  11. Security Warning: XSS via Credits

    master

    JuxtaposeJS renders the credit property (from the JS config) or the data-credit attribute (from HTML) directly as HTML.

    Warning: This creates a potential XSS vulnerability. If you are building a service that allows users to provide their own credits, you must sanitize these strings to prevent the injection of malicious code before passing them to JuxtaposeJS.