Working with Channel Members

Channels have a vast store of characteristics to be tapped by the developer using PAPI. Some can be changed in code, while others are for retrieval only. We focus on the read-only members first. We start with a comprehensive code example, then an alphabetical list of read-only members specific to Channel objects, followed by an alphabetical list of read-only members inherited for use by Channel objects.

Then we focus on read/write members. Again, we start with a comprehensive code example, then an alphabetical list of read/write members specific to Channel objects, followed by an alphabetical list of read/write members inherited for use by Channel objects.

There are some common facts and concepts about CMS dates that will help us throughout the list of members (see the CMS Dates sidebar for details).

CMS Dates

All date and time fields use Coordinated Universal Time. The time can be converted to local time using the ToLocalTime method like this:

 x = CmsHttpContext.Channel.ChangeDate.ToLocalTime; 

ToLocalTime can also be used in client-side JavaScript so that the time zone on the browsing PC is used rather than the time zone on the server.

To indicate that a ChannelItem object never expires, set the date and time property to January 01, 3000. If the date property is January 01, 3000, this property is displayed using the string "Never" in the corresponding user interfaces. Similarly, script should be written so that a date of January 01, 3000 is displayed by your code as the string "Never".

Table 25-2 summarizes the five channel date and time fields and how they relate to one another.

After a channel has been deleted but before it is committed, all properties become read-only. However, even after a deleted channel is committed, it may still reside in an in-memory collection. IsDeleted is one of the few properties that can still be read after a deletion and before a commit. Most other properties will cause an exception if they are referenced.

Table 25-2. Channel Date and Time Fields

Created Date	ChangeDate	StartDate	ExpiryDate	LastModified Date	RevisionDate
Date created. Never changes.	Date of implicit change. Equal to most recent date greater than today: LastModifiedDate, StartDate, or ExpiryDate.	Date object becomes visible. Always less than ExpiryDate. Within range of parent StartDate and ExpiryDate.	Date object ceases to be Visible. Always more recent than StartDate. Within range of parent StartDate and ExpiryDate	Date of explicit change. Always more recent than or equal to CreatedDate.	Date of most recent ChangeDate for revisions, if any. If January 01, 3000, there is not a historical revision.

Historical revisions of a channel don't typically keep the value that was associated with the revision when it was the current version. The following properties are the only ones that can be different across all revisions: ChangeDate, CreatedBy, CreatedDate, Description, and Revision Date. All other properties represent the value of the current revision regardless of the value when the historical revision was the current revision. Attempting to assign a value to these properties for a historical revision will result in an exception.

Read-Only Members

The code to see all the read-only Channel object members is presented comprehensively. Sometimes it just helps to see the output of a property to better understand it, but we don't want to mess with a million code examples.

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 Channel into variable   Channel cmsChannel = CmsHttpContext.Current.Channel;   //2. Populate the label with read-only properties of a Channel   Label1.Text =     "<br><b>IsRoot: </b>" + cmsChannel.IsRoot.ToString() +     "<br><b>Channel: </b>" + cmsChannel.Name.ToString() +     "<br><b>ChangeDate: </b>" + cmsChannel.ChangeDate.ToString() +     "<br><b>CreatedBy: </b>" + cmsChannel.CreatedBy.ToString() +     "<br><b>CreatedDate: </b>" +       cmsChannel.CreatedDate.ToString() +     "<br><b>DisplayPath: </b>" +       cmsChannel.DisplayPath.ToString() +     "<br><b>GetHashCode: </b>" +       cmsChannel.GetHashCode().ToString() +     "<br><b>GetType: </b>" + cmsChannel.GetType().ToString() +     "<br><b>Guid: </b>" + cmsChannel.Guid.ToString() +     "<br><b>IsDeleted: </b>" + cmsChannel.IsDeleted.ToString() +     "<br><b>IsDescendantOf: </b>" +       cmsChannel.IsDescendantOf(cmsChannel.Parent).ToString() +     "<br><b>IsWorkingRevision: </b>" +       cmsChannel.IsWorkingRevision.ToString() +     "<br><b>LastModifiedBy: </b>" +       cmsChannel.LastModifiedBy.ToString() +     "<br><b>LastModifiedDate: </b>" +       cmsChannel.LastModifiedDate.ToString() +     "<br><b>OwnedBy: </b>" + cmsChannel.OwnedBy.ToString() +     "<br><b>Path: </b>" + cmsChannel.Path.ToString() +     "<br><b>QueryString: </b>" +       cmsChannel.QueryString.ToString() +     "<br><b>QueryStringModeUnpublished: </b>" +       cmsChannel.QueryStringModeUnpublished.ToString() +     "<br><b>QueryStringModeUpdate: </b>" +       cmsChannel.QueryStringModeUpdate.ToString() +     "<br><b>RevisionDate: </b>" +       cmsChannel.RevisionDate.ToString() +     "<br><b>Url: </b>" + cmsChannel.Url.ToString() +     "<br><b>UrlInner: </b>" + cmsChannel.UrlInner.ToString() +     "<br><b>UrlInnerPlain: </b>" +       cmsChannel.UrlInnerPlain.ToString() +     "<br><b>UrlModePublished: </b>" +       cmsChannel.UrlModePublished.ToString() +     "<br><b>UrlModeUnpublished: </b>" +       cmsChannel.UrlModeUnpublished.ToString() +     "<br><b>UrlModeUpdate: </b>" +       cmsChannel.UrlModeUpdate.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 25-7.

Figure 25-7. Show read-only members

Read-Only Members Specific to Channels

IsRoot

The IsRoot property is the only read-only member of the Channel object that is not inherited from another class. As discussed at the beginning of this chapter, there can only be one RootChannel, and it is built in to CMS. It is always called /Channels. If the Channel represented by the object is the built-in CMS RootChannel, it will return true; otherwise, it will return false.

This member can be useful for determining when we are at the top of the channel hierarchy when dynamically building navigation or a breadcrumb display. It is essentially a shortcut for determining if the current object equals the RootChannel.

Read-Only Members Inherited for Use by Channels

ChangeDate (Inherited from ChannelItem)

The ChangeDate property retrieves the date and time of the latest implicit change. It has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section. This date can change without any user interaction. The passage of time could bring a ChannelItem to its StartDate or its ExpiryDate, resulting in a change in ChannelItem status. The date of these implicit changes is recorded here. So, this date will be equal to the most recent LastModifiedDate, StartDate, or ExpiryDate that is greater than today.

This member can be useful for identifying fresh content on a Web Property.

CreatedBy (Inherited from HierarchyItem)

The CreatedBy property retrieves a User object indicating the user that created the referencing ChannelItem.

This member can be useful for showing a few characteristics about the user that created the ChannelItem.

CreatedDate (Inherited from HierarchyItem)

The CreatedDate property retrieves the date and time that the ChannelItem was created. It has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section.

This member can be useful for showing the date and time that the ChannelItem was created or identifying aged information still found on a Web Property.

DisplayPath (Inherited from ChannelItem)

The DisplayPath property retrieves the fully qualified path using the DisplayName rather than the Name of the ChannelItems involved. The DisplayPath begins, ends, and is delimited with a forward slash ("/"). The RootChannel is concatenated sequentially with the name of each ChannelItem in the object's ancestry.

This member can be useful for showing the full path to this Channel Item but can be used as input to the Searches method of a Context or for dynamically constructing a URL.

GetHashCode (Inherited from CmsObject)

The GetHashCode method retrieves the hash code for the object.

This identifier is not frequently used by the developer.

GetType (Inherited from System.Object)

The GetType method retrieves the name of the namespace for the instance that the object represents. For example, Channel objects will always return Microsoft.ContentManagement.Publishing.Channel.

This member can be useful for determining what kind of object is represented by an item in the AllChildren Collection, the ChannelItem property of a CmsHttpContext, or the result of Context Searches.

Guid (Inherited from HierarchyItem)

A GUID property by definition contains a globally unique identifier. This is generated when the object is created and committed into the CMS Repository, and it never changes. Effectively a candidate key, the GUID is alphanumeric, 32 characters long, separated by dashes, generated in part by the hardware on which the code is running, and guaranteed to be unique across the globe forever.

When a new ChannelItem has been created but has yet to be committed, a temporary, all zero GUID is used.

This member can be especially useful for searching for a ChannelItem in a Context. This property was employed in the code example for creating a new ChannelItem earlier in this chapter. Since the assigned GUID doesn't change (like Name and therefore Path can), an object's GUID is a good candidate to be held in application state (query string, form element, view state, and cookie, to name a few), used to dynamically construct URLs (it contains no special characters), or used to index a custom collection.

IsDeleted (Inherited from HierarchyItem)

The IsDeleted property retrieves a Boolean value that indicates whether the referencing ChannelItem has been deleted or not. It will be true if the referencing ChannelItem has been deleted.

This member can be useful to check through a collection when a user wants to undo a deletion before a commit. After a committed delete, this member is obviously useful to determine whether a specific object in a collection has been deleted or not. If it has, we avoid accessing any other method so as not to invoke an exception. This property was employed in the code example for creating and deleting the Channel Item hierarchy earlier in this chapter.

IsDescendantOf (Inherited from HierarchyItem)

The IsDescendantOf method determines whether the referencing ChannelItem is an eventual child of another ChannelItem object. This is the only ChannelItem member that requires a parameter. We must indicate what object we want to verify is the referencing ChannelItem's ancestor.

This member can be useful for dynamically creating navigation and breadcrumbs.

IsWorkingRevision (Inherited from HierarchyItem)

The IsWorkingRevision property retrieves a Boolean value that indicates whether the referencing ChannelItem is a working revision (work in progress) rather than a historical revision. It will be true if it is a working revision. Working revisions can be edited, whereas historical revisions cannot.

This member can be useful to determine if an edit will, regardless of user rights, even be possible.

LastModifiedBy (Inherited from HierarchyItem)

The LastModifiedBy property returns a User object indicating the user that created the referencing ChannelItem. It is the same as the Created By property if the referencing ChannelItem has never been modified.

This member can be useful for showing a few characteristics about the user that last modified the ChannelItem.

LastModifiedDate (Inherited from HierarchyItem)

The LastModifiedDate property has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section.

This member can be useful for showing the date and time that the ChannelItem was last modified or for identifying aged/fresh information found on a Web Property.

OwnedBy (Inherited from HierarchyItem)

The OwnedBy property returns a User object indicating the user that currently owns an object. When a user begins updating properties for a ChannelItem, they become the OwnedBy user unless someone else is making changes. Only one person at a time is allowed to make changes to a ChannelItem, so there is a kind of automatic checkout process to prevent users from concurrently updating the same object. In communist states, this property can return a value of Everybody. When that happens, the ChannelItem becomes community property edit at will, comrade.

This member can be useful to find out who is currently editing the object that we want to edit. If code isn't calling CommitAll quickly enough, this can wreak havoc on a busy site.

Path (Inherited from HierarchyItem)

The Path property retrieves the fully qualified path using the Name property of the ChannelItems involved. The Path begins and ends with and is delimited by a forward slash ("/"). The RootChannel is concatenated sequentially with each ChannelItem in the object's ancestry.

This member can be useful for searching for a ChannelItem using the GetByPath Context Searches method when using a GUID is impractical.

QueryString, QueryStringModeUnpublished, QueryStringModeUpdate (All Inherited from ChannelItem)

All three of these properties retrieve the URL query string parameters used to view the referencing ChannelItem. The QueryString property will present the parameters to use the same mode as currently in use, while the QueryStringModeUnpublished and QueryStringModeUpdate will present the parameters that could be used to navigate to the referencing ChannelItem in Unpublished or Update PublishingMode, respectively.

These members can be useful to redirect the user to the same ChannelItem in a different mode or to dynamically create a link.

RevisionDate (Inherited from HierarchyItem)

The RevisionDate property has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section.

This member can be useful for showing the date and time that the ChannelItem was last revised or for identifying aged/fresh information found on a Web Property.

Url (Inherited from ChannelItem)

The Url property retrieves the root relative URL for the referencing ChannelItem that will execute the OuterScriptFile (see the OuterScript File property in the Read/Write Members section later in this chapter), if any.

This member can be useful to redirect the user to the same Channel Item in the same mode or to dynamically create a link.

UrlInner (Inherited from ChannelItem)

The UrlInner property retrieves the root relative URL for the referencing ChannelItem that will not execute the OuterScriptFile (see the OuterScriptFile property in the Read/Write Members section later in this chapter), if any.

This member is not frequently used.

UrlInnerPlain (Inherited from ChannelItem)

The UrlInnerPlain property retrieves the root relative URL for the referencing ChannelItem that will not execute the OuterScriptFile (see the OuterScriptFile property in the Read/Write Members section later in this chapter), if any, nor will it propagate any query string parameters from the current request.

This member is not frequently used.

UrlModePublished, UrlModeUnpublished, UrlModeUpdate (All Inherited from ChannelItem)

All three of these properties retrieve a root relative URL for the referencing ChannelItem based upon site configuration. Hierarchy-based sites will retrieve a path-based URL, while Node-ID-based sites will retrieve a GUID-based URL. Both URL versions accomplish the same function. The UrlModePublished, UrlModeUnpublished, and UrlMode Update will present the URL that could be used to navigate to the referencing ChannelItem in Published, Unpublished, or Update Publishing Mode, respectively.

These members can be useful to redirect the user to the same ChannelItem in a specific mode or to dynamically create a link to that mode.

Read/Write Members

As before, the code to see all the read/write Channel object 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 RollbackOn SessionEnd property. By default, this property is false, so all changes are committed. In general, the properties of historical revisions can't be altered.

It is highly recommended that template file developers validate any date set to be sure that it is within the acceptable range for that property. Otherwise, CMS will have to alter it to be within the acceptable range when the change is committed. No message is generated when CMS changes the date, so the user could be surprised by the change. This problem can easily be avoided by validating dates before committing them.

As we discovered earlier, a user must have sufficient rights to make changes to any property, and the Context must be in an Update Publishing Mode (see the Getting into Update PublishingMode sidebar earlier in this chapter). It is always wise to place the verification that a user has sufficient rights and the actual modification of a property within a .NET try/catch block.

Avoid Hack by Using HtmlEncode

Users will likely be allowed by your Web Property to enter free-form text in properties like the Channel Name, DisplayName, and Description. In the likely event that those properties are rendered back to the user's browser on a posting, the template file developer should be aware of the following underlying risk.

Typical users will simply enter the text that was intended, and everything will work as smoothly as planned. But it is possible for the user to enter any text into those properties, including HTML or even script. A malicious or misguided user could enter values that might be undesirable or even hazardous. Consider the following benign examples.

The user enters the following text in the channel description:

Really cool <a href=http://homepage.com>home page</a>.

When the channel description is rendered, the browser evaluates the text and displays

Really cool home page.

where "home page" is a clickable link.

Or worse, the user enters the following text in the channel description:

Really <script language=VBScript>Function body_onclick() Msgbox ('Gotcha') End Function</script> cool Channel.

When the channel description is rendered, the browser evaluates the text and displays

Really cool Channel.

Assuming that the HTML body tag (or some other tag) has an "id=body", which anyone could discover by simply viewing the source sent to their browser, when the user clicks anywhere on the body of the page, they will get a pop-up dialog containing the message "Gotcha".

This out-of-sight hack could go undetected for a long time. A creative user could really wreak havoc, running potentially malicious scripts in windows that open behind the main page as the page is loading, or worse.

To prevent this kind of attack, we recommend that the template developer use the HtmlEnode method of System.Web.HttpUtility to prevent the browser from interpreting the text in the property.

So, rather than coding like this:

 x = CmsHttpContext.Current.Channel.Description; 

protect yourself and code like this:

[View full width]
 x = HttpUtility.HtmlEncode(CmsHttpContext.Current.Channel .Description); 

An ounce of prevention, you know.

The read/write properties we can set in code using PAPI can also be set using the Site Manager interface.

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 Channel into variable   Channel cmsChannel = CmsHttpContext.Current.Channel;   //2. Populate the label with read/write properties of a Channel   Label1.Text =    "<br><b>ApplyOuterScriptToPostings: </b>" +      cmsChannel.ApplyOuterScriptToPostings.ToString() +    "<br><b>DefaultPostingName: </b>" +      HttpUtility.HtmlEncode(        cmsChannel.DefaultPostingName.ToString()) +    "<br><b>OuterScriptFile: </b>" +      cmsChannel.OuterScriptFile.ToString() +    "<br><b>Description: </b>" +      HttpUtility.HtmlEncode(cmsChannel.Description.ToString()) +    "<br><b>DisplayName: </b>" +      HttpUtility.HtmlEncode(cmsChannel.DisplayName.ToString()) +    "<br><b>ExpiryDate: </b>" + cmsChannel.ExpiryDate.ToString() +    "<br><b>IsHiddenModePublished: </b>" +      cmsChannel.IsHiddenModePublished.ToString() +    "<br><b>IsImportant: </b>" + cmsChannel.IsImportant.ToString() +    "<br><b>IsRobotFollowable: </b>" +      cmsChannel.IsRobotFollowable.ToString() +    "<br><b>IsRobotIndexable: </b>" +      cmsChannel.IsRobotIndexable.ToString() +    "<br><b>Name (HtmlEncoded): </b>" +      HttpUtility.HtmlEncode(cmsChannel.Name.ToString()) +    "<br><b>SortOrdinal: </b>" + cmsChannel.SortOrdinal.ToString() +    "<br><b>StartDate: </b>" + cmsChannel.StartDate.ToString(); } 

Lines 3 and 4 in the code are necessary because the default galleries may not have been set and would return a null value. If we try to retrieve the Name property of a null value, we will receive an exception. So, we check for this condition and capture the name only if the gallery reference exists; otherwise, we show an empty string.

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 25-8.

Figure 25-8. Show read/write members

As you can see, many of the read/write property values are not set by default for a Channel object.

Read/Write Members Specific to Channels

ApplyOuterScriptToPostings

The ApplyOuterScript property holds the Boolean value that indicates whether the OuterScriptFile (see the OuterScriptFile property later in this section) will or will not be executed when a posting is requested by URL. The OuterScriptFile is always executed when a channel is requested by URL. The property will be true if the referencing Channel object will execute the OuterScriptFile when a posting is requested by URL. The default value for this property is false.

As a Boolean, this property can only be set to true or false. It must be set to true for frames to work correctly.

This member can be useful to specify whether to run the Outer ScriptFile when a posting is requested by URL.

DefaultPostingName

The DefaultPostingName property holds the case-insensitive name of the posting that will be shown if a user requests the referencing channel without specifying a posting. This is similar to the default document in an IIS virtual directory. However, unlike in IIS, there can only be one default posting specified, and if the posting specified is not found, CMS will either display the first posting in the channel or the CMS Welcome screen if there isn't a first posting. Since CMS does not prevent duplicate posting names, it is possible that this property could refer to an ambiguous name. However, CMS uses the SortOrdinal (see the SortOrdinal property later in this section) to choose which one to display. CMS will display the default posting for the appropriate PublishingMode requested.

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

This member can be useful to specify which posting to show by default when a channel is requested without a posting.

OuterScriptFile

The OuterScriptFile property holds the virtual path (IIS virtual directory and ASPX file name) to the script file executed when a channel, and perhaps when a posting (see the ApplyOuterScriptToPosting property earlier in this section), is requested by URL.

CMS will automatically trim leading and trailing spaces and truncate the length to 2000 characters for any string assigned to this property. Typical alphanumeric characters are allowed, but we recommend against using spaces. CMS does not validate the virtual path provided against IIS for accuracy but does require that it begin with a forward slash ("/"). The virtual path must specify the frameset for frames to work correctly.

This member can be useful to specify the virtual path and name of the outer script file.

Read/Write Members Inherited for Use by Channels

Description (Inherited from HierarchyItem)

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

CMS will automatically trim 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 ChannelItem that the user is using.

DisplayName (Inherited from ChannelItem)

The DisplayName property holds the free-form text of the long name or business name for the referencing ChannelItem intended for display purposes (see the Avoid Hack by Using HtmlEncode sidebar). If this property is empty or has never been set, the value in the Name property will be used instead. Unlike the Name property, the DisplayName is never used to construct URLs and doesn't indicate the Path to the Channel Item. It is the default sort order for any ChannelCollection.

CMS will automatically trim leading and trailing spaces and truncate the length to 250 characters for any string assigned to this property. Typical alphanumeric characters are allowed.

This member can be useful for setting and showing a user-friendly description of the ChannelItem that the user is using. This is especially useful for constructing aesthetic dynamic navigation.

ExpiryDate (Inherited from ChannelItem)

The ExpiryDate property holds the date value for when a ChannelItem will no longer be visible in Published PublishingMode. It has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section.

This member can be useful for showing the date and time that the ChannelItem will expire. It can be an excellent field on which to sort ChannelItems in a collection. It could also be useful to proactively provide a warning to users about content that is about to expire.

IsHiddenModePublished (Inherited from ChannelItem)

The IsHiddenModePublished property holds the Boolean value that indicates whether the referencing ChannelItem will or will not be included in any ChannelItem collection when the Context is in Published or Staging PublishingMode. It will be true if it should be excluded from the collection and false if it should be included in the collection. This does not restrict access to the hidden object; it just removes it from the collection. The default value for this property is false.

If the AutoFilterHidden property of the Context SessionSettings is set to false the setting in this property is ignored, and all ChannelItems are displayed in all collections in all PublishingModes.

As a Boolean, this property can only be set to true or false.

This member can be useful to control what is visible when developers are dynamically constructing site navigation.

IsImportant (Inherited from ChannelItem)

The IsImportant property holds the Boolean value that indicates whether the referencing ChannelItem is important or not. It will be true if the ChannelItem is important and false if it isn't. Importance of a ChannelItem is determined entirely by the user. The default value for this property is false.

As a Boolean, this property can only be set to true or false.

This member can be useful in classifying ChannelItems into two categories, important and not important. That might be useful for generating some kinds of dynamic navigation.

IsRobotFollowable, IsRobotIndexable (Both Inherited from ChannelItem)

The IsRobotFollowable and IsRobotIndexable properties hold the Boolean values that together indicate whether the referencing ChannelItem allows robots (search engine programs that crawl sites) to follow links and index the site or not. It will be true if robots are allowed to follow links or index, respectively, and false if they aren't. In either case, an appropriate ROBOT META tag is generated to advise the search engine of our preference. However, a META tag can't enforce the preference, just encourage or discourage it. The default value for these properties is true.

As Booleans, these properties can only be set to true or false.

These members can be useful for instructing search engines whether we want our Web Property to be indexed or not, and if indexed, whether we want links to be followed or not.

Name (Inherited from HierarchyItem)

The Name property holds the free-form text of the actual name for the referencing ChannelItem. 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 but can be nonunique (not recommended). Changing the value of the Name property actually changes the value of the read-only Path property.

CMS will automatically trim leading and trailing spaces and truncate the length to 100 characters for any string assigned to this property. Typical alphanumeric characters are allowed, but we recommend against using spaces in ChannelItem names. In fact, it frequently makes sense to let the user set the value of the DisplayName and to systematically set the name of a new ChannelItem for them.

This member can be useful for setting and showing a system-oriented description of the ChannelItem. This is especially useful for constructing the links used in dynamic navigation.

SortOrdinal (Inherited from ChannelItem)

The SortOrdinal property holds the custom sort sequence number for the referencing ChannelItem that is, the user-defined sequence that this ChannelItem would display relative to other ChannelItems at the same level in a collection.

For example, if there were three ChannelItems named A, B, and C and we wanted them to show in C, A, B order, we may give C a SortOrdinal of 30, A a SortOrdinal of 20, and B a SortOrdinal of 10. In this way we achieve a custom sort sequence, highest to lowest. As you can see, not every value is needed to order the ChannelItems relative to one another. Leaving gaps can potentially make inserting a new value easier, although duplicate values are allowed. We use descending numbers because new ChannelItems are given a SortOrdinal of zero (0).

Only numeric values are allowed.

This member can be useful for custom sorts but also for deciding which of two identically sorted items to show first. Since a series of sort methods applied to a ChannelCollection or PostingCollection behave like a multikey sort, when duplicate values occur, we can use SortOrdinal as a consistent tiebreaker.

StartDate (Inherited from ChannelItem)

The StartDate property holds the date value for when a Channel Item will first be made visible in Published and Staging publishing modes. It has the standard characteristics of a CMS date and time field described and summarized with the other dates at the beginning of this section.

This member can be useful for showing the date and time that the ChannelItem will become live. It can be an excellent field on which to sort ChannelItems in a collection. It could also be useful to proactively provide a warning to users about content that is about to go live.