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
• Lost password recovery
• Allows users to change their password and email address

Who Can Use It?

If your identity model is fairly similar to the standard identity model (using SQLObjectIdentityProvider), 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.

TurboGears version 1.0 (or greater) is required. Currently, only Python 2.4 is supported.

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 don't begin with 'register_'. For the 'register_*' 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 simply:

tg-admin quickstart -t 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.

All necessary database tables should be automatically created when you start your project up.

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 import register_controllers
        
class Root(controller.RootController):
    registration = register_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 register_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 register_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 register_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 register_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 register_widgets, ExistingUserFields should expose elements you would like an existing user to be able to modify
• In register_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 directory (beginning with register_*) 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 'templates.register_login'. You may need to fix the url in register_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.
• 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.

Software Details

You can email any questions, problems, or ideas to plewis at spamcop dot net

Download: registration-0.3-py2.4.egg Feb 13, 2007

Changelog

Project page / subversion repository

License

This is the MIT License.

Copyright (c) 2007 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.