Working with PlaceholderDefinition Members | Microsoft Content Management Server 2002: A Complete Guide

We will use the same approach with PlaceholderDefinition that we took with Placeholder: read-only members first followed by nonprotected read/write members.

Read-Only Members

The code to see all the read-only PlaceholderDefinition members is presented comprehensively.

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 Template into variable   Template cmsTemplate = CmsHttpContext.Current.Posting.Template;   //2. Grab the first PlaceholderDefinition to view   PlaceholderDefinition cmsDefinition =     cmsTemplate.PlaceholderDefinitions[0]     as PlaceholderDefinition;   //3. Check to see if we found the specified PlaceholderDefinition   if (cmsDefinition != null)   {     //4. Populate the label with the read-only properties     Label1.Text = "Read Only PlaceholderDefinition Members";     //5. Add to label info about GetAttributes     if (cmsDefinition.GetAttributes() != null)       if (cmsDefinition.GetAttributes().Count > 0)         Label1.Text += "<br><b>GetAttributes[0] TypeID: </b>" +           cmsDefinition.GetAttributes()[0].TypeId.ToString();       else         Label1.Text += "<br><b>GetAttributes Count: </b>" +           cmsDefinition.GetAttributes().Count.ToString();     else       Label1.Text += "<br><b>GetAttributes: </b>none";     //6. Add to label info about GetClassName     Label1.Text += "<br><b>GetClassName: </b>" +       cmsDefinition.GetClassName().ToString();     //7. Add to label info about GetComponentName     Label1.Text += "<br><b>GetComponentName: </b>" +       cmsDefinition.GetComponentName().ToString();     //8. Add to label info about GetConverter     Label1.Text += "<br><b>GetConverter: </b>" +       cmsDefinition.GetConverter().ToString();     //9. Add to label info about GetDefaultEvent     if (cmsDefinition.GetDefaultEvent() != null)       Label1.Text += "<br><b>GetDefaultEvent DisplayName: </b>" +         cmsDefinition.GetDefaultEvent().DisplayName.ToString();     else       Label1.Text += "<br><b>GetDefaultEvent: </b>none";     //10. Add to label info about GetDefaultProperty     if (cmsDefinition.GetDefaultProperty() != null)       Label1.Text += "<br><b>GetDefaultProperty: </b>" +         cmsDefinition.GetDefaultEvent().ToString();     else       Label1.Text += "<br><b>GetDefaultProperty: </b>none";     //11. Add to label info about GetClassName     if (cmsDefinition.GetEvents() != null)       if (cmsDefinition.GetEvents().Count > 0)         Label1.Text += "<br><b>GetEvents[0] DisplayName: </b>" +           cmsDefinition.GetEvents()[0].DisplayName.ToString();       else         Label1.Text += "<br><b>GetEvents Count: </b>" +           cmsDefinition.GetEvents().Count.ToString();     else       Label1.Text += "<br><b>GetEvents: </b>none";     //12. Add to label info about GetHashCode     Label1.Text += "<br><b>GetHashCode: </b>" +       cmsDefinition.GetHashCode().ToString();     //13. Add to label info about GetProperties     if (cmsDefinition.GetProperties() != null)       if (cmsDefinition.GetProperties().Count > 0)         Label1.Text += "<br><b>GetProperties[0] DisplayName: " +           "</b>" + cmsDefinition.GetProperties()[0].DisplayName           .ToString();       else         Label1.Text += "<br><b>GetProperties Count: </b>" +           cmsDefinition.GetProperties().Count.ToString();     else       Label1.Text += "<br><b>GetProperties: </b>none";     //14. Add to label info about GetType     Label1.Text += "<br><b>GetType: </b>" +       cmsDefinition.GetType().ToString();     //15. Add to label info about IsReadOnly     Label1.Text += "<br><b>IsReadOnly: </b>" +       cmsDefinition.IsReadOnly.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-8.

Figure 27-8. Read-only PlaceholderDefinition members

graphics/27fig08.jpg

Read-Only Members for a PlaceholderDefinition

All of the following properties are inherited from the CustomReflectionObject:

GetAttributes
GetClassName
GetComponentName
GetConverter
GetDefaultEvent
GetDefaultProperty
GetEvents
GetProperties

GetHashCode, GetType

The same as Placeholder.

IsReadOnly

The IsReadOnly property retrieves the Boolean value that indicates whether the PlaceholderDefinition can be modified or not. If it returns true, the PlaceholderDefinition is read-only, and any attempt to set a property will result in an exception.

A PlaceholderDefinition can become read-only if it is cloned with the optional parameter set to true.

Read/Write Members

As before, the code to see all the read/write PlaceholderDefinition members is presented comprehensively. All these members can be assigned a value in code or through various other user interfaces. However, none of these changed values will become permanent until CommitAll is called on the Context. Uncommitted changes can be discarded by calling RollbackAll. If neither method is explicitly called when the Context in which the change is made is destroyed (goes out of scope or is disposed of), the disposition of the changes will be decided by the value of the RollbackOnSessionEnd property. By default, this property is false, so all changes are committed. In general, the properties of deleted or marked-for-delete PlaceholderDefinitions and historical revisions can't be altered.

Properties can only be altered when the PlaceholderDefinition is retrieved from the PlaceholderDefinitions collection property of a Template object rather than the Definition property of a Posting object's Placeholder property. Of course, the user must have sufficient rights (the Posting object's CanSetProperties property must return true), and the mode must be in Update PublishingMode.

Setting a property may change the state of a template and any ConnectedTemplates.

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 Template into variable   Template cmsTemplate = CmsHttpContext.Current.Posting.Template;   //2. Grab the first PlaceholderDefinition to view   PlaceholderDefinition cmsDefinition =     cmsTemplate.PlaceholderDefinitions[0]     as PlaceholderDefinition;   //3. Check to see if we found the specified PlaceholderDefinition   if (cmsDefinition != null)   {     //4. Populate the label with the read-only properties     Label1.Text = "Read Write PlaceholderDefinition Members";     //5. Add to the label with PlaceholderDefinition Description     Label1.Text += "<br><b>Description: </b>" +       HttpUtility.HtmlEncode(cmsDefinition.Description.ToString());     //6. Add to the label with PlaceholderDefinition Name     Label1.Text += "<br><b>Name: </b>" +       HttpUtility.HtmlEncode(cmsDefinition.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-9.

Figure 27-9. Read/write PlaceholderDefinition members

graphics/27fig09.gif

Read/Write Members for a PlaceholderDefinition

As with Placeholders, BeginWrite, EndWrite, and BeginRead are all protected members that are accessed by the PlaceholderDefinition-specific classes on our behalf. Suffice it to say that altering members for a PlaceholderDefinition 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 PlaceholderDefinition. To save a modified PlaceholderDefinition object requires the implementation and calling of the EndWrite method. BeginRead should be implemented and called whenever a PlaceholderDefinition property is read.

The OnCloned method can be implemented to create a proprietary solution when a PlaceholderDefinition is cloned. If this method is implemented, it overrides the default behavior discussed earlier in this chapter.

Description (Inherited from HierarchyItem)

The Description property holds the free-form text description (see the Avoid Hack by Using HtmlEncode sidebar in Chapter 25) for the referencing PlaceholderDefinition.

CMS automatically trims leading and trailing spaces and truncates the length to 500 characters for any string assigned to this property. Typical alphanumeric characters are allowed.

This member can be useful for setting and showing a verbose description of the PlaceholderDefinition that the user is using.

Name (Inherited from HierarchyItem)

The Name property holds the free-form text of the actual name for the referencing PlaceholderDefinition. This name is not intended for display (see the Avoid Hack by Using HtmlEncode sidebar) per se but is visible to the user in the URL and Path. This property is not allowed to be empty and must be case-insensitive unique within the collection.

CMS automatically trims leading and trailing spaces and truncates the length to 100 characters for any string assigned to this property. Typical alphanumeric characters are allowed, but we recommend against using spaces in PlaceholderDefinition names.

This member can be useful for setting and showing the Name of the PlaceholderDefinition.