Writing Functions In Sassenach CMS
I am currently carrying out a little more cleaning up of the Sassenach CMS codebase, starting with themes. At the moment, Sassenach CMS themes are fairly complicated and easy to break if you don't know what all the code does. This may seem an obvious point, but the average person designing a template doesn't necessarily want to deal with the entire codebase - they just want to style their website. In order to take away most of the complicated code, I have set about writing functions that call the code from elsewhere.
This, unfortunately, took much longer than I was expecting. In fact, it took 6 hours last night just to get one function working. It was, of course, all my own fault. So, before I explain the functions, two quick tips: firstly, if your function doesn't appear to work, make sure you've called it properly. Let's say we have the following function:
function my_new_function {
}
That's fine, as long as it is declared within PHP. However, when it comes to calling the function, don't make the mistake of doing this:
my_new_function; // This will not work!
Instead, make sure you call it like this:
my_new_function(); // This will work!
Basically, I forgot to include the parentheses when calling my function. Silly. Anyway, there was a further problem which manifested itselfwhen including other external files within my function. I was trying to do this:
include $file;
This wasn't working, however. So, I tried the actual file I wanted to include on this occasion:
include 'file.php';
No problem. As far as I was concerned, $file == 'file.php', so it should all work. I couldn't work it out. It didn't make sense. It should work - but it doesn't. I checked my PHP and MySQL book, but it didn't give me an answer. I Googled for 3 hours, with no result. I checked the PHP website, Tizag, DevShed, everywhere else I could possibly think of, but no, nothing.
I chatted to someone on the phone about it. We decided Greek made more sense. Then, one of my housemates came back. We chatted for a bit. I rambled on about the problem for a few minutes. They listened politely, but I may as well have been talking Chinese.
Then, I went back to it. It still didn't work, so I copied a snippet of code from the PHP website. It worked. I adapted it. It still worked. I didn't understand at all. And then it hit me like a concrete block. It was obvious. Talke a look:
$file = "'functions/'.$function.'php'"; // Do you see the problem here?
include $file;
I am a muppet. I had double quotes that were completely unwarranted and broke the script. No amount of Googling would come up with that answer.
So, having exposed my blatant error to the world, hopefully I have saved others from the same mistake - and we can move on to Sassenach CMS functions. I didn't want the functions to all come from the database, because that puts unnecessary load on the database. Similarly, I didn't want to include every function at the top of every script when they weren't always needed. Thus, I have written a function that is designed to call other functions as required. Here it is:
function get_sassenach_function($function) {
$sassenach_function = 'functions/'.$function.'.php';
include $sassenach_function;
}
Thus, if you called the function like this:
get_sassenach_function(links);
Then Sassenach CMS would, ultimately, run the script at 'functions/links.php', which then executes the code that no-one should really need to deal with.
However, there is a chance that people may want to use their own custom functions. What happens then? There is, of course, the option to hack the scripts, but I wouldn't advise this, especially as any upgrade would likely overwrite them again. Instead, we will have a directory within which people can place their own modified scripts and run them. So, that might look like this:
function get_sassenach_user_function($function) {
$sassenach_user_function = 'functions/user/'.$function.'.php';
include $sassenach_user_function;
}
Thus, users can define their own functions and call those without having to worry about having their custom functions overwritten. More importantly, they can call their own custom functions easily.
There is, however, one other possibility. What if a particular theme wants to call its own functions? Well, the same kind of principle applies, except that the functions would be stored in a functions directory in that themes folder, and would use another slightly different call, yet to be written, which would be get_sassenach_theme_function($function). This will need to be a little different in design as it requires knowledge of which directory the theme is found in, but it will still wirk without too much trouble.
There is one more problem to overcome - what if you need to call a function more than once? This is actually quite easy to overcome, and it is done like so:
if (!function_exists('example_function')) {
function example_function() {// The function is defined here
}
}
example_function(); ?>
So, each time the function is called, the top of the function file checks to see whether the function has been defined before. If it has, there is a problem - that functions can only be defined once. So, if the function has already been defined, it just calls the function. Otherwise, it defines the function and then calls it.
And so there you have it, a guide to functions in Sassenach CMS. What a fun post. Does anyone still have the will to live? If so, feel free to comment. Comments should now be working - if they're not, you should let me know!
There are currently no comments on this article.