Working with Posting Members
| Postings 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 sample, and then we provide an alphabetical list of read-only members specific to postings. Since channel and posting both inherit functionality from ChannelItem and HierarchyItem, all read-only members inherited for use by postings have already been covered in depth in Chapter 25. 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 postings. Again, the read/write members inherited for use by postings are covered in depth in Chapter 25. Exceptions are noted where necessary. Likewise, the common facts and concepts that will help us throughout the list of members are the same as those given in the Working with Channel Members section of Chapter 25. This applies to date and time fields, the recommended use of ToLocalTime, the use of January 01, 3000, as an indicator that a date is set to never expire, the rules regarding deleted items and the use of the IsDeleted property, and the rules regarding historical revisions. See the Working with Channel Members section of Chapter 25 for details. Read-Only MembersThe code to see all the read-only posting 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 samples. Replace the Button1_Click function of our Scratchpad template 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. Populate the label with read-only properties of a Posting Label1.Text = "<br><b>ChangeDate: </b>" + cmsPosting.ChangeDate.ToString() + "<br><b>ChangeToken: </b>" + cmsPosting.ChangeToken.ToString() + "<br><b>CreatedBy: </b>" + cmsPosting.CreatedBy.ToString() + "<br><b>CreatedDate: </b>" + cmsPosting.CreatedDate.ToString() + "<br><b>DisplayPath: </b>" + cmsPosting.DisplayPath.ToString() + "<br><b>GetHashCode: </b>" + cmsPosting.GetHashCode().ToString() + "<br><b>GetType: </b>" + cmsPosting.GetType().ToString() + "<br><b>Guid: </b>" + cmsPosting.Guid.ToString() + "<br><b>HasInaccessibleConnectedPostings: </b>" + cmsPosting.HasInaccessibleConnectedPostings.ToString() + "<br><b>IsConnected: </b>" + cmsPosting.IsConnected.ToString() + "<br><b>IsDeleted: </b>" + cmsPosting.IsDeleted.ToString() + "<br><b>IsDescendantOf: </b>" + cmsPosting.IsDescendantOf(cmsPosting.Parent).ToString() + "<br><b>IsWorkingRevision: </b>" + cmsPosting.IsWorkingRevision.ToString() + "<br><b>LastApprovedDeclinedBy: </b>" + cmsPosting.LastApprovedDeclinedBy.ToString() + "<br><b>LastModifiedBy: </b>" + cmsPosting.LastModifiedBy.ToString() + "<br><b>LastModifiedDate: </b>" + cmsPosting.LastModifiedDate.ToString() + "<br><b>OwnedBy: </b>" + cmsPosting.OwnedBy.ToString() + "<br><b>Path: </b>" + cmsPosting.Path.ToString() + "<br><b>QueryString: </b>" + cmsPosting.QueryString.ToString() + "<br><b>QueryStringModeUnpublished: </b>" + cmsPosting.QueryStringModeUnpublished.ToString() + "<br><b>QueryStringModeUpdate: </b>" + cmsPosting.QueryStringModeUpdate.ToString() + "<br><b>State: </b>" + cmsPosting.State.ToString() + "<br><b>StateApprovedVersion: </b>" + cmsPosting.StateApprovedVersion.ToString() + "<br><b>StateUnapprovedVersion: </b>" + cmsPosting.StateUnapprovedVersion.ToString() + "<br><b>Url: </b>" + cmsPosting.Url.ToString() + "<br><b>UrlInner: </b>" + cmsPosting.UrlInner.ToString() + "<br><b>UrlInnerPlain: </b>" + cmsPosting.UrlInnerPlain.ToString() + "<br><b>UrlModePublished: </b>" + cmsPosting.UrlModePublished.ToString() + "<br><b>UrlModeUnpublished: </b>" + cmsPosting.UrlModeUnpublished.ToString() + "<br><b>UrlModeUpdate: </b>" + cmsPosting.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 26-8. Figure 26-8. Show read-only members
Read-Only Members Specific to PostingsChangeTokenThe ChangeToken property is a numeric value assigned to a posting when it is hydrated from the database. Its primary purpose is to be used with the ValidateChangeToken method (described earlier in this chapter) to determine if anyone else has committed changes to the posting since it was retrieved. If not, any changes that are about to be committed will not be overwriting someone else's changes. A code sample was included with the ValidateChangeToken method. HasInaccessibleConnectedPostings, IsConnectedThe IsDeleted property retrieves a Boolean value that indicates whether the referencing Channel object has been deleted or not. The HasInaccessibleConnectedPostings property retrieves a Boolean value that indicates, typically to scripts, whether the referencing Posting object has ConnectedPostings that the current user does not have access to. It will be true if the referencing Posting object has one or more postings that the current user cannot access, but obviously "true" does not tell the calling code how many are inaccessible. On the other hand, it will be false if the user has access to all ConnectedPostings even if there are none. Use the IsConnected property to determine whether there are ConnectedPostings or not. The related IsConnected property retrieves a Boolean value that indicates whether there are ConnectedPostings or not. It will be true if the referencing Posting object has one or more ConnectedPostings, but, obviously, "true" does not tell the calling code how many there are. On the other hand, it will be false if there are no ConnectedPostings. These properties are useful to determine whether a posting shares its content with ConnectedPostings and whether the user has access to all of them or not. LastApprovedDeclinedByThe LastApprovedDeclinedBy property retrieves the User object associated with the last user to approve or decline a posting, if any. State, StateApprovedVersion, StateUnapprovedVersionThe State property retrieves the unique two-character code that the USPS has designated to represent each of the 50 regions that make up the United States. Wrong. The State property really retrieves the current physical page status for the current posting, as represented and discussed earlier in this chapter. Table 26-1 lists all the values that State can hold and their relationship to the page status, and Figure 26-2 depicts how a posting can transition from one state to another. The StateApprovedVersion property retrieves the current physical page status for the Approved version of the current posting. If there isn't an Approved version, the State will be None. The StateUnapprovedVersion property retrieves the current physical page status for the Unapproved version of the current posting. If there isn't an Unapproved version, the State will be None. All three states were included in the first code sample in this section. Review Figure 26-3 and the discussion leading up to that figure. Read-Only Members Inherited for Use by PostingsThe following members have the same functionality as described for Channel object's read-only members in Chapter 25:
ChangeDate (Inherited from ChannelItem)The ChangeDate property retrieves the date and time of the latest implicit change. The Posting object's ChangeDate is only different from the Channel object's ChangeDate because it includes the StartDate and ExpiryDate for its Parent, whereas the Channel object's ChangeDate does not. Url, UrlInnerPlain, UrlModePublished, UrlModeUnpublished, UrlModeUpdate (All Inherited from ChannelItem)All Url property rules for Posting objects are less complicated than they are for Channel objects. If there is a reference to an OuterScriptFile and the ApplyOuterScriptToPostings is true, the URL retrieved will execute the OuterScriptFile. Otherwise, it will execute the script referenced by the template. The definition about what the different Url properties return is the same as it is for Channel objects. Read/Write MembersAs before, the code to see all the read/write Posting 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 Rollback OnSessionEnd property. By default, this property is false, so all changes are committed when the session ends. 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 PublishingMode (see the Getting into Update PublishingMode sidebar in Chapter 25). 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. There are some properties that the user will be allowed to put free-form text into. We should use the HtmlEncode method of the .NET System.Web.HttpUtility object when displaying what the user has entered to prevent any issues that could arise out of that (see the Avoid Hack by Using HtmlEncode sidebar in Chapter 25). When any change is made to a posting through any property or method, the posting and all its ConnectedPostings will become owned by the current user. 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. Also, if the changes are made and committed for an Approved posting, the state of that posting will potentially change to WaitingForModeratorApproval, and the changes will only be visible after approval is given. If there are no channel moderators or if the current user has sufficient rights to approve the change, the state will not change. Once a posting is marked for submission, approved, or declined, changes to that posting's properties will fail. The properties can only be changed again after a CommitAll or RollbackAll has been called. The read/write properties that we can set in code using PAPI can also be set using the Site Manager interface.
NOTE: We discuss using Site Manager in detail in Chapter 9. Replace the Button1_Click function of our Scratchpad template 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. Populate the label with read/write properties of a Posting Label1.Text = "<br><b>Description (HtmlEncoded): </b>" + HttpUtility.HtmlEncode(cmsPosting.Description.ToString()) + "<br><b>DisplayName (HtmlEncoded): </b>" + HttpUtility.HtmlEncode(cmsPosting.DisplayName.ToString()) + "<br><b>ExpiryDate: </b>" + cmsPosting.ExpiryDate.ToString() + "<br><b>IsHiddenModePublished: </b>" + cmsPosting.IsHiddenModePublished.ToString() + "<br><b>IsImportant: </b>" + cmsPosting.IsImportant.ToString() + "<br><b>IsRobotFollowable: </b>" + cmsPosting.IsRobotFollowable.ToString() + "<br><b>IsRobotIndexable: </b>" + cmsPosting.IsRobotIndexable.ToString() + "<br><b>Name (HtmlEncoded): </b>" + HttpUtility.HtmlEncode(cmsPosting.Name.ToString()) + "<br><b>SortOrdinal: </b>" + cmsPosting.SortOrdinal.ToString() + "<br><b>StartDate: </b>" + cmsPosting.StartDate.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 26-9. Figure 26-9. Show read/write members
Read/Write Members Specific to PostingsThere are none. Read/Write Members Inherited for Use by PostingsThe following members have the same functionality as described for the Channel object's read/write members in Chapter 25:
|
EAN: 2147483647
Pages: 298