GameMe Administrator Documentation
The ATutor administrator has control over the default Events, Badges, Levels, with the ability to customize any of the default settings for these. Once customized, these settings are made available to courses, and if the administrator has enable editing of default settings, course instructors can also customize these at the course level to meet the needs of specific courses. See the GameMe Instructor documentation for more about what instructors can modify.
GameMe 1.0 Instructor Documentation
Default Events
Events occur when particular features in ATutor are viewed, or a tool is used, and event related request variables are set. In the welcome event, described below, when the bounce.php file is accessed, and the $_REQUEST['course'] variable is set, the event runs, typically scoring points, issuing a badge, and/or sending an alert email. See the README.md file with the module for a full list of events (and badges) in this version of GameMe.
Each of the elements that make up events are described in this section. All may be edited by administrators at the system level, and by instructors at the course level, except where indicated otherwise.
- Alias - (string) A short unique identifier used as a reference to access an event's properties. Alphabetic, underscores, no spaces. (only editable by admin user)
- Description - (string) A few words to describe the event to users.
- Repetition - (integer) Set to 1 to disable repetitions, allowing an event to occur only once. Set to 0 to allow an event to reoccur
- Reach Reps - (integer) The number of times an event occurs before triggering a reach event
- Max Points - (integer) The maximum number of points an event can accumulate
- Each Badge - (integer) The id number of the badge issued each time an event occurs, typically for single occurence events
- Reach Badge - (integer) The id of the badge issued when a reach event occurs
- Each Point - (integer) The number of points issued each time an event occurs
- Reach Points - (integer) The number of bonus points issued when a reach event occurs
- Each Callback - (string) A reference to a function in GMCallBacks.class.php, that runs each time an event occurs, typically used to send an email notice (only editable by admin user)
- Reach Callback - (string) A reference to a function in GMCallBacks.class.php, that runs when a reach event occurs, typically used to send an email notice (only editable by admin user)
- Reach Message - (string) The content of the message to send to a user when a reach event callback runs
Creating New Events
WARNING: Be careful when creating, editing, and deleting events. If the required coding for an event, described below, contains bugs, it can cause ATutor to become unavailable. You are advised not to create new events on a production ATutor environment. Also, if you delete a default event that has already been running in a course collecting points etc., error messages will be generated, and any data associated with the deleted event will need to be manually deleted from the database to resolve the messages.
Creating new events is possible on standalone ATutor installations, where the administrator has access to the ATutor source code. ATutorSpace users will not be able to add new events themselves, though they may suggest new events using Contact ATutorSpaces, and if possible, we'll add the new event for you.
Clicking on the Add+ link at the top right of the administrator's Default Events editor, opens a form with the default event fields described above. At a minimum an event should have an Alias, Repetition set to 1 (off) or 0 (on), and the Each Points value set. Though all options except the Alias are optional, without other options set the event would not do much.
Creating new events requires making modification to the module's events.php file. Events typically occur when a particular page loads, and particular request variables are set. The following code describes the elements of the Welcome event, which runs the first time a user logs into a course.
if(strpos($_SERVER['PHP_SELF'],
"bounce.php")&& $_REQUEST['course'] >
0){
//if the page loading is bounce.php,
and
//
$_REQUEST['course'] is set, trigger the event
$_SESSION['course_id'] =
$_REQUEST['course'];
// in this case we need to manually set
the session course_id
$gamification->executeEvent('welcome',
array( // using the
"welcome" event alias, execute that event
'user_id'=>$_SESSION['member_id'],
// a user id must always be set,
usually the session's member ID
'alias'=>'welcome_badge',
// associate a badge using the
welcome_badge alais (see badges below)
'email'=>$gm_member['email'],
// include the user's email address if
this event triggers an email event
'firstname'=>$gm_member['first_name'],
// first name, used to address users in
messages
'contact_email'=>$_config['contact_email'],
// content sender's email address,
typically set to the default ATutor contact
'badges'=>$gamification->getUserBadges()));
// generate a list of the badges
prevously earned, sent with the reach event email
}
|
Event Callbacks
When creating an event, you may also make reference to a function that runs when an each event, or reach event occurs. Callbacks are optional, though in most cases you'll want to create one that runs when a reach event occurs. A callback reference looks something like this one used as the welcome callback (GmCallbacksClass::WelcomeCallback), that sends an email and a badge to the user the first time they log into a course. The code for the WelcomeCallback is described below, and is located in the module's GmCallbacksClass.php file.
// This function sets up the message
sent to users when the welcome event occurs
// Then passes the message to the
SendMail function for mailing
// $params are those set in
$gamification->executeEvent(), described above in
events.php
static function WelcomeCallback($params)
{
if
($params['firstname']){
$feedback_img
= '<div style="float:left;text-align:top;height:5em; width:5em;
margin-left:1.2em;margin-top:-.5em;">
<img
src="'.self::getBadgeFile($params['alias']).'"
alt="" style="float:left;"/></div>';
$feedback
.= '<div
style="height:auto;float:left; clear:both;">'.
$feedback_img.self::getReachMessage('welcome').'</div>';
$message
.= self::getNewBadge($params, $feedback);
$message
.= self::getCurrentBadges($params['badges']);
}
if(!empty($message)){
self::SendMail($params,
$message);
$_GET['fb']
= $feedback;
}
return
true;
}
|
Editing Existing Events
To edit existing events in the Default Events editor, click on, or keypress, any cell then edit the contents directly as if editing a form field. Click out of the field, or press the tab key, to save the change. Again, be careful when editing events, particularly when editing a reference to an event callback. See the Warning above.
Default Badges
Badges are issued to users when a particular event occurs, or when an event has reached a particular number of repetitions. Administrators can modify the Default Badges, and decide whether instructors can edit them at the course level.
Each of the elements that make up badges are described in this section. All except the Id may be edited by administrators at the system level, and by instructors at the course level, except where specified.
- Badge - (string) The badge image preview and drop zone, store the relative path to the badge image in the database
- Id - (integer) The id number assigned to the badge and referred to in the each badge and reach badge fields in the Events Editor
- Alias - (string) A short identifier used as a reference to access a badge's properties. Alphabetic, underscores, no spaces. (only editable by admin user)
- Title - (string) A short name for the badge (1-3 words typically)
- Description - (string) A sentence or two that describes to the recipient why they received the badge.
Creating New Badges
Creating badges is much more straight forward than creating events, though you will normally want to edit the existing badges. New badges are typically added when a new event has been created, or perhaps if you accidentally delete a badge you shouldn't have. Creating, or editing badges is much safer than creating and editing events, and can be performed on a production system. Deleting badges that have already been issued to users, will produce a broken image wherever the badges appears (easily fixed be recreating the badge).
Clicking on the Add+ link at the top right of the administrator's Badge Editor, opens a form with the default badge fields described above (except Id, which is assigned automatically). At a minimum a badge should include an Alias and Title. To add the badge image, Save the badge properties and in the row added to the Badge Editor, drag a badge image, maximum 95px x 95px, less than 15k in size, into the drop zone area in the row's first cell. You can also click or keypress the dropzone cell to open your local filmanager, and upload a badge image this way. The maximum image and file size settings are editable in the module's upload_badge.php file, if needed.
Editing Existing Badges
To edit existing badges in the Badges Editor, click on, or keypress, any cell then edit the contents directly as if editing a form field. Click out of the field, or press the tab key, to save the change. To change the badge image, drag the appropriately sized image file to the dropzone in the first column, or click the dropzone to open your local file manager to select an image.
Default Levels
Levels are awarded when a user surpasses a particular number of points. By default stars icons of varying colours are awarded for each level (11 levels by default). Unlike badges though, which are associated with particular events, levels are associated with points earned. So, any number of levels can potentially be created. The default levels should accommodate most courses, adjusted to the length of the course, the tools enabled, and how the tools are being used.
Instructors will typically want to edit the Points Thresholds for levels, so the upper levels can realistically be reached over the duration of a course, given the features enabled in that course.
Each of the elements that make up levels are described in this section. All may be edited by administrators at the system level, and by instructors at the course level.
- Icon - (string) The level icon image preview and drop zone, store the relative path to the icon image in the database
- Level Name - (integer) A short name for the level (1 to 3 words, e.g. Level 1, Newbee, Novice Member, Superstar)
- Description - (string) A few words describing the level that was reached
- Points Threshold - (integer) The level Icon is issued to users when they reach this number of points
Creating New Levels
Creating new levels is much like creating new badges. Click on the Add+ link in the Levels Editor, fill in at least the required fields (Level Title, Points Reached), save, then drag a level icon into the icon dropzone for the new level (icon maximum 95px x 95px badge image, less than 15k in size, editable in upload_level_icon.php).
Editing Existing Levels
To edit existing levels in the Levels Editor, click on, or keypress, any cell then edit the contents directly as if editing a form field. Click out of the cell, or press the tab key, to save the change. To change the level's icon image, drag the appropriately sized image file to the dropzone in the first column, or click the dropzone to open your local file manager to select an image.
Options
Most options are handled at the course level by instructors, though the administrator has the option to disable instructors editing of events, badges, and levels.