Customizing the User Login Page in Drupal 7

I was recently tasked with theming a customized user login page in Drupal 7. I could not find a whole lot of documentation for this so the first place I looked was in the core modules folder hoping to find something like user--login.tpl.php that I would be able to copy and put in my theme folder for an override. No such luck, I looked in /modules/user but nothing there I could use. Next I looked around drupal.org and found some vague references to doing this in scattered posts. This took me a several hours but finally I pieced together code from a bunch of posts and came up with a method that worked well for me.

The Code

You can add this code to your theme's template.php file where "your_themename" is the machine name of your theme. Here we tell Drupal that we want a user-login.tpl.php file in our theme folder. 

function your_themename_theme() {
  $items = array();
  // create custom user-login.tpl.php
  $items['user_login'] = array(
  'render element' => 'form',
  'path' => drupal_get_path('theme', 'your_themename') . '/templates',
  'template' => 'user-login',
  'preprocess functions' => array(
  'your_themename_preprocess_user_login'
  ),
 );
return $items;
}

You can now create a user-login.tpl.php and put it in your theme folder or the theme's template folder if there is one. Note that there are no "double dashes" in this file name as is typically traditional with Drupal 7 template file names. 

A Few Ways to Theme it.

<?php print drupal_render_children($form) ?>

This is probably fine in some cases but I needed to have something more granular. For this, I print out the individual variables at the top of my user-login.tpl.php file to see what's available for theming. 

<?php
  /* print the variables if needed to allow for 
  individual field theming or breaking them up. */
  print '<pre>';
  print_r($variables);
  print '</pre>';
?>

Now clear your cache and reload /user/login and the variables should print out. You will see a huge mostly undecipherable list of variables here. What we are looking for are the top level array items. These will include:

[name] => Array
[pass] => Array
[form_build_id] => Array
[form_id] => Array
[actions] => Array

Themable Output

I can covert these into themable output as such:

 <?php
 /* split the username and password from the submit button 
   so we can put in links above */

    print drupal_render($form['name']);
    print drupal_render($form['pass']);
    print drupal_render($form['form_build_id']);
    print drupal_render($form['form_id']);
    print drupal_render($form['actions']);

?>

Well, you can see where this is going, you can really theme this page however you want now that all the fields are separate. I also needed to add an image to this page so I can do that using the theme path for my image.

<div class="login-photo">
    <img src="<?php print base_path() . drupal_get_path('theme', 'your_themename') 
   . '/images/login-photo.jpg'; ?>" 
        alt="Login" title="Login" width='327' height='221' />
</div>

Again, be sure to change your_themename to the machine name of your theme. I've attached the finished theme file below so to use if for Drupal 7, you simply need to add in your template.php code above and then theme it however you want. Note, to achieve the screen capture above of my custom login page, I used a little module I created to remove the login tabs so I could have a more simple and elegant look to the page. I was now able to print those links just above the login button.