gumlet.js
gumlet.js allows developers to easily generate responsive images using the srcset and sizes attributes on the <img> tag. This lets you write a single image URL that is parsed and used to make images look great at any screen size, by using gumlet to process and resize your images on the fly.
Responsive images in the browser, simplified. Pure JavaScript with zero dependencies. 3.5 KB minified and gzipped.
Overview
Before you get started with gumlet.js, it's recommended that you read Eric Portis' seminal article on srcset and sizes. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of gumlet.js is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your gumlet.js experience.
Installation
The best and easiest way to install gumlet.js is by including it in <head> section of all your pages.
<meta property="gm:host" content="{{mysubdomaiin}}.gumlet.com" />
<script src="https://cdn.gumlet.com/gumlet.js/1.0/gumlet.min.js"></script>Please replace {{mysubdomain}} in above code to the subdomain created by you on Gumlet.
Usage
Once above steps are complete, your users will automatically start getting responsive images! Yes, it's that simple. We however recommend that you make following changes to your <img> tags to make images even more optimised.
1. Add sizes attribute
sizes attribute helps browser determine best image needed for a given viewport and device. If you don't set this attribute, gumlet.js will by default set it to 100vw, which means delivered image width will always match browser width.
If you have an image which is displayed only at 1/3rd of page, you can set this attribute to 33vw and it will be served as 1/3rd of browser width. If you want the image to be always 500px wide, set sizes attributes as 500px and browser will always ensure the same size is delivered.
This attribute is very powerful and you can even write media queries and set image width conditions. Above mentioned article by Eric Portis describes it in great detail if you need to learn more about it.
2. Rename src="" to data-src=""
If you are currenly serving images from a CDN or your webserver, chances are that you would have all <img> tags with src attributes. We recommend you change them to data-src attributes.
If you don't do this step, whenever a user loads a page, browser will request image available in src attribute and as soon as gumlet.js processes it, browser will cancel the request. This is very inefficient and should be avoided. Once you set data-src attribute, gumlet.js will ensure that browser loads only the required image and no extra requests are made to server.
This is all that was needed to deliver responsive images to your users.
How it works?
Let us describe how gumlet.js works under the hood. We use capabilities to deliver responsive images available in modern browsers.
If you write img tag such as below,
<img
data-src="https://demo.gumlet.com/logo.png?w=300&h=500"
alt="Gumlet Logo"
sizes="100vw"
>Gumlet.js will generate HTML something like the following:
<img
data-src="https://demo.gumlet.com/logo.png?w=300&h=500"
alt="Gumlet Logo"
sizes="100vw"
srcset="
https://demo.gumlet.com/logo.png?w=100&h=167 100w,
https://demo.gumlet.com/logo.png?w=200&h=333 200w,
…
https://demo.gumlet.com/logo.png?w=2560&h=4267 2560w
"
src="https://demo.gumlet.com/logo.png?w=300&h=500"
>Since Gumlet can generate as many derivative resolutions as needed, gumlet.js calculates them programmatically, using the dimensions you specify (note that the w and h params scale appropriately to maintain the correct aspect ratio). All of this information has been placed into the srcset and sizes attributes.
All responsiveness will be handled automatically by the browser as the page is resized. All browsers will also automatically detect device pixel ratio as well as device viewport and breowsers will only select the best image required for the user.
Web-Proxy source
If you are using web proxy source for your image distribution, you can set following meta tag such that gumlet.js generates URLs for proxy source.
<head>
<meta property="gm:proxy" content="true">
...
</head>Disabling auto-initialization
By default, gumlet.js will automatically run as soon as the DOMContentLoaded event fires, immediately processing all img tags on the page that are set up. You can disable this auto-initialization behavior by including the following meta tag in your document's head:
<head>
<meta property="gm:init" content="false">
...
</head>Manually initializing
If you disable auto-init discribed above, you can manually initialize gumlet.js. For example:
gumlet.init();Changes to image with javascript and new dynamically added images
Gumlet.js observes all existing images for changes to "src" tags. If any change is detected, the image is automatically processed.
Gumlet.js also monitors if any new image is added to DOM. If new image is detected, the image is processed automatically.
Ignore images
If you want to exclude some <img> tags from being processed by gumlet.js, you can set data-gumlet="false" attribute and it will not be processed by this library.
Browser Support
- By default, browsers that don't support
srcset,sizes, orpicturewill gracefully fall back to the defaultimgsrcwhen appropriate. If you want to provide a fully-responsive experience for these browsers, gumlet.js works great alongside Picturefill!
Use with your image server
gumlet.js was not built to work exclusively with Gumlet.com. In fact, we expect users to use gumlet.js with their own image servers. Only requirement is that your image server shoud support resizing images with w and h parameters supplied in URLs.
If you want to serve images from your own image server, just replace the meta tag in your head section with the domain name of your image server like this:
<meta property="gm:host" content="yourimageserver.com" />Build Library
You can download source code form this repo and built the library by running following commands:
npm install
gulp minifyThis will generate gumlet.js and gumlet.min.js files in dist directory. If you want to do development on your local machine, we recommend you watch for changes and build the js files automatically using gulp watch. This will build the distributable files each time you save any file in src directory.
Licence
gumlet.js was made by Gumlet. It's licensed under the MIT license (see the license file for more info). Any contribution is absolutely welcome.
