Module: utils

Utilities
Source:
Parameters:
Name Type Description
srcset srcset Options with either `breakpoints` or `min_width`, `max_width`, and `max_images`
Source:
Returns:
Array of breakpoints
Type
Array.<number>

Members

(private, inner, constant) URL_KEYS

A list of keys used by the url() function.
Source:

Methods

(private, static) archive_params(options) → {object}

Returns a Hash of parameters used to create an archive
Parameters:
Name Type Description
options object
Source:
Returns:
Archive API parameters
Type
object

(private, static) build_custom_headers(headers) → {Array.<string>|object|string}

Build the custom headers for the request
Parameters:
Name Type Description
headers
Source:
Returns:
An object of name and value, an array of header strings, or a string of headers
Type
Array.<string> | object | string

(static) download_archive_url(options) → {String}

Returns a URL that when invokes creates an archive and returns it.
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Default Description
resource_type string <optional>
"image" The resource type of files to include in the archive. Must be one of :image | :video | :raw
type string <optional>
"upload" The specific file type of resources: :upload|:private|:authenticated
tags string | Array <optional>
list of tags to include in the archive
public_ids string | Array.<string> <optional>
list of public_ids to include in the archive
prefixes string | Array.<string> <optional>
list of prefixes of public IDs (e.g., folders).
transformations string | Array.<string> <optional>
list of transformations. The derived images of the given transformations are included in the archive. Using the string representation of multiple chained transformations as we use for the 'eager' upload parameter.
mode string <optional>
"create" return the generated archive file or to store it as a raw resource and return a JSON with URLs for accessing the archive. Possible values: :download, :create
target_format string <optional>
"zip"
target_public_id string <optional>
public ID of the generated raw resource. Relevant only for the create mode. If not specified, random public ID is generated.
flatten_folders boolean <optional>
false If true, flatten public IDs with folders to be in the root of the archive. Add numeric counter to the file name in case of a name conflict.
flatten_transformations boolean <optional>
false If true, and multiple transformations are given, flatten the folder structure of derived images and store the transformation details on the file name instead.
use_original_filename boolean <optional>
Use the original file name of included images (if available) instead of the public ID.
async boolean <optional>
false If true, return immediately and perform the archive creation in the background. Relevant only for the create mode.
notification_url string <optional>
URL to send an HTTP post request (webhook) when the archive creation is completed.
target_tags= string | Array.<string> <optional>
array. Allows assigning one or more tag to the generated archive file (for later housekeeping via the admin API).
keep_derived string <optional>
false keep the derived images used for generating the archive
Source:
Returns:
archive url
Type
String

(static) download_zip_url()

Returns a URL that when invokes creates an zip archive and returns it.
Source:
See:
  • download_archive_url

(static) extractTransformationParams(options) → {Object}

Create a new object with only transformation parameters
Parameters:
Name Type Description
options object The source object
Source:
Returns:
An object containing only transformation parameters
Type
Object

(static) extractUrlParams(options) → {Object}

Create a new object with only URL parameters
Parameters:
Name Type Description
options object The source object
Source:
Returns:
An object containing only URL parameters
Type
Object

(static) generate_auth_token(options) → {string}

Generate an authorization token
Parameters:
Name Type Description
options authTokenOptions
Source:
Returns:
the authorization token
Type
string

(static) html_attrs(attrs) → {*}

Parameters:
Name Type Description
attrs
Source:
Returns:
Type
*

(private, static) jsonArrayParam(data, modifieropt) → {String|null}

Returns a JSON array as String. Yields the array before it is converted to JSON format
Parameters:
Name Type Attributes Description
data object | String | Array.<object>
modifier function <optional>
called with the array before the array is stringified
Source:
Returns:
a JSON array string or `null` if data is `null`
Type
String | null

(static) NOP()

Empty function - do nothing
Source:

(private, static) only(source, …keys) → {object}

Returns a new object with key values from source based on the keys. `null` or `undefined` values are not copied.
Parameters:
Name Type Attributes Description
source object The object to pick values from.
keys string <repeatable>
One or more keys to copy from source.
Source:
Returns:
A new object with the required keys and values.
Type
object

(static) option_consume(options, option_name, default_valueopt)

Deletes `option_name` from `options` and return the value if present. If `options` doesn't contain `option_name` the default value is returned.
Parameters:
Name Type Attributes Description
options Object a collection
option_name String the name (key) of the desired value
default_value * <optional>
the value to return is option_name is missing
Source:

(private, static) patchFetchFormat(options)

Handle the format parameter for fetch urls
Parameters:
Name Type Description
options url and transformation options. This argument may be changed by the function!
Source:

(private, static) present(value) → {boolean}

Verify that the parameter `value` is defined and it's string value is not zero.
This function should not be confused with `isEmpty()`.
Parameters:
Name Type Description
value string | number The value to check.
Source:
Returns:
True if the value is defined and not empty.
Type
boolean

(static) zip_download_url()

Utility method that uses the deprecated ZIP download API.
Deprecated:
  • Replaced by {download_zip_url} that uses the more advanced and robust archive generation and download API
Source:

(private, inner) createSrcset(publicId, stops, options) → {string}

Create the srcset attribute
Parameters:
Name Type Description
publicId string The public ID of the resource.
stops Array.<(string|number)> A list of breakpoints (width specifications).
options object The transformation parameters, configuration parameters, and standard HTML <img> tag attributes to apply to the image tag.
Source:
Returns:
The srcset attribute
Type
string

(inner) hashToQuery(hash) → {string}

Convert a hash of values to a URI query string. Array values are spread as individual parameters.
Parameters:
Name Type Description
hash object Key-value parameters
Source:
Returns:
A URI query string.
Type
string

(private, inner) join_pair(key, valueopt) → {string}

Render the key/value pair as an HTML tag attribute
Parameters:
Name Type Attributes Description
key string
value string | boolean | number <optional>
Source:
Returns:
A string representing the HTML attribute
Type
string

(inner) normalize_expression(expression) → {Object|String}

Normalize an offset value
Parameters:
Name Type Description
expression String a decimal value which may have a 'p' or '%' postfix. E.g. '35%', '0.4p'
Source:
Returns:
a normalized String of the input value if possible otherwise the value itself
Type
Object | String

(private, inner) process_if() → {string}

Parse "if" parameter Translates the condition if provided.
Source:
Returns:
"if_" + ifValue
Type
string

(private, inner) process_layer(layer) → {string}

Parse layer options
Parameters:
Name Type Description
layer object | * The layer to parse.
Source:
Returns:
layer transformation string
Type
string

(inner) process_video_params(param) → {String}

A video codec parameter can be either a String or a Hash.
Parameters:
Name Type Description
param Object vc_[ : : []] or { codec: 'h264', profile: 'basic', level: '3.1' }
Source:
Returns:
: : []] if a Hash was provided or the param if a String was provided. Returns null if param is not a Hash or String
Type
String

(private, inner) singleSource(publicId, options, width) → {string}

Create a single source entry for the srcset attribute
Parameters:
Name Type Description
publicId The public ID of the resource
options object The transformation parameters, configuration parameters, and standard HTML <img> tag attributes to apply to the image tag.
width string | number The breakpoint (width specification) of the current entry
Source:
Returns:
a single srcset entry
Type
string
Helper function. Gets or populates srcset breakpoints using provided parameters Either the breakpoints or min_width, max_width, max_images must be provided.
Source:
Parameters:
Name Type Description
srcset srcset Options with either `breakpoints` or `min_width`, `max_width`, and `max_images`
Source:
Returns:
Array of breakpoints
Type
Array.<number>

Members

(private, inner, constant) URL_KEYS

A list of keys used by the url() function.
Source:

Methods

(private, static) archive_params(options) → {object}

Returns a Hash of parameters used to create an archive
Parameters:
Name Type Description
options object
Source:
Returns:
Archive API parameters
Type
object

(private, static) build_custom_headers(headers) → {Array.<string>|object|string}

Build the custom headers for the request
Parameters:
Name Type Description
headers
Source:
Returns:
An object of name and value, an array of header strings, or a string of headers
Type
Array.<string> | object | string

(static) download_archive_url(options) → {String}

Returns a URL that when invokes creates an archive and returns it.
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Default Description
resource_type string <optional>
"image" The resource type of files to include in the archive. Must be one of :image | :video | :raw
type string <optional>
"upload" The specific file type of resources: :upload|:private|:authenticated
tags string | Array <optional>
list of tags to include in the archive
public_ids string | Array.<string> <optional>
list of public_ids to include in the archive
prefixes string | Array.<string> <optional>
list of prefixes of public IDs (e.g., folders).
transformations string | Array.<string> <optional>
list of transformations. The derived images of the given transformations are included in the archive. Using the string representation of multiple chained transformations as we use for the 'eager' upload parameter.
mode string <optional>
"create" return the generated archive file or to store it as a raw resource and return a JSON with URLs for accessing the archive. Possible values: :download, :create
target_format string <optional>
"zip"
target_public_id string <optional>
public ID of the generated raw resource. Relevant only for the create mode. If not specified, random public ID is generated.
flatten_folders boolean <optional>
false If true, flatten public IDs with folders to be in the root of the archive. Add numeric counter to the file name in case of a name conflict.
flatten_transformations boolean <optional>
false If true, and multiple transformations are given, flatten the folder structure of derived images and store the transformation details on the file name instead.
use_original_filename boolean <optional>
Use the original file name of included images (if available) instead of the public ID.
async boolean <optional>
false If true, return immediately and perform the archive creation in the background. Relevant only for the create mode.
notification_url string <optional>
URL to send an HTTP post request (webhook) when the archive creation is completed.
target_tags= string | Array.<string> <optional>
array. Allows assigning one or more tag to the generated archive file (for later housekeeping via the admin API).
keep_derived string <optional>
false keep the derived images used for generating the archive
Source:
Returns:
archive url
Type
String

(static) download_zip_url()

Returns a URL that when invokes creates an zip archive and returns it.
Source:
See:
  • download_archive_url

(static) extractTransformationParams(options) → {Object}

Create a new object with only transformation parameters
Parameters:
Name Type Description
options object The source object
Source:
Returns:
An object containing only transformation parameters
Type
Object

(static) extractUrlParams(options) → {Object}

Create a new object with only URL parameters
Parameters:
Name Type Description
options object The source object
Source:
Returns:
An object containing only URL parameters
Type
Object

(static) generate_auth_token(options) → {string}

Generate an authorization token
Parameters:
Name Type Description
options authTokenOptions
Source:
Returns:
the authorization token
Type
string

(static) html_attrs(attrs) → {*}

Parameters:
Name Type Description
attrs
Source:
Returns:
Type
*

(private, static) jsonArrayParam(data, modifieropt) → {String|null}

Returns a JSON array as String. Yields the array before it is converted to JSON format
Parameters:
Name Type Attributes Description
data object | String | Array.<object>
modifier function <optional>
called with the array before the array is stringified
Source:
Returns:
a JSON array string or `null` if data is `null`
Type
String | null

(static) NOP()

Empty function - do nothing
Source:

(private, static) only(source, …keys) → {object}

Returns a new object with key values from source based on the keys. `null` or `undefined` values are not copied.
Parameters:
Name Type Attributes Description
source object The object to pick values from.
keys string <repeatable>
One or more keys to copy from source.
Source:
Returns:
A new object with the required keys and values.
Type
object

(static) option_consume(options, option_name, default_valueopt)

Deletes `option_name` from `options` and return the value if present. If `options` doesn't contain `option_name` the default value is returned.
Parameters:
Name Type Attributes Description
options Object a collection
option_name String the name (key) of the desired value
default_value * <optional>
the value to return is option_name is missing
Source:

(private, static) patchFetchFormat(options)

Handle the format parameter for fetch urls
Parameters:
Name Type Description
options url and transformation options. This argument may be changed by the function!
Source:

(private, static) present(value) → {boolean}

Verify that the parameter `value` is defined and it's string value is not zero.
This function should not be confused with `isEmpty()`.
Parameters:
Name Type Description
value string | number The value to check.
Source:
Returns:
True if the value is defined and not empty.
Type
boolean

(static) zip_download_url()

Utility method that uses the deprecated ZIP download API.
Deprecated:
  • Replaced by {download_zip_url} that uses the more advanced and robust archive generation and download API
Source:

(private, inner) createSrcset(publicId, stops, options) → {string}

Create the srcset attribute
Parameters:
Name Type Description
publicId string The public ID of the resource.
stops Array.<(string|number)> A list of breakpoints (width specifications).
options object The transformation parameters, configuration parameters, and standard HTML <img> tag attributes to apply to the image tag.
Source:
Returns:
The srcset attribute
Type
string

(inner) hashToQuery(hash) → {string}

Convert a hash of values to a URI query string. Array values are spread as individual parameters.
Parameters:
Name Type Description
hash object Key-value parameters
Source:
Returns:
A URI query string.
Type
string

(private, inner) join_pair(key, valueopt) → {string}

Render the key/value pair as an HTML tag attribute
Parameters:
Name Type Attributes Description
key string
value string | boolean | number <optional>
Source:
Returns:
A string representing the HTML attribute
Type
string

(inner) normalize_expression(expression) → {Object|String}

Normalize an offset value
Parameters:
Name Type Description
expression String a decimal value which may have a 'p' or '%' postfix. E.g. '35%', '0.4p'
Source:
Returns:
a normalized String of the input value if possible otherwise the value itself
Type
Object | String

(private, inner) process_if() → {string}

Parse "if" parameter Translates the condition if provided.
Source:
Returns:
"if_" + ifValue
Type
string

(private, inner) process_layer(layer) → {string}

Parse layer options
Parameters:
Name Type Description
layer object | * The layer to parse.
Source:
Returns:
layer transformation string
Type
string

(inner) process_video_params(param) → {String}

A video codec parameter can be either a String or a Hash.
Parameters:
Name Type Description
param Object vc_[ : : []] or { codec: 'h264', profile: 'basic', level: '3.1' }
Source:
Returns:
: : []] if a Hash was provided or the param if a String was provided. Returns null if param is not a Hash or String
Type
String

(private, inner) singleSource(publicId, options, width) → {string}

Create a single source entry for the srcset attribute
Parameters:
Name Type Description
publicId The public ID of the resource
options object The transformation parameters, configuration parameters, and standard HTML <img> tag attributes to apply to the image tag.
width string | number The breakpoint (width specification) of the current entry
Source:
Returns:
a single srcset entry
Type
string