Add a custom action: Difference between revisions From Online Manual

Jump to: navigation, search
No edit summary
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
By the end of this article, you should be able to confidently create a basic action on your forum.
{{TOCright}}
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?===
===What is an action?===
An action is a page off the base of your forum. It is comprised of two files, one is a source file, and the second is a template file.
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 '''<nowiki>index.php?action=search</nowiki>''', SMF will display the search page.  If you add an action called '''youraction''', you will be able to use a URL '''<nowiki>index.php?action=youraction</nowiki>''' 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'''
{{code|1=<nowiki> 'xmlhttp' => array('Xml.php', 'XMLhttpMain'),</nowiki>}}
'''Add After'''
{{code|1=<nowiki> // Your Custom Action
'youraction' => array('YourAction.php', 'YourActionMain'),</nowiki>}}
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===
===Source File===
The source file is the base foundation of the action, it loads the template along with anything else the action might need, such as permissions or additional functions.
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.


===Template File===
=====./Sources/YourAction.php=====
The template file is everything that you see when you go to ?action=youraction, it is defined to the action by the actions source file.
'''Add'''
{{code|1=<nowiki><?php


===Language Strings===
// First of all, we make sure we are accessing the source file via SMF so that people can not directly access the file.
The language strings define text in both the template file, and the source file so they can be edited more easily and also translated to other languages more easily.
if (!defined('SMF'))
die('Hack Attempt...');


===./Themes/default/languages/Modifications.english.php===
function YourActionMain()
'''Add Before End'''
{
<nowiki>// Your Action Language Strings
$txt['your_action'] = 'Your Action';
$txt['page_title'] = 'This is your page title';</nowiki>


===./Themes/default/languages/Who.english.php===
// Second, give ourselves access to all the global variables we will need for this action
'''Add Before End'''
global $context, $scripturl, $txt, $smcFunc;
<nowiki>// Your Action Who String
$txt['whoall_youraction'] = 'Viewing <a href="' . $scripturl . '?action=youraction">Your Action</a>.';</nowiki>


The edit you make in Who.english.php defines the action for the ?action=who page. So people can see what action you are on.
// Third, Load the specialty template for this action.
loadTemplate('YourAction');


Also remember to clear your forums cache or the text strings will not show up.
//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']));




First of all, we need to define the action along with the source file name and function.
//Fifth, define the navigational link tree to be shown at the top of the page.
====/index.php====
$context['linktree'][] = array(
'''Find'''
  'url' => $scripturl. '?action=youraction',
    <nowiki>'xmlhttp' => array('Xml.php', 'XMLhttpMain'),</nowiki>
'name' => $txt['youraction'],
'''Add After'''
);
  <nowiki>// Your Custom Action
  'youraction' => array('YourAction.php', 'YourActionMain'),</nowiki>


[hr]Notes about the first edit: the array that defines actions inside index.php is alphabetically ordered, to keep everything organized, it is smart to label what the code you added was for, and also keep it alphabetically labeled. [quote]'action-in-url' => array('Source-File.php', 'FunctionToCall'),[/quote][hr]
//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';
             
}


Now that we have defined our action, lets create our Source file.
?></nowiki>}}


Create a file in ./Sources named "YourAction.php".
===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.


====./Sources/YourAction.php====
In ./Themes/default, create a file named "YourAction.template.php" with the following contents:
====./Themes/default/YourAction.template.php====
'''Add'''
'''Add'''
<nowiki><?php
{{code|1=<nowiki><?php
 
if (!defined('SMF'))
function template_main()
die('Hack Attempt...');
{
function YourActionMain()
{
// Globalize what we need...
global $context, $scripturl, $txt;
// Load our template
loadTemplate('YourAction');
// Define a page title
$context['page_title'] = $txt['page_title'];
// Define our link tree
$context['linktree'][] = array(
  'url' => $scripturl. '?action=youraction',
  'name' => $txt['your_action'],
);
}
?></nowiki>


[hr]Notes about the source file: first of all, we make sure we are accessing the source file via SMF so that people can not directly access the file. Then, we globalize the variables we need for the main function, load our template, define our page title and our link tree item[hr]
// Make sure we have all the global variables we need
global $context;


Now that we have our action defined, and a source file for our base, lets work on our template file.
// Catbg header
echo '<div class="cat_bar">
  <h3 class="catbg">', $context['youraction_Head'], '</h3>
</div>';


Go to ./Themes/default and create a file named "YourAction.template.php".
// 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 />';


Once created, complete the following edit.
}


===./Themes/default/YourAction.template.php===
?></nowiki>}}
'''Add'''
 
<nowiki><?php
===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.
function template_main()
 
{
====./Themes/default/languages/Modifications.english.php====
'''Add Before End'''
// Globalize what we need...
{{code|1=<nowiki>// Your Action Language Strings
global $txt;
$txt['youraction'] = 'Your Action';
$txt['youraction_PageTitle'] = 'This is your page title';</nowiki>}}
// Catbg header
 
echo '<div class="cat_bar">
====./Themes/default/languages/Who.english.php====
    <h3 class="catbg">', $txt['your_action'], '</h3>
'''Add Before End'''
</div>';
{{code|1=<nowiki>// Your Action Who String
$txt['whoall_youraction'] = 'Viewing <a href="' . $scripturl . '?action=youraction">Your Action</a>.';</nowiki>}}
// Windowbg2 Content
 
echo '<div class="windowbg2">
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.
  <span class="topslice"><span></span></span>
 
    <div class="content">Your Page Content</div>
===Finally===
  <span class="botslice"><span></span></span>
Once you have put all these pieces in place, clear your forum's cache to force the new/changed text strings into the cache.
</div><br />';
 
Remember -- you have not yet created a new menu button/navigational tab for your new action.
}
?><nowiki>


Now our action should be accessible and working correctly, except no text will be showing, so lets define the strings we used.
===Alternative methods===
[[Add a custom action using integration_hooks]]


Another optional edit would be to add a navigation tab for it. Take a peak at the document on adding tabs to do that.
[[Category:Customization tips and tricks]]
[[Category:Developing SMF]]
[[Category:Developing Mods]]

Latest revision as of 15:33, 27 July 2014

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



Advertisement: