Using Custom PHP with Suffusion

One of Suffusion’s neat little features is the Custom Styles option. Based on some feedback that I had received from some users, in release 3.4.2 I provided a way to bundle custom PHP with your installation.

In this post I will walk you through the following scenarios explaining how you can use this functionality:

1. Adding your own meta tags.
2. Creating your own short codes.
3. Passing extra parameters to queries for fetching posts.

Here is how you begin:

1. Create a PHP file called, say, custom-code.php. Put this file somewhere under your “wp-content” folder, but not under the “suffusion” folder. If you put it in the “suffusion” folder it will get overwritten upon an upgrade!
2. Go to Suffusion Theme Options → Blog Features → Custom Includes → Custom PHP. Put in the file name with the path, as instructed.
3. Now for some serious business. Open the file you created in an editor. You could use any editor that you want (but not a Word Processor!!), like Notepad or Vim or Emacs or EditPlus or Textpad. Your choice depends on your individual preferences and your Operating System. I personally use Vim for editing minor things because of my Unix-based background, and a full-blown IDE like PhpStorm or Aptana Studio or Eclipse for the heavy-duty stuff.
   Now build the shell for the file as follows:

   
   <?php
   /**
    * Custom includes
    */
   ?>
   

   Make sure that you have no white-spaces or new lines or text before the “<?php” or after the “?>”. This is critical. If you have spaces there, you will get nasty PHP errors that will require you to replace file/folder contents using FTP.

Now let us address each of our scenarios.

Scenario 1: Adding your own meta tags

This is something I have addressed on the support forum. Let’s say you want to create your own meta tags with name “my-custom-tag” and value “my-custom-tag-value”. Here is what your code looks like:

<?php
/**
 * Custom includes
 */
//The hook for publishing the document header is suffusion_document_header.
//This tells the code to add an extra action to suffusion_document_header:
add_action('suffusion_document_header', 'suffusion_include_custom_meta_tags');

function suffusion_include_custom_meta_tags() {
    echo "<meta name=""my-custom-tag"" content=""my-custom-tag-value"" />n";;
}
?>

That’s it. You can add as many “echo” statements as you want in the “suffusion_include_custom_meta_tags” function.

Scenario 2: Creating your own Short Codes

The ability to use your own short codes with Suffusion speeds up things several notches. The following code is from one of my previous posts, and it demonstrates how to add a short code that will execute any PHP function. You can add it within the “<?php” and “?>” tags:

function sc_php_function($attr) {
    $function = $attr['function'];
    $params = $attr['params'];
    $params = explode("||", $params);

    if (is_callable($function)) {
        $ret = call_user_func_array($function, $params);
    }

    return $ret;
}

add_shortcode('php-function', 'sc_php_function');

This will create a short code called “php-function” which is like RDX – it will let you execute any PHP function from within a post or a page.

The short code above is dangerous if you have a multi-user blog, or if you are using a plugin that enables short codes in the comments section, because it will let anyone execute any PHP function on your site – it is a significant security risk, so use it with utmost care!

Scenario 3: Passing extra parameters to queries for fetching posts

I recently introduced a hook called “suffusion_query_posts”. This hook is executed before your posts are parsed (aka The Loop), so you can use this to modify what you want to display. It is present on different templates, like Author, Category, Date, Index, Page of Posts, Search and Tag. Let’s say you want to exclude posts belonging to the category with id 15. Here is what you add in the PHP code in the file:

add_action('suffusion_query_posts', 'suffusion_query_enhancer');
function suffusion_query_enhancer() {
    global $wp_query, $query_string;
    $query_string .= "&cat=-15";
}

You could think of a lot of other scenarios where you could use the custom PHP inclusion. Note that like its more popular cousin, the Custom Styles, this too is upgrade-proof. It also adds to Suffusion the feel of a theme framework. If you are looking to add some functionality and you don’t see a hook for it, do post your query on the support forum.