Backstretch.js Filters

Full Screen Background Images relies heavily on Backstretch.js, and open source jQuery plugin that allows for background images to nicely fit the background of your page or an element on your page.

Like many jQuery plugins and other open source code there are filters available to modify the default behavior. To enable our users to benefit from these filters we've added our own WordPress filters that modify the Backstretch.js defaults.

By the way, you can find a full list of Options available in Backstretch.js and how they're used here. Not all of them are available to use in Full Screen Background Images though as some have been deprecated, are available to be modified in the plugin's settings, or otherwise cause issues with our plugin. A full list of available filters is provided below.

Backstretch.js Filters Available in Full Screen Background Images

Note: all of the filters in Full Screen Background Images for the Backstretch.js options use the prefix fsbi_ with the same option name used in Backstretch.js. For example, fsbi_alignX in Full Screen Background Images would relate to the alignX option in Backstretch.js.

  • fsbi_alignX: (integer or string) default value is 0.5. This parameter controls the horizontal alignment of the image. Can be 'center'/'left'/'right' or any number between 0.0 and 1.0.
  • fsbi_alignY: (integer or string) default value is 0.5. This parameter controls the vertical alignment of the image. Can be 'center'/'top'/'bottom' or any number between 0.0 and 1.0.
  • fsbi_scale: (string) default value is 'cover'. Controls the scaling mode. Can be 'cover'/'fit'/'fit-smaller'/'fill'.
  • fsbi_transition: (string or array) default value is 'fade'. Type of transition to use. If multiple are specified, then it will be chosen randomly.
  • fsbi_transitionDuration: (integer or string) default value is 0. This is the duration at which the image will transition in. Integers in milliseconds are accepted, as well as standard jQuery speed strings (slow, normal, fast).
  • fsbi_animateFirst: (boolean) default value is true. If true, the first image will transition in like all the others. See fsbi_fadeFirst.
  • fsbi_fadeFirst: (boolean) default value is true. Synonym for animateFirst.
  • fsbi_paused: (boolean) default is false. For slideshows: Disables the change between slides.
  • fsbi_preload: (integer) default is 2. How many images to preload at once? i.e. Lazy-loading can be enabled by specifying 0.
  • fsbi_preloadSize: (integer) default is 1. How many images to preload in parallel? If we are preloading 5 images for the next slides, we might want to still limit it to only preload 2 or 3 at once, according to the expected available bandwidth.
  • fsbi_bypassCss: (boolean) default is false. Avoid adding any CSS to the IMG element. i.e if you want a dynamic IMG tag that is laid out with the content.
  • fsbi_alwaysTestWindowResolution: (boolean) default false. Always test against window's width instead of the element's width.
  • fsbi_resolutionRefreshRate: (integer) default 2500. Threshold for how long to wait before the image resolution will be switched.
  • fsbi_resolutionChangeRatioThreshold (integer) default 0.1 (i.e. 10%). Threshold for how much should the different in the resolution be before switch image.

Example Filter Usage 

add_filter( 'fsbi_alignX', 'custom_horizontal_alignment' );
function custom_horizontal_alignment( $value ){
	return 0.75;
}