Overview
This document contains all of the functions you can use to optimize your images. These functions are to be placed within your implementation of Resolve.
Options
The fields used by the options object specify the configuration information that Resolve needs to connect to StackPath's image optimization service.
The fields of this object follow the format {field1: value1, field2: value2,
..., fieldn: valuen}
.
The table below lists and describes all of the available fields for for the options object.
Field | Type | Default | Use |
advancedOptions | Object | Provides a way to customize Resolve. | |
base | String | Specifies a prefix to prepend to the string value defined in the data-resolvesrc attribute of the <img> tag if the data-resolvesrc attribute does not start with a valid protocol name, such as "http:" or "file:". | |
imageFit | String | 'container' |
Defines how the image is scaled to fit within the image container defined in the CSS or <img> tag. Valid values are:
|
lazyLoad | Boolean | false | Enables or disables lazy loading. |
preloadImage | Boolean | true |
Indicates whether or not images are preloaded and stored in a buffer before replacing existing images due to a response or an API event.
|
options.advancedOptions
The advancedOptions fields allow you to customize Resolve.
The fields for this object follow the format {field1: value1, field2: value2,
..., fieldn: valuen}
.
The table below lists and describes all of the available fields for the advancedOptions object.
Field | Type | Default | Use |
allowImageUpscaling | Boolean | false |
Determines whether or not Resolve will scale images to a size that exceeds the native resolution.
|
alwaysUseSSL | Boolean | false |
Forces all connections to use HTTP over SSL (HTTPS).
This field is ignored if neverUseSSL is set to true. |
cacheThreshold | Integer | 100 |
Specifies the number of pixels used to determine when Resolve updates an image if the browser window is resized and the container width or height changes by this value. For example, if this value is 100, Resolve updates an image every time its container size changes by at least 100 pixels. Setting the interval to a large number of pixels increases the likelihood that similar requests will be served from StackPath's CDN cache. |
completedClass | String | 'ResolveComplete' | Overrides the default name that identifies the CSS class of image tags that Resolve has processed. |
containerPadFillColor | Color | 'white' | Defines the color of the padding when the imageFit options is set to 'containerPad'. |
enabledClass | String | 'Resolve' |
Overrides the default name that identifies the CSS class of image tags that Resolve needs to process. If blank, Resolve will process all image elements. |
expires | String |
Adds an Expires HTTP header, set to the value specified, to the response. To indicate the current date, enter "now". This field is ignored if using data-resolvechain and an expires argument is already present in the sink command. |
|
ignoreGif | Boolean | false |
Determines how Resolve handles GIF images when used as data-resolvesrc. When true, if a GIF image is recognized as data-resolvesrc, Resolve skips the image and sets the source to data-resolvesrc. If using an image chain with data-resolvechain, Resolve processes the GIF image without scaling it. If false, Resolve does not skip GIF images. |
lazyLoadOptions | Object |
Defines the settings to use when displaying an image when the viewport is not fully visible. This object is ignored if options.lazyLoad is set to false. |
|
maxPixelRatio | Integer | Undefined |
Specifies the maximum pixel ratio allowed. The resulting ratio is n:I where n is the value entered here. When defined, the pixel ratio never exceeds this value, regardless of the advancedOptions.overridePixelRatio or data-resolveoverridePixelRatio settings or the pixelRatio value entered in the output callback. |
neverUseSSL | Boolean | false |
Forces all connections to use HTTP.
If this is set to true, Resolve will never convert requests to HTTPS, even if alwaysUseSSL is set to true. |
overridePixelRatio | Integer |
Specifies a pixel ratio that overrides the pixel ratio of the browser. The resulting ratio is n:I where n is the value entered here. This ratio is applied globally. |
|
pageResizeDelay | Integer | 200 |
Specifies the time, in ms, to wait before Resolve determines whether or not the window has been resized. This is ignored if runOnPageResizeDown and runOnPageResizeUp are set to false. |
responsive | Boolean | true |
Indicates whether or not Resolve will process images after a window resize event occurs.
|
runOnPageLoad | Boolean | true |
Determines whether or not Resolve automatically processes images when the browser page is loaded.
|
options.advancedOptions.lazyLoadOptions
The lazyLoadOptions object consists of objects and a callback function that allows you to configure how Resolve processes images before and after they intersect a given viewport.
The settings specified in these options are ignored if the options.lazyLoad field is set to false.
observerOptions
The observerOptions object allows you to configure the Intersection Observer as described here.
The table below contains the three field descriptions and types.
Name | Type | Default | Description |
root | string | null | Specifies the target element defined as the viewport. All other properties are then applied to this viewing area. By default, this is the browser window. |
rootMargin | string | '0px 0px 0px 0px' | Defines the margins of the viewport. This property accepts a space-separated list, up to four values, representing the top, right, bottom and left margins. |
threshold | floating point | 0 | Specifies the percentage of the image that must be intersecting the viewport before it's displayed. |
onVisible(entry)
Use
Returns information about the Intersection Observer once Resolve renders the image in the viewport. This callback function returns the field defined in the following table.
Argument | Type | Description |
entry | string | Contains the information specified here. |
JavaScript API Methods
The methods in this section can be used on an instance of the Resolve object in a web page. To call these methods, use the syntax Resolve.method
, where "Resolve" is the variable name assigned when creating the Resolve instance and "method" is the method to call.
For example, if the variable name is "resolve" when creating an instance of Resolve, the following will call the blankChain method:
resolve.blankChain(10, 10)
Each of these methods is described in the following sections.
blankChain (targetWidth, targetHeight)
Use
Creates a blank image chain as a string. This is useful for setting a default image source when creating images for Resolve. This method requires the arguments defined in the table below.
Argument | Type | Description |
targetWidth | integer | Specifies the width (in pixels) of the blank image. |
targetHeight | integer | Specifies the height (in pixels) of the blank image |
Returns
Type | Description |
string | The smallest image that matches the aspect ratio. |
newImage (attributes)
Use
Creates a new HTML <img>
element with the attributes set to the values passed to Resolve. This method requires the arguments defined in the table below.
Argument | Type | Description |
attributes | object |
Contains key:value pairs specifying the <img> attributes for Resolve to use when creating the image element. If an image does not contain a width and height, Resolve will not immediately process the image. Once the image is placed in the Document Object Model, Resolve will process the image when the updateImage (element) or updateImages (imgArray) method is called. |
Returns
Type | Description |
HTML Image Element | An HTML image element <img>. |
updateImage (element, force)
Use
Instructs Resolve to process the specified HTML element. This method requires the arguments defined in the table below.
Argument | Type | Description |
element | HTML Image Element | Identifies the HTML element for Resolve to process. |
force | boolean |
Instructs Resolve to treat the image element as new and re-render the image.
|
updateImages (force)
Use
Instructs Resolve to analyze the page and update all images with the Resolve class. This method requires the arguments defined in the table below.
Argument | Type | Description |
force | boolean |
Instructs Resolve to treat each element as new and update all images.
|
updateImages (imgArray, force)
Use
Instructs Resolve to process all of the elements in the array. This method requires the arguments defined in the table below.
Argument | Type | Description |
imgArray | array | Contains a comma-separated list of the HTML image elements for Resolve to process. Because this is an array, the list must be enclosed in square brackets. |
force | boolean |
Instructs Resolve to treat each element as new and update all images.
|
JavaScript API Callback Functions
JavaScript API callback functions return information about the Resolve instance or the image and browser. These functions are to be added to the options object when creating an instance of Resolve.
When adding a callback function, the syntax <callback_name>: function(arg1,
arg2)
should be used, followed by code that handles the returned data.
In the example below, the code uses the handleEvent
callback function to display an alert if Resolve returns an error. The handleEvent
callback function provides information about the status of the Resolve instance.
handleEvent: function(response, data) { if (response == 'error') {
alert(response + ': ' + data.message;
}
}
The callback functions and returned information are described in the sections below.
handleEvent (eventName, data)
Use
Provides information about the status of the Resolve instance and associated information. This callback function requires the arguments defined in the table below.
Argument | Type | Description |
eventName | string | Contains the name or type of event for which Resolve is executing the callback. |
data | object | Contains a set of data describing the behavior of Resolve at the time of an event. |
eventName
The table below shows the possible events that handleEvent can return in the eventName argument.
Event Name | When it's fired |
started | The Resolve instance has completed initilization. |
ready |
The Resolve instance is ready to accept API commands. |
processing | The Resolve instance has initiated the optimization of an image. |
processed | The Resolve instance has optimized the resolution for a single image. |
queued | The Resolve instance receives a command while the instance is still processing a previous command. |
complete | The Resolve instance has optimized the resolution for all images that required processing. |
skipped |
The Resolve instance skips an image. |
error | An error occurs. |
data
The data object contains a set of data describing the behavior of Resolve at the time of the event. The table below shows the contents of the data object fields for each event. Some events do not return an information about the data object.
Event(s) | Object Contains |
started, ready, processing, and complete | No information. |
skipped | Element number, ID string, and reason why the event was skipped. |
processed | The command image chain string, element number, and ID string. |
queued | The string, "Resolve already running. Placed in queue." |
error | A string describing the error if Resolve recognizes the error. |
output (browser, image)
Use
Provides information about the target device and the image that Resolve is about to process. This function also returns an object containing metadata for the image. This callback function requires the arguments defined in the table below.
Argument | Type | Description |
browser | object | Contains several properties associated with the target device. |
image | object | Includes the metadata of the image. |
Returns
Type | Description |
Object | Key:value pairs used to update the metadata for the image. |
browser
The browser object contains several objects that define the properties of the target device, such as the browser and operating system. The table below shows the names and contents of these objects.
Name | Type | Contains |
browser | object | The name and version of the browser the target device is using. |
engine | object | The name of the browser engine used. |
os | object | The name and version of the Operating System of the target device. |
platform | object | The platform type and vendor. |
window | object | The pixel ratio, width, and height of the viewport on the target device. |
The table below contains a list of all other browser objects.
Object | Name | Type | Description |
browser.browser | name | string | Indicates the name of the browser on the target device. |
version | string | Specifies the version of the browser on the target device. | |
browser.engine | name | string | Indicates the name of the engine running on the browser. |
browser.os | name | string | Specifies the name of the operating system on the target device. |
version | string | Identifies the version of the operating system running on the target device. | |
browser.platform | type | string | Indicates the type, such as desktop, of the target device platform. |
vendor | string | Provides the name of the vendor that developed the platform. | |
browser.window | devicePixelRatio | floating point | Specifies the pixel ratio of the viewing container. |
width | integer | Indicates the width (in pixels) of the viewing container | |
height | integer | Indicates the height (in pixels) of the viewing container. |
image
The image object contains data about the image Resolve is currently processing. The table below contains descriptions of the key:value pairs for this object.
Name | Type | Description |
format | string |
Specifies the image type(s) used in the sink command. This field also accepts an array of strings. |
quality | string, integer, or object |
Defines the quality argument set for the sink command for the given format. This object can contain key:value pairs that specify the argument set for the different formats. You can also include a default level for formats that are not included in the list. |
source | string | Identifies the source of the image. This is the complete path of the image. |
object
The object returned as part of the output callback function includes the metadata fields described in the table below.
Name | Type | Description | Metadata Name |
format | string or array | Provides the type(s) of formats available for rendering the image. | global.resolve.format |
quality | string, integer or object | Indicates the quality level of the image. | global.resolve.quality |
expires | string | Specifies the expiry time of the image. | global.resolve.expires |
pixelRatio | integer | Identifies the pixel ratio of the image. This is the value of n in n:I. | global.resolve.pixelRatio |
HTML Tag Attributes
Resolve supports several attributes used in any <img>
tag or HTML tag that supports the background-image CSS property. The sections below contain descriptions of these attributes.
Attribute | Type | Default | Use |
class | String - Required | Identifies the CSS class of image tags. To have Resolve process the image, include the strings specified in the enabledClass field of the options.advancedOptions object. | |
data-resolvechain | String - Required if data-resolvesrc is not used | Specifies an ampersand-delimited image chain string representing the master image. | |
data-resolveheight | Integer | Value returned from StackPath |
Specifies the height (in pixels) of the image. If this attributed is omitted, Resolve queries StackPath's image optimization servers for the height of the original image. This attribute is ignored if the height is specified in the <img> tag. We recommend omitting this attribute as the query to StackPath's image optimization servers is typically fast. |
data-resolveimagefit | String | 'container' |
Defines how the image is scaled to fit within the image container defined in the CSS or <img> tag. Valid values are:
The value specified here overrides the value set in the imageFit field of the options JavaScript object. |
data-resolvesrc | String - Required if data-resolvechain is not used | Specifies the path name of the original image. If a relative path is specified, Resolve prepends the path specified with the base field of the options object. | |
data-resolvewidth | Integer | Value returned from StackPath |
Specifies the width (in pixels) of the image. If this attribute is omitted, Resolve queries StackPath's image optimization servers for the width of the original image. This attribute is ignored if the width is specified in the <img> tag. We recommend omitting this attribute as the query to StackPath's image optimization servers is typically fast. |
data-updateonpageresize | Boolean | true |
Determines if Resolve will process images in response to window resizing.
|
data-resolveoverridepixelratio | Integer |
Specifies a pixel ratio that overrides the pixel ratio of the browser. The resulting ratio is n:I where n is the value entered here. This ratio is applied only to the image or image chain specified in the HTML tag. |