Tuesday, November 8, 2011

Customizing the Login Page in SharePoint 2007


Microsoft SharePoint 2007 gives you the option of using forms authentication, but the out-of-the-box forms-based login experience is fairly bland. It’s not bad if you’re doing something for internal use, but if you’re doing something for internal use then you’re probably using Windows authentication. Forms authentication is normally found on external or customer facing sites where corporate branding is a big deal, and master pages play a major role in presenting a consistent look and feel throughout a SharePoint site. But when you apply a master page to a publishing site, or edit the default.master in a team site, you’ll quickly find out that it doesn’t alter the look and feel of the login page. In this article, we’ll take a look at why that is and what you need to do to get your login page in line with your corporate brand.
If you’re wanting to know how to enable forms authentication in SharePoint 2007, check out this article: Configuring Forms Authentication in SharePoint 2007.

Where does the login.aspx page reside?

When you try to view a protected page in a forms authenticated site, SharePoint redirects you to the login page (Figure 01). At the login screen, take a good look at the URL in your browser notice that the login.aspx page is in the _layouts folder. If you browse to the directory that houses your SharePoint application, you’ll quickly notice that there’s no _layouts folder in the directory itself. This isn’t a shocking revelation to most because a lot of the pages you see in SharePoint don’t actually exist on the file system. But if you open the Internet Information Services (IIS) manager snap-in and navigate to your SharePoint site, you’ll find that the _layouts folder is actually a virtual directory that points to the following real-life directory on your server (assuming you installed to the default location):
C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts
The layouts folder contains application and system pages used by all the SharePoint sites on your server. Upload a new document to a site you’ll end up on the upload.aspx page from the layouts folder. View the people who have access to the site you’ll be on the people.aspx page. And if you’re trying to login, you’ll be hitting the login.aspx page. There are 400 pages in the directory, each of which has its own specific point and purpose, so it’s impossible to go into detail on each page. But they are all in there.
Figure 1 – the login.aspx page

Global consequences of changing files in the _layouts folder

Armed with the location of the application system pages in SharePoint, you may be tempted fire up an editor and start hacking away at them, but you should probably know what you’re getting yourself into before going down that path. Remember how the _layouts folder in your SharePoint site is a virtual directory that points to C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts? Well, all of the SharePoint sites on your server are setup in exactly the same way. That means when you change something in the _layouts folder for one site, you’re changing it for every single SharePoint site on your server. It also means that you’re editing the only version of the file on your system, so you’d better make a backup of the folder content. Otherwise you’ll have to reinstall SharePoint to get those files back into working order if you have a nasty mishap.

Creating a site-specific _layouts virtual directory

Depending on your situation, applying changes to all of the sites on your server may or may not be a bad thing. If all of the sites on your server need the exact same branding, layout, and functionality, then go ahead and make the change directly in the standard layout folder (after backing it up). But you may just as well find yourself in a situation where each site needs to be different, so applying a sweeping change to all the sites won’t work. What do you do when you find yourself in that situation? You make a copy of the shared layouts folder specifically for your site, and make the changes in that site-specific copy. To do this, take the following actions
  1. Navigate to the C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\ folder
  2. Select the layouts folder and copy it
  3. Navigate to the root directory of your SharePoint site
  4. Paste a copy of the layouts folder in your SharePoint directory
  5. Rename the layouts folder _layouts
  6. Open the IIS manager snap-in
  7. Expand your SharePoint site’s website entry
  8. Right click on the _layouts virtual directory (you may also see a non-virtual _layouts folder) and select Properties from the context menu
  9. On the virtual directory tab, click the Browse button next to the Local Path textbox to display the directory selection dialog
  10. Navigate to the _layouts folder you just created in your SharePoint site, select it, then click OK
  11. Click OK to apply the change to the _layouts virtual directory
Now you can make changes in the _layouts folder for your SharePoint site without it affecting other sites on your server.
Warning: some operations in SharePoint Central Administrator, like extending a site or changing the authentication type for a zone, can “reset” the _layouts virtual directory in your SharePoint sites so they point back to C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts. When this occurs, just go back into the IIS manager snap-in and point the virtual directory back over at the _layouts folder copy for your site.

Login.aspx and its Master Page

When you open the login.aspx page you’ll quickly discover it’s a content page containing markup for a title, layout table, username textbox, password textbox, a login button, a “remember me” checkbox, and a few content controls to helpful text labels next to some of the fields. Just enough markup for a non-descript login form, but certainly not enough to make the unsightly bluish surroundings on the Standard SharePoint login page (see Figure 1 again). The login page relies on the simple.master page in the _layouts folder to define most of the look and feel you see around the page (see Figure 2). Following is the Page directive found at the top of the login.aspx page which shows the association of the simple.master with the page:

<%@ Page Language="C#"    Inherits="Microsoft.SharePoint.ApplicationPages.LoginPage"    MasterPageFile="~/_layouts/simple.master"%>
When you’re considering changing the look and feel of the login form, you need to determine exactly what you’re trying to accomplish. If you want to change the branding surrounding the form itself, then you need to edit the simple.master page. If you want to change the login form itself, by rearranging controls, adding additional help text, graphics, etc, then you need to edit the login.aspx page.


Figure 2 – simple.master from the layouts folder

Editing the simple.master page

Like most master pages, the simple.master controls the look and feel or more than just a single page. In fact, it controls the look and feel of seven pages in the _layouts folder:

Page Name Description
AccessDenied.aspx Displays a notice that you have been denied access to the requested resource. Shows the name of the currently logged-in user and a link to sign-in as a different user.
Confirmation.aspx Displays a message indicating that the requested operation succeeded.
Error.aspx Displays a message indicating that an error has occurred. May also display additional stack trace information if the site has been configured to do so.
Login.aspx Display a login page allowing users to enter forms authentication credentials.
ReqAcc.aspx Displays a notice that you have been denied access to the requested resource.
Signout.aspx Responsible for logging a user out of the site.
Webdeleted.aspx Displays a message indicating the web site has been deleted.

People visiting your forms authenticated SharePoint site will run into a couple of these pages on a regular basis, so you’ll definitely want to include the simple.master in any branding efforts you undertake for your SharePoint site. But with seven different pages relying on the simple.master page, the question is what can you change on the simple.master page and what do you have to leave? Master pages contain ContentPlaceHolders controls that identify sections of the page into which content may be injected by a content page. Content pages contain Content controls that refer to the ContentPlaceHolder controls in the master. If a content page refers to a ContentPlaceHolder in the master, but you’ve removed that ContentPlaceHolder, an error occurs. So, the key to modifying a master page is to NOT remove any required ContentPlaceHolder controls.
Determinging exactly which ContentPlaceHolder controls are required in a master page can be fairly arduous because some of ContentPlaceHolders may be required by one page but not another. For example, the simple.master page contains a ContentPlaceHolder controls named PlaceHolderPageImage. If you remove it from the simple.master, the login.aspx page loads without a problem because the login.aspx page doesn’t reference the control. But you do get an error when you hit the AccessDenied.aspx page because it uses the PlaceHolderPageImage to insert a little icon on the page. Since the simple.master only controls the look and feel of seven pages, it doesn’t take too much time to check each page to see if you removed a required control. With other master pages you’re not so lucky. The application.master, for example, controls the look and feel of more than 200 pages. And that’s just too much to test.
One way to avoid the headache of accidentally removing required controls is to leave them on the page, but hide them. The process looks something like this:

  1. Open your master page file
  2. At the bottom of the page, add a hidden panel using the following code:
        <asp:Panel runat="server" visible="false">
        </asp:Panel>
  3. Look through the markup of your content page and locate any ContentPlaceHolder controls (or any other server controls for that matter) on the master page
  4. When you find a ContentPlaceHolder control (or a server control) cut and paste it into that hidden panel
When you finish, you’ll have a master page whose server controls are entirely contained in a hidden panel. View any page that references that master, and you’ll see that the page renders without any errors because all of controls that were originally there are still there, they’re just hidden. Of course, it also renders without any content because the hidden panel is hiding everything, but you’ll take care of that next. Now you can begin altering the look and feel of the master page by adding in the branding elements for your corporate image. As you do so, you can begin adding back in any ContentPlaceHolders and server controls that you want in the final master page.
If you’re curious, the following ContentPlaceHolders are required in the simple.master:

  • PlaceHolderAdditionalPageHead
  • PlaceHolderPageTitle
  • PlaceHolderSiteName
  • PlaceHolderTopNavBar
  • PlaceHolderTitleBreadcrumb
  • PlaceHolderPageImage
  • PlaceHolderPageTitleInTitleArea
  • PlaceHolderMain
  • PlaceHolderPageDescription
You’ll also probably want to keep the ScriptLinkControl named ScriptLink1 as well, because it contains important JavaScript includes.

Editing the login page

Editing a content page is a much less perilous task than changing a master page because any bugs you introduce are localized to the page itself. You can keep a copy of the page up in your browser and refresh the screen when you make a change to see if it breaks. Like the master page, the biggest thing to remember on a content page is that the class which controls the page is looking for specific page elements. If it tries to find a page element and it’s not there, the page throws an error and won’t render. If you do not want an element to display on the screen, you can place that control in a hidden Panel control to hide it from view without breaking the code that controls the page.
Most of the changes you’ll be making in content pages are going to be cosmetic, and will likely revolve around adding some additional content here and there and changing the layout of elements inside the page. Understand, however, that all of these SharePoint pages are built using ASP.NET technology. As such, these pages can be altered any way that you could normally alter an ASP.NET page, allowing you to do some really heavy renovations if you so choose. For example, take the login.aspx page. Here’s the Page directive found in login.aspx:

    <%@ Page Language="C#"
         Inherits
="Microsoft.SharePoint.ApplicationPages.LoginPage"
        
MasterPageFile="~/_layouts/simple.master" %>
Notice that the page references the simple.master as its master page and inherits its functionality from Microsoft.SharePoint.ApplicationPages.LoginPage class. If you don’t want the login.aspx page to use a master page, you can remove the MasterPageFile element in the Page directive and place all of the branding markup directly in the login.aspx page itself. I don’t recommend the approach, but you can do it. Or what if you don’t like the way the Microsoft.SharePoint.ApplicationPages.LoginPage class handles the page? You can remove the element to remove the page logic entirely, or point it at a different class. If you do remove the Inherits element, you can still write your own custom code for the page by adding server-side script directly in the login.aspx page. I put the following code in my login.aspx page and it works just fine (and it actually logs you into the site too!)
    <%@ Page Language="C#" %>
    <script runat="server">        protected override void OnLoad(EventArgs e)        {
            Response.Write("This is from the onload event");
            base.OnLoad(e);
        }    </script>    <html>
         
<body>              <form runat="server">                  <asp:login id="login" runat="server" />              </form>          </body>    </html>
Is it a good idea to get rid of the master page and the controlling class for a SharePoint page? Absolutely not! But it does show you the flexibility you have in editing pages.

Conclusion

You’ve seen where you can find the SharePoint login page and the master page that controls its look and feel. You’ve learned the global consequences of editing pages in the _layouts folder, and how to avoid those consequences if you need changes to apply to a single site on your server. You’ve got some good guidelines for editing master pages. And you know that you can do just about anything you want to a content page. So you should have a sporting chance at changing just about anything you want on the login page or any other SharePoint application page.

No comments:

Post a Comment