Subclassing to Create a New Action Control

Altering the appearance of existing Web Author dialogs is not supported by Microsoft. However, in some cases, there are no real technical hurdles to doing so. For example, the Save New Page dialog is an ASPX file (installed by default to C:\Program Files\Microsoft Content Management Server\Server\IIS_CMS\WebAuthor\Dialogs\PageOperation\AuthoringMode\PageSave\NewPageSaveDlg\NewPageSaveDlg.aspx). If you wanted to, you could go into the ASPX file and alter the dialog.

However, the real flexibility in the Web Author design is the fact that you can create your own .NET server controls by inheriting from the Web Author control classes. For example, if you wanted to create your own Create New Page action, you could inherit from the Microsoft. ContentManagement.WebControls.WebAuthorContext.BasePostback Action class and then add your own user interface. An added bonus to this model is that your customized control will still trigger CMS PAPI events. The same principle can be applied to the Web Author status controls.

Classes for Creating an Action Control

There are three classes for creating an action control: BaseAction, BaseNewWindowAction, and BasePostbackAction.

To create an action control that triggers client-side JavaScript, you should inherit from the BaseAction class. You can then override the ActionJavascript property to define the code that runs when the user clicks the control. This type of control can be used to render custom dialog boxes.

The BaseNewWindowAction class allows a CMS developer to create a custom Web Author control that opens a dialog box. This class includes a property called UrlNewWindow, which determines the URL that should be opened when the control is clicked.

Another option is to create a custom Web Author action control that raises an ASP.NET postback event. If you want to create an action that does this, you should subclass your action from the BasePostbackAction class. The PerformAction method is used to specify the code that runs when the postback is raised.

Example: The "createChannel" Action Control

To demonstrate the flexibility of the Web Author controls, this example shows how you might create a custom action control. One of the most commonly requested Web Author enhancements is the ability to create CMS channels directly from within the Web Author console. This is a perfect candidate for demonstrating custom action controls.

We will create a function called "createChannel" and then add it as an action control within the Web Author. The function will use the CMS PAPI to create a new channel under the root channel of the CMS Web site. The complete code for this example is available for download at www.awprofessional.com/titles/0321194446.

Once you have created your own subclass, you will want to override the functionality of the default control. You have a number of choices. The first option shown is overriding the Text property. This property determines the link text displayed on the console for the control. Other options are discussed later in this chapter.

Creating Your Subclass

This first snippet shows the base code that we will use to subclass from a Web Author class. You can see that it adds references to a number of assemblies, and it inherits from the BasePostbackAction class. This piece of code also introduces the parentChannel member variable, which we will use to determine the parent channel of the new channel.

 using System; using System.ComponentModel; using System.Collections; using System.Web; // Add references for MCMS namespaces using Microsoft.ContentManagement.Publishing; using Microsoft.ContentManagement.WebControls; using Microsoft.ContentManagement.WebControls.ConsoleControls; namespace CmsWebAuthorApplication {       public class CreateChannelAction : BasePostbackAction       {             // Instantiate MCMS HTTP Context             CmsHttpContext cmsPapiHttpContext = CmsHttpContext.Current;             // Set the root channel as the default parent channel             protected Channel parentChannel = null;    } } 

Creating Your Custom Action Function

This next section of code shows how you can create your own custom properties to use in the action control. CMS developers can then change these properties in the console file. Properties like this are powerful tools in the .NET developer's toolbox. They encourage code reuse and help avoid coding errors.

 /// <summary> /// Channel sets or returns the path for the parent channel. /// </summary> [    Browsable(true),    Description("Parent Channel"),     Category("Behavior") ] public string ParentChannel {     get { return parentChannel.Path; }     // Get a channel object using its path.     set { parentChannel = CmsHttpContext.Current.Searches.GetByPath(value) as Channel;} } 

Next is the code that actually creates the channel. Looking through this code you will see that it uses the CMS PAPI to create a channel under a certain parent channel. The parent channel is determined by the ParentChannel property. As one of the code comments notes, it is not necessary to switch to Web Author Update mode to run this code. The reason for this is that the base class already runs the code in Update mode. Since this code is inherited from that base class, we get this functionality for free.

This code creates the channel, names it, and then commits the change to the CMS database. If an error is encountered, the changes to the CMS database are canceled.

 // This function programmatically creates an MCMS channel private void createChannel() { // Instantiate MCMS HTTP Context CmsHttpContext cmsPapiHttpContext = CmsHttpContext.Current; HttpContext httpContext = HttpContext.Current; // Attempt to create a new channel // Note that the BasePostbackAction performs in update mode so we don't // need to switch try { // Identify the channel to create new channels within Channel targetChannel = cmsPapiHttpContext.RootChannel;     // Check if channels can be created within the target channel.     // Note CreateChannel can still fail even if CanCreateChannels returns true     if (targetChannel.CanCreateChannels)     {     // If channels can be created, create a channel and name it     //'ChannelFoo'         Channel newChannel = targetChannel.CreateChannel();         newChannel.Name = "ChannelFoo";         // Commit changes to the MCMS database         cmsPapiHttpContext.CommitAll();     } } catch (Exception eCreateChannel) {     // Roll back changes if an exception occurs     cmsPapiHttpContext.RollbackAll();     throw eCreateChannel; } } //End createChannel 

Overriding the Text Property

If you override the Text property of the base class, you are able to specify the text that appears in the console.

It is possible to add code within the Text property. However, this code will run every time the control is rendered within the Web Author console. Below your function, add the following code. This will override the Text property of the base class.

 public override string Text    {    get    {       //Show the text of the Create Channel link       return "Create Channel";       //Note that you could run other code within this property    } } 

Adding Your Custom Control to the Web Author Editing Console

Next you will add the class you have created as an action within the Web Author console. In the Solution Explorer window, expand the Console folder in the WoodgroveNet project. Open the DefaultConsole.ascx file. The console opens in Design view. To see the code, you will need to switch to HTML view. In this example, assume that you have added your control to the WoodgroveNet namespace. To register a prefix for the CmsWebAuthorApplication, position the cursor at the top of the DefaultConsole.ascx page and add the following code:

 <%@ Register TagPrefix="CreateChannelActionConsole" Namespace="CmsWebAuthorApplication" Assembly="WoodgroveNet" %> 

To add the CreateChannel class as an action to the default console, add the following code:

[View full width]
 <!  The "parentChannel" property determines the parent channel for the new channel  > <CreateChannelActionConsole:CreateChannelAction  runat="server"  parentChannel="/Channels"> <a  onclick="<%# Container.ActionJavascript %>;return  false;" href="#""><%# Container.Text%> </a></CreateChannelActionConsole:CreateChannelAction> 

Example: Some Other Properties That You Can Override

Refer to the CMS documentation for a complete list of Web Author class properties that you can use in your custom controls. Here are a few quick examples.

Overriding the ActionJavascript Property

The ActionJavascript property is within the BasePostbackAction base class. This property returns a string that contains client-side JavaScript for displaying a custom dialog box that retrieves the name of the channel to be created.

The simple code that follows is an example meant to demonstrate the functionality of the ActionJavascript property. Adding this code will result in an alert message popping up when the control is clicked.

 public override string ActionJavascript {     get     {     string javascriptOutput;     javascriptOutput = "alert('ActionJavascript Override')";     return javascriptOutput;     } } 

Overriding the Available Property

The Available property is another useful aspect of Web Author controls. This property allows you to add logic for determining when an action control should appear on the console. As you can imagine, this property is used by almost all Web Author controls.

Typically, it is the Web Author mode that determines when a control should be displayed. However, you could use any logic, based on your business needs. In this example, the Available property is used to check the current user's rights to the current parent channel. If the current user does not have rights to create channels, then the option is simply not displayed.

 /// <summary> /// Available overrides BaseAction.Available and returns a boolean value /// indicating whether the current user can create channels in the /// parent channel. /// </summary> public override bool Available {     get     {     return parentChannel.CanCreateChannels;     } }