A Comprehensive Guide to using Generated .NET Content Types with Ektron CMS 8.5+

The example I'm creating below is for output of images in a list, as though I were going to make a gallery. Keep in mind that there are other things I would do when actually creating a gallery, so this is by no means completed code in that regard. It is, however, a very good and simple illustration for how to retrieve and handle content from Ektron in the most .NET way possible (without a lot more separation of concerns).


First, I have some recommended reading for you. Ken McAndrew (long-time Ektron dev and now Sitecore dev) put together a nice set of posts about a class you can use to obtain Ektron's Smart Form content as .NET objects, making them much easier to work with. I recommend using Ken's version of the class (link within the blog post).

There's also a hangout featuring Bill Cava, original author of the method, Ken, and myself talking about this approach, which might help.

I looked and I think the original webinar has been taken down.

Regardless, once you have the Content Types code in place, it's relatively simple. You want to:

1. Create .NET models of your Smart Forms
2. Get the items
3. Map them to a ViewModel (optional)
4. Databind them to a ListView or Repeater control

Creating .NET Models for Smart Forms

To start this, I've created a rather simple Smart Form for a Press Photo. It contains three fields:

1. Name
2. Description / Caption
3. Image (stored as a URL string for simplicity, not as an <img /> tag)

Next, click the "XSD" button in the Smart Form's Data Design view (where you add/manage the fields) and copy all the XSD code. (You'll see the XSD button in the screenshot below, immediately above the modal.)

Save that to a file. I created a folder at C:\ContentTypes and added the file as PressPhoto.xsd there.

You'll want to run a file called XSD.exe (provided and documented by Microsoft as part of most Visual Studio installations). This will use the XSD and generate a C# class file for you - one that's friendly for deserializing the Smart Form XML into a .NET object.

Here's where to find it (as included with Visual Studio 2015):

However, running it from the command line is something I find painful since I always forget the rather lengthy path for it. So I created a Batch file to do most of the dirty work for me. I wrote it to accept three parameters, in order:

1. The path to the XSD file
2. The output path where I'd like to store the generated class file
3. The namespace I want for the generated class (tip: I always set the Namespace to include the name of the Smart Form - this prevents conflicts if you're generating classes for more than one Smart Form)

Here's the code and a screenshot of the command to execute it:

@ECHO OFF

SET xsdExePath="C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\xsd.exe"
SET xsdFilePath="%~f1"
SET outFolderPath="%~f2"
SET ns=%3

%xsdExePath% /c %xsdFilePath% /o:%outFilePath% /l:CS /n:%ns%

This generates a file named PressPhoto.cs within my C:\ContentTypes directory.

Going into my Ektron project, I'm going to add Ken's SmartForm class (referenced in his blog above) and my new PressPhoto class within a directory in my App_Code folder. Like so:

(Folder structure beneath App_Code/CSCode is up to you, but keep it organized for your own sanity.)

Add a class for each Smart Form you want to pull via API (for me, that's all Smart Forms).

I know this is seemingly a lot of prep, and compared to some other, more modern systems, it is. But this will help you immensely once you're in the habit.

Get the Items (and Map to a ViewModel)

Now that you've basically created your own APIs for getting the items (the alternative is XML Transforms, btw), you're ready to use them.

I prefer to create my own "Manager" class as well as ViewModel. If you'd prefer a different approach, then this will at least give you the sample code to move in your own direction.

I'm putting comments about the code in-line so you can read them in context.

View Model - very basic:

namespace MyProject.ViewModels
{
    /// <summary>
    /// Provides the fields necessary to display a PressPhoto Smart Form to the site.
    /// </summary>
    public class PressPhotoViewModel
    {
        public string Title { get; set; }
        public string Description { get; set; }
        public string ImageUrl { get; set; }
        public string ContentUrl { get; set; }
        public long ContentId { get; set; }
        public PressPhotoViewModel()
        {

        }
    }
}

And the "Manager" class, so as to put as little code into the code-behinds as possible. A nice, central location for all my PressPhoto logic.

using Ektron.Cms;
using Ektron.Cms.Content;
using Ektron.Cms.Common;
using Ektron.Cms.Framework.Custom;
using MyProject.SmartForms.PressPhoto;
using MyProject.ViewModels;
using System.Collections.Generic;
using System.Linq;

namespace MyProject.Managers
{
    /// <summary>
    /// Provides CRUD operations for managing PressPhoto objects within the CMS.
    /// </summary>
    public class PressPhotoManager
    {
        /* 
         * "root" is the default root element of the Smart Form XML. 
         * 
         * If you've changed this, your code will be different. Most people don't, 
         * so I'm going with the lowest-common-denominator example.
         * 
         * I normally set the "root" to something else, and thus give it a more 
         * meaningful class name. I also tend to load this manager via something more
         * similar to a singleton, but for simplicity's sake...
         */
        private SmartFormManager<root> pressPhotoManager = new SmartFormManager<root>();

        public PressPhotoManager()
        {
            // Nothing needs done here for this example.
        }

        /*
         * Usually, I'm not interested in writing information back to the DB, so
         * I'm only going to include samples for GetItem and GetList (by folder) here.
         */

        /// <summary>
        /// Retrieves a PressPhoto item by its Ektron Content ID
        /// </summary>
        /// <param name="ContentId" />Ektron Smart Form Content Id
        /// <returns>Press Photo ViewModel for display</returns>
        public PressPhotoViewModel GetItem(long ContentId)
        {
            /*
             * Get items - this returns an object that is the amalgamation of the standard 
             * Ektron ContentData object and the deserialized Smart Form information.
             * 
             * The format is:
             * * systemObject.Content = standard ContentData fields
             * * systemOjbect.SmartForm = Smart Form fields
             * 
             * For some reason, the returned object in the custom class inherits from ContentData.
             * This inheritance is probably not necessary and is also likely confusing. So only try 
             * to use the fields within the containers listed above.
             */
            var systemObject = pressPhotoManager.GetItem(ContentId, false);
            if (systemObject == null) return null;


            /*
             * I often want to map both Smart Form and ContentData fields to my output. This is where
             * a ViewModel comes in handy - it normalizes the data to be rendered. So then I'm not 
             * dealing with object.Content.* and object.SmartForm.* during rendering.
             * 
             * Another note: You might consider putting this mapping into a constructor in
             * the ViewModel in order to avoid the repetition you'll find in the GetList method
             * below.
             */
            return new PressPhotoViewModel()
            {
                ContentId = systemObject.Content.Id,
                ContentUrl = systemObject.Content.Quicklink,
                Title = systemObject.SmartForm.Name,
                Description = systemObject.SmartForm.Caption,
                ImageUrl = systemObject.SmartForm.Photo
            };
        }

        /// <summary>
        /// Retrieves a list of PressPhoto by the containing Ektron Folder Id (non-recursive)
        /// </summary>
        /// <param name="FolderId" />Ektron Folder Id
        /// <returns>Enumerable of Press Photo ViewModel for display</returns>
        public IEnumerable<pressphotoviewmodel> GetList(long FolderId)
        {
            /*
             * There are several "Criteria" objects. This is the simplist, but they also exist
             * for retrieving items from a Collection, from Taxonomy, or given a certain 
             * Metadata property value.
             */
            var criteria = new ContentCriteria();

            // Filter tells the API which folder to retrieve content from.
            criteria.AddFilter(ContentProperty.FolderId, CriteriaFilterOperator.EqualTo, FolderId);

            // Don't check sub-folders.
            criteria.FolderRecursive = false;

            /*
             * Retrieve only 12. The default is 50. Get in the habit of setting this so you 
             * don't grab 50 when you only need one.
             */
            criteria.PagingInfo = new PagingInfo(12);

            // Only return metadata when you need it, for performance. Default here is false.
            criteria.ReturnMetadata = false;

            // Ordering FTW! Hopefully self-explanatory.
            criteria.OrderByField = ContentProperty.Title;
            criteria.OrderByDirection = EkEnumeration.OrderByDirection.Ascending;

            // Same as above... 
            var systemObjectList = pressPhotoManager.GetList(criteria);
            if (systemObjectList == null || !systemObjectList.Any()) return null;

            return systemObjectList.Select(p => new PressPhotoViewModel()
            {
                ContentId = p.Content.Id,
                ContentUrl = p.Content.Quicklink,
                Title = p.SmartForm.Name,
                Description = p.SmartForm.Caption,
                ImageUrl = p.SmartForm.Photo
            });
        }
    }
}

Databinding to a List Control

For simplicity, I'm going to put this code into a .NET User Control.

Markup:

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="Gallery.ascx.cs" Inherits="Components_Controls_Gallery" %>
<asp:listview id="uxPhotoGallery" itemplaceholderid="itemPlaceholder" runat="server">
    <layouttemplate>
        <ul>
            <asp:placeholder id="itemPlaceholder" runat="server">
        </asp:placeholder>
        </ul>
</layouttemplate>
    <itemtemplate>
<li>
            <%-- 
                I'm mixing up two different ways of referencing the incoming data. One is by casting
                the DataItem to the incoming type, which gives you intellisense access to the properties.

                The other is more of a dictionary approach in which you have to type out the property name 
                as a string.

                I really like the casting approach, but it's mega-wordy.
                 --%>
            <a href="https://www.blogger.com/%3C%#((MyProject.ViewModels.PressPhotoViewModel)Container.DataItem).ImageUrl %>">
                <img alt="<%#Eval(" description="" src="<%#((MyProject.ViewModels.PressPhotoViewModel)Container.DataItem).ImageUrl %>" />" />
                <div>
                    <%#Eval("Description") %>
                </div>
            </a>
        </li>
    </itemtemplate>
</asp:listview>

Code:

using MyProject.Managers;
using System;
using System.Linq;

public partial class Components_Controls_Gallery : System.Web.UI.UserControl
{
    protected void Page_Load(object sender, EventArgs e)
    {
        var pressPhotoManager = new PressPhotoManager();

        // Whichever folder Id... 
        var photos = pressPhotoManager.GetList(75);

        if (photos != null && photos.Any())
        {
            uxPhotoGallery.DataSource = photos;
            uxPhotoGallery.DataBind();
        }
    }
}

And... that should do it. The best way I know how, in any case. There are certainly ways that require less code and prep, but this is by far my preferred as it keeps me working as much as possible in real .NET objects. Though you could use LinqToXml or other techniques, I prefer to not use them as it requires a lot more knowledge of the XML and never reads as well for the next developer, imo.

Happy coding.