How To… Navigation Tool Plugin (NAVT)

Introduction

The information presented here is not intended to teach the basics of the PHP programming language, programming logic or WordPress template construction. It is designed to provide sensible help to the “do it your-selfer” who would like to use the NAVT Plugin for WordPress and isn’t afraid to do a little template ‘hacking’ to make it happen.

Having said that, template ‘hacking’ is the very thing I hope to prevent you from doing. Adding the necessary function call to your WordPress template for the NAVT plugin doesn’t take very long to do but you need to understand the following:

  • Where the NAVT PHP interface call needs to be placed in your WordPress template,
  • How to correctly write the function call and,
  • How to style the resulting navigation list.

    • WordPress Theme Basics

    WordPress templates are not very mysterious if you understand some basic information. The content of your WordPress theme directory is composed of one large PHP script that is executed every time someone visits your blog. The theme script is divided into small files and each file name provides a clue for its intended use.

    The typical WordPress theme usually contains (at a minimum) the following files:

    • index.php
    • header.php
    • sidebar.php
    • footer.php

    The Index.php file is the start of the PHP script and code execution begins with the very first line at the top of the index.php file and ends on the very last line. index.php is responsible for assembling all of the information that produces the pages of your WordPress blog. Page assembly (or production) is accomplished by making PHP function calls that are designed to create the HTML code that is, in turn, interpreted and displayed by the viewer’s web page browser. If you already know this, bear with me; it gets more interesting later.

    There is a ‘method to the madness’ of producing web pages by your WordPress theme. The method is simply the loading and execution of known PHP files in a predetermined order. The PHP files come from your theme’s directory. Specifically, the files named: header.php, sidebar.php and footer.php. If your theme is missing any one of these files, the file of the same name will be used from the default theme directory in your WordPress installation.

    How It Works

    The first executed line in index.php is usually a call to the WordPress function get_header(). The get_header() loads the header.php in your theme directory and the PHP statements in the header.phpare executed. As one might suspect, the header.php creates the HTML header portion of the finished output.

    Once the header is complete, index.php begins fetching the contents of the page from the database. “Contents” here refers to the stories, articles, pages and so on that will be displayed when the page is complete. The database calls are made inside a loop that terminates when all of the “contents” available have been retrieved. This area of the index.php is often referred to as “the loop”.

    Once the loop has ended the next item on the agenda is usually the construction of the sidebar. This is accomplished by calling the WordPress PHP function get_sidebar(). The get_sidebar() function loads the sidebar.php file from your theme directory and the PHP statements in the file are executed. The last WordPress function call made by the index.php file is get_footer() which loads and executes the footer.php file.

    Your Mileage May Vary

    Depending on how your theme was constructed, the scripting for the navigation lists that appear in your theme can theoretically be located anywhere. We can narrow down the possible location by making an educated guess. If your theme has a horizontal navigation bar then the scripting code is probably located in the header.php file If your theme uses a vertical navigation list, then the code is probably located in the sidebar.php file. These are the two standard locations for theme navigation used by theme designers.

    To locate the actual line of PHP code (for your theme’s navigation list) in any of your theme files, do the following:

    • Open the PHP file with any simple text editor (Win users should use WordPad)
    • Using the editor’s Find or Search command, look for the word wp_list_pages

    wp_list_pages is a core WordPress PHP function call. It will appear in the file with between the PHP statements: < ?php wp_list_pages(...) ?> . The entire line will look similar to:

           <?php wp_list_pages('title_li=' . __('Pages:')); ?>

    I Found It

    Once you’ve located the wp_list_pages function call, it can be supplemented with the NAVT plugin interface function call. I’m going to create an example of how to correctly add the NAVT interface function to a sidebar.php file. The following is line 41 of the sidebar.php file found in your default theme directory. For this example, I’m going to assume that you’ve created a navigation group using the NAVT Plugin called “sidemenu”.

    
41.    <?phpwp_list_pages('title_li=<h2>Pages' ); ?>

    The above wp_list_pages statement contains a function argument instructing the routine to add the word “Pages” as a level 2 header above the navigation list. So we want to do something similar.

    However, before we add the NAVT function call to the sidebar.php file to produce the navigation group “sidemenu”, it is important to remember that plugins can be deactivated and removed. If you simply added the NAVT interface call and then later decided to deactivated the NAVT plugin, your theme will “break”. This is because the NAVT interface function would no longer be available for use by your theme. The results are ugly.

    This is true for any modification to your theme that involves adding a special function call for any WordPress plugin. Deactivate the plugin and your theme will usually “break”. Luckily, there is an easy way to prevent that from happening and that is by checking to see if the function is available before calling it.

    Modifying Your Theme

    Here is the code for the modified sidebar.php file. I’ll explain this line-by-line:

    
41.    <?php
42.    if( function_exists('navt_getlist') ) {
43.        navt_getlist('sidemenu');
44.    }
45.    else {
46.        wp_list_pages('title_li=<h2>Pages' );
47.    }
48.    ?>

    Line 41 is the start of the PHP script block that ends on line 48. Line 42 is an IF statement that that basically states: “If the PHP function navt_getlist exists then execute the code between the left brace and matching right brace that immediately follows. The PHP function call: navt_getlist function appears between the left and right brace under the IF statement on line 43. The function is given one string argument: the name of the navigation list that is to be displayed – in this case it would be : ’sidemenu’.

    The ELSE condition on line 45 for the IF statement will execute the statement on line 46 IF the navt_getlist function does not exist. This would happen if the NAVT plugin were deactivated or removed. The ELSE condition shown here will execute the original wp_list_pages statement and prevent the theme from “breaking”.

    What about the Header?

    As I mentioned, the original wp_list_pages function will place the word “Pages” above the navigation list wrapped in a HTML H2 tag. There are two ways we can accomplish the same thing.

    The first method is shown here:

    
41.    <?php
42.    if( function_exists('navt_getlist') ) { ?>
43.        <h2>Pages</h2><?php
44.        navt_getlist('sidemenu');
45.    }
46.    else {
47.        wp_list_pages('title_li=<h2>Pages' );
48.    }
49.    ?>

    Here I’ve terminated the PHP block on line 42 and inserted a new HTML statement on line 43. The HTML statement is only executed when the IF condition is true. The PHP block is started again on line 43 following the closing of the H2 tag. This example is effectively equivalent to the wp_list_pages statement.

    The alternative method is to ask navt_getlist to add the title above the navigation list; the method is similar to the way it is done with the wp_list_pages function call.

    
41.    <?php
42.    if( function_exists('navt_getlist') ) {
43.        navt_getlist('sidemenu', true, '<h2>Pages</h2>');
44.    }
45.    else {
46.        wp_list_pages('title_li=<h2>Pages' );
47.    }
48.    ?>

    Here I’ve modified the original example. On line 43 I’m using two additional arguments with the navt_getlist function call. The first argument is the name of the navigation list to be displayed. The second argument is a boolean (an argument that is either set to TRUE or FALSE).

    The second argument (when set to TRUE) instructs navt_getlist to echo the navigation list it builds directly to the output. This is the default value for the boolean. The FALSE condition would instruct the navt_getlist function to RETURN the HTML text it created and NOT write it directly to the output. The idea here is that if you wanted to do something to the HTML text and then display it then you would want the HTML text returned by the function.

    The second argument doesn’t have to be explicitly passed to the function call unless you intend to pass the third argument. The third argument is a text string; the text you want placed above the navigation list. Notice that the text string containing the word Pages on line 43 also contains the HTML opening and closing h2 tags. This means that any HTML can be enclosed within the argument string and the HTML (whatever it contains) will be displayed before the navigation list.

    
Here is an example of a complete H2 tag:
navt_getlist('sidemenu', true, '<h2 id="navsection" class="navheader" >Pages</h2>');

    
Here is an example using an image tag:
navt_getlist('sidemenu', true, '<img class="nbpic" src="/images/navbar.jpg" alt="text" />');

    Advanced Use of the NAVT Interface Function

    (coming)