Working with Placeholder Members

We will focus on the read-only members first (there are only a few). We start with a comprehensive code sample and then provide an alphabetical list of read-only members specific to a Placeholder object. Then we focus on read/write members. Again, we start with a comprehensive code sample followed by an alphabetical list of read/write members specific to a Placeholder object.

Read-Only Members

The code to see all the read-only placeholder members is presented comprehensively. Sometimes it just helps to see the output of a property to better understand it.

Replace the Button1_Click function of our Scratchpad template file with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Put current Posting into variable   Posting cmsPosting = CmsHttpContext.Current.Posting;   //2. Grab the first Placeholder to view   Placeholder cmsPlaceholder = cmsPosting.Placeholders[0]     as Placeholder;   //3. Check to see if we found the specified Placeholder   if (cmsPlaceholder != null)   {     //4. Populate the label with the read-only properties     Label1.Text =       "<b>GetHashCode: </b>" +         cmsPlaceholder.GetHashCode().ToString() +       "<br><b>GetType: </b>" +         cmsPlaceholder.GetType().ToString() +       "<br><b>Name: </b>" +         cmsPlaceholder.Name.ToString();   } } 

Build the solution and then refresh the Scratchpad posting in Internet Explorer, or browse to it and click the Button. The page should reload and look similar to Figure 27-6.

Figure 27-6. Show read-only placeholder members

Read-Only Members for a Placeholder

GetHashCode

The GetHashCode method retrieves the hash code for the object. Notice that the actual number returned is different each time.

This identifier is not frequently used by the developer.

GetType

The GetType method retrieves the name of the namespace for the instance that the object represents.

This member can be useful for determining what kind of placeholder is in use.

Name

The Name property holds the actual name for the referencing placeholder. However, this Name is different from other names we have encountered. It is read-only rather than read/write. So it is not as big a risk for the display hack (see the Avoid Hack by Using HtmlEncode sidebar in Chapter 25). This property must be unique. The value of the Name property is set at runtime and defaults to the name of the placeholder on which it is based.

The maximum length is 100 characters for any string displayed in this property. Typical alphanumeric characters are allowed, but we recommend against using spaces in any Names.

This member can be useful for getting the name of the specific Placeholder object so that it can be used in other searches.

Read/Write Members for a Placeholder

BeginWrite, EndWrite, RetrieveContent, and SaveContent are all protected members that are accessed from the placeholder-specific classes on our behalf. Suffice it to say that altering members for a Placeholder object requires the implementation and calling of the BeginWrite method to start the process and validate that the user has sufficient rights to update the placeholder. Saving a modified Placeholder object requires the implementation and calling of the EndWrite method. Likewise, retrieving and saving content requires that the RetrieveContent and SaveContent methods be called.

Datasource, Datasource.RawContent

The Datasource property and its singular RawContent property will not likely be used unless you are creating a custom control. It is recommended that you use the specific placeholder property that returns the content in a format specific to that placeholder rather than using its raw format. It is very uncommon to need to iterate through the placeholders on a template. Typically, we want to interact with a specific placeholder of a specific type. It is typically best to cast a Placeholder object and its PlaceholderDefinition as specifically as we can.

If a Placeholder object is temporary, as in the placeholder creation example, calling the protected methods is not necessary, because a transaction isn't needed to keep the Datasource in sync.

A very simple example of accessing the DataSource RawContent property follows.

Replace the Button1_Click function of our Scratchpad template file with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Put current Posting into variable   Posting cmsPosting = CmsHttpContext.Current.Posting;   //2. Grab the first Placeholder to view   HtmlPlaceholder cmsPlaceholder = cmsPosting.Placeholders[0]     as HtmlPlaceholder;   //3. Check to see if we found the specified Placeholder   if (cmsPlaceholder != null)   {     //4. Populate the label with the RawContent of the Placeholder     Label1.Text = "<b>RawContent: </b><p>" +       cmsPlaceholder.Datasource.RawContent.ToString();   } } 

Build the solution and then refresh the Scratchpad posting in Internet Explorer, or browse to it and click the Button. The page should reload and look similar to Figure 27-7.

Figure 27-7. RawContent

Again, you would be ill advised to use this polymorphic property, because it could be changed in any release of CMS, and the code written against the raw format could fail.