How to output a list of all articles by category hierarchy

Hello everyone. This article is about WordPress. Recently, we decided to create our own function to output a list of our blog posts. We created our own process to output a list of posts by category hierarchy. In this article, we introduce the program.

Note that this page is an English translation of a Japanese page. (We modified the original Japanese to make it easier to translate. Therefore, there is a possibility that the expressions may differ from the original.)

Motivation

In the past, we used a plugin to display the list of articles (post pages). However, when we checked the last update date of the plugin, we found that it was out of date. The version of WordPress is updated frequently. We wondered if we continue to use the plugin.

Then we used a WordPress theme that had the ability to output a list of articles. For a while we used that theme, but then we decided to use another one.

Currently (at the time of writing this article), the theme we are using does not have such a feature. Therefore, we decided to create our own process to output the list of articles.

The plugin we used before displayed the list as follows.

• Displays the hierarchy of categories.
• For each category, all articles belonging to that category are displayed.

A familiar example: a tree view of folders and files.

In order to create the above process by ourselves, we checked the functions provided by WordPress. We then created a program that outputs the list under certain assumptions. This article is a reminder of how we made the program ourselves.

Situation

We installed a local WordPress environment for testing.

We created some categories and post pages for testing.

There are five articles that we created. The titles of the articles are as follows.

• post0001
• …
• post0005

We created categories and set the hierarchy and number of posts to belong to as follows.

As shown above, the articles belonged only to the bottom level category.

The articles are divided into the following categories.

The following is a hierarchical view of the output results of the program for this purpose.

Category A
 Category A-01
  Article Title 0001
 Category A-02
 Article Title 0002
  Article Title 0003
Category B
 Category B-01
  Category B-01-01
   Article Title 0004
Category C
 Article Title 0005

The purpose is to display the category hierarchy and output a list of articles that belong to each category, as shown above.

Traverse the hierarchy with the function get_categories

We looked into the functions provided by WordPress to accomplish our goal. As a result, we decided to use the function get_categories().

The argument of this function is an array. There are several keys that can be set in the array. This time, we used the following key

Assume that the array specified in the argument has the above keys. Only child categories of categories whose ID is the same as the value of “parent” are returned. In particular, if the value of the key “parent” is 0, the function returns the top-level categories: categories that have no more parents.

This function returns an array of category objects.

The following is an example of setting the value of “parent” to 0.

function my_function() {
    $args = array(
        'parent' => 0,
    );

    $categories = get_categories( $args );

    echo '<pre>';
    print_r($categories);
    echo '</pre>';
}

Array
(
    [0] => WP_Term Object
        (
            [term_id] => 1
            [name] => cat-a
            [slug] => cat-a
            [term_group] => 0
            [term_taxonomy_id] => 1
            [taxonomy] => category
            [description] => 
            [parent] => 0
            [count] => 0
            [filter] => raw
            [term_order] => 0
            [cat_ID] => 1
            [category_count] => 0
            [category_description] => 
            [cat_name] => cat-a
            [category_nicename] => cat-a
            [category_parent] => 0
        )
    ...
)

As shown in the above result, the array returned by the get_categories function contains information for each of the top-level categories.

In this case, what is stored are the objects of the top level categories, “Category A”, “Category B”, and “Category C”.
The value set in the key “cat_ID” is the ID of the category. We use this value to create an array and call the function get_categories() again. By doing so, we can traverse the child categories of that category.

The following is a sample of the application of recursive calling.

function my_shortcode_function() {
    my_function(0);
}

// Recursive call
function my_function( $cat_ID ) {
    $args = array(
        'parent' => $cat_ID,
    );

    $categories = get_categories( $args );

    echo '<ul>';
    if ( empty( $categories ) ) {
        // no child 
        echo '<li>ID：' . $cat_ID . '</li>';
    } else {
        // otherwise
        foreach ( $categories as $category ) {
            echo '<li>' . $category->name;
            my_function( $category->cat_ID );
            echo '</li>';
        }
    }
    echo '</ul>';
}

<ul>
  <li>cat-a<ul>
      <li>cat-a-01<ul>
          <li>ID：4</li>
        </ul>
      </li>
      <li>cat-a-02<ul>
          <li>ID：5</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>cat-b<ul>
      <li>cat-b-01<ul>
          <li>cat-b-01-01<ul>
              <li>ID：7</li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li>cat-c<ul>
      <li>ID：3</li>
    </ul>
  </li>
</ul>

The my_function function above performs the following branching process.

• For the category corresponding to the argument $cat_ID, if the child category does not exist, $cat_ID is output.
• Otherwise, call my_function() for each child categories.

The first case is when there are no child categories. In that case, the category corresponding to the argument $cat_ID is the lowest level category.

The second case is when there is more than one child category. In this case, it calls itself recursively. For example, in the first loop, $category is an object of “Category A”. After the category name is output, the function my_function is called with the ID of “Category A”. Since the start and end tags of the li element are output before and after the call, the ul element is output inside the li element.

By changing the processing content of the first part to the output of the article list, our desired program will be completed.

By the way, there is a shortcode definition in the first place. This is the shortcode for the fixed page.

Completed program

We added a process to output the list of articles to the above program. For the part of the article list output, we used WP_Query. For this part, we used the general method.

Here is the completed program.

<?php
// shortcode
add_shortcode( 'my_shortcode', 'my_shortcode_function');

function my_shortcode_function() {
    my_function(0);
}

// recursive call
function my_function( $cat_ID ) {
    $args = array(
        'parent' => $cat_ID,
    );

    $categories = get_categories( $args );

    echo '<ul>';
    if ( empty( $categories ) ) {
        // no child 
        print_posts( $cat_ID );

    } else {
        // otherwise
        foreach ( $categories as $category ) {
            echo '<li>' . $category->name;
            my_function( $category->cat_ID );
            echo '</li>';
        }
    }
    echo '</ul>';
}

// Output article information
function print_posts( $cat_ID ) {
    $args = array(
        'posts_per_page' => -1, // (*1)
        'orderby' => 'date',
        'order'   => 'ASC',
        'cat'     => $cat_ID,
    );

    $query = new WP_Query( $args );
	if ( $query->have_posts() ) {
		while ( $query->have_posts() ) {
			$query->the_post();
            ?><li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li><?php
		}
	}
    wp_reset_postdata();
}

(*1) was added at 20220320.

<ul>
  <li>cat-a<ul>
      <li>cat-a-01<ul>
          <li><a href="[home url]/post0001/">post0001</a></li>
        </ul>
      </li>
      <li>cat-a-02<ul>
          <li><a href="[home url]/post0002/">post0002</a></li>
          <li><a href="[home url]/post0003/">post0003</a></li>
        </ul>
      </li>
    </ul>
  </li>
  <li>cat-b<ul>
      <li>cat-b-01<ul>
          <li>cat-b-01-01<ul>
              <li><a href="[home url]/post0004/">post0004</a></li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li>cat-c<ul>
      <li><a href="[home url]/post0005/">post0005</a></li>
    </ul>
  </li>
</ul>

In the above program we have defined a new function print_posts(). This function outputs the title of an article as a link.

To get the articles belonging to a category, the WP_Query function is used. By specifying the temporary argument $cat_ID of the function print_posts() as the argument of the WP_Query function, the posts belonging to that category are returned. Then, output the information of the returned array. This iterative process is the standard process for outputting a list of articles.

The function print_posts() will be called from the function my_function() if there are no child categories.
The articles we prepared this time belong only to the bottom level category. The function my_function() is called for the category. Therefore, the list of articles is output as a hierarchical view.

That’s all. I hope this is helpful to you.