Architecture
From GregariusWiki
The Gregarius source code is fairly modular and object oriented. This document aims to give you an overview of how the pieces fit together.
Contents |
[edit] Handling User Input
Most of the files in the /rss/ directory (like index.php, feed.php, author.php etc..) are just meant to handle user input and determine what sort of SQL queries to run on the database. The best way to observe when these files are being used is to turn off the config option rss.output.usemodrewrite. Most of these files have a simple structure.
As an example let us look at /rss/sticky.php. This file is used if you go to http://example.com/rss/sticky.php to show you all the items that you have marked as sticky.
- First the sticky.php file creates a new ItemList (which is an object of the class ItemList)
$stickyItems = new ItemList(); $stickyItems -> setRenderOptions(IL_NO_COLLAPSE);
- Then it calls the ItemList class method populate to decide what sort of items to put into this ItemList.
$stickyItems -> populate( "i.unread & " . FEED_MODE_STICKY_STATE );
- Then the sticky.php file adds this ItemList to the list of things that the global instance of the RSS class (called $GLOBALS['rss']) has to render. Note that at this point the global instance has not been given any other ItemLists to render.
$GLOBALS['rss'] -> appendContentObject($stickyItems);
- Then it tells this RSS class to render content using the theme template file index.php which lies in the current theme (usually at /rss/themes/default/index.php).
$GLOBALS['rss'] -> renderWithTemplate('index.php');
As you can see from this simple example above, most of the real work is done in the classes. These classes are in the /rss/cls directory and are described below in some detail. The other php files in the /rss directory like index.php, feed.php, author.php etc.. do pretty much the same thing as sticky.php except that sometimes it is more complicated to determine what items to render and sometimes additional objects are rendered.
[edit] Classes and Wrappers
Most things that you see in a gregarius webpage like a header, footer, sidemenu, itemslist (and even the items themselves), feeds are actually classes in Gregarius and they are defined in the /rss/cls/ directory. The big daddy class is the rss class defined in /rss/cls/rss.php. Some of these classes have wrapper functions defined in /rss/cls/wrapper/ so that plugins and themes may safely and cleanly use these classes without worrying about the implementation details and the fact that these details might change in future versions of Gregarius.
For example the function rss_main_title() in /rss/cls/wrapper/header.php returns a string that is going to be the document title.
[edit] Themes
Some of the classes defined above like Itemlist, Feedlist etc have render methods which usually call renderWithTemplate(...). If a class does this, then Gregarius looks for a template in the current theme and uses that template to render objects of this class. Themes make heavy use of the wrapper functions and they can change the layout of the page as well as provide additional functionality. This is covered in some more detail in the Theme Authoring Guide on the wiki.
[edit] Plugins
At some key locations throughout the Gregarius source-code call-back hooks are defined. They are functions that look like rss_plugin_hook('rss.plugins.*', ...). When the program flow gets to a function like this, it calls any plugins that might have registered for this hook. As an example look at the following hook rss.plugins.items.newiid in /rss/util.php
rss_plugin_hook('rss.plugins.items.newiid',array($newIid,$item,$cid));
This mean that when Gregarius is about to add a new item into the database it will call any plugin function that has registered for the rss.plugins.items.newiid hook. When this plugin function finished execution, Gregarius continues its normal program flow. These concepts are covered in more detail in the Plugin Authoring Guide.
[edit] External Libraries
Gregarius uses a few external libraries to do some important tasks. Some of them are MagpieRSS to parse the feeds, Snoopy to actually fetch the feeds and favicons and Sajax to help with the AJAX functions. You can find these files in /rss/extlib/
[edit] Database interaction
Database interaction in Gregarius is handled through an abstraction layer, allowing the developers to access the database without having to bother about RDBMS specificities.
In a nutshell, developers access the database through a set of functions defined in /rss/db.php which then map to the currently active database system implementation, defined in /rss/cls/db/
Adding support for a new RDBMS is achieved by creating a subclass of /rss/cls/db/db.php. The subclass must implement each of the functions defined in /rss/db.php. (See the MySQL and the SQLite implementations, for example)
As new features are added to Gregarius, the database schema supporting these features is updated on the fly. This is achieved by trapping specific errors returned by the underlying RDBMS (an error for a missing column on a given SQL query, for example.) When such an error is triggered, Gregarius checks the current database schema and issues ALTER TABLE and CREATE TABLE statements to roll the schema to the required state.
This mechanism is also used during the installation process: after the user has defined its database connection credentials in /rss/dbinit.php the schema is entirely generated on the first run.
