[WIP] Adding New Modification Settings for SMF 2.0

Started by Windy, November 26, 2009, 11:37:40 AM

Previous topic - Next topic

Windy

I've done up this little guide in order to assist people to help them understand how they should go about adding new mod settings for their mods.  It is a WIP and I am of course open to suggestions on how I can improve it.




What are mod settings?
Mod settings are global mod defined settings that can be used by mods and can also be modified easily by the administrators of the board through a pre-defined interface that SMF provides. In order to access these global settings one only needs to add "$modSettings" using the global keyword to be able to access these settings within their functions.



Adding a mod setting to the database
Before a mod setting can be used it must first be added to the database, this would normally done when executing the database code on installation.


global $modSettings;

// Add your mod setting to the database
if(!isset($modSettings['my_mod_setting']))
$smcFunc['db_query']('', '
INSERT INTO {db_prefix}settings
VALUES ("my_mod_setting", "my value")',
array()
);


This is how I add mod settings to the database when I go to execute my database code on installation.  I use the global keyword so I can access the global $modSettings variable within our scope of execution and then I check to see if the setting has been set, if the setting already exists within the database then it would be set here, otherwise it'll execute the insert query to add my mod setting to the database, keep in mind that while the mod setting will contain a string value to choose a value appropriate for the data type that you want the setting to be.

When choosing the names for mod settings I recommend using a standard prefix to avoid collisions with other mods that may end up using the same name.



Adding a Miscalleneous Mod Setting
One of the new features of SMF 2.0 is that it introduces a new section where mod settings are stored.  In the condition where your mod doesn't use a lot of settings I recommend putting it in the miscalleneous setting category which can be accessed under Configuration > Modification Settings... in the Admin Section.

The settings for this are stored within ManageSettings.php in the Sources directory.  Within the file you will find the following array within the ModifyGeneralModSettings function.


$config_vars = array(
// Mod authors, add any settings UNDER this line. Include a comma at the end of the line and don't remove this statement!!
);


As you can see above all mod settings should be added under that line above, the format for each mod setting is an array with the following format.  I've added comments to help explain what each element within the array is for.


array(
'int', // the data type of the settings, may be one of (int, float, text, large_text, check, select)
'name_of_setting', // the name of the setting for the code I posted above the name would be for example, 'my_mod_setting'
6, // size of the text field, by default for floats and integers the size is 6 and 0 for anything else
'label to use' // the label to use for the field, to determine the label, by default it will first check for the key 'text_label', if that hasn't been set then it will check for the variable $txt['name_of_setting'] and then if that isn't set then it will check for the 4th key in the array as seen here
'preinput' => 'for input you want before the input element',
'postinput' => 'for input you want after the input element',
);


(I am aware there are a few more options but I'm not to sure what those are)



Adding a New Mod Setting Section
Adding a new section is done in the ModifyModSettings function within ManageSettings.php, all new sections are added in the $subAction array as seen here.


$subActions = array(
'general' => 'ModifyGeneralModSettings',
// Mod authors, once again, if you have a whole section to add do it AFTER this line, and keep a comma at the end.
);


If you haven't already guessed the format of this array, the key represends the area eg. index.php?action=admin;area=modsettings;sa=general and the string value it contains "ModifyGeneralModSettings" is the name of the function that is executed.

I recommend keeping the key short and simple.  Generally what I do when I add a new function is use the ModifyGeneralModSettings function as a base and strip out the unnecessary contents like so.  For consistency I'll give the following parts I've put in bold the same key name I used in the sub action array.


function ModifyGeneralModSettings($return_config = false)
{
global $txt, $scripturl, $context, $settings, $sc, $modSettings;

$config_vars = array(
);

if ($return_config)
return $config_vars;

$context['post_url'] = $scripturl . '?action=admin;area=modsettings;save;sa=general';
$context['settings_title'] = $txt['mods_cat_modifications_misc'];

if (isset($_GET['save']))
{
checkSession();
saveDBSettings($config_vars);
redirectexit('action=admin;area=modsettings;sa=general');
}

prepareDBSettingContext($config_vars);
}


Just as an example, if I used the key name 'example' I would lay it out like the following:


function ModifyExampleModSettings($return_config = false)
{
global $txt, $scripturl, $context, $settings, $sc, $modSettings;

$config_vars = array(
);

if ($return_config)
return $config_vars;

$context['post_url'] = $scripturl . '?action=admin;area=modsettings;save;sa=example';
$context['settings_title'] = $txt['mods_cat_modifications_example'];

if (isset($_GET['save']))
{
checkSession();
saveDBSettings($config_vars);
redirectexit('action=admin;area=modsettings;sa=example');
}

prepareDBSettingContext($config_vars);
}




Adding a New Tab to the Modification Settings Section
Now if you've noticed above when adding this code that this doesn't add a new tab within the Modification Settings Section and it doesn't add the option to the drop down menu.  This is because it is an entirely separate process within the ManageSettings.php in the ModifyModSettings function.

The array containing the tabs will look something like this.


$context[$context['admin_menu_name']]['tab_data'] = array(
'title' => $txt['admin_modifications'],
'help' => 'modsettings',
'description' => $txt['modification_settings_desc'],
'tabs' => array(
'general' => array(
),
),
);


Using the same key above 'example', to add a new tab you simple do it like so, if you have set $txt['mods_cat_modifications_example'] within the language file, then that's the title that will be used for the tab.


$context[$context['admin_menu_name']]['tab_data'] = array(
'title' => $txt['admin_modifications'],
'help' => 'modsettings',
'description' => $txt['modification_settings_desc'],
'tabs' => array(
'general' => array(
),
'example' => array(
// 'label' => 'Example', // you can use the key 'label' to forcefully set the label, although it is recommended to set $txt['mods_cat_modifications_example'] within your language files.
),
),
);




Adding a New Drop Down Option to the Modification Settings Section
If you've done the above you should notice a new tab when you go the the Modification Settings... Section, but what you may also notice is that it doesn't appear when you hover over Modification Settings... on the Drop Down menu.

Adding Drop Down Menu options is done in the Admin.php file within the sources directory under the AdminMain function.  Scrolling down eventually you'll get to a section that looks like this,


'modsettings' => array(
'label' => $txt['admin_modifications'],
'file' => 'ManageSettings.php',
'function' => 'ModifyModSettings',
'icon' => 'modifications.gif',
'subsections' => array(
'general' => array($txt['mods_cat_modifications_misc']),
// Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
),
),


This is the section responsible for adding additional drop down options to the Modification Settings... menu item. Using the same format as above this is how you add a new option to the Modication Settings... sub menu.


'modsettings' => array(
'label' => $txt['admin_modifications'],
'file' => 'ManageSettings.php',
'function' => 'ModifyModSettings',
'icon' => 'modifications.gif',
'subsections' => array(
'general' => array($txt['mods_cat_modifications_misc']),
'example' => array($txt['mods_cat_modifications_example']),
// Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
),
),
All unsolicited PM's will be ignored.  Any support requests should go in their topics.

My Mods


Image Zoom Tag
Image Quote Removal
Color Picker
Additional Polls
Simple Awards System

Mods are only updated to the latest same major version of smf on request.

Arantor

Nice guide!

Just to add, ideally mod settings, if you're going to set them up at install, updateSettings is the best way to do it. Failing that, if you are going to insert rows into 2.0, please consider using $smcFunc['db_insert'] which is specifically geared for inserting on multiple DB backends, and also supports what is effectively REPLACE INTO syntax (even on PostgreSQL)

You don't have to set them up at all on install, in which case liberal use of !empty($modSettings['your_setting']) will be key.

Mave

There is a problem by use this rules to add mods

I try to explain this sometimes

it cause problems by install and uninstall the mods in admin.php and ManageSettings.php

Example admin.php
Install first mod

use this code
<file name="$sourcedir/Admin.php">
    <operation>
       <search position="before"><![CDATA[
// Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
]]></search>
       <add><![CDATA[                                                'example1' =>array($txt['admin_menu_value']),]]></add>
    </operation>


the result
                                      // Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
'example1' => array($txt['example1']),


Install next mod
use this code
<file name="$sourcedir/Admin.php">
    <operation>
       <search position="before"><![CDATA[
// Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
]]></search>
       <add><![CDATA[                                                'example2' =>array($txt['admin_menu_value']),]]></add>
    </operation>


the result
                                      // Mod Authors for a "ADD AFTER" on this line. Ensure you end your change with a comma. For example:
// 'shout' => array($txt['shout']),
// Note the comma!! The setting with automatically appear with the first mod to be added.
'example1' => array($txt['example1']),
'example2' => array($txt['example2']),


Now i can´t uninstall the first mod without error and not full uninstall.

this cause ab big problem
now i cant update mods by uninstall old and install new, without uninstall all mods after and loose the configurations.

does somebody have an idea like this problem is to be solved?



Arantor

There isn't a way around it, except to remove the second mod first - or you find somewhere else or some other way to add the code.

navarretemarce

Quotedoes somebody have an idea like this problem is to be solved?

No idea, but what about setting up a custom uninstall file, searching only for the line that your mod added and then deleting only this?
Would work?


Carceri

I followed this guide for adding some settings for my mod. Since it's only a few settings, I added them under the miscalleneous settings.

However, there seems to be a problem, which I have narrowed down to $modSettings not being updated with the new values. The new settings are written to the database, but the $modSettings variable still holds the old values. All my options are 'select' boxes, so I am not sure if this applies to other types as well. This also means that as soon as I press save, the screen refreshes with the old values selected (since apparently it uses $modSettings to determine the current values).

Any fix for this, or am I doing something wrong. I have tried disableling xcache on my server, as I thought it might be a caching problem, but that didn't change anything.

shamun

As this is very helpful for mod making, it deserves a bump.

Also, I ran into a slight issue, but resolved.  When adding a new area (not just under "misc") and you can't manage to get the label to show/try to force a label/not show as active its because you haven't finished!  When adding a new section you need to follow the steps from: Adding a New Mod Setting Section, Adding a New Tab to the Modification Settings Section, and Adding a New Drop Down Option to the Modification Settings Section.  If you don't then the label will not show up.  If you force a label then even though the text shows, it won't receive that orange highlight showing its the active tab.
It's not very apparent that you require the drop-down to be populated for the tab to be as well.

Deprecated

Is this topic obsolete? It's all I can find on Google and the information looks like several years out of date.

Aren't we supposed to be using hooks to add this stuff?

Advertisement: