Microsoft Content Management Server Development : An Image Rotator Placeholder Control (part 1)

We have all seen advertisements on websites. There are banners arranged horizontally at the top of the page, medium-sized square boxes located at a corner, long vertical banners on either side of the page—advertisements are everywhere. Generally, advertisements are just images designed to draw attention and entice visitors to click on them. A popular form of advertising these days is Shockwave Flash, which offers greater interactivity with low file size.

As advertisements are so popular on the Web, authors often have the responsibility of maintaining the list of advertisements on display. The image rotator placeholder control that we will build in this section provides the basic function of swapping pictures with each page load. All you will need to do to transform the images to actual advertisements is to make them clickable.

In authoring view, a textbox will be presented to authors. Here, they will specify a resource gallery that contains the images that will be displayed.

In presentation view, the placeholder control randomly selects and displays an image from the resource gallery. The images are randomly selected each time the page loads, so the visitor generally gets to see a different advertisement on each visit.

To up the cool factor of this control a notch, let’s give it the capability of rendering both image files and Flash files.

The ImageRotatorPlaceholderControl Class

To create the image rotator placeholder control, add a class file named ImageRotatorPlaceholderControl.cs to the UsefulPlaceholderControls project. The class requires the use of the methods from the following namespaces, so add them in.

using System;

using System.ComponentModel;
						using System.Xml;
						using System.Web.UI.HtmlControls;
						using System.Web.UI.WebControls;
						using Microsoft.ContentManagement.Publishing;
						using Microsoft.ContentManagement.Publishing.Extensions.Placeholders;
						using Microsoft.ContentManagement.WebControls.Design;
						using Microsoft.ContentManagement.WebControls;

namespace UsefulPlaceholderControls
{
}

Let’s store information about the images that will be displayed by the control as XML. As such, the control will only support placeholders defined from the XmlPlaceholderDefinition. In addition, since MCMS does not ship with a placeholder control that resembles an image rotator; we will build it from scratch, inheriting from the BasePlaceholderControl class.

. . . code continues . . .
[SupportedPlaceholderDefinitionType(typeof(XmlPlaceholderDefinition))]
						public class ImageRotatorPlaceholderControl : BasePlaceholderControl
{
  . . . code continues . . .
}

The ResourceGalleryPath property will contain the path of the resource gallery that holds the images that will be displayed. Add it directly below the ImageRotatorPlaceholderControl() constructor.

private string m_resourceGalleryPath;
[
Bindable(false),
Browsable(false),
DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden),
]
public string ResourceGalleryPath
{
  get
  {
    return m_resourceGalleryPath;
  }
  set
  {
    m_resourceGalleryPath = value;
  }
}

Specifying the Resource Gallery

Here’s how the list of images is maintained: first, resource managers will upload all the images to a target resource gallery. In authoring view, the control appears as a single-line textbox. Authors will enter the path of the target resource gallery into the textbox.

To keep the example simple, we will make the following assumptions:

• All files in the specified resource gallery will be added to the list of images to be displayed (even if they are really Word documents!).

• All files in the list are equally important. There is an equal chance of each file being chosen to be displayed in the control when presented.

• The visitor viewing the page must have at least subscriber access to the resource gallery. Otherwise, the placeholder control won’t be able to read the files in the gallery and no matter how many times the page is refreshed, nothing gets displayed.

Loading the TextBox

As mentioned earlier, we’ll provide authors with a single-line textbox to specify the path of the resource gallery containing the images. Next to the textbox are simple instructions requesting the author to enter the path. We will use a table to organize the layout of the instructions and the textbox. Add the overridden CreateAuthoringChildControls() method to the code.

TextBox txtResourceGalleryPath;
protected override void CreateAuthoringChildControls(
                                    BaseModeContainer authoringContainer)
{
  Table table = new Table();
  TableRow tr = new TableRow();
  table.Rows.Add(tr);

  TableCell td1 = new TableCell();
  td1.Text = "Please enter a resource gallery path:";
  tr.Cells.Add(td1);

  TableCell td2 = new TableCell();
  txtResourceGalleryPath = new TextBox();
  td2.Controls.Add(txtResourceGalleryPath);
  tr.Cells.Add(td2);

  authoringContainer.Controls.Add(table);
}

We could have created an interface for authors to select a resource gallery from a tree or a list, and have the author choose from the resource galleries that he or she has access to, but let’s keep the sample simple for now and stick to a single textbox.

Saving the Selected Resource Gallery Path

When the posting is saved, the path of the resource gallery is stored as XML back to the underlying XmlPlaceholder in the following format:

<ResourceGallery>
  <Path>/resources/myimages/</Path>
</ResourceGallery>

You may be wondering why we choose to store the information as XML instead of HTML, since we are only interested in a single value, namely the path of the resource gallery containing the images. The reason is because, later on, should you decide to include more information such as a specific list of images instead of using all images in the gallery, they will be easier to store and extract if they are saved as XML. Add the overridden SavePlaceholderContent() method directly below the CreateAuthoringChildControls() method.

protected override void SavePlaceholderContent(PlaceholderControlSaveEventArgs e)
{
  EnsureChildControls();
  ((XmlPlaceholder)this.BoundPlaceholder).XmlAsString =
        "<ResourceGallery><Path>"
        + txtResourceGalleryPath.Text + "</Path></ResourceGallery>";
}