Skip to content

Latest commit

 

History

History
443 lines (331 loc) · 18.9 KB

api.md

File metadata and controls

443 lines (331 loc) · 18.9 KB
Raw

imgix logo

imgix : object

imgix is the root namespace for all imgix client code.

Kind: global namespace

imgix.URL

Kind: static class of imgix

URL.attachGradientTo(elemOrSel, baseColor)

Attach a gradient of colors from the imgix image URL to the passed html element (or selector for that element)

Kind: instance method of URL

Param Type Description
elemOrSel string html elment or css selector for the element
baseColor string color in rgb or hex

URL.attachImageTo(elemOrSel, callback)

Attach the image url (.getUrl() value) to the passed html element (or selector for that element)

Kind: instance method of URL

Param Type Description
elemOrSel string html elment or css selector for the element
callback function optional callback to be called when image is set on the element

URL.autoUpdateImg(sel, callback)

When/if the url changes it will auto re-set the image on the element of the css selector passed

Kind: instance method of URL

Param Type Description
sel string css selector for an element on the page
callback autoUpdateElementCallback fires whenever the img element is updated

URL.clearParams(runUpdate)

Clear all imgix params attached to the image

Kind: instance method of URL

Param Type Description
runUpdate boolean (optional) iff using autoUpdateImg should callback be called (defaults to true)

URL.clearThenSetParams(params)

Remove an imgix param then immediately set new params. This only triggers one update if used with autoUpdateImg.

Kind: instance method of URL

Param Type Description
params object object of params to set

URL.getBaseUrl() ⇒ string

Get the base url. This is getUrl() without the query string

Kind: instance method of URL
Returns: string - the base url

URL.getColors(num, callback)

Get an array of the colors in the image

Kind: instance method of URL

Param Type Description
num number Desired number of colors
callback colorsCallback handles the response of colors

URL.getParam(param) ⇒ string

Get the value of an imgix param in the query string

Kind: instance method of URL
Returns: string - the value of the param in the current url

Param Type Description
param string the imgix param that you want the value of (e.g. txtclr)

URL.getParams() ⇒ object

Get an object of all the params and their values on the current image

Kind: instance method of URL
Returns: object - an object of params and their values (e.g. {txt: 'hello', txtclr: 'f00'})

URL.getQueryString() ⇒ string

Get the query string only. This is getUrl() with ONLY the query string (e.g. ?txt=hello&txtclr=f00)

Kind: instance method of URL
Returns: string - the query string for the url

URL.getUrl() ⇒ string

The generated imgix image url

Kind: instance method of URL
Returns: string - the generated url

new imgix.URL(url, imgParams)

Represents an imgix url

Param Type Description
url string An imgix url to start with (optional)
imgParams object imgix query string params (optional)

URL.removeParam(param)

Remove an imgix param

Kind: instance method of URL

Param Type Description
param string the imgix param to remove (e.g. txtfont)

URL.setParam(param, value, doOverride, noUpdate)

Set a single imgix param value

Kind: instance method of URL

Param Type Description
param string the imgix param to set (e.g. txtclr)
value string the value to set for the param
doOverride boolean (optional) should the value(s) be overridden if they already exist (defaults to true)
noUpdate boolean (optional) iff using autoUpdateImg should callback be called (defaults to false)

URL.setParams(dict, doOverride)

Set multiple params using using an object (e.g. {txt: 'hello', txtclr: 'f00'})

Kind: instance method of URL

Param Type Description
dict object an object of imgix params and their values
doOverride boolean should the value(s) be overridden if they already exist (defaults to true)

imgix.applyAlphaToRGB(color, alpha) ⇒ string

Apply alpha to a RGB color string

Kind: static method of imgix
Returns: string - color in rgba format rgb(255, 0, 255, 0.5)

Param Type Description
color string a color in rgb(r, g, b) format
alpha number aplpha amount 1=opaque 0=transparent

imgix.fluid([rootNode], config)

Enables fluid (responsive) images for any element(s) with the 'imgix-fluid' class. To scope to images within a specific DOM node, pass the enclosing HTML element as the first argument.

#####Option Descriptions

fluidClass string all elements with this class will have responsive images

updateOnResize boolean should it request a new bigger image when container grows

updateOnResizeDown boolean should it request a new smaller image when container shrinks

updateOnPinchZoom boolean should it request a new image when pinching on a mobile device

highDPRAutoScaleQuality boolean should it automatically use a lower quality image on high DPR devices. This is usually nearly undetectable by a human, but offers a significant decrease in file size.

onChangeParamOverride function if defined the following are passed (number h, number w, object params, HTMLElement element). When an object of params is returned they are applied to the image

autoInsertCSSBestPractices boolean should it automatically add backgroundRepeat = 'no-repeat; elem.style.backgroundSize = 'cover' elem.style.backgroundPosition = '50% 50%' to elements with a background image

fitImgTagToContainerWidth boolean should it fit img tag elements to their container's width. Does not apply to background images.

fitImgTagToContainerHeight boolean should it fit img tag elements to their container's height. Does not apply to background images.

pixelStep number image dimensions are rounded to this (e.g. for 10 the value 333 would be rounded to 340)

ignoreDPR boolean when true the dpr param is not set on the image.

debounce number postpones resize execution until after this many milliseconds have elapsed since the last time it was invoked.

lazyLoad boolean when true the image is not actually loaded until it is viewable (or within the offset)

lazyLoadOffsetVertical number when lazyLoad is true this allows you to set how far above and below the viewport (in pixels) you want before imgix.js starts to load the images.

lazyLoadOffsetHorizontal number when lazyLoad is true this allows you to set how far to the left and right of the viewport (in pixels) you want before imgix.js starts to load the images.

lazyLoadColor boolean or number or function When defined the image container's background is set to a color in the image. When value is true use first color in the color array, when value is a number use that index from the color array, when value is a function it uses whatever color is returned by the function (HTMLElement' el, Array` colors)

lazyLoadScrollContainers array Adds scroll listeners to the specified elements, in order to trigger lazy-loading on images that are scrolled into view as part of an overflowed container. Defaults to [window], but if this option is specified window is not automatically included.

throttle number ensures scroll events fire only once every n milliseconds, throttling lazyLoad activity.

maxWidth number Never set the width parameter higher than this value.

maxHeight number Never set the height parameter higher than this value.

onLoad function Called when an image is loaded. It's passed the HTMLElement that contains the image that was just loaded and the URL of that image (HTMLElement' el, String` imageURL)

Default values (passed config will extend these values)

{ fluidClass: 'imgix-fluid', updateOnResize: true, updateOnResizeDown: false, updateOnPinchZoom: false, highDPRAutoScaleQuality: true, onChangeParamOverride: null, autoInsertCSSBestPractices: false, fitImgTagToContainerWidth: true, fitImgTagToContainerHeight: false, pixelStep: 10, debounce: 200, ignoreDPR: false, lazyLoad: false, lazyLoadOffsetVertical: 20, lazyLoadOffsetHorizontal: 20, lazyLoadScrollContainers: [window], throttle: 200, maxWidth: 5000, maxHeight: 5000, onLoad: null }

Kind: static method of imgix

Param Type Default Description
[rootNode] document optional HTML element to scope operations on
config object options for fluid (this extends the defaults)

imgix.getBackgroundImage(el) ⇒ string

Returns the background image for an element

Kind: static method of imgix
Returns: string - url of the image on the element

Param Type Description
el Element the element to check

imgix.getColorBrightness(color) ⇒ Number

Gives a brightness score for a given color (higher is brighter)

Kind: static method of imgix
Returns: Number - brightness score for the passed color

Param Type Description
color string a color in rgb(r, g, b) format

imgix.getElementImage(el) ⇒ string

Intelligently returns the image on the element

Kind: static method of imgix
Returns: string - url of the image on the element

Param Type Description
el Element the element to check

imgix.getElementsWithImages() ⇒ NodeList

Gives all elements on the page that have images (or could img). Does NOT support IE8

Kind: static method of imgix
Returns: NodeList - html elements with images

imgix.getEmptyImage() ⇒ string

An empty 1x1 transparent image

Kind: static method of imgix
Returns: string - url of an empty image

imgix.hasClass(elem, name) ⇒ boolean

Checks if an element has a class applied (via jquery)

Kind: static method of imgix
Returns: boolean - true if element has the class

Param Type Description
elem Element element to check for class
name string class name to look for

imgix.hasImage(el) ⇒ boolean

Does an element have an image attached

Kind: static method of imgix
Returns: boolean - true if passed element has an image

Param Type Description
el Element element to check for images

imgix.helpers : object

The helper namespace for lower-level functions

Kind: static namespace of imgix

imgix.hexToRGB(color) ⇒ string

Converts a hex color to rgb (#ff00ff -> rgb(255, 0, 255)

Kind: static method of imgix
Returns: string - color in rgb format rgb(255, 0, 255)

Param Type Description
color string a color in hex format (#ff00ff)

imgix.isImageElement(el) ⇒ boolean

Reports if an element is an image tag

Kind: static method of imgix
Returns: boolean - true if the element is an img tag

Param Type Description
el Element the element to check

imgix.onready

Runs a function when the DOM is ready (similar to jQuery.ready)

Kind: static property of imgix

Param Type Description
ready function the function to run when the DOM is ready.

imgix.rgbToHex(color) ⇒ string

Helper method to turn rgb(255, 255, 255) style colors to hex (ffffff)

Kind: static method of imgix
Returns: string - passed color converted to hex

Param Type Description
color string in rgb(255, 255, 255) format

imgix.setElementImage(el, url) ⇒ boolean

Intelligently sets an image on an element.

Kind: static method of imgix
Returns: boolean - true on success

Param Type Description
el Element the element to check
url string the url of the image to set

imgix.setElementImageAfterLoad(el, url, callback)

Intelligently sets an image on an element after the image has been cached.

Kind: static method of imgix

Param Type Description
el Element the element to place the image on
url string the url of the image to set
callback function called once image has been preloaded and set