buildfire.imageLib

Image library is used to store and manipulate images on the Buildfire image server. This article goes through the steps for using Image Lib in your plugin.

There are 3 ways you can access your Image Library images:

1. Directly. When an image is selected from the image lib you are given a url that allows you to access the image directly from the image server
2. CDN. When you pass the image lib url to the buildfire.imagelib framework for resizing or cropping the framework redirects you to a cached version of the manipulated image for speed. However, this still requires an internet connection
3. (DEPRECATED) Locally. When you pass the image lib url to the buildfire.imagelib.local framework for resizing or cropping. The buildfire.js then checks if the image is available locally. If so, it will then serve the image from the local file system for speed and offline more. If not found, then will revert back to the CDN.

The level of complexity of implementation increases from 1 to 3 how ever the performance increases with each step.

tip

Because the framework may adjust the width and height of the image based on pixel density it is always a good idea to constrain your image size with CSS and do not rely on the image size fitting perfectly

Methods

showDialog()

buildfire.imageLib.showDialog(options, callback)

Displays a dialog that helps the user upload, reuse and manage images and icons. It also provides an integrated search for stock images that can be freely used inside the Buildfire app.

buildfire.imageLib.showDialog({}, (err, result) => {
  if (err) return console.error(err);

  console.log("Selected images and icons: ", result);
});

options

Name	Type	Required	Description	Default
showIcons	boolean	no	Shows the "Icons" tab inside the dialog	true
showFiles	boolean	no	Shows the "My Images" tab inside the dialog	true
multiSelection	boolean	no	Allows the user to choose multiple icons and multiple files	true

note

You can either select stock images or uploaded images at once. Selecting both will return only the latest selected items.

callback(err, result)

Callback function after something is done

Name	Type	Description
err	string	error string, undefined when operation is successful
result	object	Result object containing selected files and/or icons

result

Name	Type	Description
selectedFiles	[string]	Array of image urls selected from "My Images" or "Stock Images" tab
selectedIcons	[string]	Array of selected glyphicon icons ex. ["glyphicon glyphicon-cloud"]

---

resizeImage()

buildfire.imageLib.resizeImage(url, options, element, callback)

Because users may upload large high resolution images to the image server, it may be necessary to resize the image before downloading it to the client to increase performance of your plugin. This method allows you to pass the url of the image with options to resize it and download a smaller, properly sized image.

let resizedImage = buildfire.imageLib.resizeImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "half_width", aspect: "16:9" }
);
console.log("Resized image url", resizedImage);

note

element and callback are optional parameters used to enable image caching on devices.

url

Name	Type	Required	Description	Default
url	string	yes	Url of the image to be resized

options

Name	Type	Required	Description	Default
size	string	yes	Desired image width size
aspect	string	yes	Desired image aspect ratio
disablePixelRatio	boolean	no	Disables the multiplier of the screens pixel ration to account for things like retina display	false

options.size

Determines image width. Two types of sizes are available, fixed and responsive. Responsive sizes will detect the screen width and provide the correct size. For example, half_width will calculate image width to fill half the screen, regardless of device size.

Fixed

Name	Size
"xxs"	32px
"xs"	64px
"s"	128px
"m"	200px
"l"	304px
"xl"	416px
"xxl"	600px
"720"	720px
"1080"	1080px
"1440"	1440px

Responsive

Name	Size
"full_width"	Full device width
"half_width"	Half device width
"third_width"	One third of device width
"quarter_width"	One quarter of device width
"fifth_width"	One fifth of device width
"sixth_width"	One sixth of device width

options.aspect

Aspect will calculate the image height based on the size passed.

Aspect	Description
"1:1"	Square image, height equals width
"4:3"	Height is 3/4 of width
"16:9"	Height is 9/16 of width
"9:16"	Height is 16/9 of width
"11:5"	Height is 5/11 of width
"4:1"	Height is 1/4 of width
"2.39:1"	Height is 1/2.39 of width

important

aspect and size must be used together. Both are required!

note

If image size does not have the same aspect ratio as chosen in options, it will not be cropped to fit that aspect ratio when used in resizeImage. The image will be conained inside of that aspect ratio.

element

Buildfire's imageLib provides native caching to accelerate load times. Passing the element or callback parameter will enable the cache.

note

Caching only applies on devices

Name	Type	Required	Description	Default
element	HTMLElement	no	If an <img/> is passed, sets the elements src to the locally cached image. If any other element is passed, sets the elements background-image css property to the locally cached image.

callback(resizedImage)

note

Caching only applies on devices

Name	Type	Description
resizedImage	string	Cached image local path

More Examples

Responsive full width image, 16:9 aspect ratio, caching enabled

let element = document.body;
let resizedImage = buildfire.imageLib.resizeImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "full_width", aspect: "16:9" },
  element,
  (cachedImageUrl) => {
    console.log("Cached image url", cachedImageUrl);
  }
);
console.log("Resized image url", resizedImage);

Responsive half width image, 16:9 aspect ratio

//
let resizedImage = buildfire.imageLib.resizeImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "half_width", aspect: "16:9" }
);
console.log("Resized image url", resizedImage);

Fixed icon, square aspect ratio

let resizedImage = buildfire.imageLib.resizeImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "xs", aspect: "1:1" }
);
console.log("Resized image url", resizedImage);

Responsive icon, square aspect ratio

let resizedImage = buildfire.imageLib.resizeImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "sixth_width", aspect: "1:1" }
);
console.log("Resized image url", resizedImage);

---

cropImage()

buildfire.imageLib.cropImage(url, options)

Because users may upload large high resolution images to the image server, it may be necessary to crop the image before downloading it to the client to increase performance of your plugin. This method allows you to pass the url of the image with options to crop it and download a smaller, properly sized image. Function is synchronous and returns modified image url.

let croppedImage = buildfire.imageLib.cropImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "half_width", aspect: "16:9" }
);
console.log("Cropped image url", croppedImage);

url

Name	Type	Required	Description	Default
url	string	yes	Url of the image to be resized

options

Same as options for resizeImage()

Name	Type	Required	Description	Default
size	string	yes	Desired image width size
aspect	string	yes	Desired image aspect ratio
disablePixelRatio	boolean	no	Disables the multiplier of the screens pixel ration to account for things like retina display	false

element

Buildfire's imageLib provides native caching to accelerate load times. Passing the element or callback parameter will enable the cache.

note

Caching only applies on devices

Name	Type	Required	Description	Default
element	HTMLElement	no	If an <img/> is passed, sets the elements src to the locally cached image. If any other element is passed, sets the elements background-image css property to the locally cached image.

callback(resizedImage)

note

Caching only applies on devices

Name	Type	Description
resizedImage	string	Cached image local path

More Examples

Responsive full width image, 16:9 aspect ratio, caching enabled

let element = document.body;
let croppedImage = buildfire.imageLib.cropImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "full_width", aspect: "16:9" },
  element,
  (cachedImageUrl) => {
    console.log("Cached image url", cachedImageUrl);
  }
);

Responsive half width image, 16:9 aspect ratio

//
let croppedImage = buildfire.imageLib.cropImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "half_width", aspect: "16:9" }
);
console.log("Cropped image url", croppedImage);

Fixed icon, square aspect ratio

let croppedImage = buildfire.imageLib.cropImage(
  "https://www.google.com/images/srpr/logo11w.png",
  { size: "xs", aspect: "1:1" }
);
console.log("Cropped image url", croppedImage);

---

DEPRECATED METHODS

danger

The following section of imageLib is deprecated and should not be used

local.resizeImage();

buildfire.imageLib.local.resizeImage(url, options, callback)

This option will attempt to fetch the file from the local device if not found it will default back to CDN mode. Because this is meant for use on a physical device. When on the web it will revert to CDN mode. If the file is not located on the device it will also revert back to CDN mode automatically.

url

Name	Type	Required	Description	Default
url	string	yes	Url of the image to be resized

options

Name	Type	Required	Description	Default
width	number	yes	Desired image width in pixels or "full" to calculate 100% of device width
height	number	yes	Desired image height in pixels or "full" to calculate 100% of device height
disablePixelRatio	string	no	Disables the multiplier of the screens pixel ration to account for things like retina display	false

callback(err, resizedUrl)

Name	Type	Description
err	string	error string, null when operation is successful
resizedUrl	string	Resized image url

---

local.cropImage();

buildfire.imageLib.local.cropImage(url, options, callback)

This option will attempt to fetch the file from the local device if not found it will default back to CDN mode. Because this is meant for use on a physical device. When on the web it will revert to CDN mode. If the file is not located on the device it will also revert back to CDN mode automatically.

url

Name	Type	Required	Description	Default
url	string	yes	Url of the image to be resized

options

Name	Type	Required	Description	Default
width	number	yes	Desired image width in pixels or "full" to calculate 100% of device width
height	number	yes	Desired image height in pixels or "full" to calculate 100% of device height
disablePixelRatio	string	no	Disables the multiplier of the screens pixel ration to account for things like retina display	false

callback(err, resizedUrl)

Name	Type	Description
err	string	error string, null when operation is successful
resizedUrl	string	Resized image url