Agile Programming for WordPress Plugins: The Joy of Output Buffering

A standard practice of Agile programming, and good programming in general, is to separate your display code from your application logic. Bob Martin:

Today’s modern programming environments make it possible to put many different languages into a single source file. For example, a Java source file might contain snippets of XML, HTML, YAML, JavaDoc, English, JavaScript, and so on… This is confusing at best and carelessly sloppy at worst.

The ideal is for a source file to contain one, and only one, language. Realistically, we will probably have to use more than one. But we should take pains to minimize both the number and extent of extra languages in our source files.

Separating display code is central to the MVC pattern, which underlies almost all PHP frameworks (and frameworks in many other languages as well). WordPress is a blogging platform and arguably a CMS, but for plugin authors, it does not provide the typical tools of a development framework. If you want to separate out your display layer, you’re on your own.

As a result, very few plugin developers do. A common style for WordPress plugins is a single file, sometime running thousands of lines, that consists of cryptically named functions (often in no discernible order), which have the display code scattered around within the core application logic. This style might be acceptable for something small and simple. But once the functionality becomes complex, this style makes the code very difficult to understand for anyone other than the author (and the author is likely to find it hard to understand six months after finishing work on it). It also makes extending the functionality difficult. For example, adding support for a mobile UI would entail a major rewrite.

For a WordPress plugin, you can use output buffering to solve this problem. You can see an example in my ShashinMenuDisplayerAlbum class. The run() method triggers the display of the menu, and its HTML is in a separate file:

ob_start(); // start the output buffer
require_once($this->relativePathToTemplate); // get the HTML template
$toolsMenu = ob_get_contents(); // store it in a variable
ob_end_clean(); // empty the buffer and turn it off

Normally a require_once call would include the file, evaluate any PHP code, and immediately output the HTML. Including the file with output buffering turned on allows you to instead store all the output in a variable. You can then control when it is displayed. With this approach you do not have to write all your HTML inline with your application logic.

The template file being included in my example does have PHP as well as HTML in it, so I am not meeting the ideal of complete separation. But as Bob Martin points out, such total separation isn’t always possible. In this case, the PHP code used in the template is the minimum necessary for the purpose of rendering the page (for example, it contains a foreach loop to display rows of data in a table).

9 Comments

  1. Reply
    Gary Morris July 12, 2011

    Unrelated comment post for Shashin support question (per your instructions on the contact page.)

    I am not sure what has happened for sure but it seems that picasa has updated their servers to SSL only. This seems to have caused Shashin to no longer work.

    I tied to update shashin.php to https in the three places I saw that might cause the conflict but this alone did not fix the problem.

    Shashin still does not update the shashin_photo field in the Word Press database so I am obviously missing something.

    Would you mind taking a look at Shashin and updating it to work with Google’s new protocol. Shashin is exactly what we need for our site, it used to work flawlessly and I love it. As it is now I have totally hosed it and I can not get it to work even with an uninstall and a reinstall.

    Thanks for all of your hard work!

    Gary

  2. Reply
    Mike July 12, 2011

    Yes, I am working away on the new version. It’s actually a re-write, as Google’s https switch has caused problems for many people, and there is no quick fix for it in the current version (as you’ve discovered). The current version actually still works fine for me – I’m not sure why it’s failing for some people but not others.

    The new version does album sync’ing in a completely different and more robust way. You can play with the alpha version if you like: https://github.com/toppa/Shashin/ (read the README for installation instructions). It currently only has the tools menu for adding albums, but you can use it to verify it solves the problem you’re currently having. It’s independent of the old version, so you can install them side by side.

  3. Reply
    Gary Morris July 13, 2011

    Don’t you just love it when that happens. You get everything just the way you want it and then someone has to go and change things on you. lol

    Before Google changed the protocol I had an album that was showing up just fine. It was when I tried to ad another album that things stopped working for me.

    I’ll give the alpha a try, thanks for that option.

    Gary

  4. Reply
    Gary Morris July 13, 2011

    What about the SQL for the database table creation?

    Gary

    • Reply
      Gary Morris July 13, 2011

      I get the following error when I go to Tools/Shashin3Alpha :

      Shashin Error: Failed to find database record for albums

      I installed the Toppa libs, activated them, then installed the alpha files and activated it, then I went to Tools and clicked on Shashin3Alpha. This is how I received this error.

      I checked the database and the two tables (wp_shashin_album_3alpha & wp_shashin_photo_3alpha) were created but there is no data in them (because I haven’t entered any I am sure). I will try to manually enter a record and see if that eliminates the error.

      Gary

      • Reply
        Gary Morris July 13, 2011

        Indeed, I manually entered a record into the wp_shashin_album_3alpha table and everything is working fine.

        New problem though, the old shortcodes no longer work. I hope I am not missing something obvious.

        Thank you for all the time you have put towards this, it is awesome and you should charge for it.

        Since you are rewriting it, you could have two versions. A free basic version and a pay for extra features version. You talked about including (youtube and some other site, myspace I think) functionality in this new version. That sounds great, but charge for it. If you are not comfortable charging a lot then make it a minimal amount. I think everyone would be thrilled to pay for this awesome plugin myself. When you leave it up to a donation people forget about donating (I did anyway).

        Gary

        • Reply
          Mike July 16, 2011

          Hi Gary – thanks for testing it. I will upload a fix soon for Shashin 3 alpha so you don’t get that error about no albums when you first go to the tools page. I am working on the shortcodes and have not uploaded that code to github yet.

          I’m still trying to decide whether to charge for a premium version of Shashin – thanks for the input.

  5. Reply
    David Caucci July 16, 2011

    Thanks for working on this Mike! I’d really love to get a working Shashin so I don’t have to switch plugins.

    Is there any way I can help with the code?

    Best,

    David

    • Reply
      Mike July 16, 2011

      Hi David – I’m posting the code for the new version to github – https://github.com/toppa/Shashin/ I appreciate the offer to help with the coding. Perhaps first take a look at what I’ve got a github, and let me know if it’s a style of coding you’re comfortable with. I should have a new round of updates posted within a week.

Leave a Reply to Gary MorrisCancel reply