Digging into WordPress » JavaScript

Using ‘$’ instead of ‘jQuery’ in WordPress

Chris Coyier — Mon, 05 Sep 2011 18:57:29 +0000

WordPress ships with jQuery (for longevity’s sake, as I write this WordPress is v3.2.1). To use jQuery in your plugins and themes “The Right Way” all you need to do is enqueue it (probably in your functions.php file):

wp_enqueue_script("jquery");

The tricky thing is this particular copy of jQuery is in compatibility mode by default. That means that the typical ‘$’ shortcut for jQuery doesn’t work, so it doesn’t conflict with any other JavaScript libraries that use the dollar sign also, like MooTools or Prototype.

Many plugin authors and theme developers are aware of this, and they use ‘jQuery’ instead of ‘$’ to be safe.

/* Normal jQuery you see everywhere */
$("#some-element").yaddaYaddaYadda();

/* "Safe" jQuery you see in WordPress */
jQuery("#some-element").yaddaYaddaYadda();

Here’s the thing… writing out ‘jQuery’ a billion times in a script makes it harder to read and bloats its size. Let’s stop doing that.

If the script is being loaded in the footer (which you should be doing in the vast majority of cases) you can wrap the code in an anonymous function (technically any IIFE) where you pass in jQuery to be mapped to $.

(function($) {
	
	// $ Works! You can test it with next line if you like
	// console.log($);
	
})( jQuery );

If you absolutely need to load the scripts in the header, you’ll probably need to use a document ready function anyway, so you can just pass in $ there.

jQuery(document).ready(function( $ ) {
	
	// $ Works! You can test it with next line if you like
	// console.log($);
	
});

Go forth and write nice looking jQuery!

Ajax Requested Page Return Only Content

Chris Coyier — Wed, 02 Feb 2011 15:42:32 +0000

I posted a little tip on CSS-Tricks the other day about how you can load only parts of other pages on a site via Ajax, and how to do that without needing additional HTML wrapping elements to keep it clean. A common criticism of this is that the Ajax request still loads the entire page, using all that bandwidth, it’s just that it only places onto the page the part you specify via CSS selector.

Sometimes it’s hard to have discussions like this without looking at specific use case, but I see where they are coming from. Loading content you aren’t going to use is a waste of bandwidth. It does make progressive Ajax enhancements a lot easier though. And in fact, that’s how the ALL AJAX theme here on this site works.

This had me thinking though… if WordPress pages could be smart enough to know if they are being requested normally or via Ajax, they could return only the appropriate content. Turns out PHP can detect this. So here is the basic idea:



  /* This is Ajax: Return ONLY content */
  
  



  /* Normal request: Return everything (header, sidebar, content, etc) */

I haven’t tested this but it seems like a reasonable solution to me. Anyone have any experience trying something like this?

Dynamic Archives

Chris Coyier — Fri, 29 Oct 2010 17:29:59 +0000

Have you ever seen WordPress archives where you select something (usually a month/year) from a dropdown and it takes you to a page where you can view that? It’s fairly common. WordPress almost has built in functionality for it, since you can specifically tell the wp_get_archives() function that you want the values to be returned as s. We can kick it up a notch though, and make the results show dynamically on the same page as the dropdowns through some Ajaxy JavaScript. We’ll even allow for multiple dropdowns (include the category as well) and make sure it’s flexible for your own alterations.

View Demo

Step 1) Building the Dropdowns

The dropdowns are pretty easy to create. Here I’ll make a div wrapper for both of them, then include a dropdown for month/year, and for category:


	
		Month
		
	
	
		Category

Note that the WordPress functions for the two dropdowns are a bit different. wp_get_archives requires you to bring your own select wrapper, which wp_dropdown_categories does not. For the former, you’ll also need to include your own “no-choice” option. I’m sure the WordPress gang has their reasons for this kind of thing, but I’d prefer to see it standardized over time.

Step 2) Let’s get ourselves a getter.php

We’re going to be dynamically grabbing our archives and plunking them on the screen. That means JavaScript, and as usual with me, that means jQuery. But jQuery can’t do a WordPress query all by itself. JavaScript is a client-side technology and database stuff is a server-side activity. So we’re going to need an intermediary. A URL that our JavaScript can call to return to us exactly what we need. That’s what I’m calling a getter.php file.

Since we’re working with WordPress here, a great way to do this is to create a template of what we need, then publish a page using that template. That gives us a nice URL we can hit. So in our active theme, I have greated a file called “archive-getter.php”, and this is that code:





	Please choose from above.
	


	";
	        
	        endif; 
	    ?>
	
	    
	            
	            	ID, 'PostThumb', true); ?>" alt="" style="width: 35px;" />
	            	
	            	
	            	
	            
	    Nothing found.

Let’s go through it top to bottom:

Special comment to tell WordPress this is an Template file
Set variables from three POST parameters. Clean them up in the process
Create a $query string in the format WordPress likes them in
Run a query_posts from that query string
If none of the variables are set, return a message telling the user to please select values.
If at least one variable is set…
Run “The Loop”
Output a table of the results, containing the post image, content, date, comments, etc.
If nothing is found, tell the user so

Step 3) Watching for Dropdown Menu Changes

We’re going to be using jQuery, so make sure jQuery is loaded in your theme. Then we’ll need a JavaScript file from which to work. So I’ve created a file called archives.js in the js folder of my theme. I similarly made a CSS file for styling this, and then conditionally load both of them in the header.php file:

Now that we have a working JavaScript enviornment, we can watch those select dropdown menus we built for changes:

jQuery(function() {
  jQuery("#archive-browser select").change(function() {
     // dynamically load the archives
  });
});

Step 4) Dynamically Load New Archives

Using the great base we already have going here, let’s write out all the code we need to dynamically load in those archives. One thing we haven’t covered yet is, where on the page do we load in these said archives? We’ll need a target. We could append it with JavaScript, but what they hey, I just stuck it into the template itself instead:

The #archive-pot is where we’ll load in new markup as we get it. The wrapper is there because that way we can dynamically adjust the height and do it really nice and smoothly.

Now here’s the complete JavaScript:

jQuery(function() {

	jQuery("#archive-wrapper").height(jQuery("#archive-pot").height());

	jQuery("#archive-browser select").change(function() {
	
		jQuery("#archive-pot")
			.empty()
			.html("");
	
		var dateArray = jQuery("#month-choice").val().split("/");
		var y = dateArray[3];
		var m = dateArray[4];
		var c = jQuery("#cat").val();
		
		jQuery.ajax({
		
			url: "/archives-getter/",
			dataType: "html",
			type: "POST",
			data: ({
				"digwp_y": y,
				"digwp_m" : m,
				"digwp_c" : c
			}),
			success: function(data) {
				jQuery("#archive-pot").html(data);
				
				jQuery("#archive-wrapper").animate({
					height: jQuery("#archives-table tr").length * 50
				});
			
			}
			
		});
			
	});

});

Set height of wrapper to height of inside. Seems weird, but now that the wrapper has a static height and hidden overflow, it won’t blast open when new content is added, we can animate it’s heigh accordingly.
Watch for dropdown changes
When a change happens, empty out the current showing archives and add an Ajax spinner graphic
Figure out the year and date that we need by tinkering with the default WordPress values in the
Grab the selected category
Launch an Ajax request to our getter file, POSTING the values we just collected
Upon success, drop the markup into the #archive-pot
Animate the wrapper to the new height needed

Little Important Note

Notice how the data that we POST is prefixed with “digwp_”? I had a little brainbender on this, while I was trying to POST data as like “m” and “month” and things like that. Apparently WordPress doesn’t like that. It can 404 an otherwise perfectly good URL for you when you pass it parameters (GET or POST) in that format. Check it out. So anyway, using your own prefixed parameters will save you that headache.

Taking it further

This is by no means limited to what we have done here. All were are doing it passing a getter file parameters that we want built into a query string. We could make checkboxes so you could pick multiple categories. We could include authors. We could include tags. The sky is the limit really.

Demo

I just did it right on this site, so you can see our own archives.

Make an Infinite More-Posts Section

Chris Coyier — Wed, 18 Nov 2009 20:32:23 +0000

The goal here is to make a list of posts in the sidebar that show a number of recent posts. There will be a button you can click which will replaces those links to recent posts with older posts, AJAX style. You can keep clicking the button and keep getting older and older posts. On this site, we currently show 5 recent posts. So this little section shows the 5 posts after that, then clicking the button once will show 5 more older than that, and so on.

1. Create a Page Template for “Additional Posts”

All this page template does is display a list of 5 posts. Totally raw and unstyled. No DOCTYPE, no footer, no nothing.

The only thing special about this template is that it pulls down the URL parameter “offset” and scrubs it. The query_posts function will use that offset number to return posts older than that number.

2. Make sure jQuery is loaded.

We’re going to use the powers of jQuery to do this, so make sure it’s loaded. Here is a simple way to get that done, make sure this is above the wp_head() function.

I often like to load it directly from Google. To do that, see here.

3. Make a new script (or append to your already exisiting script)

We’re going to write a little JavaScript here, so this is where we’ll do that. Call this AFTER the wp_head() call so it will surely run after jQuery is loaded.

4. Make a home for the list of posts

On our site, we are putting this in our sidebar (sidebar.php file).

More Posts
... loading ...
Get more!

The #postContainer div will be the target for loading up the new list of articles. The #another link will have a click handler tied to it which will trigger the AJAX load.

5. Create a new page with your new page template

Go ahead and publish a new page. It doesn’t matter what the title is, just select your new page template from the page template dropdown menu. Click the View button to make sure it loads up a list of posts OK. Note the URL of this page.

6. Write JavaScript to do AJAX load

We’ll put jQuery in noConflict mode here just to be super safe.

var $j = jQuery.noConflict(); 

$j(function(){

    var offset = 5;

    $j("#postContainer").load("/additional-posts/?offset="+offset);
    $j("#another").click(function(){
        
        offset = offset+5;
    
        $j("#postContainer")
            .slideUp()
            .load("/additional-posts/?offset="+offset, function() {
                $j(this).slideDown();
            });
            
        return false;
    });

});

In plain English:

When the DOM is ready…
Set variable offset to 5
Load the contents of the URL /additional-posts/?offset=5 into the element with ID postContainer
When the “more” button is clicked…
Increment the offset variable by 5
Slide up the container
Load the URL again, with a new offset parameter
When done, slide the container back down

That’s it!

For a demo, check out our current sidebar on Digging Into WordPress. Thanks to Erik Lundmark for the idea.

Integrating Fading Button Navigation

Chris Coyier — Wed, 23 Sep 2009 12:32:58 +0000

I was talking with Darren Hoyt recently about building a better interactive button. The goal of the button was to provide three states: regular, hover, and active (pressed). That is standard of any good button, but we were going to integrate some fading effects into it to really making the button satisfying to interact with. Here is a demo, and now we are going to show you how to integrate it into WordPress.

I’ve said (loudly) before, that yes, this will work with WordPress. I wasn’t referring to anything in particular, but just any old technique. WordPress doesn’t care what you use within it. Any ol’ jQuery plugin you can find will work just fine. This time, I’m going to walk through the process. It will be specific to this technique, but this series of steps can be applied to incorporating just about any other JavaScript “thingy” you find and want to use on the web.

What do we have here?

Markup – we have some HTML that needs to be in place for the menu to work.
CSS – we have some CSS in place that the markup needs
Images – where should they go?
jQuery dependency – this technique is going to rely on jQuery, so we need to ensure that is available
jQuery plugin – we need a particular plugin loaded that our buttons will use
Script – we have our own JavaScript we need to run

We’d better just take this bit by bit.

1. Markup

Like any good semantic navigation markup, we’re shooting for markup like this:


   Take a Tour
   Contact Us

That is hard-coded though, and that’s no good. With WordPress, we can have this navigation be dynamic easily, by using a function to create it instead. Assuming this navigation is going to be a list of pages, we’ll use the appropriate function:

This function can be customized a ton, so check the Codex if you need to add pages, exclude pages, only go one level deep, etc.

2. CSS

We have some CSS that makes this menu look the way it does:

#nav {
    list-style: none;
}

#nav li  {
    display: inline; 
}

#nav li a {
	display: block;
	padding: 10px 0;
	text-decoration: none;
	width: 200px;
	text-align: center;
	text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.8);
	font-weight: bold;
	text-transform: uppercase;
	color: #FFF;
	font: bold .8em 'Lucida Grande',Arial;
	background:	#90b339 url(../images/button-bg.png) 0 -183px repeat-x;
	-moz-border-radius: 5px;  
 	-webkit-border-radius: 5px;
 	border: 1px solid #608925;
	float: left;
	margin: 0 10px 10px 0;
}

Now we need to consider where this CSS is needed. Is this going to be shown on every page of the site? If yes, then it should go into the main CSS that your theme already uses. Loading an additional CSS file just for this is probably overkill. If this is special navigation only being used on one (or very few) pages on the site, then you probably should not put it in the main stylesheet, but leave it seperate and load that CSS file with conditional tags in your header.

3. Images

We need images for our button. Obviously in WordPress we have “themes”. Navigation is definitely a part of a theme, so the images belong there. If you are blogging, and you use photos in your articles, I’d argue those images don’t belong in your theme images folder but in an images folder in the root. Those aren’t dependent on the current theme of your blog, whereas something like navigation is.

There is probably already an images folder in your theme folder, so put the images in there. If not, make one and put them in that. In the previous step, we referenced a background image on our anchor links. Notice the URL began with “../”. That is the relative path from the CSS file to the image file. If the CSS for your theme is also in a subdirectory in your theme (e.g. a “css” folder), then starting with the dot-dot-slash to back up one directory first makes sense. If your CSS is laying straight in your theme folder, just start the reference to that image with “images/”.

In this demo, we use a single image with a gradient. This is an efficient way to go about the technique, as all we do is shift the image up and down to accomplish the different states of the button.

4. jQuery Dependency

All we need to do here is make sure that jQuery is loaded. Do not hard-code a new direct link to jQuery. As the article linked to above goes into, you need to let WordPress know you are using a JavaScript library so that other stuff that also intends to use it doesn’t go and load their own copy too and cause conflicts. In short: do this before your wp_head(); hook:

5. jQuery Plugin

Now we need to link up a plugin file that isn’t bundled with WordPress. Technically you can use wp_enqueue_script here as well, but the benefits to doing so this time are pretty minimal since no naming convention exists for every obscure plugin out there. In this case, just toss the plugin file in a “js” folder inside your theme and link it up like this:

In our case, we’ll be using the background position plugin for jQuery to accomplish part of the effect.

6. Custom Script

Now we are in a position just like we were with the CSS. Is there some script file that is already running on every page of the site? And is this menu going to be running on every page of the site? If yes, then you can drop the JavaScript into that file, to keep things clean and not load up another file. If there isn’t any JavaScript yet, you can link up your script just like we loaded the plugin:

For our button, we are doing some pretty simple stuff. We are going to shift the background position of the gradient image a bit, to give it a subtle rollover effect. Then we’ll use the mousedown event to simulate the “active” state:

$(function(){
	
	$("#nav li a")
		.hover(function(){
			$(this).animate({
				backgroundPosition: "0 -140px"
			}, 100)
		}, function() {
			$(this).animate({
				backgroundPosition: "0 -183px"
			}, 100)
		})
		.mousedown(function(){
			$(this).css({
				backgroundPosition: "0 -220px"
			})	
		});
	
});

We Made It!

So that covers the theory of installing an already-existing demo into a WordPress site. In short, you need to break apart what is provided and figure out the best place to put or recreate all the parts in the smartest way. And again, check out Darren Hoyt’s blog for the origin of this button technique.

Display a Random Post (with AJAX Refresh)

Chris Coyier — Mon, 20 Jul 2009 12:43:32 +0000

I think you’ll be surprised at how ridiculously easy this is. We are going to leverage some serious smartness from both WordPress and from the JavaScript library jQuery.

1. Set up area for Random Post (HTML)

This could be anything really, just so long as it is a text page element with an ID you can target. I put this in our sidebar.php.

Random Post

	... loading ...

Get another!

2. Create a new Page template

The sole purpose for this page template is to query the posts and display one random post. Look how easy:

3. Publish a Page using this template

Could be anywhere you want. On this blog it’s at /random/.

4. The jQuery

You’ll need jQuery loaded and a link to your own custom script going, then add this:

$("#randomPost").load("/random/");
$("#another").click(function(){
   $("#randomPost")
            .text("... loading ...")
            .load("/random/");
   return false;
});

5. Rejoice

I told you it would be easy! Check out our sidebar for a live example.

UPDATE

The above doesn’t work as written in Internet Explorer, which likes to cache AJAX requests. To fight this, just append a random URL parameter to the end of the load URL. Like so:

$("#another").click(function(){
   $("#randomPost")
            .text("... loading ...")
            .load("/random/?cachebuster=" + Math.floor(Math.random()*10001));
   return false;
});

Thanks to Andy for this fix, who is using it on this web app.

Making an Expanding Code Box

Chris Coyier — Thu, 09 Jul 2009 15:49:56 +0000

On blogs that like to share snippets of code like this one, it is common to use the

 tag to wrap the code so that the spacing/indenting is maintained and long lines do not wrap. While this is desirable behavior, it can be undesirable to have those un-wrapped lines break out of their containers awkwardly and overlap other content.
On Digging Into WordPress, we use JavaScript (jQuery) to solve this problem. One solution could potentially be to use only CSS and expand the width with something like pre:hover, but JavaScript is more elegant:

Expands only when needed
Expands only to as wide as needed
Expands with animation



The CSS
The 
 tag is naturally block-level, so this is what we’ll use to style our code blocks and hide the overflow.
pre { 
  background: #eee; 
  padding: 10px; 
  border: 2px solid #c94a29; 
  overflow: hidden;
  margin: 0 0 15px 0; 
  width: 563px; 
  font-family: Courier, Monospace;
}
The jQuery
The real trick here is that the code blocks are wrapped not only in 
 tags but also in  tags. The code may ultimately get cut off by the pre block, but that inner code tag still has a natural width that can be measured by JavaScript. Here is the logic:

When a pre block is hovered…
Measure the internal code blocks width
If that width is wider than the pre block…
Expand the pre block to be wide enough to accommodate
On mouseOut, return the pre block to its original size

$j("pre").hover(function() {
	var codeInnerWidth = $j("code", this).width() + 10;
    if (codeInnerWidth > 563) {
		$j(this)
			.stop(true, false)
			.css({
				zIndex: "100",
				position: "relative"
			})
			.animate({
				width: codeInnerWidth + "px"
			});
		}
	}, function() {
			$j(this).stop(true, false).animate({
				width: 563
		});
	});
Couple of things of note here. The “codeInnerWidth” is calculated on every hover, because different blocks will have different inner widths. The width of the pre blocks are hard-coded though. Calculating that on every hover leads to problems like fast mouse-in-mouse-outs expanding the box and re-calculating it’s size to be larger than it was originally. The stop function prevents queuing up of animations. Also note the $j being used is just because we are using jQuery in noConflict mode:
var $j = jQuery.noConflict(); 
Demo
None of the code blocks so far have been long enough for you to see it in action, so here is a demo block (RSS readers, obviously you need to see this on our site to see it work).
This is a really long line of code that is even longer than the world super-cala-frag-alistic-espee-ala-dosis

© 2009 Digging into WordPress | Permalink | 25 comments | Add to del.icio.us | Post tags: JavaScript, jquery, tricks



Use Google-Hosted JavaScript Libraries (…still the Right Way)
Chris Coyier — Thu, 25 Jun 2009 21:05:04 +0000
I previously posted on how to include jQuery in your WordPress theme the Right Way. That is, to use the wp_register_script function to register the script first. It’s literally a one-liner in your header.php or functions.php file, but by default, it loads the internal version of jQuery that ships with WordPress. 
It’s all the rage these days (for good reason), to use Google-hosted JavaScript libraries. They even encourage it. If you’d like to hop on the bandwagon, you can do so and still use the proper wp_register_script function. 

UPDATE (December 2011)
As of WordPress 3.3, this is the best way to do it, using the proper hook (thanks David Hollander):
//jQuery Insert From Google
if (!is_admin()) add_action("wp_enqueue_scripts", "my_jquery_enqueue", 11);
function my_jquery_enqueue() {
   wp_deregister_script('jquery');
   wp_register_script('jquery', "http" . ($_SERVER['SERVER_PORT'] == 443 ? "s" : "") . "://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js", false, null);
   wp_enqueue_script('jquery');
}
Just add this code to your functions.php file:

if( !is_admin()){
   wp_deregister_script('jquery'); 
   wp_register_script('jquery', ("http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"), false, '1.3.2'); 
   wp_enqueue_script('jquery');
}

That last line there gets the script queued up for you so you don’t need to do it again in the header. Assuming you have the proper wp_head(); call in your header, you’ll be all set! Note that we have wrapped this in a conditional tag to prevent that action on Admin pages. Because this Google-hosted version of jQuery is not in noConflict mode, it interferes with the rich text editor in the admin. This prevents that.
Remember, the reason for all this is to ensure that other WordPress stuff (plugins…) are aware that the script is already loaded so don’t go around loading another copy. Loading two copies of a JS library is just bad news.
Also, I always use jQuery as an example but of course this would work with any popular JavaScript library. For example, the MooTools path at Google is:
http://ajax.googleapis.com/ajax/libs/mootools/1.2.2/mootools-yui-compressed.js
Google’s AJAX Developer’s API Guide is here.
ALSO… there are a crapload of scripts all ready to be queued up for your use in WordPress. See the full list here. 
David wrote in to tell us that he was working in an HTTPS environment, and he used this alteration to ensure the URL for the Google-hosted version of jQuery was properly served from HTTPS when needed:
if (!is_admin()) {
   wp_deregister_script('jquery'); 
   wp_register_script('jquery', ("http".($_SERVER['SERVER_PORT'] == 443 ? "s" : "")."://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"), false, '1.4.2');
   wp_enqueue_script('jquery');
}

© 2009 Digging into WordPress | Permalink | 22 comments | Add to del.icio.us | Post tags: functions, header, jquery



Including jQuery in WordPress (The Right Way)
Chris Coyier — Wed, 03 Jun 2009 01:58:16 +0000
If you want, you can just download jQuery, put it on your server and link to it from your header.php file in the  section. But that can cause you grief. For one thing, some plugins use the jQuery library, and they are going to load it as well. This can cause problems. How was your plugin to know you already had it loaded?
Another thing is that WordPress already includes a copy of jQuery. Here is how you can load up jQuery in your theme the smart (and intended) way. Put the following code in your header.php file in the  section:




Your theme probably already has the wp_head function, so just make sure you call the wp_enqueue_script function BEFORE that. Now you are all set to call your own jQuery JavaScript file, AFTER the wp_head function.

You are ready to rock, but there are still some considerations. For example, safeguarding yourself from the future possibility of conflict with other libraries. You really shouldn’t be using multiple JS libraries to begin with, but… better safe than sorry.
To be super-safe, you can put jQuery into “no conflict” mode and use a different shortcut for jQuery. In this case “$j” instead of the default “$”. The standard “$”, for example, can conflict with Prototype. Here is an example of a safe bit of jQuery JavaScript:
var $j = jQuery.noConflict();

$j(function(){

    $j("#sidebar li a").hover(function(){
    	$j(this).stop().animate({
    		paddingLeft: "20px&"
    	}, 400);
    }, function() {
    	$j(this).stop().animate({
    		paddingLeft: 0
    	}, 400);
    });

});
Can you recognize this bit of code? We use it right here on Modern WordPress to do the cool “link nudging” in the sidebar!
Translations

Belorussian translation


© 2009 Digging into WordPress | Permalink | 59 comments | Add to del.icio.us | Post tags: header, jquery

ID, 'PostThumb', true); ?>" alt="" style="width: 35px;" />
Nothing found.