Quick guide to modding SMF for YaBBSE users

[Grudge]

Note: This is only a first draft of this document so it may not be 100% correct in all places but should hopefully be a good starting point.

Nowhere is the difference between SMF and YaBBSE more apparent than when, as a modder, you first open up the sources file. SMF is a very different beast than YaBBSE and for most people it will take some time to adapt to the new coding style, functions and probably most importantly the template system. This guide is intended as a quick "introduction" to coding for SMF and is aimed at those with experience in YaBBSE although it should be useful to anyone starting to code for SMF.
Probably the first thing that is noticeable when installing SMF is the "Themes" directory that has appeared in the archive, and the fact that almost all files in the Sources directory have a corresponding file in the default sub-directory of Themes. In YABBSE all output of data to the screen was handled in the source file itself. No longer is this the case – in fact, except in a few *exceptional* circumstances, all echo'ing of data should appear in the template of a function. Equally, no database queries or processing of data should appear in the template of a function, instead that should always be part of the source files. The reason for this is clear, by providing a template with only the minimal amount of code in it, most users will be able to adapt the template easily without being confused by the sheer amount of code/queries around it. Whenever coding new features into SMF it is important to appreciate the importance of this. So how do you get variables into the template? How do you assign a template? This is where the new (and soon to be very familiar to you) variable, $context comes in.
$context is an array which should contain all the data that is needed as part of the template, and as such is often found as a global variable. Below I'm going to show a small example of a very basic function, with the main function "Hello" in the sources file, and it's template in the Themes/default folder:

Sources:

Code Select Expand


function Hello()
{
global $context, $user_info, $txt;

LoadTemplate('Display');
LoadLanguage('Help');

$context['page_title'] = $txt['hello_title'];
$context['sub_template'] = 'hello';

$context['my_message'] = 'Hello' . $user_info['name'];

obExit();
}


Themes/default:

Code Select Expand


function template_hello()
{
global $settings, $options, $context;

echo '
<span class="smalltext">', $context['my_message'], '</span>';
}


Now, Don't worry about some of the things in the sources file – I'll come back to that, the important thing is what is happening to $context. Here is a list of what is happening when Hello() is called:
1)   The template 'Display' is loaded. This effectively includes the file "Display.template.php" from the default template directory.
2)   The language file 'Help.language.php' (Where language is the users language) is included.
3)   The page title for the page is set by assigning a value to $context['page_title']. Note that this effectively replaces $yytitle from YaBBSE.
4)   The sub-template is defined. If no sub-template  is defined the template used will be called template_main in whichever template file is included. As we want to use a different template we set $context['sub_template'] to 'hello'. This means that on exit the function 'template_hello' will be called in the Display.template.php file.
5)   We assign a value to $context['my_message']. $context['my_message'] isn't a reserved value like page_title and sub_template are and as such the element is created, and in this case contains Hello USERNAME, where USERNAME is the users username.
6)   Up to this point NOTHING has been sent to the screen. Finally obExit is called, this is the "send to template" function if you will, and effectively calls the template then exits (it's a bit more involved that that but that's what it basically does!). Now obExit is called it's the templates turn to execute. It runs through and echo's out everything.

Now, this example is very basic and is only intended as a simple example of how to use the template system, Look at display.php and display.template.php for better examples of how much simpler the template system makes development and user changes. In all the examples above I always referred to the template files being in the 'Themes/default' directory – this is not always the case but this is the *default* theme that users will have installed. Many users will create their own themes and some of the more 'popular' template files may exist elsewhere – but as developers we should be more concerned with modifying the default files as it is impossible to predict what individual users may do.

Anyway – that was a long introduction to the Themes, but alas it is the biggest hurdle to overcome before you can start modding SMF. I'm now going to list some simpler changes between YABBSE and SMF which are essential to development and some important functions.

Globals:
•   $user_info. This is an array that is loaded every page load and filled with a variety of member details. These include 'email', 'username' and more simple elements. However, it contains some other important elements. 'ID_GROUPS' is an array containing all the groups that this member is a member of. 'is_guest' is set if the member is actually a guest. 'is_admin', 'is_moderator' represent other permissions. This is effectively a replacement to the old YaBBSE $settings array, $settings in SMF are a *very* different array.
•   $db_prefix. Same as YaBBSE, it's the prefix (database name and table prefix) for the forum tables.
•   $txt. As before this represents entries found in language files.
•   $modSettings. This is an array of all the settings set in the admin center under "Feature Settings and Options" and is basically the same as it was in YaBBSE (the principle is).
•   $settings. This is an array containing "theme specific" global options. Basically, it is similar to $modSettings, but on a theme by theme basis. Each theme in SMF can have different sets of options (such as "display search button on main menu"). Instead of these being loaded into $modSettings they are loaded into $settings, and these can change depending on which theme a user is using.
•   $options. This is the same as for $settings except it contains settings the *user* has chosen specific to the theme and not that the admin has chosen.
•   $ID_MEMBER. As YaBBSE – To check for a guest should always use $user_info['is_guest'].
•   $board, $topic are both global variables for the board ID and topic ID respectively, a note on passed variables is below.

Note:
$board and $topic are two of very few variables that are automatically converted to global variables when passed to the script. In YaBBSE you could pass a variable to a script and expect it to be converted into a global variable – in SMF all passed variables are found in the $_GET, $_POST and $_REQUEST variables ($_REQUEST is a combination of the two). $HTTP_POST_VARS and the like are no longer used, this goes for server variables too (replaced with $_SERVER). So, if for example, you pass 'card' through to a script as a 'get' variable you access it by either $_GET['card'] or $_REQUEST['card'].

Functions:
•   LoadTemplate. As mentioned before this will included a template file. It will first look for a template file in the users current theme directory, if the file is not found in there it will look for it in the default directory.
•   LoadLanguage. English.lng, german.lng etc are all DEAD. The language files are now split up into various bits and should be loaded as needed. LoadLanguage will include the passed language file in the current users language from their current theme directory, or, if it doesn't exist, from the default theme directory. If you forget to call this you will find you will get invalid index errors on $txt elements.
•   Is_admin(). As in YaBBSE when this is called, if the user is not an admin they get thrown an error and can't progress any further.
•   allowedTo(). This function is passed a permission name (for example allowedTo('read_pms'). If the user has this permission set the function will return true, otherwise it will return false.
•   isAllowedTo(). As above but this will not let the user pass this function if they don't have the permission (It will throw an error).
•   fatal_error(). This should be parsed some error text and will stop execution displaying this text. (ie Fatal_error("You can't get here")).
•   db_query, db_affected_rows. These should be used instead of mysql_query / mysql_affected_rows. db_query takes three parameters, the query and then error reporting parameters. Most queries will look like: db_query("SELECT * FROM {$db_prefix}tablename", __FILE__, __LINE__);
•   query_see_boards(). This function should be used whenever getting a board listing as it will only list boards people have permissions to see.
•   LoadTheme(). Loads a themes settings and is generally automatically called.
•   Redirectexit(). As in YaBBSE redirects the script to the parsed url.

In addition *many* useful loading functions are available in Load.php for loading user information. I recommend that everyone plays around with the permissions system to get an idea of how it works as it is another feature central to SMF, and without having an understanding of it you could risk leaving any features you write wide open to security issues.

Things that are gone:
$yyim, $yymain etc etc. The template is now all in index.template.php as a set of php code defining the headers and footers of the forum – the rest is filled in by the templates.
template.php – replaced by all the templates.
Language.lng – replaced by all the text files.
Many variables from Settings.php  Put in the database.
YaBBImages – replaced by the images directory off themes. Note the images directory is accessed by $settings['images_dir']

Coding formatting. When writing your code please try and stick to formatting conventions already used by SMF. The code is much tidier than YaBBSE and by keeping mod code tidy it will be easy for people to troubleshoot your code. Always use the theme system where appropriate, you will only run into difficulties if not.

Sub Actions. Many actions in SMF are actually sub actions of another action – indicated by being passed 'sa'. An example of this is the personal message center where there is only on action 'pm', yet many sub actions for inbox, deleting etc. This is done for code reuse and efficiency.

I hope this is useful to people – I've tried to keep it short and of course there are many things missing but I hope it helps ease people into the new code and understand the systems SMF puts in place. In addition it should be noted that the source files included in SMF generally have documentation included at the top of each file explaining each function in the file and should be helpful for anyone trying to work out what a function does.

[Oldiesmann]

Very useful Grudge. Thanks!

[timkenmaster]

Very Usefull, Thanks!  I kind of got overwhelmed when I first looked at the source files and template files, but it makes a little more sense now!  I still need some practice!