Monday, March 18, 2013

Using Smart Forms in Ektron

Phil Paris, Director, CMS & Web Platforms, Solution Architect & Sitecore MVP

There is usually a fair amount of structured information published to a website, which is generally entered by content managers. The structured method of entering information is preferred vs a free form text box for a few reasons. If left unstructured, content types would not look uniform, and would have the potential for breaking the style intended for the content type. It would also mean that if fields that are part of the content type were required or optional, there would be no way to enforce this. Ektron provides a simple mechanism to allow the developer to create a content type that allows the end user to enter information in a structured manner. These are called “Smart Forms” and they are fairly easy to implement. Let's go through a quick tutorial on how to create and use them.

  1. Ensure that there is a content folder to store your content items. In this case, I’ve created folder called Announcements.

  2. Next, go to Settings-->Configuration-->Smart Form Configuration. Click on “Add Smart Form.” Enter “Announcement” in the title and click “Save.”

  3. You will now be presented with the configuration screen, which allows you to the make the form that the end users will use to create a new Announcement. The form will have a few fields. Title, Short Description, and Long Description. These fields will all be text fields, so click on the text field button to enter the field information. The form looks like this.

    For now, we’ll keep things simple and use all default settings except for the size field.

    The actual smart form ended up looking like this.




  4. Now that the smart form has been configured, make sure that the content folder “Announcements” we made earlier can only contain the smart form announcement content type. You can do this by editing the properties on the Announcements folder, going to the “Smart Forms” tab, uncheck the “Inherit parent configuration” checkbox and select the announcement smart form.

  5. To actually render these content items on the site, we could use XSLT, but I am choosing to use .net and the Ektron API. In order to do this, we need to get the XSD of the form we just created and create a C# class from it. In the XML Configuration form for the smart form, click on the XSD button to the right of the screen.

    You will be able to copy and save the content to a file that xsd.exe will access. Ektron also provides a restful url to access this information but for now, let’s just save the xsd as Announcements.xsd to our c:\temp directory. Open your command prompt and make sure it’s focused on the directory that contains the xsd.exe program.

    c:\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\bin\NETFX 4.0 Tools\x64>
    Run this command on the file.
    xsd.exe c:\temp\Announcements.xsd /c /language:CS /outputdir:"c:\temp" 
    This is telling the program to read the xsd file, create a class, write the class in the C# language and output the .cs file in the temp directory.

  6. The result looks like this:
    //------------------------------------------------------------------------------
    
    // 
    
    //     This code was generated by a tool.
    
    //     Runtime Version:4.0.30319.17929
    
    //
    
    //     Changes to this file may cause incorrect behavior and will be lost if
    
    //     the code is regenerated.
    
    // 
    
    //------------------------------------------------------------------------------
    
    
    
    using System.Xml.Serialization;
    
    
    
    // 
    
    // This source code was auto-generated by xsd, Version=4.0.30319.17929.
    
    // 
    
    
    
    
    
    /// 
    
    [System.CodeDom.Compiler.GeneratedCodeAttribute("xsd", "4.0.30319.17929")]
    
    [System.SerializableAttribute()]
    
    [System.Diagnostics.DebuggerStepThroughAttribute()]
    
    [System.ComponentModel.DesignerCategoryAttribute("code")]
    
    [System.Xml.Serialization.XmlTypeAttribute(AnonymousType=true)]
    
    [System.Xml.Serialization.XmlRootAttribute(Namespace="", IsNullable=false)]
    
    public partial class root {
    
        
    
        private string titleField;
    
        
    
        private string shortDescriptionField;
    
        
    
        private string descriptionField;
    
        
    
        /// 
    
        public string Title {
    
            get {
    
                return this.titleField;
    
            }
    
            set {
    
                this.titleField = value;
    
            }
    
        }
    
        
    
        /// 
    
        public string ShortDescription {
    
            get {
    
                return this.shortDescriptionField;
    
            }
    
            set {
    
                this.shortDescriptionField = value;
    
            }
    
        }
    
        
    
        /// 
    
        public string Description {
    
            get {
    
                return this.descriptionField;
    
            }
    
            set {
    
                this.descriptionField = value;
    
            }
    
        }
    
    }
    
    
    
    
    Notice how the class name is “root”. You will most likely want to change that so let’s go ahead and change that now to Announcement. Follow this convention.
    [System.Xml.Serialization.XmlRootAttribute(Namespace = "", ElementName = "root", IsNullable = false)]
    
        public partial class Announcement
    
    
    When we change the name of the class, we need to ensure we are adding the XmlRootAttribute to the class.

  7. Now that we have a usable class, let’s write some code to read in our announcements and display them to the user. I’ve added the class to the project in the App_Code folder. I created a folder called “Custom” and placed it in there.


  8. While this definitely isn’t the ideal implementation for accessing this type of data, I condensed all the code into one user control for simplicity sake. You will see the numeric identifier of 72 in the code. That’s the folder id of the announcements folder from Ektron. Here’s the code:
    using Ektron.Cms;
    
    using Ektron.Cms.Common;
    
    using System;
    
    using System.Web.UI.WebControls;
    
    
    
    
    
    public partial class Announcements : System.Web.UI.UserControl
    
    {
    
        protected void Page_Load(object sender, EventArgs e)
    
        {
    
            Ektron.Cms.Framework.Core.Content.Content content = new Ektron.Cms.Framework.Core.Content.Content();
    
            var criteria = new Criteria();
    
            criteria.AddFilter(ContentProperty.FolderId, CriteriaFilterOperator.EqualTo, 72);
    
            var resultList = content.GetList(criteria);
    
            
    
            foreach(var result in resultList)
    
            {
    
                Announcement announcement = (Announcement)EkXml.Deserialize(typeof(Announcement), result.Html);
    
                Label title = new Label();
    
                title.Text = announcement.Title;
    
    
    
                Label shortDescription = new Label();
    
                shortDescription.Text = announcement.ShortDescription;
    
    
    
                Label description = new Label();
    
                description.Text = announcement.Description;
    
    
    
                pnlAnnouncements.Controls.Add(title);
    
                pnlAnnouncements.Controls.Add(shortDescription);
    
                pnlAnnouncements.Controls.Add(description);
    
    
    
            }
    
        }
    
    }
    
    
    
    


  9. Assuming you’ve entered an announcement into the folder, it will write out your announcement. Here’s what mine looked like.

    That’s it! Pretty easy to setup and use smart forms and get structured data in and out of Ektron!