Forms are defined as PHP arrays,

$form['noreg'] = array(
    '#type' => 'checkboxes',
    '#title' => "Reason not to register",
    '#options' => $reasons,
    '#default_value' => 0,
    '#validate' => array('fizzed_up_validator' => array())
);

When the above code fragment gets rendered into HTML it’ll be a list of checkboxes with the items in $reasons. Also note that we’re passing a custom validation function. Inside your custom validation function you could perform all the checking and if there’s an error condition you could say,

form_set_error($form, $message);

which will display an error message and redirects users back to the form. $form is a parameter your validation function takes. Forms API is well documented with examples.

There’s this need to add the user to a particular role depending on from where the user come to the download page. This should be done in the registration phase. That’s trivial to do with Drupal. You could get this “event” where the user submitted details has passed all the validation logic and about to be inserted into the database, at that time you have to fetch the role info from the DB and insert stuff to users_roles table. Oh, and the redirection part. When the form is successfully submitted (meaning user got registered) you could redirect the user to anywhere. All the API and the things you could do with it is extremely well thought out and nice to play with. To get this registration form, all I had to do was hide some attributes before the form gets rendered. For example look at the standard registration page. Embedded registration form of the newly designed page had to contain only the mandatory fields. There was no need to display rest of the stuff. So, what I had to do was in hook_form_alter unset the relevant $form['elems']. Had to define a session variable to detect we’re coming from the right page, otherwise the all the registration form instances will be changed. After that display the form,

drupal_get_form('user_register');

voila! Now you have a customized registration form. The cool thing is all the validation stuff defined for the registration form will work and you don’t have to do anything extra.

A slightly less documented API call that we use is user_external_load. This’ll load a given user’s details into the current session so that the user will be logged into the system. To pull this off successfully there needs to be an entry in the authmap table as the function implementation shows. I’ve not been able to find a way one could insert a record to this table via the admin screens.