ACF: Adding a Flexible Module Content Preview Image on Hover
If you’re building custom templates for WordPress for your clients, you most likely have used Advanced Custom Fields. A fantastic little plugin (you’ll need the Pro version for this article), ACF can speed up theme development significantly by allowing you to easily add fields for the client to edit.
The best part of the Pro version of ACF is the Flexible Content Field. Most theme builders come with a “visual builder”. While it allows an amazing amount of freedom in how you lay out each page, it can also provide just enough rope to destroy the design. Alternatively, ACF can provide a balance between freedom and the integrity of the design. You can build the theme using the Flexible Content Fields in ACF so that the client can move content around, add new content, and adjust settings, but all within the framework of the design.
But almost immediately, you’ll come across a downside of the Flexible Content Field: naming the modules. When you have a large site with multiple modules and module options, it can become increasingly frustrating for client to figure out and add in the module they’re looking for.
And so, we need a preview.
What We’re Creating: the Image Preview of the Module
The Flexible Content Field in ACF will automatically provide the setup in the backend when added to the page: (Of course these modules are ones I created for this site)
What we’re creating will look like the image below. As you hover over the module, you’ll see an image preview of that module floating to the left.
Creating the Hover Preview using jQuery and CSS
There will be two parts to setting up the hover effect: Part 1 is the coding; Part 2 is adding the images. It’s surprisingly quick and easy to add this hover effect in!
Adding the jQuery and CSS to Functions.php
The first step is adding in the jQuery and CSS needed to the admin area of the site. To do this, add the following coding into the Functions.php file. You could also create a jQuery file and a CSS file and enqueue the file into functions.php, but to allow you to quickly see the effect we’re creating, you can add it into the functions.php file for now.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | /* Hover Module Effect */ function my_acf_admin_head() { $siteURL = get_site_url(); ?> <style type=”text/css”> .imagePreview { position:absolute; right:100%; top:0px; z-index:999999; border:1px solid #f2f2f2; box-shadow:0px 0px 3px #b6b6b6; background-color:#fff; padding:20px;} .imagePreview img { width:300px; height:auto; display:block; } .acf-tooltip li:hover { background-color:#0074a9; } </style> <script> jQuery(document).ready(function($) { $(‘a[data-name=add-layout]’).click(function(){ waitForEl(‘.acf-tooltip li’, function() { $(‘.acf-tooltip li a’).hover(function(){ imageTP = $(this).attr(‘data-layout’); $(‘.acf-tooltip’).append(‘<div class=”imagePreview”><img src=”<?php echo $siteURL; ?>/wp-content/themes/themeName/modules/images/’ + imageTP + ‘.jpg”></div>’); }, function(){ $(‘.imagePreview’).remove(); }); }); }) var waitForEl = function(selector, callback) { if (jQuery(selector).length) { callback(); } else { setTimeout(function() { waitForEl(selector, callback); }, 100); } }; }) </script> <?php } add_action(‘acf/input/admin_head’, ‘my_acf_admin_head’); |
The top section of styles deals with what we want the image preview to look like. I added a small box shadow to the image and padding so there’s a visual break with the content underneath the preview image.
Note that on Line 3 of the coding above we stored the site URL in a PHP variable. We’ll use this to help tell the site where to find the image in the jQuery section. If you’re building a site with a staging site that has a different site base file structure (ie. on localhost), this will make sure the image shows up on all your versions of the site.
The next section of jQuery makes the magic happen. When they hover over one of the options, we put the module name into a variable (imageTP) and find the image in the specified folder. You might add your module image previews in another folder, but I thought the best place for them was under the theme folder, in the folder containing all the coding for my modules, inside of an images folder there (/wp-content/themes/themeName/modules/images).
There’s one final tricky part of this setup: a function called “waitForEl”. The list of modules is being added dynamically to the page when you click on the “Add Module” button. And of course, in jQuery you can’t add an event (hover or otherwise) to an element that doesn’t exist. Instead, the function “waitForEl”, run when you click the “Add Module” button (line 12), calls a setTimeout Function (line 13) that tests every 100 milliseconds to see if whether the “.acf-tooltip li” class exists yet, and then calls the function to add an event (hover) to the element that now exists.
Here’s what happens:
Clicks “Add Module” -> Function waitForEl runs
[every 100 milliseconds, checks for the .acf-tooltip li element]
When the .acf-tooltip li element is found -> stops setTimeout & adds hover effect
User Hovers over .acf-tooltip li element -> Image Preview shows up
And finally, the last line of the coding above calls this function only in the ACF admin pages.
Adding the Preview Images
Part two of this setup is saving and adding the preview images to the file structure. Again, I personally add them under my modules folder in the theme: /wp-content/themes/themeName/modules/images. Whatever setup you decide to go with, make sure you adjust the jQuery to reflect the new location.
Each image will need to be added into the file structure you chose, and they should be named as the modules are named. The easiest way to double-check the name is to hover over the module title, and right-click for “data-layout” attribute in the link:
1 | <a href="#" data-layout="team_members" data-min="" data-max="">Team Members</a> |
We’re utilizing this “data-layout” attribute to bring up the correct image. As you take screenshots (and resize and optimize!) of the modules on the front-end of the site, name them according to this “data-layout” attribute: team_members.jpg
And voila! You’ve got a beautiful new preview for your clients.
Do you have other techniques you use to make ACF easier or more intuitive for clients to use? Share below!
nice work,
I changed things up a bit, and wanted to share my solution.
in functions.php…..
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
if ( $current_page != 'post.php' && $current_page != 'post-new.php' ) {
return;
}
wp_enqueue_script( 'acf-admin-js', get_stylesheet_directory_uri().'/resources/js/admin/acf-admin.js', rand(1,100) );
wp_localize_script('acf-admin-js', 'adminLocal', ['directory' => get_stylesheet_directory_uri() ]);
});
add_action('acf/input/admin_head', function() {
$style = <<<STYLE
<style type="text/css">
.module-preview {
position: absolute;
right: 100%;
top: 0px;
z-index: 1;
background-color: #fff;
padding: 20px;
}
.module-preview img {
width: 500px;
}
.acf-tooltip li:hover {
background-color:#0074a9;
}
</style>
STYLE;
echo $style;
});
and then admin js
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
function changeImages() {
$('.acf-tooltip ul li a').hover(function(){
imageLayoutSlug = $(this).attr('data-layout')
imageSource = adminLocal.directory + '/public/images/' + imageLayoutSlug + '.jpg'
$('.acf-tooltip').append('<div class="module-preview"><img src="'+imageSource+'"></div>')
}, function(){
$('.module-preview').remove()
})
}
function checkDOMChange() {
let toolTips = document.querySelectorAll('.acf-tooltip ul li')
if (toolTips.length) {
changeImages(toolTips)
} else {
setTimeout( checkDOMChange, 100 )
}
}
function init(){
$('a[data-name=add-layout]').click( () => {
checkDOMChange()
})
}
$(document).ready(init)
})(jQuery)
Nice – I like linking out to the scripts; it’s a bit more organized. Same with the functions. Good work and thanks for the comment!
Nice, elegant and light-weight solution, love it! I added a small function to test if image exists and display a placeholder if it does not.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
/* https://whitefoxcreative.com/developers/wordpress/acf-adding-a-flexible-module-content-preview-image-on-hover/ */
/* Hover Module Effect */
function lwh_acf_admin_head() {
$module_images_path = get_template_directory_uri() . '/modules/images/';
$placeholder = get_template_directory_uri() . '/modules/images/no-preview.png';
?>
<style type="text/css">
.imagePreview {
position:absolute; right:100%;
top:0px;
z-index:999999;
border:1px solid #f2f2f2;
box-shadow:0px 0px 9px #b6b6b6;
background-color:#004f6d;
padding:5px;
}
.imagePreview img {
width:300px;
height:auto;
display:block;
}
.acf-tooltip li:hover {
background-color:#0074a9;
}
</style>
<script>
jQuery(document).ready(function($) {
function checkImage(urlToFile)
{
var xhr = new XMLHttpRequest();
xhr.open('HEAD', urlToFile, false);
xhr.send();
if (xhr.status == "404") {
return false;
} else {
return true;
}
}
$("a[data-name=add-layout]").click(function(){
waitForEl(".acf-tooltip li", function() {
$(".acf-tooltip li a").hover(function(){
imageTP = $(this).attr("data-layout");
imageFullPath = "<?php echo $module_images_path; ?>" + imageTP + '.jpg';
imagePlaceholder = "<?php echo $placeholder; ?>";
link = (checkImage(imageFullPath)) ? imageFullPath : imagePlaceholder;
$(".acf-tooltip").append('<div class="imagePreview"><img src="' + link + '" /></div>');
}, function(){
$(".imagePreview").remove();
});
});
})
var waitForEl = function(selector, callback) {
if (jQuery(selector).length) {
callback();
} else {
setTimeout(function() {
waitForEl(selector, callback);
}, 100);
}
};
})
</script>
<?php
}
add_action("acf/input/admin_head", "lwh_acf_admin_head");
That’s a nice add-in! Thanks!
Thank you so much for sharing, this is exactly what I was looking for ! 🙂
A minor improvement for let this working if you have a flexible element inside an other :
$(document).on(‘click’, ‘a[data-name=add-layout]’, function() {
instead of :
$(‘a[data-name=add-layout]’).click(function(){
Thanks again !
That’s awesome, works like a charm !
Thanks for sharing