How to Use Settings and Preferences
The other day I had a administrator over at one of the game sites come to me about a module and this administrator needed to know how to query for the data she needed to display in her module. Fortunately the data she needed to retrieve is easily queried using one of the following functions.
<?php
// get_module_setting();
// get_module_pref();
?>
Today I will go over what these functions are, where you can find them and what exactly they are supposed to do. When I am done, it is my hope you’ll have a better grasp of how and when to use them in your modules. To get started id first like to point out the utility I have setup here to help you get started with your first module or as I expand to help speed up the development process.
Now to get into the nitty gritty, what you need to understand is that both of these functions are only available as part of the library released with the game and you wont be able to use these functions without access to that library. These are both what are known as user defined functions. Each method or function, like any normal function is just code that is encapsulated that you can use repeatedly when programming and an example of this would be the following.
Say we want to multiply a sum by 8 and divide it by 3 for whatever reason.
<?php
$sum = (($sum*8)/3);
?>
We need to repeat this equation 10, 20 or maybe 50 times in our program. Instead of repeating the same equation over and over again we can encapsulate it.
<?php
function total_sum($sum){
return (($sum*8)/3);
}
$sum = total_sum($sum);
?>
As you’d imagine this isn’t the only benefit but the rest is outside the scope of this discussion.
Now as you can see from the examples our function needed what is known as a parameter and our parameter is the sum. Both of the functions we will be discussing today rely on a set of given parameters. Some of these parameters are required and others are optional parameters.
<?php
function get_module_setting($name, $module = false){
}
?>
The function above, as you can see has 2 parameters and the first of those parameters is the name of the module setting. This is the name of the module setting we want to access or retrieve the data for when we call on get_module_setting. The second parameter is our target module and this parameter is optional. Below I will show you two examples of how to use this function.
<?php
$limit = get_module_setting(‘limit’);
?>
This example illustrates how to retrieve the value limit for our module. To better illustrate this point I would like you to refer to the following example.
<?php
function myfirst_getmoduleinfo(){
return array(
‘name’=>‘My First Module’,
‘author’=>‘John Doe’,
‘version’=>‘1.0’,
‘category’=>‘Administrative’
‘settings’=>array(‘My First Module,title’,
‘limit’=>‘My limiy on gems,int|10’
)
);
}
function myfirst_install(){
module_addhook(‘newday’);
return true;
}
function myfirst_uninstall(){
return true;
}
function myfirst_dohook($hookname, $args){
global $session;
switch($hookname){
case ‘newday’:
if (get_module_setting(‘limit’) >= $session[‘user’][‘gems’]){
// Oops, looks like we reached or exceeded our limit.
// Do something exciting here to fix that and possibly become an annoyance.
}
break;
default:
}
return $args;
}
function myfirst_run(){
}
?>
If you get it and I hope you do. We are going to move on now.
<?php
$other = get_module_setting(‘other’, ‘some_module’);
?>
The example above illustrates how to retrieve the value other for another module. If you notice we supplied the second parameter which is our target module. We are getting the value for other from our target module named some_module.
Both of these illustrations should cover the uses of get_module_setting but if you still have questions you can ask and I’ll see what I can do to better elaborate.
Next we will cover the use of get_module_pref and the parameters you can feed this function.
<?php
function get_module_pref($name,$module=false,$user=false){
}
?>
As you can see from the illustration above, get_module_pref requires us to supply the name, module and user for the preference we want to retrieve. Both the name and target module are akin to the same usage as get_module_setting. So just as we discussed before, the same will apply to both of these parameters as both share the same meaning of name and target module as seen in get_module_setting.
The third and additional parameter is optional. This parameter is our target user, we can use this parameter by supplying the users account ID or what you know better as acctid. The acctid is needed to retrieve a target users preference.
<?php
$gems = get_module_ref(‘vault’);
?>
The above example shows us how to retrieve the value of vault for our module.
<?php
$gems = get_module_pref(‘vault’, ‘gemvault’);
?>
The above example shows us how to retrieve the value for vault for a target module.
As I mentioned before, both of those in essence mimic get_module_setting but the exception being the third optional parameter.
<?php
$acctid = 1;
$gems = get_module_pref(‘vault’, ‘gemvault’, $acctid);
?>
This use, shows us how to supply another users acctid to retrieve our target modules preference
By default, this parameter will use the existing sessions account ID and this means for example if you are on this page. Your session contains your acctid and this is used to identify you. So by default it retrieves your acctid but by supplying the third parameter you are able to override the default to retrieve a target accounts preference.
A good example of this might be when viewing a biography and needing to retrieve the value of a preference for the persons biography we are viewing. Refer to the example below to better illustrate this.
<?php
function myfirst_getmoduleinfo(){
return array(
‘name’=>‘My First Module’,
‘author’=>‘John Doe’,
‘version’=>‘1.0’,
‘category’=>‘Administrative’
‘prefs’=>array(‘My First Module,title’,
‘user_myfirst’=>‘My First,bool’
)
);
}
function myfirst_install(){
module_addhook(‘bioinfo’);
return true;
}
function myfirst_uninstall(){
return true;
}
function myfirst_dohook($hookname, $args){
switch($hookname){
case ‘bioinfo’:
$tl_myfirst = translate_inline(“My PvPs”);
$myfirst = get_module_pref(‘user_myfirst’, ‘myfirst’, $args[‘acctid’]);
// Here we are ussing the $args to get our bios acctid
output_notl(“`^%s:`0 `@%s`0”, $tl_myfirst, $myfirst);
break;
default:
}
return $args;
}
function myfirst_run(){
}
?>
I wont be covering sessions, they are outside the scope of this discussion but I’ll consider covering them later.
I have written two examples that you may download below. These examples are public domain and you can use them however you like but both of these examples must be installed at the same time to function properly.
[dl=example_setting_pref.zip]
Unless I am forgetting something, this pretty much covers the topic of how to use both of these functions in your modules and in that case.
Have fun and good luck with your module!
Posted on Thursday, February 5th, 2009 at 2:35pm under Category by admin.
Related Posts
Most Recent