The .NET-based PAPI object model includes all the traditional classes that CMS has always supported and some new classes as well. For instance, Templates are now accessible from the API.
Although the root of all CMS objects is the Context in which the request was made, things can get a bit confusing because objects can contain collections of objects that in turn can contain collections of objects ad infinitum. These collections contain objects that have objects that point back to the containing collection and potentially even the Context. The cyclical nature of the object model can be somewhat daunting and difficult to illustrate. So, we break it into eight separate related submodels.
Object models typically show objects and collections of objects, and their relationship to one another. PAPI is represented in this way in Figures 23-1 through 23-8. To concisely represent the infinite possibilities of this model, we use markers to reference common objects found within the model. Table 23-1 shows which marker represents each PAPI object.
Figure 23-1. PAPI object model Context
Figure 23-8. PAPI object model Searches
So, we give you the PAPI object model, starting with Context (Figure 23-1).
As stated earlier, Context is the entry point into the CMS object model. As illustrated, we can access the current Channel or the current Posting. Remember, the CmsHttpContext object is instantiated and initialized in the ASP.NET DLL before an ASPX template file is run. In contrast, the CmsApplicationContext object is instantiated manually by the developer, and it provides access to a subset of objects that is nearly the same as the set of objects that are accessible through CmsHttpContext.
There is a polymorphic object (not illustrated in Figure 23-1) that provides access to the ChannelItem, which, depending on the current state of the request or the requested asset, will provide access to the current Posting, if available, or to the current Channel.
There are references to the root object for each of the three hierarchies: RootChannel, RootResourceGallery, and RootTemplateGallery. Be aware that the roots will always be the built-in CMS objects called Channels, Resources, and Templates. So, if the Posting being viewed was in the leaf Channel of a hierarchy like this /MyChannel/Cool Channel/SubChannel the RootChannel of SubChannel would be the built-in Channels Channel rather than MyChannel. So, a better representation would look like this /Channels/MyChannel/CoolChannel/SubChannel. This is similar to a hard drive, where C:\ is the root directory rather than one of the subdirectories.
Searches is a powerful, if potentially expensive, property that can be used to locate specific objects. We describe the Searches objects in Figure 23-8 and give example code for each property in Chapter 28.
The User object is very weak in this release of CMS. There isn't very much that can be done programmatically with the User object outside of a couple of names and whether the user is in the Everybody group.
Lastly, the Context includes a SessionsSettings object that determines things like the automatic filtering of hidden items in collections and what locale an internationalized site will use.
A Channel (Figure 23-2) in a CMS Web site is the conceptual equivalent of folders (directories) in a Windows file system. Channels serve as containers for Postings and other Channels. Since a Channel can contain other Channels, the Parent property is the Channel that the referencing Channel is contained within. So, if we had a Channel hierarchy like this /MyChannel/CoolChannel/SubChannel the parent of SubChannel would be CoolChannel, the parent of CoolChannel would be MyChannel, and the parent of MyChannel would be the built-in Channels object. The parent of the built-in Channels object is null.
Figure 23-2. PAPI object model Channel
NOTE: We will explore all aspects of the Channel object in the API in Chapter 25.
On a Windows file system, a subdirectory can contain other subdirectories and/or files. Similarly, Channels can contain other Channels or Postings. So, not surprisingly, there is a potential collection of Channel objects and a potential collection of Posting objects in every Channel. CMS also provides an all-encompassing collection called AllChildren that contains all the members of both the Channels and the Postings collections.
NOTE: All CMS collections can be iterated using the .NET Framework's foreach syntax.
Each Channel has a potential collection of name/value pairs called CustomProperties. Some people use a CustomProperty to capture the constraints on an object. Each CustomProperty has an associated CustomPropertyDefinition.
NOTE: We cover the use of channel custom properties in Chapter 16.
The DefaultResourceGallery and the DefaultTemplateGallery for a Channel contain the Resource objects and Template objects that authors are encouraged to use when creating new Postings in that Channel. However, authors are not limited to using only the default gallery; they can use any gallery that they have access to. If our code references either of these objects, and they have not previously been set to a value, CMS will throw a trappable error.
A Posting (Figure 23-3) in a CMS Web site is a particular instance of a Template, combined with content for each of its Placeholders. Just as with a Channel, the Parent property of a Posting is the Channel that the referenced Posting is contained within. So, a Posting's Parent property has all the members that a Channel object has.
Figure 23-3. PAPI object model Posting
NOTE: We will explore all aspects of the Posting object in the API in Chapter 26.
A ConnectedPosting shares Placeholder content with the referenced Posting. So, there is a potential collection of ConnectedPostings. Checking the IsConnected property of a Posting will establish whether there are ConnectedPostings or not. Likewise, there is a potential collection of ConnectedTemplates. A ConnectedTemplate represents the various ways that a given Posting's content can be rendered.
Like the Channel object, each Posting object has a potential collection of name/value pairs called CustomProperties.
NOTE: We cover the use of posting custom properties in Chapter 5.
Every Posting will likely have one or more Placeholders in which content contributors put their content. So, naturally, there is a potential collection of Placeholder objects.
Every Posting is based upon a specific Template, so just as naturally, there is a specific Template object for the referenced Posting.
Postings can be changed over time. It is possible that the current Posting is not yet approved or published. So, PAPI provides the WorkingRevision Posting object as a way to get to an unpublished version of a Posting object in code.
A ResourceGallery (Figure 23-4) is a container for Resources and other ResourceGalleries in the CMS Resource hierarchy. It is a hierarchical structure that has parents and children, much like the Channel object that we discussed earlier in this chapter. However, a ResourceGallery object contains multimedia Resource objects (including images) used to create Templates and Postings rather than the Postings themselves. Resources are basically content stored in the CMS Content Repository that are referenced by URLs from CMS Postings.
Figure 23-4. PAPI object model ResourceGallery
Since a ResourceGallery can contain another ResourceGallery, the Parent property is the ResourceGallery that the referenced ResourceGallery is contained within. So, if we had a ResourceGallery hierarchy like this /MyResourceGallery/CoolResourceGallery/SubResourceGallery the parent of SubResourceGallery would be CoolResourceGallery, the parent of CoolResourceGallery would be MyResourceGallery, and the parent of MyResourceGallery would be the built-in Resources object. The parent of the built-in Resources object is null.
NOTE: We will explore the use of a resource gallery in Chapter 9.
There wouldn't be much use for a ResourceGallery without a collection of Resource objects. It isn't surprising that a referenced Resource object has a Parent property that identifies the ResourceGallery in which that Resource object is located.
A TemplateGallery (Figure 23-5) is a container for Templates and other TemplateGalleries in the CMS Template hierarchy. It has parents and children much like the Channel object that we discussed earlier in this chapter. However, a TemplateGallery contains Template objects used to create Postings rather than the Postings themselves.
Figure 23-5. PAPI object model TemplateGallery
Since a TemplateGallery can contain another TemplateGallery, the Parent property is the TemplateGallery that the referenced TemplateGallery is contained within. So, if we had a TemplateGallery hierarchy like this /MyTemplateGallery/CoolTemplateGallery/SubTemplateGallery the parent of SubTemplateGallery would be CoolTemplateGallery, the parent of CoolTemplateGallery would be MyTemplateGallery, and the parent of MyTemplateGallery would be the built-in Templates object. The parent of the built-in Templates object is null.
NOTE: We will explore the use of a template gallery in Chapter 9.
There wouldn't be much use for a TemplateGallery without a collection of Template objects. We illustrate the Template object in Figure 23-6.
Figure 23-6. PAPI object model Template
A Template is the logical representation of a physical template file upon which one or more Postings may be based. Each Template object has a Parent property that indicates in which TemplateGallery the referenced Template object can be found.
The Parent object of a Template is the TemplateGallery that the referenced Template object is contained within. So, a Template's parent property has all of the members that a TemplateGallery object has.
Each Template has a potential collection of ConnectedTemplates. Checking the IsConnected property of a Template will establish whether there are ConnectedTemplates or not.
Similar to the Channel object, each Template object has a potential collection of custom values called CustomPropertiesDefinitions.
NOTE: We cover the use of templates in Chapter 12 and template custom properties in Chapter 10.
Every Template will likely have one or more PlaceholderDefinitions that describe the structure of the template file. So, naturally, there is a potential collection of PlaceholderDefinition objects. We illustrate the Placeholder object in Figure 23-7.
Figure 23-7. PAPI object model Placeholder
A Placeholder object polymorphically encapsulates a particular type of content in a CMS Posting. A Posting orchestrates the displaying of content in a collection of Placeholders based upon the positioning and style dictated by an underlying Template (and template file), using PlaceholderDefinition objects as a logical reference to the physical placeholder controls found in the file system. The following is a list of the various placeholder types that come with CMS: AttachmentPlaceholder, HtmlPlaceholder, ImagePlaceholder, InvalidPlaceholder, OfficeAttachmentPlaceholder, OfficeHtmlPlaceholder, and XmlPlaceholder. A developer can create a custom Placeholder to handle unique content.
NOTE: We will explore all aspects of the Channel object in the API in Chapter 25, and the Searches object in the API in Chapter 28. We explored the use of Placeholders in Chapter 13.
As important as Placeholders are to CMS, the object model for them isn't very complex. Logically, each Placeholder has an associated PlaceholderDefinition object.
A Datasource object allows a Placeholder object to use a source other than CMS to save and load its data. Cool.
The referenced Placeholder will belong to a specific Posting, so there is a Posting object with all the members of a posting. This behaves much the same way you would expect a Parent property (which isn't available) would behave.
The Searches method enables you to search for Channels, Postings, Templates, TemplateGalleries, Resources, and ResourceGalleries that match specific criteria. As you can see depicted in the object model (Figure 23-8), most searches return a collection of objects, but there are three that return a single polymorphic object.
The results of a search will typically need to be cast as a specific data type in order for the object to be assigned to a variable. The following two lines of code both are equally effective at casting the search result as a posting:
myPosting = CmsHttpContext.Current.Searches.GetByGuid(sGuid) as Posting; myPosting = (Posting) CmsHttpContext.Current.Searches.GetByGuid (sGuid);
The code in this book typically casts objects using the "as" keyword followed by the data type because it is easier for the code to flow to multiple lines, which is good for displaying code in a limited-width book. However, preceding the cast object with the data type in parentheses works just as well in VS.NET.
Like most CMS objects, the Searches object automatically takes into consideration the rights and privileges of the User, the current Mode, and the possibility that multiple versions of an object exist when performing a search. Deleted items are never returned.