TheDrunkenEpic

Creating datasources that pull random content

I was recently browsing around the Overture forums the other day looking for some new tips and tricks for Symphony and came to the realization that when it comes to creating new Datasources, Symphony doesn't offer an option to randomize the result set.

I realize this won't be an issue for most people, but what if you have a portfolio section to your site and you want to pull some random portfolio entries for the front page? What if you'd like to do the same with comments or articles? This tutorial aims to provide a relatively simple solution for this small issue.

Prologue

Before we start, I thought I'd let you all know that this tutorial assumes that you have a rudimentary understanding of Datasources for the Symphony publishing platform. If not, you can access the public wiki dedicated to Symphony documentation for more information. This tutorial also assumes that you're not afraid to get your hands a little dirty with the source code.

Creating the Datasource

For the sake of this tutorial, let's just say you would like to display 3 random comments on your site's main page. To accomplish this, you must first create a new Datasource. Click the image below to get the full details of this Datasource.

As you can see, this is a very basic Datasource. In this instance, we named our DS 'Random Comments', but you can call it whatever you like. The source of our data should be set to 'Comments'. Leave the filtering options alone for this tutorial; you won't really need them. In the 'format options' section, choose what fields you want included. You can choose a sorting option, but it won't really do any good as our result set will be randomized by the end of this tutorial.

Since we only want to show 3 random comments, set the Datasource limit options accordingly. Click the 'save' button and you should be good to go!.

Digging in the Source

Before We Start:

To speed up execution times, the Symphony team set up the system in such a way that it generates a new PHP source file every time you create a new Datasource. This source file's content reflects the settings you chose when creating the actual Datasource within the Symphony interface. On the system level, when a Datasource is attached to a page, Symphony will refer to the corresponding source file by including it and then executing it, generating the appropriate XML result set based on your specified criteria.

Neato!

Back to the Program:

Now, since Symphony doesn't have an option to randomize result sets, we're going to have to dive into our new Datasource's source file and change around a few things.

First, navigate to the following directory %symphony_root%/workspace/data-sources/ and open the file named data.random_comments.php in your favorite IDE. Now that you got the file open, we can handle this one of two ways. We can either randomize the returned data using PHP's built-in randomization functions or we can add a simple SQL clause into the database query strings that fetch our data. Since the latter is much simpler we'll just go with that.

In your IDE, run a quick search for ORDER BY. There should be 2 results. In both of these instances, you will need to change ORDER BY to ORDER BY RAND(),. Be sure to note the comma(,) right next to Rand().

Next, by default, Symphony likes to cache result sets pulled from Datasources. This will pretty much put a halt to all our hardwork. If our 3 random comments are cached, the system won't pull new random comments until said cache expires and updates itself. We can't have that, so do the following:

Find:

##Check the cache
$hash_id = md5(get_class($this) . serialize($env_url));

if($param['caching'] && $cache = $this->check_cache($hash_id)){
    return $cache;
    exit();
}

And either delete it or comment it out:

//  ##Check the cache
//  $hash_id = md5(get_class($this) . serialize($env_url));
//
//  if($param['caching'] && $cache = $this->check_cache($hash_id)){
//      return $cache;
//      exit();
//  }

Now, save your changes and upload it back to its home directory.

Using Your Datasource

Using this new Datasource is no different than any other. Before the system generates your XML, you will first need to attach this Datasource to a page. To display your random comments, you will need to modify the page's main template.

Find where you would like to see your comments and add something like the following:

<xsl:for-each select="random-comments/entry/comment/">
    <div>
        <xsl:value-of select="author"/> Said:<br />
        <xsl:copy-of select="message/*"/>
    </div>
</xsl:for-each>

Naturally, you'd want to spruce it up a bit, but, for the most part, that's all you need to do. Save your page's main template and view the live result. You should now see 3 random comments appear every time you refresh your page!

Please Note

Don't let all your hard work go to waste! Every time you update your Datasource's options within Symphony's interface, the system rewrites the entire source file, thus overwriting all your changes. Just remember, if you have to make a change to the Datasource, you'll need to go back and reapply these modifications.

In Closing

Well, that's pretty much all there is to it. In this tutorial you learned how to create a Datasource that randomizes result sets by modifying its source code. See what else you can do by changing a few more things around in the source. If you mess up and break something, just re-save your Datasource in the Symphony interface to overwrite your changes.

I hope you enjoyed this tutorial as much as I enjoyed writing it! Till next time ...