Registration for TurboGears

What Is It?

The registration package is a set of templates for TurboGears applications designed to make common tasks associated with new user registration and maintenance easier. It is intended to interface with the TurboGears identity framework. Some features are:

• A new user registration form
• Email validation
• Inserts validated users into groups you define
• Reset lost passwords
• Allows users to change their password and email address
• Users can delete their accounts

Who Can Use It?

If your identity model is fairly similar to the standard identity model, and uses the same user/group/permissions layout, you are a pretty good candidate. If your identity model is significantly different, you will have some work to do to integrate the registration templates, and it may be easier to start from scratch.

The TurboGears 1.0 branch is required. Currently, only Python 2.4 and 2.5 is supported. SQLAlchemy versions greater than 0.4 are supported (as well as SQLObject).

Installation

If you have TurboGears installed, you should already have the easy_install program. The module should install with:

easy_install registration

You may need to use sudo or something similar to elevate your permissions appropriately.

Upgrading

To upgrade from a previous version of registration, use easy_install as follows:

easy_install -U registration

Setting Things Up

Add the Templates to your Project

If you have an existing project, you can add the registration files with the following command:

tg-admin update -t registration

If this is your first time installing registration in this project, you can safely say 'n' to overwriting any files, unless you actually want to replace them.

If you are upgrading the templates in your project from a previous version of registration, you can say 'n' to any files that aren't in a 'registration' folder. For the registration templates, it is probably safest to answer 'b' (for backup), which will put in the upgraded code/templates, and save a backup of your original version. Once the update is complete, you can compare the old and new versions to see if there are any changes you may have made that will need to be incorporated into the new templates.

For new projects, the command is:

tg-admin quickstart -t 'turbogears registration'

Set Up the Model

If your model User class has been modified from the original User that 'tg-admin quickstart' provides, you will need to modify the registration.model.RegistrationPendingUser class to look like your model (or at least as much as you want the user to have to fill out when they register.) Basically, you can cut and paste from your User model into RegistrationPendingUser, but be sure not to delete 'validation_key' column in the new class.

To create the registration tables in your database, the easiest way is to use the 'create_registration_tables' function, like this:

plewis% tg-admin shell
Python 2.5.1 (r251:54869, Apr 18 2007, 22:08:04) 
[GCC 4.0.1 (Apple Computer, Inc. build 5367)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
(CustomShell)
>>> import myproject.registration.model as model
>>> model.create_registration_tables()

Set Configuration Variables

In your project's config folder, there should be a new file named 'registration.cfg'. You will need to edit the values as appropriate. The purpose for most variables should be documented in the comments of the file.

Tying Everything In

Add in the Registration Controller

In your main controllers.py, you need to reference the new registration controller. If you want to expose registration off of the root of your main controller, it would be something like:

from myproject.registration import controllers as reg_controllers
        
class Root(controllers.RootController):
    registration = reg_controllers.UserRegistration()
    # the rest of your controller code
    

If you are using the stock User and Group definitions that identity provides, your work is done. However, if you have modified these classes, you still have a bit to do.

Making Registration Fit Your Model

If your User class is different from the original User, you will need to modify registration in the following areas:

• in registration.model, set class RegistrationPendingUser as appropriate (this should have already done in the 'Set Up the Model' step above)
• In registration.widgets, there is a class NewUserFields that defines the form fields for new user entry. You should modify this to provide the appropriate fields.
• In registration.widgets, there is a class NewUserSchema that provides form validation. If you want to have form fields validated, you will need to modify this class.
• In registration.controllers, the method 'create' creates a new RegistrationPendingUser based on the fields provided from the UserFields form. You should modify the parameters provided to 'create', as well as the fields used when the new RegistrationPendingUser is made.
• In registration.controllers, the method 'promote_pending_user' should work for most cases, but if you have any special fields that are in RegistrationPendingUser that you don't want to move to your User class, you can modify the list of elements that shouldn't migrate.
• In registration.controllers, the 'do_delete' method should be modified to do any custom user cleanup that needs to be done upon deleting a user.
• In registration.widgets, ExistingUserFields should expose elements you would like an existing user to be able to modify
• In registration.widgets, ExisitngUserSchema provides validation for existing user data.

The registration process also assumes you can find a User 'by_email_address', and that your link to groups is named something like 'group'. If those two cases aren't true, you have some more work to do to make things work.

Once these changes have been made, you can start your project and see the new exposed registration controls.

Template Customization

There are a number of templates in the templates/registration directory that can be customized to fit in with how your site looks.

If you would like, you can also change the login form to have a link to the lost password page. Instead of having your login controller use the 'templates.login' template, use 'yourproject.templates.registration.login'. You may need to fix the url in registration/login.kid to point to the correct 'lost_password' controller.

Key Controllers

There are a few interesting controllers that you may want to link to in other parts of your app.

• new - The starting point for new user registration
• lost_password - Recovers lost passwords
• edit_user - Allows a user to edit their email address and password.
• delete_user - Allows a user to delete their account.
• validate_new_user - You don't want to link to this, but emails sent out by the framework will point to this controller to validate that the user received the email at the address they specified.
• validate_email_change - Again, don't link to this directly, but this controller is included in emails for registered users that want to change their email address.
• reset_password - Another controller that is sent via email to users who have lost their password.

Software Details

Support

Please use the registration Google Group to ask any support related questions. Ideas or comments are also welcome on that list.

To track development or file a bug report, please refer to the Project page / subversion repository

Download

Download: registration-0.4.tar.gz Mar 24, 2008

Changelog

License

This is the MIT License.

Copyright (c) 2008 Patrick Lewis

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.