Month: March 2007

As I mentioned earlier, for came2pass.com I had promised any changes to the site would be submitted back to the community for other Pligg administrators to use. I have had several ideas of new functionality for Pligg, of which I am developing. You can expect those in the coming months. Pligg actually makes it really easy to add new functionality with a very little documented plugin architecture called Modules. I have decided to document it here for others to use. It is my hope this can expand the Pligg community even faster than before. I’d like to start this with a disclaimer that I am not a PHP developer as my first trade – my experience roots in Perl, but I do a little PHP as well for my job. So if my terminology is incorrect, please forgive me – it is my intention to have this out there as a service to the community. I am also an outsider – I did not write the Pligg code, and I have not until recently gotten involved with the Pligg community. I have only recently begun to read the Pligg internals, and I try to note my lack of knowledge in the areas I still don’t fully understand. I’ll update this blog entry if I stand corrected in anything, and if anything needs to be added.

While I’d like to delve in immediately on Modules, I should probably preface that there are actually 2 extendible architecture types in Pligg. The first is Pligg’s Module system, a pluggable architecture to extend Pligg functionality. The second are Pligg templates. These allow you to customize your own look and feel, and perhaps even add a few extra functional elements to Pligg as well. Because there is already a vast amount of documentation on the web for templates, I’ll save that for later. Today I’ll focus on Pligg Modules.

Module Hierarchy

To understand how modules work, you have to understand the filesystem hierarchy for each module. All Pligg modules exist as individual directories (listed by module name) in pliggroot/modules. I will refer to pliggroot throughout this document as the path to your pligg web application.

Within pliggroot is also a file called module.php. This is mostly just a file for use by each Module later. It’s a pretty bare-bones file that calls a few of the essential libraries needed to write pligg pages.

Within pliggroot/modules, there are also 3 php files, modules\_init.php, modules\_libs.php, and modules\_manage.php. My understanding is that these files are called when each module hook is called, and tell pligg how to load the modules. I haven’t read deep into them though, so I’ll let the Pligg maintainers explain that later if they want.

Underneath each module directory you will always have a series of files. I will explain those below:

modulename_init.php

Throughout this document, the term “modulename” is the main identifier of the module being written. It just has to be consistent, and unique – I don’t think it really matters what you name it.

modulename\_init.php is your main controller for your module. Most module\_init’s start out with a call to:

include_once(‘modulename_settings.php’);

I’ll explain what that does in a minute. To summarize, it essentially loads all the variables to be used throughout your module.

Following that block, you’ll see in most modules a:

$include_in_pages = array(‘all’);
$do_not_include_in_pages = array();

As the comments in this module says:

// tell pligg what pages this modules should be included in
// pages are minus .php
// index.php becomes ‘index’ and upcoming.php becomes ‘upcoming’

This is essentially a good way to speed up your application. By not selecting “all” and only selecting the pages you want your module to load in, your module will only be called from the pages you select. This keeps unneeded code from loading on the other pages. So, to only load your page in index.php, replace the first line above with:

$include_in_pages = array(‘index’);

$do\_not\_include\_in\_pages() works the same as above, but you are to include in that any pages you absolutely do not want your module to load in. I’m assuming that works best with ‘all’ in $include\_in\_pages.

Next, in each modulename\_init.php you’ll see a section that looks like this:

if( do_we_load_module() ) {

module_add_action(‘module_page’, ‘modulename_function’, ”);
module_add_action_tpl(‘tpl_sidebar_top’, modulename_tpl_path . ‘module_tpl.tpl’);

include_once(mnmmodules . ‘modulename/modulename_main.php’);
}

In the first part, it’s just checking the arrays we talked about above to see if we should go further.

The next module\_add\_actions are essentially setting callbacks for various sections already in the code. module\_add\_action() runs the function listed as parameter 2 at the location of the callback name listed as parameter 1. That function is located in modulename\_main.php. The 3rd parameter I believe is just any parameters you want to send to the function you just called – I haven’t gotten this to work yet though.

module\_add\_action\_tpl() works similarly. The first parameter is a callback name within a template in your templates directory. The second parameter is the name of the customized template you want to place at the location of that callback. module\_add\_action\_tpl() is a great way to insert custom html code into an already existing template.

I have also seen module\_add\_action\_js and module\_add\_action\_css – I’m pretty sure these work similar to module\_add\_action\_tpl, but for css and js files in your templates architecture.

The next line is:

include_once(mnmmodules . ‘modulename/modulename_main.php’);

This just tells modulename_init.php to include the modulename_main.php file for use with the above callbacks. I’ll explain the various callbacks in the main pligg architecture and templates later.

modulename_main.php

modulename\_main.php is simple. It’s just a list of functions you can use elsewhere in your module, such as we just mentioned in modulename\_init.php. You can use all the already included globals that have been called from module.php, including $db, $smarty, $user, and others.

modulename_settings.php

This is where you initialize and set all your variables. To define a variable that can be called from $smartyvariables in your custom templates, do something like this:

define(‘modulename_path’, my_pligg_base . ‘/modules/modulename/’);
$main_smarty->assign(‘modulename_path’, modulename_path);

You can really put anything you want in here that you want called before everything else gets called (see where it’s called above).

modulename_install.php

I can see this module being underused to it’s capacity. This module gets included/called when you click “install” or “enable” under modules as God mode under Pligg’s admin section. Most modules just use it to set some critical variables which I will explain in a second, but you could also use it to do things such as add database tables, add your own patches to Pligg, etc. if you really put it to use. I’ll stick to what most people are doing here though, and that’s set critical variables that determine if the module can be installed or not. Most modules have this code in it:

$module_info[‘name’] = ‘My Module Name’;
$module_info[‘desc’] = ‘This is my sample module description’;
$module_info[‘version’] = 0.1;
$module_info[‘requires’][] = array(‘PHP’, 5);

“name” is just your module name listed with all the other modules. “desc” is the description listed with all the other modules. “version” is the version. “requires” is an array of all required elements. I need to research “requires” further though, as I don’t know how it actually works.

modulename_readme.htm

This is just a readme file that gets linked from the list of modules page in admin mode, of which you can put anything about your module for others to see. I recommend listing notes about any special instructions you have for your users, that you know will get asked on the Pligg forums later.

lang.conf

This is exactly the same as your main lang.conf used in the main Pligg architecture. It is a file to specify global variables that you want to access later. I’m not sure if this shows up under language in your Admin or not. You can then call this lang.conf in your custom templates for your module. Just be sure to reload the main lang.conf after your template is finished, or it will overwrite the current lang.conf!

templates

This is your view. Any user interaction with your module should go here. You can add any template, css, or js file in here, so long as you call them from your callbacks listed in modulename\_init.php. I suggest researching template creation for this, and armed with everything listed above you should be able to create something pretty powerful.

Callbacks

Callbacks are what initiate the entire module process. In each main Pligg architecture php and template file are one or more “callbacks”. In the Pligg php files look for the function “check_actions()”. This function has a string in it – that is the name of your callback. When “check_actions” is called, it reads through all the modules and first looks to see if the current “SCRIPT\_NAME” environment variable (minus .php and the leading “/”) is one of those listed in the $include\_in\_pages array. If this is the case and you specified this callback name in your module_add_action call in your modulename_init.php file, it will run the function associated with that call.

For templates, in your main template architecture, look for something like:

{checkActionsTpl location=”tpl_sidebar_top”}

The {checkActionsTpl call works very similar to above. It also triggers a search for all modules looking for the callback name listed in “location=”, and inserts the template specified by that callback name into the location of the checkActionsTpl call. Again, see above to see how the callbacks are called in your module.