Add a custom action: Difference between revisions From Online Manual

Jump to: navigation, search
(grammar, addded some more explanation, demonstrated use of $context for content.)
Line 1: Line 1:
{{TOCright}}
{{TOCright}}
By the end of this article, you should be able to confidently create a basic action on your forum.
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.


===/index.php===
===Changes to /index.php===
First of all, we need to define the action along with the source file name and function.
First of all, we need to define the action along with the source file name and function.


Line 14: Line 16:
'youraction' => array('YourAction.php', 'YourActionMain'),</nowiki>}}
'youraction' => array('YourAction.php', 'YourActionMain'),</nowiki>}}


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.
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.
{{code|1=<nowiki>'action-in-url' => array('Source-File.php', 'FunctionToCall'),</nowiki>}}
 
===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.


Create a file in ./Sources named "YourAction.php".
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=====
=====./Sources/YourAction.php=====
Line 26: Line 26:
{{code|1=<nowiki><?php
{{code|1=<nowiki><?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'))
if (!defined('SMF'))
die('Hack Attempt...');
die('Hack Attempt...');
Line 32: Line 33:
{
{


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


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


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


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


//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';
             
}
}


?></nowiki>}}
?></nowiki>}}
Notes: 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
===Template File===
===Template File===
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.
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.
 
Go to ./Themes/default and create a file named "YourAction.template.php".
 
Once created, complete the following edit.


In ./Themes/default, create a file named "YourAction.template.php" with the following contents:
====./Themes/default/YourAction.template.php====
====./Themes/default/YourAction.template.php====
'''Add'''
'''Add'''
Line 66: Line 70:
{
{


// Globalize what we need...
// Make sure we have all the global variables we need
global $txt;
global $context


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


Line 77: Line 81:
echo '<div class="windowbg2">
echo '<div class="windowbg2">
   <span class="topslice"><span></span></span>
   <span class="topslice"><span></span></span>
     <div class="content">Your Page Content</div>
     <div class="content">$context['youraction_Body']</div>
   <span class="botslice"><span></span></span>
   <span class="botslice"><span></span></span>
</div><br />';
</div><br />';
Line 86: Line 90:


===Language Strings===
===Language Strings===
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.
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====
====./Themes/default/languages/Modifications.english.php====
'''Add Before End'''
'''Add Before End'''
{{code|1=<nowiki>// Your Action Language Strings
{{code|1=<nowiki>// Your Action Language Strings
$txt['your_action'] = 'Your Action';
$txt['youraction'] = 'Your Action';
$txt['page_title'] = 'This is your page title';</nowiki>}}
$txt['youraction_PageTitle'] = 'This is your page title';</nowiki>}}


====./Themes/default/languages/Who.english.php====
====./Themes/default/languages/Who.english.php====
Line 99: Line 103:
$txt['whoall_youraction'] = 'Viewing <a href="' . $scripturl . '?action=youraction">Your Action</a>.';</nowiki>}}
$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.
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.
 
Also remember to clear your forums cache or the text strings will not show up.


===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.


Another optional edit would be to add a navigation tab for it. Take a peak at the document on adding tabs to do that.
Remember -- you have not yet created a new menu button/navigational tab for your new action.


===Alternative methods===
===Alternative methods===

Revision as of 13:43, 19 September 2011

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, youractioncalls 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;

	// 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['your_action'],
	);

	//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: