registration_form

Field Value

Page name registration_form

Page id 98

Page title Setting up User Registration

Content

Table of Contents

Synopsis

Enabling Registration

Setting up Permissions to Support Registration

Sample Permissions on Users Table

Restricting Permissions on Particular Fields

Email Validation

Disabling Email Validation

Triggers: Overriding Registration Workflow

Preventing Spam with CAPTCHA

Synopsis

Xataface optionally enables you to allow users to register for an account in your application. If your users table includes a column for email, it will also perform email validation before the account is activated. Before tackling user registration, it is good to have an understanding of Xataface's authentication and permissions faculties.

Enabling Registration

To enable registration, simply add the following to the _auth section of the conf.ini file:

allow_register=1

e.g. after adding this, your _auth section might look like:

[_auth]
     users_table=users
     username_column=username
     password_column=password
     allow_register=1

After doing this, you'll notice a little Register link below the login form.

Clicking on this link will produce a registration form for the user which is essentially a "New Record" form on your users table.

Some features of this registration form include:

Checks to ensure that the username is unique
If the users table contains an email field, it will use the user-entered address for email validation before activation is complete.

Setting up Permissions to Support Registration

Xataface <= 1.2.4: You must ensure that unlogged-in users have permission to add new records to the users table. This means that your getPermissions() method on the users table should, at least, provide the new permission. In addition these users must be granted the register permission in order to be able to register to begin with.

Xataface >= 1.2.5: You no longer need to provide the new permission to allow users to register. You simply need to provide the register permission.

Sample Permissions on Users Table

In the tables/users/users.php file (assuming my users table is actually named "users")

class tables_users {

    function getPermissions($record){
        if ( isAdmin() ) return null;
        $perms['register'] = 1;
        return $perms;
     
    }
}

Note that this example is only applicable for Xataface 1.2.5 or higher. In Xataface 1.2.4 you needed to provide users with the ''new'' permission rather than the ''register'' permission, which opens up a small security hole since users could potentially just use the "new" action if they new the URL and by-pass the registration and activation email altogether.

Some notes on this example:

The isAdmin() function is not part of Xataface. It is used as a bit of *magic* here to reduce code. It is supposed to simply return true if the currently logged in user is an admin. Hence if the user is an admin, this method defers to the Application Delegate class's permissions (i.e. this method should not affect administrators).
We are giving all users (logged in or not) the register permission which enables them to register for an account on the system.
Generally you will want to restrict permissions on some of the fields in the users table. E.g. users should not be able to set their role or access level when they register. You can define more fine-grained permissions on these fields using the fieldname__permissions method of the users table delegate class (per the following example).

Restricting Permissions on Particular Fields

You probably don't want users to be able to set their access level when the register for an account, and your "users" table will quite often contain some field like "role" which stores this information. So the previous example is not quite realistic. You will also need to restrict permissions on the "role" field (and any other fields that you want to prevent users from setting themselves.

function role__permissions(&$record){
    if ( isAdmin() ) return null;
    return Dataface_PermissionsTool::NO_ACCESS();
}

This will cut off the user's ability to set their own role when they register. You will likely want to set the default role value either in the mysql table definition or in the beforeInsert? trigger.

Email Validation

As mentioned above, registration works by sending an activation email to the address specified in the user's registration. This email contains a link back to the activate action of your Xataface application, which will create the user account and log the user in. This implies that your users table must store an email address for your users. If you add a field named email to the users table, Xataface will assume that you mean to use this field as the user's email address, and thus, for email validation. However you can override this functionality and use *any* field as an email field by setting the email directive of the appropriate field in the fields.ini file for the users table.

Example: Assigning the my_addr field of the users table to be used for email validation:

In the tables/users/fields.ini file:

[my_addr]
    email=1

Disabling Email Validation

99% of the time, email validation is the preferred way of ensuring that people who register are who they say they are. You may, however, prefer to let users register directly without requiring the email activation step. You can disable email validation by overriding the register action in the actions.ini file as follows:

In your application's actions.ini file:

[register > register]
    email_validation=0

After setting this, the user account will automatically be created, and the user logged in upon saving the registration form.

Triggers: Overriding Registration Workflow

Xataface provides a number of triggers in the Application Delegate Class to override and extend the behavior of the user registration and activation process. For a list of available triggers see Application Delegate Class.

Preventing Spam with CAPTCHA

One problem with enabling automatic registration is that it invites SPAM in the form of bots that can learn how to automatically register for user accounts and then leave unwanted input into your application. The Xataface reCAPTCHA module allows you to avoid these problems to some extent by forcing users who aren't logged in to fill a CAPTCHA field in order to successfully submit the form. This is especially helpful for registration forms.

After installing the reCAPTCHA module the registration form will include a CAPTCHA field like the one depicted below:

For more information about the reCAPTCHA module click here.

Keywords registration form, _auth, authentication

Language en

registration_form[ Search for ""]

registration_form

Synopsis

Enabling Registration

Setting up Permissions to Support Registration

Sample Permissions on Users Table

Restricting Permissions on Particular Fields

Email Validation

Disabling Email Validation

Triggers: Overriding Registration Workflow

Preventing Spam with CAPTCHA