<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=1639164799743833&amp;ev=PageView&amp;noscript=1">
Diagram Views

CMS Content Rendering, Part 2: Getting Started with Content Maker

Brad McDavid
#CMS, #Episerver-Ektron Merger, #Episerver, #Ektron, #Code
Published on June 30, 2015
warren-wong-323107-unsplash-1

Diagram's Content Maker introduces functionality similar to EPiServer's content rendering engine to the Ektron CMS. Learn how to implement this code here.

As news continues to be released about the plans for the EPiServer and Ektron CMS platforms following the merger between the two companies, we’ve not only been keeping up with the latest developments, but we’ve also been working to ensure that site owners will be able to get the most out of both platforms. One particular area of interest is that of structured content, which allows a site’s users to enter data into a website without worrying about how it will be formatted.

In part one of this series, we discussed various ways to display content within EPiServer and Ektron, with EPiServer utilizing a rendering engine, and Ektron using either XSLT or Content Types. In this article, we will cover how to get started with Diagram's Content Maker code, which brings EPiServer’s concept of views for content to Ektron Content Types.

Requirements

To utilize the Content Maker code, the following requirements must be met:

  • Ektron web site must be at version 8.7 or greater
  • Visual Studio 2012 or greater
  • NuGet installed for Visual Studio.

Installation

The quickest way to get up and running with the Content Maker is to utilize the pre-built NuGet package. This package is hosted on our NuGet feed, which can be added as a source using these instructions. Once the Diagram NuGet source has been added, open the web site within Visual Studio. Next, navigate to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution to open the NuGet GUI. The Content Maker package named Diagram.EktronCms.ContentMaker can be found in the online section under the name given to the Diagram NuGet feed when the source was added.

Alternatively, the Content Maker can also be installed by cloning the Git repository and building the source from Visual Studio. Several files will need to be copied to the web site; these are noted in the readme file on GitHub.

Creating Content Types

This step will be the most familiar to Ektron developers, but for those who are not familiar, a knowledge base article will guide you through creating a content class representation of an Ektron smart form. Also, it is important to note that the Content Maker doesn’t use any content type code like the code available on http://developer.ektron.com; we just kept the content type terminology that developers are familiar with.

Creating Model Classes

The model classes in the Content Maker serve many purposes. First, they create a convention to get de-serialized data from smart form XML into the content type classes. Next, they make a central place to handle any errors, such as null references for fields that are empty or removed from a smart form during content entry. For example, optional images and hyperlinks will read as null if they are left blank, and model classes will ensure that these null fields do not cause any errors.

Model classes also allow for computed properties, such as full name, which can be a combination of the first name and last name fields in a smart form. Another example of a computed property would be taking a content selector ID value from a smart form and creating a fully populated model instance from it. For example, if a blog post smart form has an author content selector, the blog post model can then have a blog author property that has all the information about the author from just the ID reference stored in the smart form data.

However, the biggest advantage for these model classes are allowing for simple views (ASP.Net user controls) to display their data. This happens because the logic to handle errors is in the model class, so once those conditions are handled, content data can be safely displayed with minimal template code.

Model Class Requirements

Model classes need to be decorated with the ASP.Net attribute Diagram.EktronCms.ContentMaker.Attributes.ContentDescriptor, with XmlConfigId set to match the smart form configuration ID in the work area. This attribute creates a relation between content created with the smart form configuration and the model class used for template views. Model classes also require two constructors, one that is empty and the other that accepts the following parameters: Diagram.EktronCms.ContentMaker.Interfaces.IContent c and string xml. Finally, they need to inherit the interface Diagram.EktronCms.ContentMaker.Interfaces.IContent or from a class that already implements the interface, such as Diagram.EktronCms.ContentMaker.Models.ContentType<T> where T is the content type class made with the XSD utility. Many model class examples are included in the samples project of the Content Maker GitHub repository; these can serve as a great reference while getting started.

Content Views for Model Classes

Now that we have a model class representing our smart form data, we need to create a view (an ASP.Net user control) to display the information. This user control has some conventions. The first is that the control needs to exist in a Views folder in the web site root folder. Next, content views must inherit the Diagram.ObjectRenderer.WebControls.ControlBase<T> base class, where T is an object, like the model class. Inheriting this class is important, as it exposes the CurrentData property that is strongly typed to the model T. This allows for simple data calls like <%= CurrentData.Heading %>, should the model T contain a Heading property.

Next, the code behind the class needs to be decorated with the Diagram.ObjectRenderer.Attributes.TemplateDescriptor attribute, which includes the following properties:

  • Path – Required string that is the full relative path of the user control. For example: ~/Views/BlogPost/ListView.ascx.
  • Default – Optional Boolean with default value of false. Default views carry a higher weight when resolving views for content models, and only one should exist per type. They are typically reserved for the main view of the content, such as a detail page.
  • Inherited – Optional Boolean with default value of false. Inherited views are typically used for content models that utilize interfaces or base classes.
  • Tags – Optional string array used to store the labels/tags associated with the content view. For example, Tags = new string[] { "ListView" }, creates a list view label for the view.
  • RequireTags – Optional Boolean with default value of false. If this value is true, and no tags are requested or do not match, then the template will not get selected.

Displaying Content Views

The final step to displaying content is to utilize the Diagram.ObjectRenderer.WebControls.ObjectRenderer web control, which is typically added to a template like:

<Diagram ID="wDynamicContent" runat="server" />

Notable properties of the object renderer include:

  • Item – A single object assigned to the renderer for display.
  • ItemList – An IEnumerable<object> of objects assigned to the renderer for display.
  • WrapTag – Optional string value of HTML tag to wrap around item(s) displayed in the renderer.
  • ItemWrapTag – Optional string value of HTML tag to wrap around each item in the renderer.
  • TagsString – Optional comma delimited list of tags used to find specific views of content, like the ListView tag.
  • DebugMode – Optional Boolean for troubleshooting views for content. This displays a detailed list of each item to be displayed along with the template selected for the object.

Utilizing this web control on an Ektron site can greatly reduce the number of templates needed, which is similar to the early days of Ektron using the default XSLT assigned in the work area. Also, content views for models can include ObjectRenderer web controls to display more items, like a listing of blog posts for an author, which creates a robust, re-usable view system for all the web site content.

Code Extensions

While the components listed above are all that is required to display content, additional functionality is available in the Content Maker to further simplify tasks. For example, by including the extensions namespace Diagram.EktronCms.ContentMaker.Extensions in the code behind the page or control template, you can get the fully populated model class by calling this.GetDynamicContent() which reads the ID value from query string  to pull the data. Additionally, a list of content can be retrieved with just a few lines:

// Create criteria object
var criteria = this.GetContentCriteria();

// Assign filters
criteria.AddFilter(Ektron.Cms.Common.ContentProperty.Id,
     Ektron.Cms.Common.CriteriaFilterOperator.GreaterThan, 30);

// Get listing of IContent from criteria
var content = criteria.GetContent();

Which can then be assigned to an ObjectRenderer’s ItemList property for displaying. Many more code examples can be found on the GitHub sample project.

Stay tuned for the final part of this blog, in which we will provide more information on how to use advanced functionality such as site settings and language glossaries. Also, please share any questions in the comments below, or contact me via Twitter. If you have any other questions, please contact us. We’re excited to see how people utilize this new functionality!