Add a custom action

This article explains how to add an action to your forum by editing index.php. This is the method used to add actions in SMF 1.1.x. It requires editing index.php, adding a file in the Sources directory, and adding a file in the Themes directory. In order to make your action easily translatable into other languages, you will need to add language strings, which you will use in making up your new page.. If you want the "whois" display to show when users and guests are using this new action, you must also add a string to Who.<language..php.

If you are using SMF 2.0, it is best to add a custom action using integration_hooks instead.

What is an action?

In SMF, an action mean some feature of the forum that is executed when the URL contains the query parameter action. Which action is executed is determined by the value of the action parameter. For example, if the URL contains index.php?action=search, SMF will display the search page. If you add an action called youraction, you will be able to use a URL index.php?action=youraction to see that feature.

Changes to /index.php

First of all, we need to define the action along with the source file name and function.

Find

	'xmlhttp' => array('Xml.php', 'XMLhttpMain'),

Add After

	// Your Custom Action
	'youraction' => array('YourAction.php', 'YourActionMain'),

The SMF developers made sure to organize the action array in alphabetical order (English). When you add a new element, insert it in the proper alphabetical order, and use a comment to label the addition. This will make it easier to keep track of all the actions added by different mods and customizations.

Source File

The source file contains everything necessary to make the new action happen, except for the code to actually write the HTML to the document (please read more about separating calculation from display in SMF). The source file does load the appropriate template for the action.

In this example, youraction calls a function YourActionMain in the file YourAction.php. To make this work, you'll need a file called YourAction.php in the ./Sources directory.

./Sources/YourAction.php

Add

<?php

// First of all, we make sure we are accessing the source file via SMF so that people can not directly access the file. 
if (!defined('SMF'))
	die('Hack Attempt...');

function YourActionMain()
{

	// Second, give ourselves access to all the global variables we will need for this action
	global $context, $scripturl, $txt, $smcFunc;

	// Third, Load the specialty template for this action.
	loadTemplate('YourAction');

	//Fourth, Come up with a page title for the main page
	$context['page_title'] = $txt['youraction_PageTitle'];
	$context['page_title_html_safe'] = $smcFunc['htmlspecialchars'](un_htmlspecialchars($context['page_title']));


	//Fifth, define the navigational link tree to be shown at the top of the page.
	$context['linktree'][] = array(
  		'url' => $scripturl. '?action=youraction',
 		'name' => $txt['youraction'],
	);

	//Sixth, begin doing all the stuff that we want this action to display
	//    Store the results of this stuff in the $context array.  
	//    This action's template(s) will display the contents of $context.
	$context['youraction_Head'] = $txt['youraction'];
	$context['youraction_Body'] = 'Hello World';
              
}

?>

Template File

The template file takes the information you have stored in $context and actually generates the HTML that the user will see. In SMF, none of the HTML is written to the page until after all the calculations are completed. The template file for an action is specified by the action's source file, in the loadTemplate call.

In ./Themes/default, create a file named "YourAction.template.php" with the following contents:

./Themes/default/YourAction.template.php

Add

<?php

function template_main()
{

	// Make sure we have all the global variables we need
	global $context;

	// Catbg header
	echo '<div class="cat_bar">
   			<h3 class="catbg">', $context['youraction_Head'], '</h3>
	</div>';

	// Windowbg2 Content
	echo '<div class="windowbg2">
  			<span class="topslice"><span></span></span>
  		  		<div class="content">', $context['youraction_Body'], '</div>
  			<span class="botslice"><span></span></span>
	</div><br />';

}

?>

Language Strings

The language strings define text used in the source and/or template files. These language strings are stored in language files. The correct language file is loaded for each forum or user. This means that you can supply one version of the source code, and depend on the language files to translate your output into every different language.

./Themes/default/languages/Modifications.english.php

Add Before End

// Your Action Language Strings
$txt['youraction'] = 'Your Action';
$txt['youraction_PageTitle'] = 'This is your page title';

./Themes/default/languages/Who.english.php

Add Before End

// Your Action Who String
$txt['whoall_youraction'] = 'Viewing <a href="' . $scripturl . '?action=youraction">Your Action</a>.';

As soon as you define the whoall_ text string, you make it possible for members to see when other forum users are using your action.

Finally

Once you have put all these pieces in place, clear your forum's cache to force the new/changed text strings into the cache.

Remember -- you have not yet created a new menu button/navigational tab for your new action.

Alternative methods

Add a custom action using integration_hooks