Enough core editing, start module making!

[longcountdown]

I have around 650 members on my site. It's a good community with thousands of comments posted since its launch in January. As such, I get a lot of user feedback.

In response to one member who questioned why his comments were vanishing (that's another story), I replied:

I'm trying to upgrade JapanSoc to the latest version on a test site, but it's incredibly difficult. To put it in perspective, imagine if every plugin and theme change on a Wordpress site required you to edit core Wordpress files, and then when you upgrade, you have to do all those edits again and "hope" it all still works. That's what Pligg is like.

Some examples of the modifications I'm using are: Displaying saved stories in the sidebar, Enable admin to killspam from a user's profile, Extended user profiles and Email notification for comments.

When you browse the forum, there are hundreds of requests for new features, and almost all of them require the editing of core files. As it stands, these modifications are essential for creating a unique Pligg site. However, would it not be better to stop editing the core, put in some hooks, and focus on writing modules instead?

Where can we learn about making modules? How do hooks in Pligg work?
Update: I found this Building Modules wiki entry which isn't a bad start.

I'd like to see the Pligg community rally together to "get out of the core". Not only would this make upgrading far easier, but it would allow the more experienced developers to work on security and upgrades to the core files, while the rest of us can create our own modules and templates to share with each other. What are your thoughts on this?

[longcountdown]

Since I made a speech about how we should make modules, I figured I should learn the basics and try myself. I decided to make a little module that shows a message on the screen. It took me a crazy four hours of trial and error before I got it working, but here it is. I may have made mistakes, but hopefully some people will find this useful.

The show_message module

I started by copying the agree_to_terms folder and renaming it "show_message". I then stepped through the module-making process as logically as I could, renaming the files to show_message as I did so...

1. Put a hook in my Pligg template

At the bottom of my templates/my_template/header.tpl file (maybe different for you), I put a hook - the thing that attaches the module to the rest of Pligg.

{checkActionsTpl location="tpl_show_message"}

2. modules/show_message/show_message_settings.php

I edited everything in the agree_to_terms settings file with "show_message", resulting in this:

<?php

define('show_message_path', my_pligg_base . '/modules/show_message/');
define('show_message_lang_conf', '/modules/show_message/lang.conf');
define('show_message_tpl_path', '../modules/show_message/templates/');

define('show_message_lib_path', './modules/show_message/libs/');

define('show_message_img_path', './modules/show_message/images/');


// don't touch anything past this line.

if(isset($main_smarty) && is_object($main_smarty)){
	$main_smarty->assign('show_message_path', show_message_path);
	$main_smarty->assign('show_message_lang_conf', show_message_lang_conf);
	$main_smarty->assign('show_message_tpl_path', show_message_tpl_path);
	$main_smarty->assign('show_message_lib_path', show_message_lib_path);
	$main_smarty->assign('show_message_img_path', show_message_img_path);
}

?>

3. modules/show_message/show_message_init.php

It took me a while to figure this one out. I eventually came up with this:

<?php
if(defined('mnminclude')){
	
	include_once('show_message_settings.php');

	// tell pligg what pages this modules should be included in
	// pages are <script name> minus .php
	// index.php becomes 'index' and upcoming.php becomes 'upcoming'

	$include_in_pages = array('all');
	$do_not_include_in_pages = array();
		
	if( do_we_load_module() ) {		
		module_add_action_tpl('tpl_show_message', show_message_tpl_path . 'show_message.tpl');
		// include_once(mnmmodules . 'show_message/show_message_main.php');

	}
}
?>

It looks like the purpose of module_add_action_tpl is to display a template file when called. The tpl_show_message bit is the name I gave the hook in my template, and the rest is the path set in the settings file.

Note that I commented out the line that includes show_message_main.php because there aren't any functions in this module.

4. modules/show_message/show_message_main.php

Since I didn't need any functions, my "main" file looked like this:

<?php
	
function show_message() {
		global $main_smarty;
	}
?>

5. modules/show_message/lang.conf

This seemed like a good place to put the message.

//<SECTION>Show Message</SECTION><ADDED>0.1</ADDED>
PLIGG_SHOW_MESSAGE_Text = "Hello World!"

6. modules/show_message/templates/show_message.tpl

This is the stuff that actually gets shown. First, I had to include the lang file I just edited, then show the text.

{config_load file=show_message_lang_conf}
{#PLIGG_SHOW_MESSAGE_Text#}
{config_load file="/languages/lang_".$pligg_language.".conf"}

That last line was the only way I could tell Pligg that "I've finished with my homemade lang file, you can go back to the one you usually use now". Without that line, anything beyond my hook wouldn't show. Note that I nabbed that last line from the top of my pligg.tpl template, and it's from .9.9.5.

7. modules/show_message/show_message_install.php

Before uploading everything, I had to edit the install file. This is what it looked like:

<?php
	$module_info['name'] = 'Show Message';
	$module_info['desc'] = 'Displays a message on the screen.';
	$module_info['version'] = 0.1;

?>

8. modules/show_message/show_message_readme.html

<h2>Show Message v0.1</h2>
<strong>Created by:</strong> Nick Ramsay (longcountdown)<br>
<strong>Created on:</strong> 2008/8/11<br>
<strong>Requires:</strong> None

<h3>Description</h3>
Displays a message on the screen.<br />

To change the message, edit lang.conf in this module's folder.<br/>

<h3>Installation</h3>
Upload the show_message folder to /modules.<br />
Install through the Module Management section of your admin panel.<br />
Add the following in one of your template files, in the place you want the message to appear:<br />

<blockquote>{checkActionsTpl location="tpl_show_message"}</blockquote>

<h3>Revision History</h3>
v0.1 2008/8/11 longcountdown - First version<br />

9. Upload everything and test

I uploaded the module folder first, then installed it through the admin panel. After that, I uploaded my header.tpl file, refreshed the page and my little message appeared! (see attachment).

I've also attached the module itself if you'd like to play with it. Of course, it's easier to type the message directly into your template file than use a module, but this is just an experiment in module-making, and I hope I can expand on this as I learn how things work. The important thing is, I didn't touch the core files!

[catchpen]

Good tut thanks for taking the time to figure it out!