Difference between revisions of "Beginner's Guide to Programming"

Security

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.

<?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;

?>

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.

<?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;

?>

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!

Where to put it

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 :

<?php

require_once( '../lib-common.php' );

$display =  COM_siteHeader();

$display .= "Hello World";

$display .= COM_siteFooter();

echo $display;

?>

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

Alias /hello/ "/path/to/your/hello/"

Of course, this means that your require_once statement will have to contain the full path to lib-common.php

require_once( '/path/to/geeklog/public_html/lib-common.php' );

To Plug it in, or not

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.

Some Odds and Ends

A couple of more quick points on some basic Geeklog stuff

Functions, Bring Me Functions!

We've already seen two of the most widely used functions that Geeklog has to offer - COM_siteHeader() and COM_siteFooter(). It is important to note with this that there are optional parameters you can pass to each of them to achieve certain results. COM_siteHeader() displays the header and the left blocks, while it's partner controls the footer and the right blocks. By default COM_siteHeader() displays the left blocks, and by default COM_siteFooter() does not display the right blocks. Check the source code in lib-common.php for details on how to change this behavior.

Another set of similar workhorse functions which are also defined in lib-common.php along with the aforementioned functions are COM_startBlock() and COM_endBlock(). COM_startBlock() accepts 3 optional parameters : title, helpfile and template. THe most useful and almost always used is title, which is a text string which will appear in the title bar of the block. If a helpfile is specified, Geeklog will display the help question mark icon and link to a help file for that block. And by default the 'blockheader.thtml' template is used unless another is specified. COM_endBlock() must be called once for each call to COM_startBlock(), and it's only optional parameter is template, the default being blockfooter.thtml.

Blocks can be nested inside of each other, which is obvious by simply looking at just about any geeklog website.

<?php

require_once( 'lib-common.php' );

$display =  COM_siteHeader();

$display .= COM_startBlock("Outer Block")
             . "This text should be inside the outer block but outside the inner block"
             . COM_startBlock("Inner Block")
             . "This text should be inside the inner block"
             . COM_endBlock()
             . COM_endBlock();

$display .= COM_siteFooter();

echo $display;

?>

When using nested blocks inside of HTML tables, one simply has to be certain to call COM_endBlock() in the write place since it outputs HTML tables as well, and otherwise the display may not render properly.

<?php

require_once( 'lib-common.php' );

$display =  COM_siteHeader();

$display .= COM_startBlock("Outer Block")
             . "This text should be inside the outer block but outside the inner blocks"
             . "<table align=center width=100% border=0>"
             . "<tr><td align=center width=50%>"
             . COM_startBlock("Left Inner Block")
             . "This text should be inside the left inner block"
             . COM_endBlock()
             . "</td>"
             . "<td align=center width=50%>"
             . COM_startBlock("Left Inner Block")
             . "This text should be inside the right inner block"
             . COM_endBlock()
              . "</td></tr></table>"
             . "This text should be below the inner blocks but inside the outer block"
             . COM_endBlock();

$display .= COM_siteFooter();

echo $display;

?>

The great advantage of using these two functions is that whenever the site admin or user changes their Geeklog theme, your GUI will change to match. Your program will always retain the same look-and-feel of the site in general.

There are also some useful form functions found in lib-common.php which come in very handy and make life a bit easier. COM_optionList( $table, $selection, $selected=, $sortcol=1 ). This creates an HTML "<option" list generated from the given table, using the passed variable "$selected" in the SELECT statement of the HTML query. See source code for a better idea of what the function does, but it is very useful.

In a similar vein, COM_checkList( $table, $selection, $where=, $selected= ) creates a list of check boxes from the given table, with the given select and where clauses being passed to the SQL statement inside the function.

One more useful function is the COM_errorLog($logentry, $actionid = ) function which logs to the Geeklog logfile if $actionid is 1, or to the screen if it is set to 2.

COM_checkWords( $Message ) gives you access to Geeklog's (somewhat rudementary) profanity filter. We find it to be fairly useless since if you include for example the word "cock" in your filter, you will also filter out the completely innocuous word "peacock". If you nonetheless want to use the geeklog profanity filter, simply do this :

$text = COM_checkWords( $text )

COM_mail( $to, $subject, $message, $from = , $html = false, $priority = 0 ) does exactly what the name suggests and lets you send mail to someone.

THere are far too many functions in lib-common.php to discuss here, so we'll end off with two very important ones which can be used for accessing query-string variables. What's a query string? If you have a URL like this :

http://www.example.com/someprogram.php?variable=value&othervariable=othervalue

In this example, inside the text of someprogram.php, if the PHP installation has "register_globals" turned on, the variable "$variable" will automagically exist in the program and will have the value "value". But there are certain security problems with using "register_globals" in PHP so a lot of people do not like to have it turned on. Unfortunately Geeklog requires that it be turned on (at least for now until the programmers get it rewritten to eliminate the need), so to mitigate the risks involved you can use special functions to obtain your query string variables.

Near the top of your program simply insert something like the following, first to define which are the only global variables your program expects to see, then finally to safely obtain the value of those variables :

COM_setArgNames(array('variable','othervariable'));
$variable               = COM_getArgument('variable');
$othervariable       = COM_getArgument('othervariable');

Support and Such

THe best place for Geeklog support is of course the main Geeklog site. But there are a few other great places to check including Squatty and Portal Parts. Squatty and Blaine are hard-core Geeklog developers and are responsible for several popuarl themes, plugins and hacks.