Revision history for URModuleHowTo
Revision [23355]
Last edited on 2016-05-20 07:38:47 by BrianKoontz [Replaces old-style internal links with new pipe-split links.]Additions:
This page outlines the steps that can be used to write a [[http://docs.wikkawiki.org/UserRegistrationValidationFramework | UR (user registration) module]]. UR modules are pluggable, standalone modules that are used to interface with the UR validation framework introduced in [[http://docs.wikkawiki.org/WikkaReleaseNotes1164 | 1.1.6.4]].
Deletions:
Additions:
----
CategoryURModules
CategoryURModules
Additions:
===Extending the ##""URAuthTmpl""## class===
===##""URAuthTmplDisplay()""##===
===##""URAuthTmplVerify()""##===
===##""URAuthTmplDisplay()""##===
===##""URAuthTmplVerify()""##===
Deletions:
===##URAuthTmplDisplay()##===
===##URAuthTmplVerify()##===
Additions:
===Extending the ##URAuthTmpl## class===
===Creating the constructor===
===##URAuthTmplDisplay()##===
===##URAuthTmplVerify()##===
When a user clicks the Register button, several validation checks are made against the user-entered data by ##usersettings.php##. Prior to any of these checks being made, the action class calls ##""URAuthVerify()""##, which in turn calls ##""URAuthTmplVerify()""## on every registered UR module. Return values from each module are ANDed together, so **all registered UR modules must return TRUE from ##""URAuthTmplVerify()""## before validation continues.**
##""URAuthTmplVerify()""## must return only one of two values: boolean FALSE (registration is invalid) or boolean TRUE (registration is valid). Remember that the ##usersettings## action will continue to carry out its internal input validations and might override your module's TRUE return value.
We consider a registration to be valid if the user enters the correct invite code. Therefore, we will compare the user's input with the correct invite code, and return TRUE if the values match, FALSE otherwise:
function URAuthTmplVerify()
return false;
if(isset($_POST['UR_inviteCode']) &&
$_POST['UR_inviteCode'] === $this->inviteCode)
return true;
return false;
Note that as a failsafe, we simply return FALSE if no conditions are evaluated, which is probably favorable over returning TRUE when we haven't correctly anticipated all possible cases.
Also, remember that after the user POSTs with the Register button, your module is reinstantiated, and previous instance variable values are lost. This is important if you plan on comparing data that is derived or created in ##""URAuthTmplDisplay()""## with user-entered values in ##""URAuthTmplVerify()""##. You will probably have to persist the data in a client-side or server-side (session) cookie so that the data is accessible in subsequent POSTs. This topic is beyond the scope of this tutorial. The URCaptchaModule offers a working example of how this might be accomplished.
===Implementation and testing===
To test your new module, simply create the following parameters in your ##wikka.config.php## file:
'UR_validation_modules' => 'URInviteCodeModule'
'UR_InviteCode_password' => 'some_invitation_code'
Reload your ##""UserSettings""## page (you will need to logout first). You should see output similar to the following:
{{image class="center" alt="module output" title="module output" url="images/URInviteCode_ex1.jpg"}}
The framework will generate a generic error message if registration is disapproved by any registered module, so for this module, we simply chose to use this generic error for user notification:
{{image class="center" alt="module error" title="module error" url="images/URInviteCode_ex2.jpg"}}
Successful entry of the invite code should generate a successful registration:
{{image class="center" alt="module success" title="module success" url="images/URInviteCode_ex3.jpg"}}
===Creating the constructor===
===##URAuthTmplDisplay()##===
===##URAuthTmplVerify()##===
When a user clicks the Register button, several validation checks are made against the user-entered data by ##usersettings.php##. Prior to any of these checks being made, the action class calls ##""URAuthVerify()""##, which in turn calls ##""URAuthTmplVerify()""## on every registered UR module. Return values from each module are ANDed together, so **all registered UR modules must return TRUE from ##""URAuthTmplVerify()""## before validation continues.**
##""URAuthTmplVerify()""## must return only one of two values: boolean FALSE (registration is invalid) or boolean TRUE (registration is valid). Remember that the ##usersettings## action will continue to carry out its internal input validations and might override your module's TRUE return value.
We consider a registration to be valid if the user enters the correct invite code. Therefore, we will compare the user's input with the correct invite code, and return TRUE if the values match, FALSE otherwise:
function URAuthTmplVerify()
return false;
if(isset($_POST['UR_inviteCode']) &&
$_POST['UR_inviteCode'] === $this->inviteCode)
return true;
return false;
Note that as a failsafe, we simply return FALSE if no conditions are evaluated, which is probably favorable over returning TRUE when we haven't correctly anticipated all possible cases.
Also, remember that after the user POSTs with the Register button, your module is reinstantiated, and previous instance variable values are lost. This is important if you plan on comparing data that is derived or created in ##""URAuthTmplDisplay()""## with user-entered values in ##""URAuthTmplVerify()""##. You will probably have to persist the data in a client-side or server-side (session) cookie so that the data is accessible in subsequent POSTs. This topic is beyond the scope of this tutorial. The URCaptchaModule offers a working example of how this might be accomplished.
===Implementation and testing===
To test your new module, simply create the following parameters in your ##wikka.config.php## file:
'UR_validation_modules' => 'URInviteCodeModule'
'UR_InviteCode_password' => 'some_invitation_code'
Reload your ##""UserSettings""## page (you will need to logout first). You should see output similar to the following:
{{image class="center" alt="module output" title="module output" url="images/URInviteCode_ex1.jpg"}}
The framework will generate a generic error message if registration is disapproved by any registered module, so for this module, we simply chose to use this generic error for user notification:
{{image class="center" alt="module error" title="module error" url="images/URInviteCode_ex2.jpg"}}
Successful entry of the invite code should generate a successful registration:
{{image class="center" alt="module success" title="module success" url="images/URInviteCode_ex3.jpg"}}
Additions:
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:
var $inviteCode;
and initialize this variable inside the ##""URInviteCodeModule""## constructor:
$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.
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:
var $inviteCode;
and initialize this variable inside the ##""URInviteCodeModule""## constructor:
$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.
Additions:
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.
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.
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/##.
===Setting up a new module (""URInviteCodeModule"")===
%%
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
%%
%%
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)
{
...
}
%%
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.
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/##.
===Setting up a new module (""URInviteCodeModule"")===
%%
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
%%
%%
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)
{
...
}
%%
Deletions:
This tutorial will outline the steps I took to convert YodaHome's excellent FreeCap anti-spam captcha code to a UR module. I modified the original code for 1.1.7, but since the UR framework has not yet been ported to trunk, this example will use a clean checkout of the 1.1.6.4 version (the release [[http://wikkawiki.org/downloads/Wikka-1.1.6.4.tar.gz tarball]]/[[http://wikkawiki.org/downloads/Wikka-1.1.6.4.zip zipfile]] will work as well). Setting up a working 1.1.6.4 Wikka instance is an [[http://docs.wikkawiki.org/Installing1164 exercise left for the reader]], and is a prerequisite for continuing with the tutorial.
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, although I will probably favor "folders" because it's shorter to type (UNIX users, please stand down -- I'm on your side). As an example, the UR folder that is located in the top-level libs folder will be shown as ##libs/UR/##.
Action steps will be set apart from comments using left-justified grey float boxes.
===Setting up a new module (""URCaptchaModule"")===
<<mkdir libs/UR/""URCaptchaModule""
cd libs/UR/""URCaptchaModule""<<::c::
<<cp ..""/URDummyModule/URDummyModule.php"" ""URCapthcaModule""<<::c::
Since UR modules are intended to be self-contained, all module-related files should be contained within the module folder. This module utilizes the [[http://www.puremango.co.uk/cm_php_captcha_script_113.php FreeCap]] library, so we'll unzip the FreeCap file into our module folder:
<<wget http://www.puremango.co.uk/freecap1.4.1.zip
unzip freecap1.4.1.zip<<::c::
Copy error messages
Rename constructor, class name
.htaccess
Additions:
Copy error messages
Rename constructor, class name
.htaccess
Rename constructor, class name
.htaccess
Deletions:
Additions:
Since UR modules are intended to be self-contained, all module-related files should be contained within the module folder. This module utilizes the [[http://www.puremango.co.uk/cm_php_captcha_script_113.php FreeCap]] library, so we'll unzip the FreeCap file into our module folder:
<<wget http://www.puremango.co.uk/freecap1.4.1.zip
unzip freecap1.4.1.zip<<::c::
Even though
<<wget http://www.puremango.co.uk/freecap1.4.1.zip
unzip freecap1.4.1.zip<<::c::
Even though
Additions:
===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, although I will probably favor "folders" because it's shorter to type (UNIX users, please stand down -- I'm on your side). 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.
Action steps will be set apart from comments using left-justified grey float boxes.
===Setting up a new module (""URCaptchaModule"")===
Modules must reside in the ##libs/UR/## folder. Start by creating a new folder:
<<mkdir libs/UR/""URCaptchaModule""
cd libs/UR/""URCaptchaModule""<<::c::
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"" ""URCapthcaModule""<<::c::
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, although I will probably favor "folders" because it's shorter to type (UNIX users, please stand down -- I'm on your side). 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.
Action steps will be set apart from comments using left-justified grey float boxes.
===Setting up a new module (""URCaptchaModule"")===
Modules must reside in the ##libs/UR/## folder. Start by creating a new folder:
<<mkdir libs/UR/""URCaptchaModule""
cd libs/UR/""URCaptchaModule""<<::c::
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"" ""URCapthcaModule""<<::c::
Additions:
This page outlines the steps that can be used to write a [[http://docs.wikkawiki.org/UserRegistrationValidationFramework UR (user registration) module]]. UR modules are pluggable, standalone modules that are used to interface with the UR validation framework introduced in [[http://docs.wikkawiki.org/WikkaReleaseNotes1164 1.1.6.4]].
Basically, a UR module contains all the logic necessary for alternative methods of user registration validation, and utilizes callbacks set up 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 will outline the steps I took to convert YodaHome's excellent FreeCap anti-spam captcha code to a UR module. I modified the original code for 1.1.7, but since the UR framework has not yet been ported to trunk, this example will use a clean checkout of the 1.1.6.4 version (the release [[http://wikkawiki.org/downloads/Wikka-1.1.6.4.tar.gz tarball]]/[[http://wikkawiki.org/downloads/Wikka-1.1.6.4.zip zipfile]] will work as well). Setting up a working 1.1.6.4 Wikka instance is an [[http://docs.wikkawiki.org/Installing1164 exercise left for the reader]], and is a prerequisite for continuing with the tutorial.
