Placeholder Types

In CMS, there are three intrinsic placeholder controls and six definitions. Each placeholder control has a corresponding placeholder definition. The HTML and attachment placeholder controls can also be bound to the OfficeHtmlPlaceholderDefinition and OfficeAttachmentPlaceholderDefinition, respectively. The last placeholder definition type, the XMLPlaceholderDefinition, does not have a corresponding control. The most common use for this placeholder definition is in the development of custom placeholders. For more information on developing custom placeholders, refer to Chapter 29.

Each placeholder has its own "specialty" when it comes to content. Depending on the solution, one or more of these placeholders may be added to your templates. In the following sections, we'll discuss each of the three intrinsic controls and their corresponding definitions. Because of the overlap between each of the placeholder controls, we're only going to cover the differences between placeholders. For example, we'll cover a lot of background on the HTML placeholder but won't repeat the same information for the other placeholder controls unless there are significant differences.

HTML Placeholder

If any placeholder could be called the "bread and butter" placeholder, it would be the HTML placeholder. The HTML placeholder is probably the most commonly used placeholder in CMS, since it will generally accept any kind of content from HTML content (as the name suggests) to attachments (files uploaded to CMS) to images with no trouble at all.

General Usage

HTML placeholders can be used in a number of situations. Most commonly, they're used as a "big bucket" for content. In other words, since HTML placeholders can accept any kind of content, they're often used to allow content contributors to contribute a fairly wide variety of content. When template designers don't know the actual structure of the contributed content or feel that the structure is too complex to handle programmatically, they'll often provide one HTML placeholder configured to accept any content. Although this is one approach, we don't recommend it, but it does work in some cases.

In Figure 13-1, we show two HTML placeholders in the BOTS Consulting site. These two placeholders happen to be located on the press release template. If you look at the upper right corner of a placeholder, you should notice different icons. These icons provide a pictorial guide to the type of content that may be added to the placeholder. Each icon represents a specific setting for the placeholder. These settings determine what types of content can be contributed to the placeholder and how that content can be manipulated. For example, the first placeholder, the Press Release Body Copy placeholder, is configured to accept plain text, HTML styles, and hyperlinks. The second placeholder, Disclaimer Text, is configured to accept plain text, text markup, and hyperlinks. Although all placeholders have a version of these icons, the HTML placeholders have the most varied combination of potential icons.

Figure 13-1. HTML placeholders in the BOTS press release template


Depending on how the placeholder is configured, HTML placeholders will generally accept any content or formatting. Refer to Figure 13-1 again. Look near the top of the screen shot. Notice the two new toolbars. These toolbars are similar to any Office toolbar you may have seen in the past. These toolbars, for the HTML placeholder, provide the basic formatting options available to the content contributor. If you look closely at Figure 13-1, you'll notice that most of the buttons are grayed out. Based on the settings in the placeholder definition and the placeholder control, CMS will automatically eliminate functionality that is disabled. Now, if we move our cursor to the second placeholder, for the disclaimer text, notice how the toolbar changes in Figure 13-2. Notice that the drop-down list that showed Normal is grayed out now, and the B, I, and U buttons (for bold, italics, and underline) are enabled. Should a contributor add content that has invalid (disallowed) formatting applied (i.e., copying and pasting content), the formatting will be stripped out during the save operation (although it will initially appear as if the formatting were accepted).

Figure 13-2. The IE toolbars connected to the HTML placeholder


Now, let's take a look at another HTML placeholder that is set up to accept more formatting and content. In Figure 13-3, you'll see the Case Study Detail template. This template has two placeholders, both HTML. Looking at the Case Study Body Copy placeholder, you'll notice that the icons in the upper right corner indicate the additional types of content that can be contributed to this placeholder. The two paperclip icons (yes, they're paperclips) indicate that you can contribute attachments. In other words, a content contributor can upload one or more files to this placeholder. Each file or "attachment" will be displayed as a link. In addition, this placeholder allows images to be contributed in a similar fashion; the placeholder will accept one or more images. Unlike the attachment, when an image is contributed, it will automatically appear inside the placeholder. In Figure 13-4, you can see the same posting with an image and an attachment contributed.

Figure 13-3. A BOTS Consulting case study with the placeholder exposed


Figure 13-4. An image and an attachment contributed to the HTML placeholder


Now that you have a sense of what an HTML placeholder looks like in a template, let's take a closer look at how you set up this particular type of placeholder.


All placeholders in a template are really two objects: a placeholder definition in the template gallery item (TGI) and a placeholder server control. The setup of a placeholder is a combination of two of these objects (and is generically referred to as simply "a placeholder"). It doesn't matter which element you start with, since you need both for the placeholder to function properly. In our case, we'll review the placeholder control first and then review the placeholder definition.

All placeholder controls are located in the Toolbox in VS.NET. There are only three intrinsic placeholder server controls: HTML, Attachment, and Image. The HTML placeholder control is used with the HTMLPlaceholderDefinition and the OfficeHTMLPlaceholderDefintion. In Figure 13-5, you'll see a shot of the Toolbox in VS.NET listing the three controls we just mentioned. Keep in mind that the controls are only visible in the Toolbox if you're in Design view when reviewing a template file.

Figure 13-5. The intrinsic placeholder controls in the VS.NET Toolbox


If we want to add a placeholder to a template, we simply drag and drop that placeholder to the Web form. In doing so, a new object appears on our form. In our example, we created a new template file called "sample" to allow us to play with the placeholders. Once you've added your placeholder control to your template file, you can click it to see the object properties. Figure 13-6 shows the various properties that can be set at the object level, and the following list explains each setting.

  • BackColor: Controls the background color of the placeholder. The background color will be applied to each line of text individually.

  • BorderColor: Controls the border color of the placeholder.

  • BorderStyle: Determines if the placeholder has a border around it and what the border looks like.

  • BorderWidth: Determines the width of the border applied to the placeholder. Be careful with this setting. As much as it seems intuitive that the border will not frame the placeholder as a whole, it will actually frame each line of text; the result is not pretty.

  • CssClass: At design time or runtime, can be set to a specific CSS class. Keep in mind that authors could potentially override this property setting by changing font attributes during contribution.

  • Font: Determines the font that is used in the placeholder. This specific property has subproperties that determine the specific font attributes that can also be applied. Again, the content contributor could potentially override these settings.

  • ForeColor: Controls the color of the text in the placeholder. While you are editing, the chosen color won't be seen, but the font will assume the set color if you preview or save the page and view it in Edit or Live mode.

  • AllowHtmlSourceEditing: Allows content contributors to switch to a view of the content that exposes the HTML tags that are written in the background. This property should generally be set to False to prevent nontechnical users from accidentally changing the HTML tags. However, this property may be set to True for more advanced users and where more HTML editing flexibility is needed.

  • EnableAuthoring: Allows you to turn off authoring within a placeholder. This property should generally be set to True. One example of where this property may be used is when a developer needs to restrict access to a placeholder's content if the current user isn't an editor (an editorial comments placeholder, for example). The author should be able to read the content in the placeholder but not be able to change it. When an author is editing the posting, the property could be set to False. When the editor edits the posting, the property can be programmatically set to True.

  • EnableViewState: Controls whether the .NET view state is enabled.

  • ToolTip: Allows you to enter a string that will appear when you roll your mouse over the placeholder border in authoring mode and over the text in Live mode. Because the tooltip appears in Live mode, it may not be appropriate in all cases.

  • Visible: Determines whether the placeholder is visible at runtime. This setting affects both authoring and Live mode. Building on the example of a comments placeholder, this property would be useful for hiding the contents entirely when the page is published to the live site.

  • DataBindings: Is inherited from the System.Web.UI.Control namespace. For more information on the System namespace, please refer to

  • PlaceholderToBind: Defines to what placeholder definition the placeholder object is bound. The drop-down list for this property will only list compatible placeholder definitions. For example, you can't bind an image placeholder definition to an HTML placeholder object.

  • EditControlHeight: Determines the height, in pixels, of the control in authoring mode. This setting does not constrain the content in Live mode.

  • EditControlWidth: Determines the width, in pixels, of the control in authoring mode. This setting does not constrain the content in Live mode.

  • ID: Is inherited from System.Web.UI.Control. For more information on the System namespace, please refer to

Figure 13-6. The properties of an HTML placeholder in VS.NET


Now that we know the various object-level settings that we can apply to a placeholder, let's examine the placeholder definition for an HTML placeholder. To begin, switch to the Template Explorer in VS.NET. In our template gallery, we've created a corresponding TGI to match our new sample template. We used the same name for our TGI (sample). Once you've created the new TGI, find the property PlaceholderDefinitions. Click the ellipsis next to that property, and you should see the Placeholder Definition Collection Editor, shown in Figure 13-7.

Figure 13-7. The Placeholder Definition Collection Editor


If you've been reading this book from the beginning, you'll likely recognize this interface from Chapter 12. If you haven't been reading from the beginning, then it's new to you. In any event, this interface is the tool that you'll use to create the various placeholder definitions for each of your placeholder objects. You'll end up adding one placeholder definition to the collection for each placeholder control on your template.

Let's create a placeholder definition for the HTML placeholder we added earlier. To do so, simply click the Add button. Even though there are six placeholder definition types, CMS will create an HTML placeholder definition by default. If you want to create a different type, you can click the down arrow at the right of the Add button. Once you've created your new definition, you should see something like Figure 13-8.

Figure 13-8. A new placeholder definition in the Placeholder Definition Collection Editor


Once you have your new placeholder definition, you can begin to set the various properties for the definition. The settings for the HTML placeholder definition are explained in the following list.

  • AllowHyperlinks: Determines whether content contributors are allowed to contribute hyperlinks to the placeholder. Setting this property to False will disable the link icon in the placeholder toolbar. Keep in mind that if you set the placeholder to allow HTML editing, it's possible for the content contributor to manually enter a hyperlink into the placeholder.

  • AllowLineBreaks: Determines whether content contributors can insert line breaks in the content. This setting is useful when you want to use a placeholder for a title or you don't want content contributors to press Enter (or Shift-Enter) and insert blank lines in the content.

  • Formatting: Provides five options for text formatting.

    • NoFormatting: Does not allow any formatting to be applied to content in the placeholders.

    • FullFormatting: Allows all formatting possibilities to be applied to content in a placeholder. These options include HTML styles, bold, italics, font, font color, background color, alignment, lists (ordered and unordered), indenting, and tables. This is the only option that allows tables.

    • TextMarkup: Allows content contributors to apply basic bold, italics, and underlining to content.

    • HtmlStyles: Allows content contributors to apply HTML styles such as headings (H1, H2, and so on), Formatted, Address, and lists. Most HTML styles are supported. However, tables are not supported as a style.

    • TextMarkupandHtmlStyles: Is a combination of the text markup and HTML styles settings. This gets you pretty close to full control, allowing users to apply HTML styles as well as ad hoc bold, italics, and underline.

  • Description: Allows you to provide a description of a placeholder. The text entered into this field will show up as default text within the placeholder when a user creates a posting based on the template.

  • Name: Allows you to name the placeholder definition. This name will be the string index in the placeholder collection. Should you need to programmatically retrieve or modify content, you will use this name to access the placeholder object using the Publishing API.

  • Type: Returns the placeholder type (HTML, XML, Office, and so on). This is a read-only property.

  • AllowAttachments: Determines whether a content contributor can upload files to the placeholder.

  • AllowImages: Determines whether a content contributor can upload images to the placeholder.

  • MustUseResources: Is related to the AllowImages and AllowAttachments properties. It determines whether attachments or images have to come from a shared resource gallery or whether they can be uploaded from the contributor's local or network drive.

  • UseGeneratedIcon: Determines whether uploaded attachments are represented by icons or text links. CMS natively has all the Office icons, but less common files will get a generic icon.

Design Considerations

HTML placeholders can provide a tremendous amount of flexibility. However, there are several design considerations you should take into account when developing your template.

  • Generally, HTML placeholders provide enough flexibility for most authoring situations. Unfortunately, table editing is not a strength. Content contributors can easily create tables of specific column and row depth, but after the initial creation, it's not possible to edit the table definition. In order to edit tables once they've been created, you'll have to turn on HTML editing in the placeholder object or delete the existing table and re-create it.

  • Users who contribute images to an HTML placeholder will find they can't exercise enough control over the placement of that image, unless it has been copied and pasted from another source that defined the layout. For example, there's no easy way to add an align attribute to the image tag that's created when the image is contributed. The best way to provide this sort of flexibility is to create several placeholders, each specializing in a particular type of content. Then, arrange the content programmatically, or extract the raw content from the placeholder and "manually" render the values, hiding the placeholder control (set the Visible property to false). Alternatively, create the content in a tool like FrontPage or Dreamweaver, and copy and paste the HTML directly into the placeholder; images will have to be uploaded separately once you've copied the HTML framework over. Also, depending on the content, you can use the Authoring Connector and Word to appropriately format the content before it goes into CMS.

  • There's a small gap in authoring flexibility between the TextMarkupandHTMLStyles and the FullFormatting settings. Specifically, you have to set the placeholder to full control in order to allow tables. Your specific design will determine the best way to mitigate this situation, but we've found that it's generally not a huge problem to overcome.

  • CMS will strip out placeholder content that isn't allowed by the definition. This is generally a good thing. However, if a content contributor enters content that's outside the scope of a given placeholder, they won't realize that certain formatting or content isn't allowed until after they save. For example, even if you have the placeholder set to TextMarkup, a user could copy and paste a table from Word. Initially, the placeholder will display the table as it was in Word. When the user saves the content, however, the table will be stripped out. This is largely a training issue, but it can generate a help desk call or two.

NOTE: If the properties of the placeholder are changed on an existing template and made more restrictive, the original content will continue to be displayed until that page is edited. Once the page is edited, the old content will be displayed for authoring, but on save, the now invalid formatting will be stripped out.

Single Attachment Placeholder

The single attachment placeholder (attachment placeholder) is used to allow content contributors to upload files to a posting. In truth, the attachments may not always be uploaded directly from the contributor's machine to a posting; essentially, the attachment placeholder allows content contributors to display a link to a file within the context of their posting. The actual file could be stored in a resource gallery, or it could have been uploaded from a local source directly to the posting. Either way, the attachment will reside in the CMS repository once it has been contributed (preventing broken links). In Figure 13-9, an attachment placeholder is shown on the attachment template for BOTS Consulting.

Figure 13-9. An attachment placeholder on the attachment template in BOTS Consulting


General Usage

The attachment (or single attachment) placeholder is useful in a number of situations. At a very basic level, it's useful for allowing content contributors to upload files to CMS. Unlike the HTML placeholder, however, the attachment placeholder only allows one file per placeholder. However, this is only part of the story. It's also possible to use the attachment placeholder to integrate Flash (Macromedia) into your design. A user can contribute the Flash movie to the placeholder, and then the template will extract the resulting link to integrate with an object tag in the HTML


As you saw in Figure 13-9, the attachment placeholder looks quite different from the HTML placeholder. As with the HTML placeholder, a paperclip indicates an attachment, except that in the case of the attachment placeholder, the paperclip is a button in the upper left. This button also allows you to choose the attachment the placeholder will hold. You'll also notice that there are other buttons located in the upper left. The button immediately to the right of the paperclip allows content contributors to set the display name of the attachment, and the last button (the X) allows content contributors to clear the value in the placeholder. Let's switch to VS.NET and explore the attachment placeholder object.

We're using the same sample template we used when talking about the HTML placeholder. In this template, we've now added an attachment placeholder. In Figure 13-10, you can see the template with both the HTML and attachment placeholders added to the Web form. Notice that there isn't any visible difference, except that the label on the control is SingleAttachmentPlaceholder.

Figure 13-10. An attachment placeholder on the sample template


The single attachment placeholder shares most of the same properties as the HTML placeholder properties. In fact, the attachment placeholder has fewer properties, since there's much less flexibility to determine display characteristics. Most notably, there aren't any height and width properties; attachment placeholders are always the same size. However, even though we have a placeholder definition for our HTML placeholder, if you use the drop-down list for the PlaceholderToBind property, you'll notice that the HTML placeholder definition isn't listed. Again, this property will only list compatible types. In the case of the attachment placeholder, the only compatible definition types are AttachmentPlaceholderDefinition and OfficeAttachmentPlaceholderDefinition.

Once we've created the new placeholder definition, let's look at each of the properties. The following list provides a brief explanation of each.

  • Description: Allows you to provide a description of a placeholder.

  • Name: Allows you to name the placeholder definition.

  • Type: Returns the placeholder type (HTML, XML, Office, and so on). This is a read-only property.

  • MustUseResources: Determines whether attachments or images have to come from a shared resource gallery or can be uploaded from the contributor's local or network drive.

  • UseGeneratedIcon: Determines whether uploaded attachments are represented by icons or text links. CMS natively has all the Office icons, but less common files will get a generic icon.

Design Considerations

The attachment placeholder is a pretty simple animal. However, there are some design considerations that you should be aware of when developing templates with this placeholder type.

  • Attachment placeholders, by default, display either the display name of the attachment or an icon. This may be the desired behavior. However, if the only elements on a template are an attachment and a longer description (likely in an HTML placeholder), consider building an attachment redirect template. Code samples and an explanation are provided in Chapter 36.

  • If you allow content contributors to use local resources, as opposed to using share resources from the resource gallery, each attachment becomes a unique entity. Even if two files are exactly the same, CMS has no way of knowing and will create a new entity for the duplicate file, thereby doubling the storage requirement for that attachment. Strongly consider using the resource galleries to control what files are used in your site. Not only do resource galleries provide a little more content control, but attachments that are used more than once will not be duplicated, and if the resource changes, the change will cascade across the site.

  • If a content contributor uploads a local resource to an attachment and then later deletes it, the orphaned asset will be removed from the database when the nightly CMS cleanup occurs (assuming the SQL agent is enabled on your server).

  • If you have to visually represent an attachment placeholder differently from the default behavior, it's very easy to get the URL and display text back from the placeholder, as well as set the icon used for the file programmatically. The AttachmentPlaceholder class in the PAPI provides a granular selection of properties to enable extracting what you need.

Single Image Placeholder

The image placeholder allows content contributors contribute images to a posting. As with the attachment placeholder, this object is used when you want to have a single object in a container, as opposed to having multiple images or attachments in an HTML placeholder. In Figure 13-11 you can see what a single image placeholder looks like in the BOTS Consulting site. In this case, the image placeholder is used as a call-out image on the General template.

Figure 13-11. A single image placeholder in the BOTS Consulting site


General Usage

Overall, single image placeholders are useful when you need to allow a content contributor to provide a single image for an element of a page. This sounds a little obvious, but like the attachment placeholder, this is really the "single" alternative to allowing multiple attachments or images in an HTML placeholder. This is not to suggest that if you have a single image placeholder on a template, you only need one image. In fact, you can effectively have more than one image placeholder on a template. It's very likely that you will prefer this design, since it provides a lot more control over the visual design of your end page.

The single image interface is similar to that of the attachment placeholder. Notice that at the upper left of the placeholder, there are three buttons. The first button indicates that this is an image placeholder (although the "place picture here" default image probably gave it away as well). It also allows you to browse to the image that you want to add to the placeholder, in the same way that the attachment placeholder did. The next two buttons provide the ability to change the ALT attribute for the resulting image tag and to clear the placeholder contents. Let's switch to VS.NET and explore the properties of this placeholder object.


In Figure 13-12, you can see what the image placeholder object looks like in VS.NET.

Figure 13-12. The single image placeholder in the sample template


Again, there isn't any visual difference beyond the label that CMS provides on the object. However, there are some differences with regard to the properties. The image placeholder allows you to size the display height and width. Unlike with the HTML placeholder, these settings don't affect authoring, but they do affect the live site view. In essence, the properties DisplayHeight and DisplayWidth control the scaling of the image; physically, these properties are represented as the height and width attributes of the resulting image tag.

Now, let's look at the single image placeholder definition. Open the Placeholder Definition Collection Editor and create a new image placeholder definition. Remember to use the down arrow next to the Add button to add a definition other than an HTML definition. In Figure 13-13 we've provided a screen shot of the Placeholder Definition Collection Editor.

Figure 13-13. The Placeholder Definition Collection Editor with the new image placeholder definition


In the definition there are several properties of note. The following list provides a brief description of each.

  • AllowHyperlinks: Allows you to determine whether you will allow content contributors to provide a hyperlink on the image.

  • Description: Allows you to provide a description of a placeholder.

  • Name: Allows you to name the placeholder definition.

  • Type: Returns the placeholder type (HTML, XML, Office, and so on). This is a read-only property.

  • MustUseResources: Determines whether images have to come from a shared resource gallery or can be uploaded from the contributor's local or network drive.

Design Considerations

As with the single attachment placeholder, the single image placeholder is a pretty straightforward control. However, here are some design considerations for when you develop your template.

  • During authoring, there's no way to stipulate alignment for an image. In other words, there's no way to specify the align attribute of the image tag that's rendered in presentation (Live) mode. If you want to provide authors with the ability to align images when they contribute them, consider using a custom property on the template that specifies the image alignment. The value of the custom property can be extracted programmatically and used to provide the alignment value desired. Programmatically, you can simply set the attributes of the resulting image tag using the Attributes property.

  • If you use the DisplayHeight and DisplayWidth properties of the image placeholder, keep in mind that the control will scale the image. It will not resize the image. This behavior could have undesirable results. However, not stipulating a height and width for an image tag will cause the browser to take longer to render the page. One solution would be to set up specific resource galleries that hold images of a particular size. These galleries would correspond to the image placeholder sizes on your templates.

Microsoft Content Management Server 2002. A Complete Guide
Microsoft Content Management Server 2002: A Complete Guide
ISBN: 0321194446
EAN: 2147483647
Year: 2003
Pages: 298 © 2008-2017.
If you may any questions please contact us: