Bugs

A while ago we created our own small bug reporting script to handle, well, bug reporting. That script (http://msuconfuciusinstitute.org/scheduler/bugs/) is the first live test of FrameWorks 2. It seems to be running well so far.

Parser 1.4.1 , Pages, Request & Ajax

Parser 1.4.1

Major updates on the Parser object. Version 1.3 included Parser Extensions. Version 1.4.1 includes Parser Extensions and Link formatting, in 3.5 different flavors.

First, two FrameWorks-style tags were added, "link" and "url". They do about what you'd expect, ie: "link" generates an internal link and "url" generates an internal URL. Here's the syntax:
{link:page}
{link:page|Link Text}
{url:page}

These work with the new global $fgLinkStyle. Those familiar with MediaWiki will recognize this, it's essentially the same thing, just a string with $1 in it somewhere that tells the parser how to format links.

There's also two pseudo-WikiMarkup additions: [[link]] and [http://link], which work exactly as they do in MediaWiki, including the | deliminator.

Pages

The way we'll handle pages has finally been worked out. This is fairly intricate, but also entirely encapsulated and modular, so I think it's a fair deal. New pages are stored in their own files (though you could, of course, store multiple pages in the same file). This file calls a function, ffAddPage, which takes 2-4 parameters. First is the "label" for the page, ie: some kind of text name that will appear in the URL or querystring. Second is a unique callback function (I've been starting callbacks with "fc") that actually does the processing for the page. More on this in a minute. The third and fourth parameters are booleans, setting the #3 to true will make this page the default, setting #4 true will make it the error page. This is pretty unnecessary, as there's a built-in error page you can use.

The callback functions need to take four parameters, preferably by reference—at least for the first three. Here's the format:
fcPageCallback( &$Parser, &$User, &$Request, $Subpage = false ) {...}

The $Parser parameter is the global fgParser object. The $User parameter is the global fgUser, and the $Request parameter is the global fgRequest object. The subpage is any part of the parameter after the first '/' character.

So, calling
index.php?page=page/subpage
will result in the following: if "page" exists, and the callback is defined, say fcPage, fcPage will be called with the parameters above, including the $Subpage = "subpage". It's the responsibility of the callback fcPage to output material to the browser. This lets pages generate RSS feeds using RSSFeed.

Request & Ajax

Request is a new object that handles getting variables from the HTTP request for you, including escaping quotes if magic_quotes is off. Use the method $fgRequest->getVar('varname'); to get either any request var. Note that POST vars take precedence over GET vars, and that, even if you use the POST method, if there are no POST vars, it will interpret this as essentially GET.

Ajax is almost identical to the AjaxDispatcher object in MediaWiki, that is, if $fgUseAjax is set to true, and you pass a request var called "action" set to "ajax", it will call the Ajax object and use a user-defined callback function. (Note you actually need to set "action=ajax", "rs=callback", and "rsargs=functionarguments" in your request. Though, of course, you could always global in the $fgRequest object and access anything that way.) User-defined callback functions have to be added using the void ffAddAjaxFunction( string Callback ) function.

The Ajax callback has to do two things: 1) accept a string or array as the only parameter, and 2) if necessary, it needs to handle any output to the browser.

Lots of Small Changes

In the past week, there have been several small changes made throughout the FrameWorks system. Let me 'splain. No, there is too much. Let me sum up:

Parser 1.2.2: Parser got a little upgrade, to have a little more in common with Smarty and to simplify the code in pages that use it. The "addVariable" method was shortened to "set" (with an alias left for backwards compatibility) and the "setTemplate" method was made private (this may cause scripts to crash) and template selection was limited to the output function, as in Smarty. So now, code should look something like:

$parser = new Parser;
$parser->set('name', 'value');
echo $parser->output('default.htm');

It also now gets the default template directory from LocalSettings.php, which means you must first include LocalSettings.php, which means you must first define the security constant.

Calendar 1.2.1: Calendar just got updates to follow the new Parser code formats.

RSSFeed 1.1: RSSFeed got similar updates to Calendar 1.1. It now uses Parser to generate code, instead of encoding raw XML. The "addItem" method was also shortened to "add" (with an alias for backwards compatibility).

User 2.0.1 and Userdata 1.0.1: To streamline the process of accessing user information, the Rights array and associated functions were moved to the Userdata object. The User method "hasRight" is now a reference to the mUserdata object's "getRight" method.

The only major update planned for any of these at this time is the addition of ParserExtensions to the Parser object. These would use callback functions to allow custom extensions, as in the MediaWiki parser. I am currently undecided about the format for such tags or how data will be passed to the callback.

Calendar 1.2

The next major revision of Calendar is done. Calendar 1.2 simplifies Calendar 1.1, reducing the CSS requirements and overall shortening the code by over 100 lines. It also abstracts the process of generating HTML, which used to be done in the Calendar object itself but now relies on templates with loops—a feature of Parser 1.2.

Currently Calendar 1.2 needs three templates. This is due to the inability to nest loops. This does give pretty specific control over how each section will look, though. The only lost functionality is the ability to use completely different CSS for "big days," used to display seven days or less, and "small days," used for two-week and month displays. Practically, the only difference was a height factor, which could easily be changed on a page-by-page basis, or left to float, with a min-height attribute.

With these major revisions of Parser and Calendar I am now going back to work on User 2.0. If anyone has advice on the best way to do session-based user login, let me know. Version 1.0 serialized the itself and stored the data in the session. Any new User object would check for the session data, and, if found, copy the data into itself. I can't decide if I want to do something like this again, or store the whole object in the session.

Parser 1.2

On the way to Calendar 1.2, which will use Parser to simplify the process of looping through days and make it, yet again, easier to update, I realized my templates were going to be bloody long and fairly ... static, so I had to update to Parser 1.2.

Parser 1.2 has yet another new feature: foreach loops. This allows you to--OK, here it gets complicated--define as a variable an array, call it $Loop, of associative arrays, say $Data, with tag => value data. Each $Data has the same array keys (theoretically) and different array values (theoretically). Then you put in the template something like:

{foreach:loop}
{name1} likes {name2}<br />
{endforeach:}

This would print, provided the tags name1 and name2 were defined in each member of the variable "loop," one row of who-likes-who for each member of "loop." The structure is something like...

$Loop = Array (
0 => Array (
  "name1" => "Jessica",
  "name2" => "Mark"
),
1 => Array (
  "name1" => "Stewart",
  "name2" => "Leslie"
),
);
$parser->addVariable("loop", $Loop);

And this would print something like, using that template above:

Jessica likes Mark<br />
Stewart likes Leslie<br />

The potential here is obvious. It's a little tricky, yes, and not something one would want to do by hand, but it's not too hard to do it automatically, having another loop add arrays to the $Loop array before adding it as a variable. This is exactly what Calendar 1.2 will be doing.

All I wanted to do was streamline Calendar, and I ended up with a whole new control structure in Parser. Imagine that.

FrameWorks 2.0

If nothing else, I'm learning a lot about practical programming through this project.

The original backbone, FrameWorks 1.0CI, had more bugs than your average Microsoft release, and was about as useful as anything before Service Pack 2. It couldn't do much of anything, except handle user authentication and basic data access. The "CI" part of the version also meant it had been rewritten for PHP4, and lost a lot of its performance.

The first part of the new version, FrameWorks 2.0, was the Calendar object, an abstraction of basic calendar functions, which I talked about in the last post. Calendar is currently in version 1.1.2, but I'm hard at work on version 1.2.

The Calendar object caused me to build a Math object, which is nothing but a bunch of static functions (I love PHP5) to do basic math that PHP doesn't have built in, like a true modulo function. Math basically augments versions every time I find a new function it needs.

I also created my own exception class, called Error. Currently in version 1.0.1, Error simply cleans up the messages created by the built in Exception class.

The next big project was a template parser, called, simply, Parser. Parser is like a slimmed down version of Smarty. It's missing some of the big features, mostly because it works much differently. Smarty, for instance, compiles templates into workable PHP code. It then caches these compiled files. It doesn't have true page-caching. Parser, on the other hand, doesn't compile templates, so it can't cache them, so, summarily, it has no caching system (yet). Since all the pages are dynamic, I'm not too worried about this, either.

Parser 0.1-1.0 involved a built-in Menu system, which would create automatic variables known to fill in a menu and submenu. Parser 1.1 ditched this (retrospectively dumb) idea for two much more powerful implementations: template inclusion and basic boolean logic. This pretty much eliminated the need for a difficult-to-implement menu system anyway. Now it's much easier to just create a "menu.htm" template with various if/then statements to decide which link to highlight or whatever.

Parser also uses an internal object called Translator. This is my first real stab at multiple language support. Language files just have an associative array with the text label and translation. This will let the new version of the OTS support users native languages. And through the Translator, the Parser can interact with the Calendar to change the language and date formats there, too.

Also new is an RSSFeed object, which will be able to automatically generate RSS feeds (either static files, like through cron or publishing script, or dynamic through another script). The idea for the OTS is that users will be able to subscribe to a feed with their next 10 appointments or something.

Finally, major updates are planned for both the DB and User classes, which should both be in a functional 2.0 by the end of the week.