PDA

View Full Version : GARS: Module making 101


The Geek
02-22-2006, 06:47 PM
Module creation in GARS is actually VERY simple once you get your head around the framework. If you know a tad bit of HTML and a tad bit of PHP, obs your uncle and GARS is your friend.

In this Tutorial, Ill introduce you to making your own modules that allow you to easily grab extra data and display it. Please note that this is a bare bones example with little fluff designed to show you a BARE minimal approach.

It is also to try and help a user that was asking for this functionality :)

What Ill do is create a module that will allow users to select a rating for the imaginary 'movie' they are rating. In essence, all we will be doing is providing a combo box at edit/new thread time, capturing the input and then displaying the results when someone reads the entry.

Make sure you clean the input!

Here is the code in its entirety:

<?php
if ($stage == "edit")
{
$output .= "Rating: <SELECT name=\"custom1[my_rating]\">
<OPTION value=\"G\">G - General Audiences</OPTION>
<OPTION value=\"PG\">PG - Parental Guidance</OPTION>
<OPTION value=\"PG13\">PG13 - Children under 13 are too cute for this movie</OPTION>
<OPTION value=\"R\">R - Under 17's not admitted without parents</OPTION>
<OPTION value=\"X\">X - It marks the spot</OPTION>
</SELECT>";
}
elseif($stage == "persist")
{
$my_rating = $this->vb->GPC['custom1']['my_rating'];
$values['my_rating'] = $my_rating;
}
elseif($stage == "display")
{
$title = "Rating";
$bits = "<tr><td class=\"alt1\" align=\"center\">" . $values['my_rating'] . "</td></tr>";
eval('$output.="' . fetch_template('GARS_mod_container') . '";');
}

?>


Now lets take it apart

The first thing you will notice is how everything is broken into 'stages'.

In total, there are 5 stages:

[B]edit - A user is creating or editing a gars thread (first post)
persist - A user is saving a gars thread (first post)
display - A user is viewing a gars thread
settings - An admin is viewing the settings for the module
persistsettings - The admin is saving the settings.In this example, we are skipping the last 2 for simplicity (I am hoping to expand on this simple module in another tutorial to include these stages later).

The edit stage provides you with the ability to add additional fields for the user to enter when they create a new thread or edit an existing thread.

Here all we are doing is creating a drop down combo box with a selection of items to choose from and appending it to the $output variable:

$output .= "Rating: <SELECT name=\"custom1[my_rating]\">
<OPTION value=\"G\">G - General Audiences</OPTION>
<OPTION value=\"PG\">PG - Parental Guidance</OPTION>
<OPTION value=\"PG13\">PG13 - Children under 13 are too cute for this movie</OPTION>
<OPTION value=\"R\">R - Under 17's not admitted without parents</OPTION>
<OPTION value=\"X\">X - It marks the spot</OPTION>
</SELECT>";

NOTE:

Your HTML elements need to be named custom1[MYVARNAME] in order to work. You MYVARNAME should be unique as well!

Another note:

Whatever output you want to produce MUST be APPENDED to the $output variable. In other words:

$output = 'my stuff';

IS BAD while

$output .= 'my stuff';

is good! If you use the former, then you may overwrite other module output.

[break=Persist stage]the persist stage is where we save whatever custom entries we want to save.
The first thing we do is capture the variable from the GPC:

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

Now we can validate it (or in this case not!) and apply it to our $values array like so:

$values['my_rating'] = $my_rating;


And GARS will do the rest!

[break=Display stage]This is where we layout the custom fields how we want.

Since I'm using the GARS_mod_container template (which gives you the expandable box), I set the title:

$title = "Rating";

The GARS_mod_container template is a table that expects a variable called $bits, so we make that and stick our $values['my_rating'] in there:

$bits = "<tr><td class=\"alt1\" align=\"center\">" . $values['my_rating'] . "</td></tr>";

Notice that we stick it in a table row!

Then we use the handy eval command to paste it all together into the $output variable (note how it is appended to output instead of assigned!)

eval('$output.="' . fetch_template('GARS_mod_container') . '";');


[break=Closing]
To wind this up, simply save it as a php file in your geek/gars/mods folder. You can then register it and assign it to any module set.
It will be pretty useless in a forumdisplay page, so I would recommend adding it to a showthread module set page.

[B]nJoy

Origin2
08-27-2008, 10:01 AM
wow thanks useful stuff ^^