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

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 and thus, when WordPress displays a collection of them, this will be just 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 (to point to) elements that have also got hierarchical structure and can contain (to point to) other elements and so on, in consequence, when WordPress displays a collection of them, it should be always presented as a tree and never as a list.

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 )

but for that, one of the most common things that we need do is precisely to be able to represent, at the same time, one element (pages) and the TREE structure associated with the alement (the tree of its children pages), ie, for any elements to be able to display a ordered list of the subelements that belong to this element; in other words, for example, in the case of a book, its index of all chapters and sections; for a company, its organization scheme: the list of animals that belong to a concrete Order, etc. In the case of this website, for example, for each published plugin, it’s shown the index of all its related subpages (see the example of reCAPTCHA in WP comments form plugin) inside a box called Plugin Documentation.

Creating the Table of Contents for wp Pages

For creating the tree-type index of pages (table of contents), 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 for 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.

 
And adding some CSS styles you can obtain fantastic results.

Have a nice WordPressing!