User Defined Code
Usercode
Usercode is a way of fairly easily and quickly adding code to a theme that can modify posts or even run amok, that is, code can modify all posts, and, late in the initialization process after the site has been configured, code can be run in the global scope.
There are four types of usercode.
1. Applied to all posts.
2. Applied to a single post.
3. A single function to run in limited scope once during start-up.
4. A PHP file that is included in the global scope to support the first three points.
First, by "user" we do not mean people visiting the website. We mean people "using" this program. Usercode can only be created and installed by an Administrator.
Second, the usercode is in an INI file which is read into an array and the data is used to create functions. The INI file is editable by the Admin code so an Administrator can modify the code at anytime. As an INI file there is only a slightly less chance of typographical errors, but it provides a way to parse the code and catch errors while maintaining the overall security of the site.
Third, there can exist a PHP source file that will simply be included in global scope if it exists. This allows Administrators total control to modify the running of the code as much as possible without having to modify the core code.
There is no "Plugin API", no "hook functions" and no classes. Just code. Knowledge of how the core code works and how it operates is the API.
Usercode is associated with a theme and is in the USERCODE.INI
file. The default theme's usercode file is empty. Here is how to add some usercode.
In Admin, click on the edit
command. To the right, click on htm/usercode.ini
and then add the following and save:
[signature] $r = $record['body']."<br>— All's well, that ends well."; return $r;
It's straight PHP code. There are no limitations. There can be multiple usercode sections. The return value later overwrites $record['body']
if it loosely tests true (but is expected to be a string—more on that later).
To have usercode applied to a post, in Admin, create a post with the line, right after the title:
line, and before the body of text:
usercode: signature
When previewed the post will end with the "signature" defined above.
Perhaps you now see why our Admin post form is so spartan. What was just done in one minute, the editing of one file to modify the program, would have taken an hour and many files, perhaps having to "implement a plugin class extension", in just about every other Blog application.
More Details
There can be any number of usercode sections. And a certain two have special function. A section with the name [allposts]
will have it's code applied to all posts. A section with the name [global]
will have it's code executed once during start-up, after the site has been initialized and after any theme's FUNCTIONS.PHP
file has been included—more about that later.
The usercode has copy of the post record. And if the usercode returns a string that string will then be copied into the record body. If the usercode decides to not change the post body it should return 0
(or NULL
or FALSE
).
The usercode ID can have arguments, separated by commas, and they will be in an array variable $user_args
, with $user_args[0]
the usercode ID and other members any arguments.
The allposts
usercode can be bypassed for any post which has a header of noall:
.
The post body is run through the "post translation" code (as described in one of the default posts when the program is run for the first time) before the usercode is run.
The [global]
usercode runs with only the super globals in scope, but of course can call any existing function. There are no arguments to the global code.
Implementation
The code to support usercode is really small and is in the USERCODE.PHP file, which is included almost last by INDEX.PHP, initializes itself automatically, has no global data and has a single entry point, usercode()
, which is called by only one function, displayrecord()
, in the DISPLAY.PHP file.
There are two ways to disable usercode, 1) by a CONFIG.INI
setting of nousercode = 1
; 2) by removing the include "usercode.php";
line from INDEX.PHP.
FUNCTIONS
If a FUNCTIONS.PHP
file exists in the theme directory it will automatically be included. This file has no constraints and no requirements (other than being valid PHP code).
The default theme templates and the theme data file (HTML.INI
) are always included even if the default theme is overridden (see file THEMES). However, only the set theme's usercode and functions are used—i.e. if you create a theme and use the themedir = newtheme
configuration setting, the default theme's usercode will not be used (and there is no default theme functions file).
Notes
1. But, since in the global scope, can do anything.
2. We will eventually convert the INI file to a PHP file. But the reason we have an INI file is, 1) we were not too smart when we started; 2) we want a minimalist Admin text editor to remotely edit the code. We actually do not want a PHP file filled with defined functions for this, as that would not work. An associative array of code is how to make this work.
3. If there is a parse error in the usercode that code section will be discarded. (A function not found error will stop execution—I don't think that can be avoided.)
4. The file should have write permissions—if it does not please email us about it so we fix it!
5. We are going to incrementally change the interface. The next step will be to use a PHP formatted file (an associative array of code). Then we will see what comes next.