User Controls

User controls are created visually in VS.NET. Generally, user controls are created by dragging and dropping server controls onto what almost appears as a Web form. Once you've added the server controls you want, you can create new, unique functionality by adding additional code to the control. By now, you're already familiar with the user control supplied by CMS, the edit console, which is a collection of CMS console controls. The edit console is used on almost every template to provide content contribution functionality. But what if you wanted to create your own controls?

Creating your own user controls can be a very good way to extend functionality in your templates. Also, because you can create user controls visually, the process of creating new controls is relatively easy. Let's take, for example, the need in the BOTS Consulting site to add labels over each placeholder. These labels will serve as a cue to the content contributor, indicating what content goes in a particular placeholder. Since this is something you'll have to do over and over again, a user control may make a great deal of sense, since it is easy to create and is reusable.

To begin, let's take a closer look at the problem for a moment. In the BOTS site, we want to make sure that each placeholder has a label above it. This label would ensure that content contributors know what content to put in each placeholder. However, we only want these labels to show in certain cases specifically, when placeholders are visible. If this is a one-time event, it's probably better to use an existing control and wrap it in some conditional logic. However, if you have multiple placeholders across multiple templates, it's probably better to create a control. In this case, we're going to create a user control.

Start by creating a new user control in your project. To create the control, right-click the folder in your project where you want to create the control. From the context menu, choose Add, then Add New Item. In the next dialog that appears, choose Web Project Items and then click (once) the Web User Control type. In the "name" field, type "CMS PlaceholderLabel". As we mentioned before, we've created a special folder in the BOTS Consulting project for user controls called UserControls (we told you we're not that creative when it comes to names); in Figure 29-1 you'll see our new user control in that folder.

Figure 29-1. CMSPlaceholderLabel in the UserControls folder

Once you have your new user control, you'll need to add other controls and code. In this example, we want to create a control that displays text within your Web page selectively, based on the Web Author context. In our example, we're going to add a literal control to our user control. The literal control will allow us to place any sort of text on the page we like (and it doesn't add <SPAN> tags to the HTML as label controls do). Just drag a literal control from the Toolbox directly onto your control (in Design view). Now, name the control OutputText. The actual name of your object doesn't have to match what we've defined, but the code in this section will reflect our name. In Figure 29-2, you'll see the Design view of VS.NET with the new literal control added and with the Name property set.

Figure 29-2. The literal control added to the user control

Now that you have the literal added to your user control, you'll have to add the appropriate namespace references. For this example, all we need to add is the Microsoft.ContentManagement.WebControls namespace.

 using System; using System.Data; using System.Drawing; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.HtmlControls; using Microsoft.ContentManagement.WebControls; 

Next, we're going to add a property definition, which will allow the developer to set the label text above the placeholder. An added benefit of using the literal control is that it will allow the developer to add HTML tags in the label to control items, such as bold. In the following code, you can see the Text property within the control.

 private string text = ""; public string Text {       get       {             return text;       }       set       {             text = value;       } } 

So up to this point, this is a pretty basic user control. There's nothing inherently "CMS-like" except the namespace we added. However, as we mentioned earlier, we only want the label appear under certain conditions. Specifically, you want the label to appear when the Web Author is in either of two modes: AuthoringNew and AuthoringReedit. Based on the mode, we'll programmatically manipulate the visibility property of the literal control. In the following code, you'll see how we use the Web Author Context object and the mode enumeration provided in the PAPI to determine when the label should appear.

 // Set a variable equal to the current Web Author Context WebAuthorContext myContext = WebAuthorContext.Current; // Check to see what mode we're in and set the visibility accordingly if(myContext.Mode == WebAuthorContextMode.AuthoringNew ||       myContext.Mode == WebAuthorContextMode.AuthoringReedit)       {this.OutputText.Visible=true;} else {this.OutputText.Visible=false;} 

If we examine the code line-by-line, we find the following:

• We set a variable equal to the current WebAuthorContext (as much for space as for convenience, but not necessary).

• We determine whether we're in the AuthoringReedit or AuthoringNew mode of the Web Author. These two modes correspond to authoring within CMS. AuthoringReedit mode occurs when you're editing an exiting posting, while AuthoringNew is the mode during the creation of a new posting. In both cases, we set the visibility of the literal control to "true". Notice that we're using the WebAuthorContextMode enumeration to get a list of potential modes. If you've been watching the query string through the various exercises, you'll notice that it's possible to use the query string values to accomplish what we've done here watch for particular values and conditionally set the visibility of the literal control. However, that methodology isn't as clean, and it tends to be difficult to nail down the combination of parameters.

• If both conditions are false (meaning we're not in either mode), we set the visibility of the literal to "false" so that it's not seen on the "live" site or even in Edit mode if the placeholders aren't visible.

Again, what we've done here isn't revolutionary. It is, however, very useful and utilizes the PAPI to create a "CMS aware" user control. This control can be used from project to project. Practically speaking, the control can be dragged from your project directly to the design surface. When the control is implemented, the developer simply sets the "text" property in the tag to the desired label for a placeholder as follows:

[View full width]
 <uc1:cmsplaceholderlabel  runat="server" text="<b>Press Release  Date:</b><br>"> </uc1:cmsplaceholderlabel> 

Once you've done everything we've discussed so far, you should have a fully functional placeholder label. In addition, you could use this label control beyond basic labeling by adding some additional code. In Listing 29-1 you'll see the code for the BOTS Consulting placeholder label user control.

Listing 29-1 Complete code for the BOTS Consulting PlaceholderLabel user control

 namespace botsconsulting.usercontrols {       using System;       using System.Data;       using System.Drawing;       using System.Web.UI;       using System.Web.UI.WebControls;       using System.Web.UI.HtmlControls;       using Microsoft.ContentManagement.WebControls;       /// <summary>       ///         The placeholderlabel user control is used to place a       ///         descriptive label above a placeholder.       /// </summary>       public abstract class CMSPlaceholderLabel : System.Web.UI.UserControl       {             private bool displayinauthormode = true;             private bool displayineditmode = false;             protected System.Web.UI.WebControls.Literal OutputText;             public bool DisplayinAuthorMode             {                   get                   {                         return displayinauthormode;                   }                   set                   {                         displayinauthormode = value;                   }             }             public bool DisplayinEditMode             {                   get                   {                         return displayineditmode;                   }                   set                   {                         displayinauthormode = value;                   }             }             private string text = "";             public string Text             {                   get                   {                         return text;                   }                   set                   {                         text = value;                   }             }             private void Page_Load(object sender, System.EventArgs e)             {                   // Set default values for the control if no values are given                   displayinauthormode = true;                   displayineditmode = false;                   // Set the literal control TEXT property based on the TEXT property                   OutputText.Text = this.text;                   // Set a variable equal to the current Web Author Context                   WebAuthorContext myContext = WebAuthorContext.Current;                   // Check to see what mode we're in and set the visibility accordingly                   if((myContext.Mode == WebAuthorContextMode.AuthoringNew ||                         myContext.Mode == WebAuthorContextMode.AuthoringReedit)                         && displayinauthormode)                   {this.OutputText.Visible=true;}                   else if ((myContext.Mode == WebAuthorContextMode.PresentationUnpublished)                         && displayineditmode)                   {this.OutputText.Visible=true;}                   else                   {this.OutputText.Visible=false;}             }             #region Web Form Designer generated code             override protected void OnInit(EventArgs e)             {                   //                   // CODEGEN: This call is required by the ASP.NET Web Form Designer.                   //                   InitializeComponent();                   base.OnInit(e);             }             ///            Required method for Designer support - do not modify             ///            the contents of this method with the code editor.             /// </summary>             private void InitializeComponent()             {                   this.Load += new System.EventHandler(this.Page_Load);             }             #endregion       } } 

In Listing 29-1 you'll notice that BOTS added a few elements to the basic placeholder label control we've talked about. Specifically, they added the ability to control in which mode the label is displayed. In other words, it may be useful for the control to display in Edit mode, even if the placeholders aren't visible. To handle this situation, BOTS added two new properties: DisplayinAuthorMode and DisplayinEdit Mode. The main difference is the addition of the extra condition to determine if the Web Author is in PresentationUnpublished, which corresponds to the mode the Web Author is in when the edit console is visible, but the content contributor can't author. Further, they integrated the two properties that allow the developer to set the modes in which the label should show itself. To help clarify the various states of the Web Author context, BOTS chose to distinguish the various modes of the Web Author as follows:

• Live: The site renders all approved content as if a subscriber were viewing the content.

• Edit: The site displays the edit console, but the pages look largely as they do when the site is in Live mode. No content contribution is possible.

• Authoring: The placeholders are visible, and an author can contribute content.

It's likely that you won't see these modes talked about in the Microsoft documentation, but we've found that this is a good way to classify the various states so that it's clear not only to the developers, but to the content contributors as well.