Child Themes and Templates

This article will explain how to replace default WPAdverts templates with your own template files, and how to create theme files for Advert custom post type and taxonomies.

Replacing Default Templates

Why replace default templates? Sometimes you might want to change default layout in WPAdverts shortcodes or Ad details page, to make it more suitable to your niche for example. You could do that directly in the WPAdverts files, but this is highly discouraged as your changes would be overwritten when plugin is updated. The recommended method is to use ‘adverts_load_template‘ filter instead.

Before we will go into details lets see what template files are available in the plugin by default. The templates directory is wpadverts/templates you will find all templates files there.

add.php – [adverts_add] shortcode, (1st step) the form user needs to fill in order to post an Ad.
add-preview.php – [adverts_add] shortcode, (2nd step) Ad preview page.
add-save.php – [adverts_add] shortcode, (3rd step) Ad save and/or payment form.
categories-all.php – [adverts_categories show=”all”] shortcode, displays all categories.
categories-top.php – [adverts_categories show=”top”] shortocde, displays top categories only.
form.php – can be used as any form template (by default it is used only in 3rd step when posting an Ad).
list.php – [adverts_list] shortcode, Ads list (uses list-item.php to display template for each item in the list).
list-item.php – [adverts_list] shortcode, this file is used as template for each item in the list.
manage.php – [adverts_manage] shortcode, list of user posted Ads.
manage-edit.php – [adverts_manage] shortcode, displays Ad Edit form.
single.php – used on Ad details page (for example http://example.com/advert/lorem-ipsum/ ).

Using ‘adverts_load_template’ filter.

Lets assume we want to display some additional text above Ads list in [adverts_list] shortcode (of course the easiest way to do it would be to enter the text in wp-admin / Pages panel, but for the sake of example, we will do it using adverts_load_template filter).

Inside your wp-content/plugins directory create folder ‘custom-list-template‘, inside this folder create file custom-list-template.php, inside this file we can add following code.

<?php
/*
 * Plugin Name: Custom List Template.
 * Plugin URI: https://wpadverts.com/
 * Description: This plugin replaces default WPAdverts templates/list.php file with list.php file inside this directory.
 * Author: Greg Winiarski
 */
 
add_action("adverts_template_load", "custom_list_template");

function custom_list_template( $tpl ) {

    // $tpl is an absolute path to a file, for example
    // /home/simpliko/public_html/wp-content/plugins/wpadverts/templates/list.php
    
    $basename = basename( $tpl );
    // $basename is just a filename for example list.php
     
     if( $basename == "list.php" ) {
        // return path to list.php file in custom-list-template directory
        return dirname( __FILE__ ) . "/list.php";
     } else {
        return $tpl;
     }
}

We also need to create list.php file inside the custom-list-template directory, we only want to display some custom text above Ads list, the rest of the template will stay the same, so in new list.php we will add the text and load the default list.php template after it. This code can look like this:

<?php

printf( '<div>Today is %s.</div>', date( 'Y-m-d' ) );
include ADVERTS_PATH . '/templates/list.php';

Now go to wp-admin / Plugins panel, on the list find “Custom List Template” plugin and activate it, then refresh page with [adverts_list] shortcode it should now display ‘Today is <current date>’ text above the list.

The whole working example you can download here.

Loading Templates from current Theme directory

Instead of writing filter function for each template, you can use the Override Templates plugin available in WPAdverts Snippet directory. This addon will load templates from your current theme or child-theme instead of wpadverts/templates directory.

For example if your current theme name is my-theme, then when loading template list.php WPAdverts will first look for the list.php file in wp-content/themes/my-theme/wpadverts/list.php if the file won’t be found there it will load default list.php file.

In order to use it, download the override-templates.php file, upload it to wp-content/plugins directory on your server and activate from wp-admin / Plugins panel.

Custom Post Type Template

When displaying Ad details page your theme will usually use a single.php file in your current theme directory, most of the time this is fine, but sometimes you might want to remove or change some content not applicable to Ads. The best way to do this is to go to your current theme directory (via FTP), create there file single-advert.php, copy to it content from single.php (or page.php) file, if needed remove / change content and save single-advert.php.

Now when loading Ad details page the single-advert.php file will be used as a template, using the_content filter or function single-advert.php will load wpadverts/templates/single.php file in order to display actual Ad details (description, location, category and gallery).

Custom Taxonomy Template

Similarly as in previous paragraph in your current theme directory create a file taxonomy-advert_category.php, copy to it content from taxonomy.php or archive.php and customize to your needs.

For best results WPAdverts will try to use default Page template on category pages, we need to disable this functionality to allow plugin to use the custom template. Adding the code below to your theme functions.php file will do that.

add_action("init", "my_theme_wpadverts_init", 20);
function my_theme_wpadverts_init() {
    remove_filter('template_include', 'adverts_template_include');
}

Note in some themes the category list might not work as expected (that might be due to how the archive.php template is created), in this case in your taxonomy-advert_category.php file replace the while(have_posts()) ... endwhile; loop with following code snippet

<?php 
    global $wp_query;
    remove_filter("the_content", "adverts_the_content");
    echo shortcode_adverts_list(array(
        "category" => $wp_query->get_queried_object_id()
     ));
 ?>

This will make the category pages display correctly.

If you are using some other taxonomies (for example Locations in Maps and Locations add-on) then you would create the taxonomy-advert_location.php and in the code snippet above remove line "category" => $wp_query->get_queried_object_id() everything else would be the same as with default categories.