Jun 22, 2008

User control in wss3

It is important to understand that WSS does not support user customization of user controls. User controls are always loaded from the file system of the front-end Web server and compiled into assembly DLLs. Furthermore, user controls can be copied to the front-end Web server only by someone with farm-level administrative privileges. For these reasons, you can assume that you can always write in-line code in an .ascx file.

Just like the virtual _layouts directory for the purpose of deploying application pages, WSS provides a similar virtual directory for deploying user controls. Inside the TEMPLATE directory resides a nested directory named CONTROLTEMPLATES. This directory contains many different user controls that are deployed as part of the standard WSS installation.

The CONTROLTEMPLATES directory is also a place where you should deploy custom user control files. However, it’s a good practice to create your own nested directory inside the CONTROLTEMPLATES directory to avoid potential file name conflicts. The CustomSitePages project creates a company-specific inner directory named Litware and copies its user controls into that directory. Each custom user control is copied to a physical path that looks like the following: TEMPLATES/CONTROLTEMPLATES/Litware/UserControl1.ascx

Each Web application is configured with a virtual directory named _controltemplates that points to the physical CONTROLTEMPLATES directory. This makes it possible to reference any user control file by using a standard path relative to the hosting Web application. For example, one of the user controls from the CustomSitePages project can be referenced by using a virtual path that looks like the following: ~/_controltemplates/Litware/UserControl1.ascx

When deploying user controls, it’s important to remember that they follow the same rules with respect to safe mode processing. If you want to place a user control on a site page that might be customized, the .ascx file must be registered as a safe control in the web.config file of the hosting Web application. Fortunately, you don’t have to worry about this if you deploy your custom user controls inside the virtual _controltemplates directory because the standard web.config file for a Web application already contains the following SafeControl entry:

            
            

Now that you have seen how to create and properly deploy a user control, the final step is constructing a page template that references the .ascx file and creates an instance. Similar to constructing pages with custom controls, this is accomplished by placing a Register directive on the page template. However, the process is different with user controls because the Register directive requires an src attribute that points to the virtual path of the target .ascx file.

            <%@ Page MasterPageFile="~masterurl/default.master"
            meta:progid="SharePoint.WebPartPage.Document" %>

            <%@ Register TagPrefix="luc" TagName="UserControl1"
            src="~/_controltemplates/Litware/UserControl1.ascx" %>