Creating a tree-type index of pages or TOC using wp_list_pages function

WordPress has the hability to works with nuclear posts and also with posts that can contain posts, ie, posts with hierarchical structure. Today we’re going to see how to create an list of the second ones, as an index of pages, Table of contents (TOC), etc.

Panzerbaum

As default, WordPress supports two different kinds of elements: posts and pages. The basic difference between them is that the first ones, are treated as individual elements, organized in a long linear list of elements (like the natural numbers 1, 2, 3, 4, for example) meanwhile the second ones have got a hierachical structure, ie, each element can contain elements that have also got hierarchical structure.

WordPress Posts and Pages Scheme

In this second case, using these elements with hierarchical structure, we can create complex information structures like, for example

  • Book ( Book > Chapter > Section > Paragraphs )
  • Company Organization ( Management > Areas > Departaments > Employees )
  • Animal Classification ( Kingdom > Phylum > Class > Order > Family > Genus > Species )

and, in all of these cases, one of most common things that probably we need do, is to create the index of subelements that belong to one element, ie: the index of all chapters and sections for a specific Book, a company organization scheme, the list of animals that belong to a concrete Order, etc. For example, in this website, for each published plugin, it’s shown the index of all its related pages (see the example of reCAPTCHA in WP comments form plugin) inside a box called Plugin Documentation.

Creating the tree-type index

For creating the tree-type index of pages, we’ll use the WP function wp_list_pages() (for further informaction, see official documentacion of wp_list_pages()) and we’ll add the tree-type index to a specific page using a shortcode. Of course, the tree-type index can be added to the page directly, via template, but, in this example, we’ll develop this procedure in two steps: First we create the shortcode, that we can put in any position inside the page content, and second we decide the type and content of the tree-type index using the wp_list_pages() function.

Creating the ShortCode

For creating a new shortcode we have to use the WP function add_shortcode() and we’ll call the shortcode function inside the action wp_loaded. Doing this, during the shortcode declaration WordPress is already completely loaded and the WP query is already executed so that, we can check all WordPress parameters, WP Query vars, elements related to the current $post, etc.

In this next code, for exemple, we’ll make just a a simple check, we add the shortcode only for the specific post type my_special_post_type but remember that inside the loading_environment function you can check whatever you want because all WordPress, WP Query and $post vars are available.

<?php
function render_tree_type_index_callback_function( $atts ) {
    // we'll develop the code later
}
function loading_environtment() {
    global $post;
    // Here, if we want, our checking points
    if ( $post->post_type == 'my_special_post_type' ) {  
        add_shortcode( 'TREETYPEINDEX', 'render_tree_type_index_callback_function' );
    } else {
        // Other environments loads
    }
}
add_action ( 'wp_loaded', 'loading_environtment' ), 10 );
?>

The tree-type index using wp_list_pages function

Now we’re going to create the tree-type index so that, we have to use the wp_list_pages() function, and we have to pass to this function some parameters: the first leaf $post->ID of the tree, the depth of the tree, etc. (See the list of all parameters of wp_list_pages() function).

Of course, we could develop the shorcode function completely and to pass these parameters via shortcode arguments but this is not the objective of this article but talking about tree-type indexes so that, for simplicity, we pass directly the array of parameters to the function wp_list_pages() and other day we’ll talk extensively about the add_shortcode function.

<?php
function render_tree_type_index_callback_function( $atts ) {
    global $post;
    $out  = '<div class="tree-type-index">';
    $out .= '<h5>' . __( 'Tree-type Index Title', 'textdomain' ) . '</h5>'; // the index title
    $out .= '<ul>';
    $out .= wp_list_pages (
       array ( 'child_of' => (int) $post->ID, // the first leaf ID
               'depth' => 0, // all depth, all elements
               'post_type' => $post->post_type,
               'title_li' => '', // we don't show any title, we'll create it manualy
               'echo' => FALSE
       ) );
    $out .= '</ul>';
    $out .= '</div>';
    return $out;
} ?>

With these simple parameters, we are listing the permalinks of all subtree elements (posts), in any depth of the tree, that belong to the first leaf element whose ID is equal to $post->ID.

See the shortcode in action

For example, following the hierarchy shown in the image example of the prior section, if we put the shortcode inside the page whose ID is equal 572 in wp post editor, something like this,

// in the WP post editor
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse id blandit justo. Mauis sed pellentesque leo. Aenean nec nibh metus. Nunc sed lectus sed tortor porttitor scelerisque. Suspendisse ac nunc lobortis, aliquam elit ac, mattis justo. Cras ac nisi volutpat, aliquet quam vitae, faucibus libero.
[TREETYPEINDEX]
Suspendisse blandit condimentum justo. Proin quis lectus quis nisi suscipit maximus. Ut dapibus ullamcorper mauris, quis hendrerit ligula bibendum nec. Phasellus a ornare purus. Donec sollicitudin, nisl vitae vulputate lobortis, ante enim tempor nisl, a ullamcorper turpis erat vel nisi.
Donec eu libero hendrerit, feugiat orci vel, blandit leo. Quisque vel sodales dui. Proin sed metus sit amet quam cursus elementum. 
Aenean nec nibh metus. Nunc sed lectus sed tortor porttitor scelerisque. Suspendisse ac nunc lobortis, aliquam elit ac, mattis justo. Cras ac nisi volutpat, aliquet quam vitae, faucibus libero. 

We’ll obtain something like this on the screen but with Post Titles and Permalinks instead of simple numbers, of course. It’s just an example.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse id blandit justo. Mauis sed pellentesque leo. Aenean nec nibh metus. Nunc sed lectus sed tortor porttitor scelerisque. Suspendisse ac nunc lobortis, aliquam elit ac, mattis justo. Cras ac nisi volutpat, aliquet quam vitae, faucibus libero.

Tree-type Index Title

Suspendisse blandit condimentum justo. Proin quis lectus quis nisi suscipit maximus. Ut dapibus ullamcorper mauris, quis hendrerit ligula bibendum nec. Phasellus a ornare purus. Donec sollicitudin, nisl vitae vulputate lobortis, ante enim tempor nisl, a ullamcorper turpis erat vel nisi.

Donec eu libero hendrerit, feugiat orci vel, blandit leo. Quisque vel sodales dui. Proin sed metus sit amet quam cursus elementum.

Aenean nec nibh metus. Nunc sed lectus sed tortor porttitor scelerisque. Suspendisse ac nunc lobortis, aliquam elit ac, mattis justo. Cras ac nisi volutpat, aliquet quam vitae, faucibus libero.

 
And adding some CSS styles you can obtain fantastic results.

Have a nice WordPressing!

Leave a Comment

   Mandatory field
You can use these HTML tags inside the commment.
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>