<a href='http://www.geeklog.net/'>Geeklog</a> is a powerful weblog (blog) content management system (CMS) which is written in the popular programming language <a href='http://www.php.net/'>PHP</a>, and uses the popular <a href='http://www.mysql.com/'>MySQL</a> database. While Geeklog is powerful enough that many users will not have a need to write their own applications for it, it is flexible enough to allow those who do require extra functionality to do so easily. These people write there programs in PHP, with some minor restrictions and using the Geeklog function library.
[b]Hello, World[/b]
The first program you write in any computer language is "Hello World", and here it is in Geeklog. THis is saved in a file "hello.php" in Geeklog's "public_html" directory, and so is surfable at http://www.example.com/hello.php
[code]
<?php
require_once( 'lib-common.php' );
$display = COM_siteHeader();
$display .= "Hello World";
$display .= COM_siteFooter();
echo $display;
?>
[/code]
There are a few important things to be noted from the given program.
geeklog programs stay in PHP mode - there is no flipping back and forth between PHP and HTML as is possible in the PHP language. This means that all programs have "<?php" on the first line, and "?>" on the last line, and everything in between is PHP code.
there is only ever 1 "echo" statement to spit out the HTML. The whole rest of the program up to this point is simply putting together a string of HTML which gets spit out at the bottom. For debugging purposes you can put "echo" statements elsewhere and this output will appear at the top of the screen. But aside from debugging, in general you only have a single "echo" statement at the bottom.
"lib-common.php" is the single file which must be included in all your Geeklog programs. It includes everything else you need unless you decide to make your own include files, so it's one-stop shopping.
there are functions in Geeklog to do lots of stuff for you - like for example COM_siteHeader() and COM_siteFooter(). In general Geeklog functions start with 2 or 3 capital letters and an understore - this tells you what type of function it is. Then the name of the function. COM_ functions are "common" functions - not a terribly meaningful name. But SEC_ functions like SEC_inGroup() which allows you to test if a user is in a particular group, allow your programs to access some of the powerful security features of Geeklog. And DB_ commands allow you to access the Geeklog database.
[b]Security[/b]
Speaking of the powerful Geeklog security model (one of the key reasons I originally chose Geeklog for my sites), let's alter the hello world program such that any user in the "quay" user group will see the "hello world" message, but anyone not in that group (which includes users not logged in) will get a "permission denied" error.
[code]
<?php
require_once( 'lib-common.php' );
$display = COM_siteHeader();
if ( SEC_inGroup( 'quay' ) )
$display .= "Hello World";
else
$display .= "Access Denied";
$display .= COM_siteFooter();
echo $display;
?>
[/code]
To check out the full range of security functions available to you, and how to use them, read the /path/to/geeklog/system/lib-security.php file, which is where they are implemented.
Though the above code format is a bit clunky and not terribly useful, so let's make another change which shows us how most programs deal with group permissions issues.
[code]
<?php
require_once( 'lib-common.php' );
$display = COM_siteHeader();
if ( ! SEC_inGroup( 'quay' ) )
{
$display .= "Access Denied";
$display .= COM_siteFooter();
echo $display;
exit;
}
$display .= "Hello World";
// do some other stuff here
$display .= COM_siteFooter();
echo $display;
?>
[/code]
The big difference in this version of the program is that right at the top of the program we test for group permissions, and if the users does not have them we display the site footer, then exit. So a user not in the 'quay' group will end right there and never see what the rest of the program does. Very simple, but very powerful!
[b]WHere to put it[/b]
If you are only writing a small program, then sticking a single file in the public_html directory as shown above will work fine. As soon as you get to the point, however, when you start having your own include files and so on, you probably want to create a directory for it. In our case we could create a directory in "public_html" called "hello", and then create a file "index.php" with the above program. THis will require a very minor change to the original program - see if you can pick it out before peeking :
[code]
<?php
require_once( '../lib-common.php' );
$display = COM_siteHeader();
$display .= "Hello World";
$display .= COM_siteFooter();
echo $display;
?>
[/code]
Yup, that's right, we had to add "../" to the "lib-common.php" in the "require_once" (which BTW is a type of "include" in PHP). The reason is simple : lib-common.php lives in public_html, and our first program was in that directory as well. This new program is in a subdirectory of public_html, so we have to go to the parent directory to get our include file.
If you want to keep your geeklog installation "pure", as I usually do, you can also put your program directory somewhere outside of the geeklog directory, and use directives for your webserver to map that directory into the web space of your geeklog installation. That's easier than it sounds - with Apache just use the "Alias" directive
[code]
Alias /hello/ "/path/to/your/hello/"
[/code]
Of course, this means that your require_once statement will have to contain the full path to lib-common.php
[code]
require_once( '/path/to/geeklog/public_html/lib-common.php' );
[/code]
[b]To Plug it in, or not[/b]
This is a bit of an advanced topic which in some ways is out of place at this point, but just about everyone who knows Geeklog and has used it a bit, knows about Geeklog plugins. And when writing your own Geeklog programs, this will obviously be something in your mind. Not all Geeklog programs are plugins - and the above examples are not. Plugins involve writing your program in a specific way, and defining specific functions which Geeklog will expect to find. It also involves making some entries in the Geeklog database to let Geeklog know that your plugin is there.
In general if you want to use the Geeklog comment engine, the Geeklog search engine (i.e. integrate your program data into the search feature of Geeklog), or the Geeklog submission engine, you must write a plugin. Otherwise you can just write code. Size doesn't matter. THere is no limit after which you have to make it a plugin.
[b]Some Odds and Ends[/b]
A couple of more quick points on some basic Geeklog stuff
the $_USER array comes pre-populated for you by Geeklog. If $_USER['uid'] is greater than 1, then you know your user is logged on. Otherwise they are anonymous. So in the above example if you wanted to test for "logged on user" rather than "member of quay group", just change the 'if' statement accordingly. This array contains all of user table from geeklog, the next most useful subscript being $_USER['username']
the $_CONF array contains everything you set in your config.php, if you need it. Just check config.php for what all is there.
both of the above arrays are global, and as such if you use them in a function you must declare them in the function with the 'global' directive, as is normal for PHP. Outside of any function in the main body of the program they can be just used.
[b]Support and Such[/b]
THe best place for Geeklog support is of course the main Geeklog site http://www.geeklog.net/. But there are a few other great places to check including http://www.squatty.com/ and http://www.portalparts.com/. Squatty and Blaine are hard-core Geeklog developers and are responsible for several popuarl themes, plugins and hacks.
If you want to report a bug or request a feature, set yourself up an account <a href='http://project.geeklog.net/tracker/?atid=105&group_id=6&func=browse'>here</a> and do so. If they don't know it is broken, the cannot fix it. I've reported several bugs and have had them fixed prompty. I've also tracked down and fixed several bugs and simply submitted the code which was accepted. And I've also requested several major features which have been added over the years at my request. The Geeklog development team is small, but very dedicated and they love to get feedback from the user base.
