Total Pageviews

Saturday, 16 July 2022

spotlight

 Web's most easy to integrate lightbox gallery library. Super-lightweight, outstanding performance, no dependencies.

https://nextapps-de.github.io/spotlight/

Demo  •  Getting Started  •  Gallery Groups  •  Options  •  Styling  •  API  •  Changelog

Whats new in 0.7.0?

The new version includes tons of fixes, new features and improvements which was collected over the last two years. Read the Changelog to get all new features.

Live Demo:

https://nextapps-de.github.io/spotlight/

Spotlight runs out of the box:

  • No additional Javascript coding
  • No additional HTML snippets
  • No additional CSS resources
  • No additional icons/assets
  • No additional handling of dynamic content and event listener

Features

  • Video Support
  • Mounting HTML node fragments as slides (you can add just everything as a slide!)
  • Gallery groups:
    • group images to specific galleries
    • group options inheritance
  • Toolbar & Gallery tools:
    • Fullscreen
    • Zoom in/out
    • Toggle resize
    • Switch theme
    • Autoslide
    • Download
    • Progress Bar
    • Page
    • Title (also inherits from image "alt"-attribute)
    • Description
    • Customizable button
  • Adaptive responsive images (by viewport size, pixel ratio and available internet bandwidth)
  • Auto-fit images and videos (as "contain" or as "cover")
  • Custom Controls
  • Fully configurable via markup
  • Loading Spinner
  • Smart Preloading (prefetch next image including cancellation)
  • Customize via standard options
  • Simply customize via markup (data-attributes)
  • Built-in animations
  • Custom themes
  • Custom animations
  • Supported controls:
    • Keyboard
    • Touch
    • Mouse (Move + Wheel)
  • Back-Button (Android)
  • Callbacks (onclick, onshow, onclose, onchange)
  • Global API for programmatic usage

Technical properties:

  • Outstanding performance
  • Memory optimized, tiny footprint, fully cleans up
  • Event capturing (just one single global event listener)
  • Bind additional global event listener dynamically:
    • install when gallery opens
    • cleanup when gallery was closed
  • No dependencies, no jQuery
  • Fully Responsive
  • Touch-friendly mobile support
  • Super-lightweight, all in all just 9kb gzip (js + css + html + icons)
  • Support for ES6 module system

Pending Feature Suggestions:

  • Inline Gallery
  • Pinch Zoom Support
  • 2-Panel-Paging Strategy
  • Swipe down to close

Getting Started

Get Latest Stable Build (Recommended):

Bundle: (all assets bundled into one single file: js + css + html + icons)
spotlight.bundle.js Download https://rawcdn.githack.com/nextapps-de/spotlight/0.7.8/dist/spotlight.bundle.js

Non-Bundled: (js and css are separated, css includes icons as base64)
spotlight.min.js Download https://rawcdn.githack.com/nextapps-de/spotlight/0.7.8/dist/js/spotlight.min.js
spotlight.min.css Download https://rawcdn.githack.com/nextapps-de/spotlight/0.7.8/dist/css/spotlight.min.css

Sources: (not bundled at all, images as url to original resources)
ES6 Modules Download The /src/js folder of this Github repository
LESS Files (source) Download The /src/css folder of this Github repository
spotlight.css (compiled) Download https://rawcdn.githack.com/nextapps-de/spotlight/0.7.8/src/css/spotlight.css
src.zip Download Download all source files including image original resources.

Get Latest (NPM):

npm install spotlight.js

Get Latest Nightly (Do not use for production!):

Just exchange the version number from the URLs above with "master", e.g.: "/spotlight/0.7.8/dist/" into "/spotlight/master/dist".

If you are using markup on anchor elements to inject the library, then it is recommended to load the lib inside your head section of the document. Because that will better prevent the original behavior of the anchor tag (e.g. when library wasn't fully loaded on page start).

Use Bundled Version

The bundled version includes all assets like js, css, html and icon images as base64.

<html>
<head>
    <script src="spotlight.bundle.js"></script>
</head>
<body></body>
</html>

Use Non-Bundled Version

The non-bundled version needs to load js and css separately (css also includes icons as base64).

<html>
<head>
    <link rel="stylesheet" href="spotlight.min.css">
    <script src="spotlight.min.js"></script>
</head>
<body></body>
</html>

Preload Library / Async Load

If you are using markup on anchor elements to inject the library, then it is recommended to load the lib inside your head section of the document. Read example above.

Just add a link tag to the header sections which indicated to preload the script. Right before the body is closing add your site scripts. Depending on your code you may need to load them in the right order.

<html>
<head>
    <title></title>
    <link rel="preload" href="spotlight.bundle.js" as="script">
</head>
<body>
    <!--
    
    HTML CONTENT
    
    -->
    <!-- BOTTOM OF BODY -->
    <script src="spotlight.bundle.js" defer></script>
    <!-- YOUR SCRIPT -->
    <script src="my-script.js" defer></script>
</body>
</html>

You can also load the non-bundled version in the same way.

In rare situations it might produce a short flashing/reflow after page load, depending on your stack. Moving the script tag into the head section will solve this issue. Also try to use the non-bundled version.

ES6 Modules

The ES6 modules are located in src/js/. You need to load the stylesheet file explicitly (includes icons as base64).

<head>
    <link rel="stylesheet" href="dist/css/spotlight.min.css">
</head>
<script type="module">
  import Spotlight from "./src/js/spotlight.js";
</script>

You can also load modules via CDN, e.g.:

<script type="module">
  import Spotlight from "https://unpkg.com/spotlight@0.7.8/src/js/spotlight.js";
</script>

The ES6 modules are not minified. Please use your favored bundler or build tool for this purpose.

Basic Usage (Markup)

Anchor + Images

The most simple way is the combination of img tags as preview images (thumbs) wrapped in an anchor element which points to the fully sized image. The advantage of this workaround is it fully falls back to a classical behavior. It is the universal markup language which all web tools already understand. Therefore, it may have some advantages for SEO also.

Just add the class spotlight to an anchor element accordingly, e.g.:

<a class="spotlight" href="img1.jpg">
    <img src="thumb1.jpg">
</a>
<a class="spotlight" href="img2.jpg">
    <img src="thumb2.jpg">
</a>
<a class="spotlight" href="img3.jpg">
    <img src="thumb3.jpg">
</a>

This also works with dynamically loaded content. There is no need to inject listeners on new elements. Instead, Spotlight make use of global event capturing.

Non-Anchor Elements

Alternatively you can use non-anchor elements also:

<div class="spotlight" data-src="img1.jpg">
    <!-- image or any other elements -->
</a>

Pretty much the same like anchors but uses data-src instead of href.

Gallery-Groups

Grouping galleries is useful when you have multiple images on your page which should be separated into groups, instead of adding all images to one single gallery when opened.

Give one of the outer wrapping element the class spotlight-group, e.g.:

<!-- Group 1 -->
<div class="spotlight-group">
    <a class="spotlight" href="dog1.jpg">
        <img src="dog1-thumb.jpg">
    </a>
    <a class="spotlight" href="dog2.jpg">
        <img src="dog2-thumb.jpg">
    </a>
    <a class="spotlight" href="dog3.jpg">
        <img src="dog3-thumb.jpg">
    </a>
</div>
<!-- Group 2 -->
<div class="spotlight-group">
    <a class="spotlight" href="cat1.jpg">
        <img src="cat1-thumb.jpg">
    </a>
    <a class="spotlight" href="cat2.jpg">
        <img src="cat2-thumb.jpg">
    </a>
    <a class="spotlight" href="cat3.jpg">
        <img src="cat3-thumb.jpg">
    </a>
</div>

Each of these groups now opens in its own gallery.

Gallery-Groups are also useful to declare global configuration as markup just once (group options inheritance).

Basic Usage (API)

Also you can programmatically use Spotlight via the library API. This way does not require any dependant HTML elements (e.g. the classname "spotlight").

Define a gallery group as follows:

var gallery = [
    { src: "cat1.jpg" },
    { src: "cat2.jpg" },
    { src: "cat3.jpg" }
];

Show gallery with default options:

Spotlight.show(gallery /*, options */);

Options

Pass options declarative via data-attributes in the HTML markup or use the Spotlight API.

When using markup follow these style: data-option="value" (change option and value accordingly), e.g.: <a class="spotlight" data-preload="false"></a>.

When using API follow thse style { option: value } (change option and value accordingly), e.g.: { preload: false }.

You can either apply the following data-attributes to the spotlight-group wrapper element or apply them separately to each spotlight anchor element (that also overrides inherited group definitions).

When using API the spotlight-group is represented by the options payload, also you can assign attributes separately to each gallery entry (that also overrides inherited group definitions).

Option         Values Description Default
class string Set a classname to this gallery instance to apply custom styles besides themes independently. null
media "image"
"video"
"node" 		Sets the the type of the media which should be added to the page. image
animation string
Array<string>
"fade"
"slide"
"scale"
 Change animation (use built-ins or custom classname)
Note: Markup as comma-separated list, e.g: data-animation="slide,fade,scale". 		slide, fade, scale
control string
Array<string> 		Show/hide control elements as "whitelisted" through a comma-separated list, e.g. data-control="autofit,page,fullscreen" page, zoom, autofit, fullscreen, close
page true / false Show/hide page in the toolbar true
fullscreen true / false Show/hide fullscreen button (automatically hides when not supported by the browser) true
zoom true / false Show/hide both zoom buttons in the toolbar true
zoom-in true / false Show/hide zoom-in button in the toolbar true
zoom-out true / false Show/hide zoom-out button in the toolbar true
autofit true / false Show/hide autofit button in the toolbar true
close true / false Show/hide the close icon in the toolbar true
theme true / false Show/hide theme button false
play true / false / number Show/hide play button. When passing a numeric value it will be used as a delay in seconds between each tick. false
autoslide true / false Autoslide when opening gallery. false
progress true / false Show/hide the animated autoslide progress bar true
infinite true / false Restart from beginning when no slides left false
autohide true / false / number Enable/disable automatically hide controls when inactive, also set cooldown time in seconds. 7
theme string
"white"		 The classname of your custom theme. The theme "white" is a built-in theme. null
title string / false Set image title or hide it
Note: When using image elements, this attribute will also inherit automatically from <img alt="..."> as well as from <img title="...">. To prevent this behavior you can set data-title="false" explicitly. This will hide the title regardless of any image alt-attributes.		 null
description string / false Set image description or hide it null
spinner true / false Enable/disable the spinner. When disabled the image will not hide until it is fully loaded, that could be useful for progressive jpeg. true
button str Enable/disable a button in the footer section, also set button text.
Note: When using as markup you have to provide a click target for the button or you can assign an onclick callback via options when used programmatically.		 null
button-href str When using a button as markup you can provide a click target for the button, e.g. <a button="click me" button-href="https://domain.com">. null

Additional Image Options

Option         Values Description Default
src-{size} src-1200
src-2400
src-3800
... 		The tag/key represents the size of the image longest side. The content contains the path or url to the image (e.g. data-src-800="image_800x400.jpg"). null
preload true / false Enable/disable preloading of the next image true
fit "contain"
"cover"		 Auto-fit the media either as "contain" or as "cover" contain
download true / false Show/hide the download icon in the toolbar false

Additional Video Options

Most of these options for a video are inherited by the attributes of a standard video element.

Option         Values Description Default
src-{format} src-webm
src-ogg
src-mp4
... 		The tag/key represents the format of the video. The content contains the path or url to the video (e.g. data-src-webm="video.webm"). null
fit "contain"
"cover"		 Auto-fit the media either as "contain" or as "cover" contain
autoplay true
false 		Start the video immediately. false
muted true
false 		Start playing as muted. false
preload true
false 		Preload the video. false
controls true
false 		Show/hide the video controls. true
inline true
false 		Make the video player inline (equal to "playsinline"). false
poster string The path or URL to the preview image. null

from https://github.com/nextapps-de/spotlight

Posted by at
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)