The vB Geek

The vB Geek (http://www.thevbgeek.com/index.php)
-   Tutorials (http://www.thevbgeek.com/forumdisplay.php?f=12)
-   -   GARS: Module making 102 (http://www.thevbgeek.com/showthread.php?t=1157)

The Geek 02-22-2006 08:00 PM

GARS: Module making 102
 
In the 101 tutorial, I showed a very brief, easy way to add custom field capturing to GARS. In this version, I build off of the example given and create a slightly more sophisticated version to show off a couple more stages.

In this version of the Movie rating pull down box, I add the ability for the admin to select which ratings to show in the pull down box via the Settings stage and the persist settings stage. I am assuming you have already read the 101 tutorial!

Please note that this is not exactly how I would approach this, its just meant to try and be a guide that should be semi easy to follow.

Make sure you clean the input!

Here is the 102 completed code:
PHP Code:

<?php
 
if ($stage == "settings")
    {
     
print_description_row("This module will allow users to select a rating for the movie");
        if (
$settings['my_rating_settings'])
        {
         foreach(
$settings['my_rating_settings'] as $key => $value)
            {
             if (!
$keys)
                {
                 
$keys ="$key";
                    
$texts "$value";
                }
                else
                {
                 
$keys .=",$key";
                    
$texts .= ",$value";
                }
            }
        }
        
print_input_row("Ratings:<dfn>Enter each rating letter seperated by a comma (i.e. G,PG,R)</dfn>""my_rating_keys[$itemid]"$keys);
        
print_input_row("Text:<dfn>Enter each rating description seperated by a comma (i.e. G - General,PG - Parental Guidance</dfn>""my_rating_text[$itemid]"$texts);
    }
    elseif (
$stage == "persistsettings")
    {
        global 
$vbulletin;
        
$vbulletin->input->clean_array_gpc('p',array(
         
'my_rating_keys'  =>  TYPE_ARRAY_ARRAY_STR,
            
'my_rating_text' => TYPE_ARRAY_ARRAY_STR
        
));
        
$keys $vbulletin->GPC['my_rating_keys'][$itemid];
  
$text $vbulletin->GPC['my_rating_text'][$itemid];
        
$keyarray explode(",",$keys);
        
$textarray explode(","$text);
        
$results = array();
        if (
is_array($keyarray))
        {
         foreach(
$keyarray as $itemkey => $itemvalue)
            {
             
$results[$itemvalue] = $textarray[$itemkey];
            }
        }
        
$settings['my_rating_settings'] = $results;
    }
    elseif (
$stage == "edit")
    {
        
$items $settings['my_rating_settings'];
        if (
is_array($items))
        {
         
$output .= "Rating: <SELECT name=\"custom1[my_rating]\">";
            foreach(
$items as $arraykey => $arrayvalue)
            {
                if (
$values['my_rating'] == $arraykey)
                {
                 
$selected "selected=\"selected\"";
                }
                else
                {
                 
$selected "";
                }
                
$output .= "<OPTION value=\"$arraykey\" $selected >$arrayvalue</OPTION>";
            }
            
$output .="</SELECT>";
        }
    }
    elseif(
$stage == "persist")
    {
        
$my_rating $this->vb->GPC['custom1']['my_rating'];
        
$values['my_rating'] = $my_rating;
    }
    elseif(
$stage == "display")
    {
        
$title "Rating";
        
$items $settings['my_rating_settings'];
        
$bits "<tr><td class=\"alt1\" align=\"center\">" $items[$values['my_rating']] . "</td></tr>";
  eval(
'$output.="' fetch_template('GARS_mod_container') . '";');
    }
?>



The Settings stage is the stage that gets run when an admin views a module through the module set editor in their admincp. It allows you to capture settings specific to the module in the exact place of the module. This enables you to have the same module several times on the same page, but each one with its own unique settings.

Before I get started, its important to identify some KEY words that you DO NOT want to use in your modules as variables:

$settings - Holds your modules settings
$values - holds your modules values that the user entered
$itemid - The unique position for the module
$output - the output for the module
$vbphrase - vb's phrases

OK. That out of the way, lets look at what the hell im doing here. The goal is to allow the admin the ability to define their own selection of 'movie ratings' for the poster.

NOTE: All of vbulletins admin functions are usable here (which is what Im using)

First I start by defining a description row. This is good practice when making a module:

PHP Code:

print_description_row("This module will allow users to select a rating for the movie"); 

Though maybe not IDEAL, Im using two input boxes to allow them to enter in a comma seperated list of ratings, then of the descriptions.

I want to first see if any settings already exist. If not, I want to skip the processing of them. In the next section, you will see that I save the settings as an associative array called 'my_rating_settings'. Therefore if they have settings, it will be in the array as such:
PHP Code:

        if ($settings['my_rating_settings'])
        { 

If there are values, I 'break' them appart so its easier for the user to edit them:
PHP Code:

         foreach($settings['my_rating_settings'] as $key => $value)
            {
             if (!
$keys)
                {
                 
$keys ="$key";
                    
$texts "$value";
                }
                else
                {
                 
$keys .=",$key";
                    
$texts .= ",$value";
                }
            } 

This leaves me with 2 variable: $keys and $texts that I can display to the admin:
PHP Code:

        print_input_row("Ratings:<dfn>Enter each rating letter seperated by a comma (i.e. G,PG,R)</dfn>""my_rating_keys[$itemid]"$keys);
        
print_input_row("Text:<dfn>Enter each rating description seperated by a comma (i.e. G - General,PG - Parental Guidance</dfn>""my_rating_text[$itemid]"$texts); 

Note that the element name is my_rating_keys[$itemid] and my_rating_text[$itemid].
YOUR ELEMENT NAMES MUST BE UNIQUE AND USE $itemid LIKE THIS:
PHP Code:

my_unique_name[$itemid

This guarantees that the settings here will be unique to ONLY this module.


The persistsettings stage allows you to process and save the settings.

I start by sanitizing any values (always best practice). I start by decalring $vbulletin as global so I can access it. Then I call vbulletins sanitizing proceedure. Each type is a string, and since its a multidimensional array, its declared as TYPE_ARRAY_ARRAY_STR. If it was a number, it would be TYPE_ARRAY_ARRAY_INT. The reason its a multi dimensional array is because a user may have 1 or 1,000 of this exact same module in the same set, each with its own unique settings. This enables you to keep the settings unique!Notice how I do this:
PHP Code:

        global $vbulletin;
        
$vbulletin->input->clean_array_gpc('p',array(
         
'my_rating_keys'  =>  TYPE_ARRAY_ARRAY_STR,
            
'my_rating_text' => TYPE_ARRAY_ARRAY_STR
        
)); 

Then I put the values in a local variables:
PHP Code:

        $keys $vbulletin->GPC['my_rating_keys'][$itemid];
  
$text $vbulletin->GPC['my_rating_text'][$itemid]; 

Notice how I access it with the $itemid variable? This ensures I am getting the values ONLY FOR THIS MODULE!

Here is where I do some silly processing of the values. For simplicity, I am turning the values into an associative array so that the Key becomes the rating (i.e. G or PG) and the text becomes the value. This simplifies the display portion:
PHP Code:

        $keyarray explode(",",$keys);
        
$textarray explode(","$text);
        
$results = array();
        if (
is_array($keyarray))
        {
         foreach(
$keyarray as $itemkey => $itemvalue)
            {
             
$results[$itemvalue] = $textarray[$itemkey];
            }
        } 

NOTE: This assumes that they have passed values through correctly (i.e. the same amount of keys as text and each key unique). They may not! However we are assuming they have :D

Finally, I set the results to the $settings array:
PHP Code:

$settings['my_rating_settings'] = $results

Phew. The rest is downhill from here :)



The only real difference to the edit stage is in the way we retieve the values that the admin has set.

first, we grab the values the admin has set:
PHP Code:

$items $settings['my_rating_settings']; 

Then we check that it is indeed an array. Otherwise it means that the admin hasnt set ANY values

PHP Code:

        if (is_array($items))
        { 

Then we start pasting together a select drop down combo box full of the options the admin has created:
PHP Code:

$output .= "Rating: <SELECT name=\"custom1[my_rating]\">"

Note how we APPEND it to the output variable?!?

Now we loop through our items array and create the options:
PHP Code:

            foreach($items as $arraykey => $arrayvalue)
            {
                if (
$values['my_rating'] == $arraykey)
                {
                 
$selected "selected=\"selected\"";
                }
                else
                {
                 
$selected "";
                }
                
$output .= "<OPTION value=\"$arraykey\" $selected >$arrayvalue</OPTION>";
            } 

Notice how we also check the $values['my_rating']? If there IS a value in there, it means that the thread is getting edited. It makes sense to set the drop down box to what the user already had selected :)

Finally, we end the select HTML
PHP Code:

            $output .="</SELECT>";
        } 



The persist stage is where we save our users selection! This is pretty easy and basically the same as the 101 version so I wont dwell on it here.
PHP Code:

        $my_rating $this->vb->GPC['custom1']['my_rating'];
        
$values['my_rating'] = $my_rating

A side note: $this is the GARS object. GARS holds a reference to $vbulletin as vb. Therefore $this->vb is the same as $vbulletin however $vbulletin is not in scope (hence why I did global $vbulletin in the previous stage though I just as easily could have skipped the global and simply used $this->vb).


The display stage isnt much different either. in fact, in some ways its actually easier!

The only real difference is that we get the text from our settings array!
PHP Code:

        $title "Rating";
        
$items $settings['my_rating_settings'];
        
$bits "<tr><td class=\"alt1\" align=\"center\">" $items[$values['my_rating']] . "</td></tr>";
  eval(
'$output.="' fetch_template('GARS_mod_container') . '";'); 

See?



Well, in closing I hope I have covered some of the key concepts in creating modules. They are actually very very easy and sometimes I wonder if these tutorials actually make it MORE difficult just because at first glance it looks complicated.

The important thing to remember is how much freaking flexability you have with the system and what you can do.

nJoy (and get out there and make some mods!)


All times are GMT. The time now is 10:04 PM.

Powered by vBulletin® Version 3.8.5
Copyright ©2000 - 2017, Jelsoft Enterprises Ltd.

Tutorial powered by GARS 2.1.9 ©2005-2006