So you want to create a mod for SMF but do not know where to really start?

Do not worry, we have all been in that same spot. Hopefully this will give you a basic idea of how to create your first mod that will display the classic "Hello World!" on the screen, wrapped by your SMF header and footer.

Note: These tutorials show you how SMF works, not how to code PHP. If you do not know PHP, please read and complete all of the PHP Tutorials that we have here. You should also use a decent text editor (NOT Dreamweaver or Frontpage) to edit your files.

While this mod will be relatively simple, it will use actions, text strings, source files, and templates.

Let's begin!

We need to open index.php in your main SMF directory and add a new action. We will call this action "hello (all lowercase) and it will load it's own Source file.

Since we like to keep things organized, lets put this action in the index list in alphabetical order, so locate the following code:

'groups' => array('Groups.php', 'Groups'),

	
	'help' => array('Help.php', 'ShowHelp'),
	
	'helpadmin' => array('Help.php', 'ShowAdminHelp'),

We will insert our new action between the "groups" and "help" action.

'groups' => array('Groups.php', 'Groups'),

	
	'hello' => array('Hello.php', 'DisplayHello'),

	
	'help' => array('Help.php', 'ShowHelp'),
	
	'helpadmin' => array('Help.php', 'ShowAdminHelp'),

So what does that mean? Lets break it down... the first part, "hello" is the action. To access this action, we would visit http://yoursite/index.php?action=hello. Actions should always be lowercase for consistencies sake.

The second part, array('Hello.php', 'DisplayHello'), contains two important pieces of information. The 'Hello.php' is the file in the Sources directory that we want to load, and 'DisplayHello' is the name of the function we want to call after opening that file. You can name these whatever you want really, it doesn't make a difference.

Let's create Hello.php. Open your text editor and create a new file and save it as Hello.php in your /Sources directory.

Create an empty function named DisplayHello in that file, so your Hello.php should look like this:

<?php

function DisplayHello()
{

}

?>

We need to create our template file. For consistency, we'll call it Hello.template.php. Create this new empty file in your /Themes/default directory.

Let's create a function in that file named template_hello_world, so your Hello.template.php looks like this:

<?php

function template_hello_world()
{

}

?>

Okay, let's do some real coding now. Let's go back to Hello.php. We need to load our template file we've created so that SMF will be able to find it later, so add the following line to DisplayHello():

loadTemplate('Hello');

We get 'Hello' from Hello.template.php.

Now we need to tell SMF which template function to use (in our case, template_hello_world). To do this we'll need add it to SMF's $context variable. $context is an array that SMF uses to store data that is being passed around to different functions or between the source and template files. First thing that we'll need to do is tell our DisplayHello() function that context is a global variable, so add this to the top of your DisplayHello() function:

global $context;

Now we can set the 'sub_template' key of the $context array to our template function. After the loadTemplate() function call, insert the following:

$context['sub_template'] = 'hello_world';

Notice that we don't include the template_ part of the function name. SMF adds this automatically, so there's no need for you to do it.

So by now, your Hello.php file should look like this:

<?php

function DisplayHello()
{
	global $context;

	loadTemplate('Hello');

	$context['sub_template'] = 'hello_world';
}

?>

Right now if you test your mod you'll just see a blank page with an SMF header and footer (if you got a PHP error, check your code). It's always appropriate to define your text strings in the language files, NEVER in the templates. So let's open up /Themes/default/languages/Modifications.english.php add the following line to it:

$txt['hello_world'] = 'Hello World!';

Save and close that file. If you are using SMF 2.0 and have caching enabled, you will need to clear your file cache for the language strings to take effect. You can do this in Admin > Maintenance > Forum Maintenance > Routine, and it's the last option.

Let's go back to your template file now, Hello.template.php. Since we'll be using the global $txt variable, we need to let the function know it's a global variable. Add the following to the top of your template function:

global $txt;

Now we just need to add one more thing and we should able to see 'Hello World!' displayed to the world. Add an echo statement for the new text string we created:

echo $txt['hello_world'];

So now your template file should look like this:

<?php

function template_hello_world()
{
	global $txt;

	echo $txt['hello_world'];
}

?>

Ok, now visit your new action and you should see 'Hello World!' displayed on the screen

<a href="http://forum/index.php?action=hello" class="bbc_link new_win" target="_blank">http://forum/index.php?action=hello</a>