Revision [19943]
This is an old revision of URModuleHowTo made by BrianKoontz on 2008-05-17 21:46:48.
Writing a UR (User Registration) Module
This page outlines the steps that can be used to write a UR (user registration) module. UR modules are pluggable, standalone modules that are used to interface with the UR validation framework introduced in 1.1.6.4.
Basically, a UR module contains all the logic necessary for alternative methods of user registration validation, and utilizes method hooks in the framework to display registration fields and text, retrieve user input, approve/disapprove registration requests, and display appropriate confirmation and error messages. Designing a UR module should never require modification to the Wikka core code libraries and routines.
About this tutorial
This tutorial outlines the development of the URInviteCodeModule, a simple module that prompts for a predetermined code before a registration request is processed. The module ships with Wikka 1.1.6.4, and can be found in the <wikka-dir>/libs/UR directory. If you are following thee tutorial, you might want to move/rename the URInviteCodeModule directory so you have the original to compare with if you run into problems.
Conventions
All file references will be with respect to your top-level installation directory (the directory which contains the folders/subdirectories 3rdparty, actions, handlers, etc.). The term "folders" and "subdirectories" are used interchangeably. As an example, the UR folder that is located in the top-level libs folder will be shown as libs/UR/.
I develop on a Mac iBook using the UNIX command line, so you might have to modify your commands accordingly for other platforms.
Setting up a new module (URInviteCodeModule)
Modules must reside in the libs/UR/ folder. Start by creating a new folder:
mkdir libs/UR/URInviteCodeModule
Make libs/UR/URInivteCodeModule your current directory. From this point on, the tutorial will make the assumption that you've done this step.
cd libs/UR/URInviteCodeModule
We'll use the URDummyModule as a template, so let's copy that into our new module folder from the libs/UR/URDummyModule folder:
cp ../URDummyModule/URDummyModule.php URInviteCodeModule
All modules must extend the URAuthTmpl class. So the first step is to change the class declaration to reflect the name of your new class. Change this line:
class URDummyModule extends URAuthTmpl
to this:
class URInviteCodeModule extends URAuthTmpl
The constructor function will also need to be changed to reflect the new name you've given your class...so modify the constructor:
function URDummyModule(&$wakka)
{
...
}to:
function URInviteCodeModule(&$wakka)
{
...
}The main purpose of the module constructor is to initialize the parent with the current $wakka instance and to initialize any parameters that are needed for your specific module. Any parameter added to wikka.config.php will be available to your module via the $wakka->config array. The UR framework will handle details involving instantiation of your module and multiple modules defined in the UR_validation_modules parameter, so you should never have to access this in your code.
Our module requires one parameter: The invite code that the user will have to match in order for site registration to be successful. We create a new instance variable to hold this value:
class URInviteCodeModule extends URAuthTmpl
{
var $inviteCode;and initialize this variable inside the URInviteCodeModule constructor:
function URInviteCodeModule(&$wakka)
{
$this->URAuthTmpl($wakka);
if(isset($wakka->config['UR_InviteCode_password']))
{
$this->inviteCode = $wakka->config['UR_InviteCode_password'];
}
}When UserSettings is first called by the browser, the underlying action (actions/usersettings.php) makes a call to a hook function called URAuthDisplay(). In turn, the framework passes this call on to any registered modules. Therefore, if you want your module to output form elements, you will need to define an instance method called URAuthTmplDisplay(). (Currently, this call is made between the creation of the Login-related form fields [Your WikiName, Password] and the Register-related form fields [Confirm password, Your e-mail address]. Plans are to include additional function hooks to allow for placement of output elsewhere on the generated page.)
We have need of only one input field: A field for the user to enter the invite code. Any error messages should be displayed at this time as well.
function URAuthTmplDisplay()
{
if(!isset($this->inviteCode))
{
echo '<em class="error">Error in URInviteCode module</em>';
return;
}
echo "Enter invitation code: <input type='textarea' name='UR_inviteCode'/><br/>";
} The "error" class is a Wikka-specific class used for styling errors throughout the application; I recommend using this same styling for your own error messages. The name of the input field (UR_InviteCode) will be available to your module via the $_POST array.
