Background Slideshow in Oxygen using ACF and Backstretch

This developer-specific tutorial is a different way of achieving the same visual output as my previous post, Background Slideshow in Oxygen.

The focus here is on the implementation and the code part of it and not so much as the actual end result.

We shall

• add a Repeater field containing an image subfield on a custom admin settings page using ACF Pro
• In a function hooked to wp_enqueue_scripts inside a functionality plugin, load Backstretch, loop over the images uploaded on the settings page, store the image URLs in an array and pass this to JavaScript as the source to initialize Backstretch on the body tag using wp_localize_script()
• build a div in Oxygen and overlay it centered on top of the page.

Step 1

Install and activate Advanced Custom Fields Pro.

Install and activate Code Snippets plugin if you haven’t already.

Add a new Snippet named say, “ACF Options Page” having:

if ( function_exists( 'acf_add_options_page' ) ) {

    acf_add_options_page();

}

Set it to run only in admin.

Step 2

Add a new Field Group named say, “Background Images Group” having a background_images Repeater.

Add a background_image image field inside the Repeater.

Leave the Return Value at the default, Image Array. The reason for not setting this to Image URL is because of the risk involved in giving the control to the clients who may upload huge images that are way too big (file size and dimensions-wise) than what is necessary. We shall register a custom image size and use the URLs of images sized to it.

Here’s the export file of the field group.

Step 3

Install and activate my custom functionality plugin.

Step 4

Upload jquery.backstretch.min.js to wp-content/plugins/my-custom-functionality/assets/js.

Create a file named say, backstretch-init.js in the same location having the following:

(function ($) {

    $('body').backstretch(BackStretchImg.src, {
        duration: 4000, // amount of time in between slides in milliseconds. Default: 5000
        fade: 750,
    });

})(jQuery);

Step 5

Edit plugin’s plugin.php.

a) Add

add_image_size( 'background-image', 1600, 900, true );

Regenerate thumbnails if necessary.

b) Inside custom_enqueue_files(), add

if ( is_page( 'background-slideshow' ) ) {
    wp_enqueue_script(
        'backstretch',
        plugin_dir_url( __FILE__ ) . 'assets/js/jquery.backstretch.min.js',
        array(),
        '2.1.16',
        true
    );

    wp_enqueue_script(
        'backstretch-init',
        plugin_dir_url( __FILE__ ) . 'assets/js/backstretch-init.js',
        array( 'backstretch' ),
        '1.0.0',
        true
    );

    $image_urls = array();

    if ( have_rows( 'background_images', 'option' ) ) {
        while ( have_rows( 'background_images', 'option' ) ) : the_row();

            $image = get_sub_field( 'background_image' );

            if ( ! empty( $image ) ) {
                $image_urls[] = $image['sizes']['background-image'];
            }

        endwhile;
    }

    wp_localize_script(
        'backstretch-init',
        'BackStretchImg',
        array(
            'src' => $image_urls,
        )
    );
} // End if().

Change if ( is_page( 'background-slideshow' ) ) depending on where you want to have the background slideshow.

Step 6

Go to Options in the dashboard add your background images.

Step 7

Edit your Page/template with Oxygen. Do not inherit from any other template since we want to start with a totally blank page.

Add a Section.

Set Horizontal Item Alignment to Center.

Set Height to 100vh.

Advanced > Layout: Set Justify Content to center.

Add a Div inside the Section. This is our overlay div. Add your desired elements like Heading, Text, and Button inside this Div.

For the overlay div, set Display to flex, Flex Direction to column, Horizontal Item Alignment and Vertical Item Alignment to Center and Middle respectively.

Set a Width of say, 800px.

Background color: rgba(255,255,255,0.8)

Padding: 80px at top and bottom, 40px at left and right.

That’s it!

References:

https://www.advancedcustomfields.com/resources/repeater/

https://www.advancedcustomfields.com/resources/image/

https://stackoverflow.com/a/3045647/778809

https://www.advancedcustomfields.com/resources/get-values-from-an-options-page/