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:

<?php 

/* Page template, or single.php, or any other typical 
    theme file in charge of displaying a whole page */

the_post();

/* Ajax check  */
if (!empty($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest') { ?>

  /* This is Ajax: Return ONLY content */
  <h1><?php the_title(); ?></h1>
  <?php the_content(); ?>

<?php } else { ?>

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

  <?php get_header(); ?>

  <section id="main-content">
  	<article class="post" id="post-<?php the_ID(); ?>">
  		<h1><?php the_title(); ?></h1>
  		<?php the_content(); ?>
  	</article>
  </section>

  <?php get_sidebar(); ?>
  <?php get_footer(); ?>

<?php } ?>

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

© 2011 Digging into WordPress | Permalink | 16 comments | Add to del.icio.us | Post tags: ajax, pages, PHP

Default action being smart

A while ago I was moaning about one particular area where I didn’t find the default being so smart. When you publish a new Post, the default goes to New Post. To me it would make sense when you publish a new Page to have that button be New Page. If you have a WordPress site where you publish a lot of pages, you can feel me.

Reader Otto let me know there is a way you can change this. Here is Otto:

Adding the New Page as default there is actually rather simple.

Look in wp-admin/includes/template.php. Down towards the bottom of the file, you’ll find the function favorite_actions().

In that function, it reads the wp-admin page name and sets a $default_action based on that. For example, when you’re looking at the edit-pages.php screen, the default action becomes “New Page”.

The Page editor screen is page.php. Note that it has no default action. To give it one, simply add a case ‘page.php’: in the correct place. You can add it directly before that case ‘edit-pages.php’ if you want the default action to be the same New Page link.

If you want this change made to core, then I suggest making an Enhancement ticket to that effect on the WordPress trac. As always search first, somebody else might have already made that ticket request.

So to fix my particular gripe, I just opened the file at the path mentioned above and found the favorite_actions function. It’s a pretty readable function, and adding a new bit to change the behavior is pretty easy. I just added this right above the one for edit-pages.php

case 'page.php':
   $default_action = array('page-new.php' => array(__('New Page'), 'edit_pages'));
   break;

Fixed!

Important notes

This is what you would call a “core hack”. Meaning that next time you upgrade WordPress, this code will be gone. It doesn’t mean “don’t do it” and it especially doesn’t mean “do it and don’t upgrade”. It means that you should make a note somewhere handy to yourself that when you do upgrade, you can see if it’s fixed and if it’s not, make the same alteration again.

Also as Otto suggested, there is an official channel for getting stuff done like this, the WordPress trac. I’ve never submitted anything there before, but to put my money where my mouth is I opened a ticket.

© 2010 Digging into WordPress | Permalink | 6 comments | Add to del.icio.us | Post tags: Admin, pages, tricks

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.

<?php
    /*
        Template Name: Additional Posts
    */
        
    $offset = htmlspecialchars(trim($_GET['offset']));
    if ($offset == '') {
        $offset = 5;
    }
   
    query_posts('showposts=5&offset='.$offset); 
?>

<ul>
    <?php    
        if (have_posts()) : while (have_posts()) : the_post(); ?>
            <li><a href='<?php the_permalink(); ?>'><?php the_title(); ?></a></li>
    <?php 
        endwhile; endif; 
    ?>
</ul>

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.

<?php wp_enqueue_script('jquery'); ?>

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.

<script type="text/javascript" src="<?php bloginfo('template_url') ?>/js/YOUR-SCRIPT.js"></script>

4. Make a home for the list of posts

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

<h4>More Posts</h4>
<div id="postContainer">... loading ...</div>
<p><a href="#" id="another">Get more!</a></p>

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:

1. When the DOM is ready…
2. Set variable offset to 5
3. Load the contents of the URL /additional-posts/?offset=5 into the element with ID postContainer
4. When the “more” button is clicked…
5. Increment the offset variable by 5
6. Slide up the container
7. Load the URL again, with a new offset parameter
8. 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.

© 2009 Digging into WordPress | Permalink | 9 comments | Add to del.icio.us | Post tags: jquery, pages, PHP

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?

1. Markup – we have some HTML that needs to be in place for the menu to work.
2. CSS – we have some CSS in place that the markup needs
3. Images – where should they go?
4. jQuery dependency – this technique is going to rely on jQuery, so we need to ensure that is available
5. jQuery plugin – we need a particular plugin loaded that our buttons will use
6. 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:

<ul id="nav">
   <li><a href="#">Take a Tour</a></li>
   <li><a href="#">Contact Us</a></li>
</ul>

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:

<ul id="nav">
   <?php wp_list_pages("title_li=");
</ul>

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:

<?php wp_enqueue_script("jquery"); ?>

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:

<script type='text/javascript' src='<?php bloginfo('stylesheet_directory'); ?>/js/plugin.js'></script>

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:

<script type='text/javascript' src='<?php bloginfo('stylesheet_directory'); ?>/js/script.js'></script>

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.

© 2009 Digging into WordPress | Permalink | 19 comments | Add to del.icio.us | Post tags: button, pages, Theme

Digging into the wp_list_pages() template tag

Almost everyone is familiar with the wp_list_pages() template tag, and it has served us well since WordPress version 1.5. Using this tag is easy, just add the following code to your sidebar or other choice location:

<?php wp_list_pages(); ?>

And then you can customize that in many ways using the fine menu of arguments provided at its Codex Reference Page. Some of the highlights include:

Extreme Sorting Power

You can sort your pages by the descriptor of any field in the wp_post table of the WordPress database. By default, you get alphabetical by page title, but there are some other great options as well. Here are some delicious copy-&-paste recipes for your next project:

<?php wp_list_pages('sort_column=menu_order'); // sort by admin-specified order ?>
<?php wp_list_pages('sort_column=post_date'); // sort by time of page creation ?>
<?php wp_list_pages('sort_column=post_name'); // sort by name of the page slug ?>
<?php wp_list_pages('sort_column=id&sort_order=asc'); // page id in ascending order ?>
<?php wp_list_pages('sort_column=id&sort_order=desc'); // page id in descending order ?>

That first one there is a little wonky, but can prove very helpful for getting your pages to display in any order imaginable. To configure custom Page order to display via the menu_order parameter, you simply assign each Page a numerical value in its Write/Edit Admin screen. You can see a full list of available descriptors here.

Include and Exclude Anything

WordPress makes it easy to include and exclude any pages to create the perfect page menu. By default, the wp_list_pages displays all pages, but this is easily customized with three useful arguments:

<?php wp_list_pages('exclude=1,2,3'); // exclude only these three page ids ?>
<?php wp_list_pages('include=1,2,3'); // include only these three page ids ?>
<?php wp_list_pages('exclude_tree=1,2,3'); // exclude these parent pages and all children ?>

The exclude_tree parameter is new as of WordPress version 2.7. It makes it super-easy to omit an entire branch of pages (the parent page and all descendant pages) from your page listings.

Control the Depth of Pages

There are two parameters designed to control the depth of pages displayed by the wp_list_pages() tag. The first is the depth parameter, which by default displays all subpages, regardless of depth. There is also the child_of parameter, which defaults to a value of 0 to display all pages and subpages. Here are some recipes to customize these default values:

<?php wp_list_pages('depth=0'); // display all pages and subpages via indented lists ?>
<?php wp_list_pages('depth=-1'); // display all pages and subpages without indentation ?>
<?php wp_list_pages('depth=1'); // display only top-level pages ?>
<?php wp_list_pages('depth=2'); // display all pages and first level subpages ?>
<?php wp_list_pages('depth=n'); // display all pages and subpages to the nth level ?>

<?php wp_list_pages('child_of=0'); // displays all pages and subpages ?>
<?php wp_list_pages('child_of=3'); // displays all subpages of page with id 3 ?>

The child_of parameter is a great way to display sub-menus of specific pages, for example for implementation of drop-down menus and so forth. Note that multiple instances of wp_list_pages() may be used on any given web page.

Use with Custom Fields

Here is an extremely powerful way to customize your page menus using custom-field values. Using meta_key and meta_value parameters, you can tell WordPress to display only those pages that contain specific custom-field key/value pairs. Here are some examples:

<?php wp_list_pages('meta_key=menu&meta_value=page'); // display pages with menu/page custom field ?>
<?php wp_list_pages('meta_key=icon&meta_value=true'); // display pages with icon/true custom field ?>

This parameter also gives you the flexibility of modifying page listings without having to touch any source code. Great for clients and family members who may not feel comfortable “digging in” ;)

Even more functionality (new in WordPress 2.7 & 2.8)

WordPress recently rolled out some new tricks for the wp_list_pages() tag. Namely, we now have the ability to wrap the anchor text of our page listings with any HTML or text. Other new features include the number of pages to display as well the number of pages to pass over when displaying page listings. Let’s have a look:

<?php wp_list_pages('link_before=<span>&link_after=</span>'); // wrap anchor text with a span tag ?>
<?php wp_list_pages('number=7'); // display only the first seven pages ?>
<?php wp_list_pages('offset=7'); // skip the first seven pages ?>

A complete copy/paste recipe for wp_list_pages()

There are several more useful parameters for the wp_list_pages() tag, but rather than explaining each one, I will refer you to the Codex for all the boring details. So now, before digging into the juicy stuff, here is a “super-delicious” tag recipe equipped with every possible parameter, especially designed for easy customization:

<?php wp_list_pages('sort_column=post_title&sort_order=asc&exclude=0&exclude_tree=0&include=0&depth=0&child_of=0&show_date=&date_format=&title_li=&echo=1&meta_key=menu&meta_value=page&link_before=<span>&link_after=</span>&authors=0&number=0&offset=0'); // contains all parameters as of version 2.8 ?>

Alright, enough of the basics, let’s explore some truly delicious page-listing recipes.

List all subpages of current page

Here is a way to simplify your sidebars and overall page designs. Instead of listing every subpage on all of your site’s web pages, you can dynamically display subpages only when the visitor is viewing the parent page. So for example, your homepage sidebar would list all of your parent pages, and then each of the parent pages would display a list containing all of its subpages. Here’s one way to do it, as demonstrated in the Codex:

<?php 
$children = wp_list_pages('title_li=&child_of='.$post->ID.'&echo=0');
if ($children) { ?>
	<ul>
		<?php echo $children; ?>
	</ul>
<?php } ?>

Placed in your theme template file, this code will generate a list of all subpages for the current parent page. If there are no subpages, nothing will be displayed.

As is, this method will only display the subpages when visiting the parent page, but we can modify the code so that all subpages are displayed when visiting either the parent page or any of the subpages:

<?php
if($post->post_parent)
	$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
else
	$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
if ($children) { ?>
	<ul>
		<?php echo $children; ?>
	</ul>
<?php } ?>

And you can do even better than that. With this next method, your page listings will be displayed as follows:

• When visiting main page, all top level pages are listed in the sidebar.
• When visiting a top level page with no children, all top level pages are listed.
• When visiting a top level page with children, just the children pages, and descendant pages, are listed.
• When visiting a child page, just the children, and descendant pages, of that parent, are listed.

<?php
$output = wp_list_pages('echo=0&depth=1&title_li=<h2>Top Level Pages</h2>' );
if (is_page( )) {
	$page = $post->ID;
	if ($post->post_parent) {
		$page = $post->post_parent;
	}
	$children=wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );
	if ($children) {
		$output = wp_list_pages ('echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>');
	}
}
echo $output;
?>

All this is great, but it’s also helpful to know how to style the markup generated by the wp_list_pages() template tag. Let’s look at that next..

Styling wp_list_pages() markup

Here is the default markup generated by the wp_list_pages() template tag (assuming a total of five pages with the current page having an ID of “1”):

<li class="pagenav">Pages
	<ul>
		<li class="page-item-1 page_item current_page_item">Page ID 1</li>
		<li class="page-item-2 page_item">Page ID 2</li>
		<li class="page-item-3 page_item">Page ID 3</li>
		<li class="page-item-4 page_item">Page ID 4</li>
		<li class="page-item-5 page_item">Page ID 5</li>
	</ul>
</li>

You can strip the outer <li class="pagenav"> and the enclosing <ul></ul> tags by including “title_li=” (empty string) as a parameter in the wp_list_pages() template tag. You may also keep these outer tags and customize the “Pages” text with whatever markup and/or text you need. Instead of an empty string, use something like “title_li=<h2>Pages</h2>” instead. Note also that specific class attributes will be applied to both parents and ancestors of the current page (see next section).

Styling page menus generated by wp_list_pages()

Here is a list of the selectors available for styling your page menus:

.pagenav {}               /* li tag containing page menu */
.page_item {}             /* inlcuded on every page item */
.page-item-n {}           /* specifies page with id of n */
.current_page_item {}     /* specifies the current page */
.current_page_parent {}   /* any parent of current page */
.current_page_ancestor {} /* any child of current page */

Now, ready for some new stuff? Brace yourself..

Digging into the wp_page_menu() template tag

So what about this new wp_page_menu() template tag? With all of the flexibility of wp_list_pages(), why is it necessary? In a nutshell, wp_page_menu() is a simplified version of wp_list_pages(). In addition to accepting a few of the same parameters, this new tag brings one new trick to the table: it provides the ability to add your site’s Home page to the list of Pages displayed. This tag was introduced in WordPress version 2.7, and, in my opinion, should have been integrated into the existing Page-listing template tag. In any case, for those looking for an easy way to include your Home page into the list of Pages, here you go:

<?php wp_page_menu(); ?>

As mentioned, most of the parameters are the same as before. Here is a list of common parameters:

• sort_column
• include
• echo
• link_before
• link_after

And — drum roll please — here are the new parameters: menu_class and show_home! Let’s check ‘em out..

menu_class

This is a no-brainer. It simply specifies the class attribute for the surrounding <div>. Yes, the list is wrapped in a division. Any string may be used, here is an example:

<?php wp_page_menu('menu_class=pages'); // wrap list in div with class="pages" ?>

show_home

Ahh, the long-awaited “include-the-home-page” functionality. Now, instead of hacking your client’s functions.php file to include the Home Page in the main menu, you can simply do this instead:

<?php wp_page_menu('show_home=1'); // include the home page in the list ?>
<?php wp_page_menu('show_home=0'); // exclude the home page in the list ?>

By default, this parameter returns false and no Home Page is displayed. When set to true, the Home Page will be displayed as the first item in the page list. The URL for the Home Page is taken from the value for your site’s “Blog address”, as specified in the WordPress Admin under Settings > General.

When the Home Page is displayed, the default anchor text is simply “Home”, but you can customize that to whatever you want by specifying such for the parameter value:

<?php wp_page_menu('show_home=Digging%20into%20WordPress'); // include the home page ?>
<?php wp_page_menu(array('show_home'=>'Digging into WordPress', 'sort_column'=>'menu_order')); // include the home page ?>

For more information on this new tag, check it out at the WordPress Codex

Take-home message

WordPress provides two different ways to list your pages: wp_page_menu() and wp_list_pages(). The wp_list_pages() tag is powerful, flexible and fully functional. So, unless you need to include your Home Page, your best bet is always wp_list_pages(). For page menus that include the Home Page, you will need to use wp_page_menu() instead. Beyond listing your Home Page, the wp_page_menu() can do a few things, but nothing that wp_list_pages() can’t already handle.

My question for the day is: Why wasn’t the home-page functionality integrated into the existing tag? Why complicate things with an otherwise redundant tag? Share your thoughts!

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