Theia's award system really shines when you implement awards that are automaticly given to members, upon earning them. This means that you don't need to sit back and review what members need to be given which awards, and it keeps members more active as they see the effect of their activity immediately.

Unfortunately, adding automatic awards in Theia is not a simple, idiot-proof procedure. And sadly, it does require that you have a grounding in PHP concepts, or are at least confident enough to tinker.

On the bright side, we have covered everything you need to know to pull this off in our documentation now, so if you're feeling brave, you may really want to pick this up. Not only will this tutorial give you an understanding of automating awards, but it will give you a strong sense of working with Theia's signal system, which means you will gain insight into an easy way to port your own code into Theia.

Create the award

When we are talking about "automatic awards" here, we don't mean that the awards themselves are created automatically; this is instead referring to the ability to have awards given to members automatically. So you still need to manually create the award. This is done in the "manage awards" (admin tool 166), which is under the "award management" area on tools.

For the sake of this tutorial, let's assume we have created an award emblem/icon, and are going to call it "Busy Bee", and award it for posting 100 items on the site. Fill all this information in on the form to create a new award (at the bottom of "manage awards") and create the award. It's important to remember the ID of the award you are going to automate, so after it is created, view the URL for one of the images that were generated for the award's emblem. The filenames consist of and ID, followed by an underscore, and then the image's dimensions (width). For example: 129_100.png; 100 is the width of the image, and 129 is the award's ID.

Creating an event file

At this point, you should now be informed that the following information will only make any sense to you if you have a grounding in Theia's signals and events system. If you don't know what this is, or how or why it is used, you should read up on this before continuing.

First we need to figure out what we are going to call this new event file. Since it is assumed at this point that you should be aware that event file names must start with the signal of the event. With this in mind, we need to figure out what signal this action is related to. For this, look over the list of signals.

As we can see on the list, signal 3 (new item), seems to be the most relevant; since the award we want to automate is given for members who create 100 items. Now that we know our signal, let's call the file something like:

3_busybee.php

Again, it's important that the event file begins with 3, since this file should be processed every time signal 3 is announced (the creation of a new item). Though we will help you get the idea of what to write in the file lower in this tutorial, at this point it should just be clarified how these files work...

Whenever events are processed, a quick scan of the DIR_EVT directory is performed (which, unless you have changed this, should be lib/event). As this directory is read, any files starting with the signal of the signal from the processed event will be executed automatically. Thus automated custom tasks can be a snap working with the signals and events system.

What should be in the event file?

First of all, event files should be straight-up PHP code, surrounded by a beginning PHP tag at the beginning of the file, and an ending PHP tag at the end of the file. For example:

<?php
/* some code here... */
?>

Anything in this file should be just PHP code; no HTML output.

Now you're probably wondering how you're supposed to figure out how many items the member has. That's good; and don't worry, because this is where the Stats class comes in!

Working with the Stats class

Just a little reassurance here: the presence of the Stats class is not here to make things harder by requiring you learn something else. Actually it's very easy to pick up, and the end result of knowing how to use the Stats methods properly will provide you with an easy interface for determining lots of otherwise advanced member statistics!

Like with how you determine what signal to use for the file name, again here you should check out the different methods of the Stats class, because many advanced statistic processes on members have already been written, and can easily be used with a line of code.

OK, and now back to our award example of "Busy Bee"; which is given out to members who have 100 items. After looking into what some of the Stats methods do, it looks like Stats::ItemCounts is the most relevant here.

Now here is where a little more thinking comes in. We can see that the method can operate on a single member or every member, so let's think about this; since only an item is being added, only one person added the item; thus, we don't care what the stats are for all of the members. To figure out how many items the user has, we need to do something like this:

$items = Stats::ItemCounts($user); 

Where the value of $items would give us the number of items the $user has. If you're now thinking, "what are we supposed to write to stat the user who made the item"; then you're in good shape.

Let's go back and check out the details on signal 3. The area that interests us now is Data saved with announcement, as this is a list of all the variables you have to work with in event files (for that particular signal, since different signals have different data available to them). Here we can see that the key, user, holds the ID of the user who created the item (and thus, the one we should check for). It should also be pointed out that:

All data variables are accessible in event files as an element of the array, $d

Thus, the value of the user ID who created the item is stored as the value of $d['user']. Expanding on this knowledge, our code in the event file can now look more like this:

// get the item creator's total item count
$items = Stats::ItemCounts($d['user']); 

And now, let's throw in the logic:

// get the item creator's total item count
$items = Stats::ItemCounts($d['user']);
if ($items >= 100)
 {
 /* give the award! */
 } 

And finally, here comes a little code which you haven't see in the Stats class or signals and events system...

Awards::Give()

The Give method of the Award class, is not dependent on an object, and thus can be called like so:

Award::Give(); 

It contains three arguments:

• member ID
• award ID
• note

The third argument (note) is optional, but we think it's preferred to write something like "auto" for this, just so there is a distinction in their activity between a manually given award and one given automatically. Keep in mind, anytime you want to give an award, you need to have the Award class loaded, as it may not be! For example:

require(DIR_LIB . "/class/Award.php"); 

You should always use DIR_LIB to the library folder, and avoid hard coding the path to the directory. This allows your files to remain portable and distributable to others who use Theia. Also, whenever you load up classes in Theia, it's always best to make sure they don't exist before loading them (otherwise errors will be encountered). Here's the ideal way to do that:

class_exists('Award') || require(DIR_LIB . "/class/Award.php"); 

You may be wondering why we both use this method and recommend it, as opposed to using something like require_once instead. The answer is really simple: it's much faster. Actually, in most situations, it's several times faster to do things this way and avoid using require_once which isn't nearly as quick. Fortunately we've been aware of this little quirk in PHP for a long time and have taken it into account when naming files and classes. The class name will always be the same as the filename (only the filename will contain .php at the end).

Putting it all together

And finally, we will throw all that we've learned together and create the file which will automatically give out the Busy Bee award we've described here. And here it is:

<?php
// require the necessary classes
class_exists('Stats') || require(DIR_LIB . "/class/Stats.php");
class_exists('Award') || require(DIR_LIB . "/class/Award.php");
// get the item count for the user
$items = Stats::ItemCounts($d['user']);
// perform the logic
if ($items >= 100)
 {
 Award::Give($d['user'], 129, "auto");
 }
?>

And here's what it all means... The lines that start with // are comments in PHP, and are provided just to show you what is going on in the code. The first thing that is done is the Stats and Award classes are loaded up if they don't exist yet. Then, a check is performed to see how many items the user who created the new item has. Finally, some logic is performed which basically says "if this user's items are equal to or greater than 100, then give them the award". Award::Give() is then invoked, which gives the award. The first argument, $d['user'] is the user's ID (as we know from the documentation on signal 3), and the second argument (129) is the ID of the award we are giving (if you can remember that far back in this tutorial!). The third argument is completely optional, but here we just write "auto" so whenever this award is given a note is saved to it reminding us it was given out automatically. When this code is saved to a file named something like 3_busybee.php (it needs to start with 3; it's signal) and uploaded/stored in your event directory (DIR_EVT; lib/event on default installations), it will then automatically be processed whenever there is an event of signal 3 to process (the occurrence of a new item).

And that is all there is to it! It probably feels overwhelming at first, but once you're familiar with how things work, you should hopefully find it easy to work with, since you aren't forced to go into other parts of the code for general tasks.