Result Templating

Making direct changes to the results files

This guide is for advanced users/developers. Please do not modify the template files if you have no experience in HTML/PHP programming.

From version 4.0 the search plugin generates HTML output based on specific template files. This means, that you are now able to modify HTML structure of every result.

You can find these files in the wp-content/plugins/ajax-search-pro/includes/views/results/ directory.

Important! Before you start

Do not make changes directly to these files! To have permanent changes make a new folder called “asp” in your theme directory like so:

wp-content/themes/your-theme-name/asp/

and copy the desired files from

wp-content/plugins/ajax-search-pro/includes/views/results/

directory there. The plugin will automatically look and use the files from the theme “asp” directory if they exist. Now you can edit these copied files and prevent future search plugin updates to remove your changes.

Directory Structure

Each of the 4 layouts (vertical, horizontal, isotopic, polaroid) has a separate template file available:

• vertical.php

• horizontal.php

• isotopic.php

• polaroid.php

For grouped result layouts, you can change the group header and footer in:

• group-header.php

• group-footer.php

For no results and keyword suggestions the following template files are used:

• no-results.php

• keyword-suggestions.php

How does this templating work?

After the search process the plugin outputs the results. At certain points these template files are included in the output process. For example when the plugin finds 5 results and the vertical layout is used, the vertical.php file is included for each result individually.

In this case these template files there is some HTML structured mixed with PHP variables, which represent the values for each result. This is very similar to actual WordPress themes.

If you open up any of these result template files in your code editor, you will find a brief description about which variables are available and how to use them. In these files you can use any WordPress related functions.

Result template files and variables

As mentioned earlier, each layout uses a different file to output a result item (vertical.php, horizontal.php, isotopic.php and polaroid.php). These files are very similar as they are called in the same loop.

Each of these files feature 2 additional variables to use:

• $r – the result Object

• $s_options – the search options array

You can find multiple uses of the $r variable through the template code. The $r is not equivalent with a post object, so don’t try to use wp_loop or post reference functions on it, it won’t work.

The $r object has the following attributes, that you can use (optional values may not exist):

• $r->id – this is the item id. It can be a post ID, term ID, user ID… – depending on what the actual content type is

• $r->content_type – this holds information about the current content type. It can be one of the following values:

  • ‘pagepost’ – a post, page or custom post type

  • ‘term’ – a taxonomy term (category, product category, etc..)

  • ‘user’ – a user

  • ‘comment’ – a comment

  • ‘blog’ – a blog (on multisite networks)

  • ‘bp_group’ – a buddypress group

  • ‘bp_activity’ – a buddypress activity

• $r->title – the result title

• $r->link – the result link

• $r->content (optional) – the result content

• $r->image (optional) – the url of the result image

• $r->date (optional) – the result date

• $r->author (optional) – the result author name

These are the main attributes, some others may exist, you can do a var_dump($r) to see the exact list of them.

Examples

In the following chapter you can check practical examples of using the templating system.

Example #1 – Putting a horizontal ruler below vertical result title

Lines 52-57 of vertical.php print the title h3 tag:

<h3><a href='<?php echo $r->link; ?>'<?php echo ($s_options['results_click_blank'])?" target='_blank'":""; ?>>
        <?php echo $r->title; ?>
        <?php if ($s_options['resultareaclickable'] == 1): ?>
        <span class='overlap'></span>
        <?php endif; ?>
</a></h3>

So the the HR should be put after these lines:

<h3><a href='<?php echo $r->link; ?>'<?php echo ($s_options['results_click_blank'])?" target='_blank'":""; ?>>
        <?php echo $r->title; ?>
        <?php if ($s_options['resultareaclickable'] == 1): ?>
        <span class='overlap'></span>
        <?php endif; ?>
</a></h3>
<hr>

Save the template file. You should notice the horizontal ruler after the result title when searching now.

Example #2 – Printing post meta into the content

Since you have access to the post ID via the $r->id, you can get custom field values and put them before/after the content easily.

If you look ate lines 76-80 in vertical.php, you see the content is being printed there:

<?php if ($s_options['showdescription'] == 1): ?>

    <?php echo $r->content; ?>

<?php endif; ?>

Let’s get and print a meta value there in a custom div element and modify the code like this:

<?php
// This is the meta key
$key = 'my_meta_key';

// We only want to do this on posts/pages/custom post types
if ($r->content_type == 'pagepost') {
  $meta_value = get_post_meta( $r->id, $key, true );
  if ($meta_value != '')
    echo "<div class='my_class'>" . $meta_value . "</div>";
}
?>

<?php if ($s_options['showdescription'] == 1): ?>

    <?php echo $r->content; ?>

<?php endif; ?>

If the post meta with the ‘my_meta_key’ exists, then it will be printed before the description, inside a new div element.