AJAX in WordPress – not the kind where you load all or part of a page, but the kind where you use admin-ajax to execute an action – was fairly opaque for me when I first tried to implement it. Granted, that was as part of the Customizer, not the easiest thing in the world to come to grips with. However, it seems to me I had to piece together multiple tutorials to get a complete picture, so I thought I’d put out a simple example that still addresses all of the components.

The main idea: admin-ajax.php (view code on Trac) is a file that executes actions. Those actions can do anything, but generally they are either saving information or displaying content. I’ll stick to displaying content.

AJAX being what it is, setting it up requires both PHP and JavaScript files. I think the easiest way to explain it is probably to walk through an example. This is code for a plugin that provides the ability to pop the primary WordPress menu up in a lightbox (in this case Colorbox) from any element to which you give the id “menu-popper”. It relies on jQuery. The plugin is simply called Colorbox Menu, and in fact if you download jquery.colorbox-min.js and stick it in a folder with the following two files, you can use it (though you’ll want some CSS too).

JavaScript (colorbox-menu.js):

PHP (colorbox-menu.php):

So, what is going on here? The script is executing AJAX in the usual jQuery way, with some specifics required by WordPress and/or best coding practices. There are three lines to highlight:

• url: colorboxMenu.ajaxurl
  This line tells JavaScript where it is making its request, which is the full URL for admin-ajax.php (likely to be the same relative location in most WP installs, but certainly not all). This is an object property whose value will be the actual URL. The value will be provided to the script when the script is enqueued – more when we look at the PHP file. For now just know there are numerous tutorials that tell you the address of admin-ajax is automatically filled in if you put simply url: ajaxurl; this is true on the admin side, but not when the call is made from the front end.
• action: 'colorbox_menu_display_main_nav',
  The only data we are sending in this example is the name of the action we want executed. You will see in the PHP discussion that it is not actually the name the action is registered under, and need not be the name of the PHP function that gets executed.
• $.colorbox( { html:result, } );
  Your action will send back text or html, just as a string. Colorbox lets you tell it the content of the lightbox when it’s called, which is what we are doing here. You could also insert this into an HTML element with, e.g., .append() or .html().

The PHP file is doing two things: enqueuing and localizing the script, and teaching admin-ajax how to react to the AJAX request. Enqueuing is as usual; you just have to do it before localizing. The remaining noteworthy pieces:

• wp_localize_script( 'colorbox-menu', 'colorboxMenu', array( 'ajaxurl' => admin_url( 'admin-ajax.php' ) ) );
  Script localization is the process of swapping out variables for data known at load time, such as the URL of the admin-ajax file. This tells WordPress that within the script enqueued under the handle “colorbox-menu” it needs to replace properties of the object colorboxMenu with the values associated to them in the array given as the third parameter. You need to pass the URL in this way, but you could pass other information as well, as long as it is known/determined by the time of script loading.
• function colorbox_menu_load_main_nav()
  This is the function that will ultimately be called by the user’s click. It needs to do two things: echo any return information, and terminate itself. wp_nav_menu echos the menu code already so it can be used bare. Anything that needs to be preceded by an echo command in a template file (e.g. home_url) needs to be preceded by an echo command in this function, and you can simply echo strings as well. I was pleased to discover that echoing a function that would typically be called from within a page and simply close out PHP to print HTML onto the page (such as get_template_part) works perfectly well also.
• add_action( 'wp_ajax_nopriv_colorbox_menu_display_main_nav', 'colorbox_menu_load_main_nav' );
add_action( 'wp_ajax_colorbox_menu_display_main_nav', 'colorbox_menu_load_main_nav' );
  Here we have something seemingly odd. If you look at the admin-ajax.php code, it tacks wp_ajax_nopriv_ or wp_ajax_ on to the front of whatever action it is asked to execute, so when you add your action you need to put those prefixes on to whatever action name you sent in your AJAX data parameter. The second input is the name of the function the action calls. This may seem cumbersome, but it allows you to react differently to AJAX calls depending on whether the person who clicked is logged in to the site (wp_ajax_) or not (wp_ajax_nopriv_).

There you have it: what information to include, how to get it where it needs to be, and how to name the pieces.

The post AJAX in WP: a simple example appeared first on rweber.net.

Last time we set up the PHP (slash HTML, slash CSS) to dynamically generate Media Library Assistant gallery shortcodes and an album menu. Everything works without any JavaScript. Today we’re going to add JavaScript, with jQuery, to do three things.

1. Hide the album menu under a button, a la a mobile menu. This will prevent the problem of a menu that’s so large the gallery is four pages down.
2. Use AJAX to reload only the portion of the page containing the gallery. This will make for a smoother experience.
3. Push each new URL into the browser history, so that the back button works and individual albums can be bookmarked. It’s always a source of an annoyed “really?” when I try to go back to a page I bookmarked and find that the address leads to only the most general version of the page, not where I actually was.

Edit: Since I have made so many additions to Twenty Fifteen, I thought it would be useful to assemble them into a single child theme. You can see the Fancy Fifteen code on GitHub, or look at all posts here tagged fancyfifteen.

Here’s a pair of screenshots. You can’t tell in this because I didn’t make a ton of categories, but the menu will also drop over the photos. Again, at least for the time being, you can see and interact with this on my testing site.

All three steps are actually handled in one short jQuery-reliant JavaScript file.

Call it gallery-menu.js, put the following into it, and save it in your child theme folder:

Line 2 is sort of pre-Step-1. It’s for graceful degradation – it adds a class so we can style the menu and gallery separately depending on whether JavaScript is enabled or not.
Lines 3-6 control Step 1. They hide the menu to begin with and activate the button to show and hide it.

The rest is Steps 2 and 3. If you click a link within the menu, JS swoops in and stops the browser from following it (line 9). Then we construct the relevant piece of the desired URL from the link, using the data-slug attribute we added into the PHP last time, and furthermore tack on the specific div that holds the images (lines 10-11). Line 12 does the AJAX, Line 13 re-hides the menu as it would be were the page reloaded, and Line 14 pushes the new URL into the browser history.

And this is why hearts fly out of my eyes sometimes when I work with jQuery.

Edit 3 May: To get my lightbox plugin to apply to this gallery I had use JS to add a rel attribute to each link. The AJAX – or maybe simply do_shortcode – seemed to prevent the automatic application of the lightbox to the image links (which wasn’t the case with the Flickity slideshow). What you need will depend on what plugin you use, of course, but for WP Lightbox 2 I had to add $( '#current-album a' ).attr( 'rel', 'lightbox[album]' ); at line 7 and as a post-AJAX function to the .load call (see my notes on .load syntax).

Are we there yet?

Of course not. We have bonus steps to this part of the program as well.

Tack this onto the end of your functions.php file:

Insert this CSS just before the media queries in style.css:

And finally, insert this CSS inside the max-width: 43.75em media query (not the portrait one):

The styling could be way better, so play with it till you lose your mind.

The post Gilding the Gallery 3: Ajaxifying the filterable gallery appeared first on rweber.net.

Working on the filterable gallery I mentioned in the Flickity/MLA carousel post, there were a lot of little things I had to look up or work out by trial and error, some of which were ultimately quite simple but took a while to figure out. I want to lay them out for future reference, my own and potentially that of readers of the (forthcoming) post(s) about the gallery itself.

• If something that’s supposed to be clickable only works on part of its area, such as a div where only the bottom half is clickable, check for overhang. You can’t click through another div even if it’s empty.
• String concatenation: . for PHP, + for JavaScript.
• $.load puts the second thing into the first thing: $( ‘#wrapper’ ).load( ‘source-page.php #contents’ ), not $( ‘#contents’ ).load( ‘source-page.php #contents’ ). The latter will result in two divs with the id ‘contents’. This of course means you have to build your page with a wrapper div.
• $.load seems to require that the function to run after loading completes be an anonymous one. Putting in a named function doesn’t necessarily work (I found sometimes it did and sometimes it didn’t). That is, not $.load( ‘source.php’, setup() ); but instead $.load( ‘source.php’, function() { setup(); });
• If all you want is to add or change a query string (that is, ‘?attr=value’) on the current URL, $.load() needs only the query string itself. If you give it the page slug also, WordPress will show you the correct page, but the slug will be doubled in the URL. The same goes for window.history.pushState();
• Using WordPress’s get_terms to access a taxonomy nets you an array of objects. The PHP syntax to access pieces of an array is completely different than the syntax used to access pieces of an object. Remember that and things will work better.
• You can add whatever information you want to an anchor element by adding a data attribute; syntax is <a href="..." data-slug="...">, where “slug” would be whatever the kind of data is in your application.

John Steuart Curry’s painting Ajax via Wikimedia Commons.

The post Things I’ve (re)learned recently appeared first on rweber.net.