We have all been in that situation where we start creating a transformation, and we need to put some logic into it. Initially, we might think we won’t need very much code for our logic, so we start coding away in the text editor in the Kentico Portal Engine. We then quickly realize that the number of lines of code is getting hard to manage within the transformation. How do we solve this problem? With custom transformation methods. Custom transformation methods allow us to separate our logic from our ASCX Transformations, and make the code much easier to manage using a full-featured IDE like Visual Studio.
Setting Up Your File
First, you will want to navigate to the CMS
/App_Code folder of your project within Visual Studio. If your project is a web application, then you will want to navigate to
CMS/Old_App_Code. Within this folder, create a new folder and call it CustomTransformationMethods and within this folder, create a new file and name it
CMSTransformation.cs.
The version of Kentico that you are running will determine which namespace the CMSTransformation partial class that you will be extending is a part of. If you are on Kentico 8 or 9, then the namespace that you will be using is
System.CMS.Controls. If you are using Kentico 10 or greater, the namespace that you will be using is
System.CMS.DocumentEngine.Web.UI. See the Code examples below for the version of Kentico you are running.
Kentico 8 and 9
using System;
namespace CMS.Controls
{
/// <summary>
/// Partial class to be extended for Kentico versions 8 and above.
/// </summary>
public partial class CMSTransformation
{
/// <summary>
/// Your super awesome custom Transformation Method
/// </summary>
public string YourAwesomeMethod(object someParamater)
{
}
}
}
Kentico 10 and above
using System;
namespace CMS.DocumentEngine.Web.UI
{
/// <summary>
/// Partial class to be extended for Kentico versions 8 and above.
/// </summary>
public partial class CMSTransformation
{
/// <summary>
/// Your super awesome custom Transformation Method
/// </summary>
public string YourAwesomeMethod(object someParamater)
{
}
}
}
Writing Your Custom Transformation Method
For this example, let’s write a method called
AddDayOrdinalIndicator to add the ordinal indicator to the end of a date (ex: March 24 would become March 24th). First, we are going to determine what data type we are going to be passing to our custom transformation method. You will most likely be passing the returned value of a transformation method to your custom transformation method, so be sure to reference the
Kentico docs for the data type that is returned by the transformation method that you are using. All out-of-the-box transformation methods provided by Kentico return strings, unless stated differently in the Kentico documentation.
In the
AddDayOrdinalIndicator custom transformation method, I need to format the BlogPostDate column; therefore, I will use the
FormatDateTime transformation method provided by Kentico. The return type for this transformation is a little unclear in the transformation methods docs, but if you go to the
Kentico API reference, it states that the return value is of type Object. Therefore, I will have my
AddDayOrdinalIndicator custom transformation take one parameter of type object.
public string AddDayOrdinalIndicator(object day)
{
}
Next, we just need to write our logic. For the scope of this post, I will not go into details of the logic, as the purpose of your custom transformation method will likely be different than mine. See the code snippet below for the code of the entire CMSTransformation.cs file.
using System;
namespace CMS.Controls
{
/// <summary>
/// Extends the CMSTransformation partial class.
/// </summary>
public partial class CMSTransformation
{
/// <summary>
/// Trims text values to the specified length.
/// </summary>
/// <param name="day">Original text to be trimmed</param>
public string AddDayOrdinalIndicator(object day)
{
string ordinalIndicator = "th";
var dayInt = Convert.ToInt32(day);
if (dayInt % 10 == 1 && dayInt != 11)
{
ordinalIndicator = "st";
}
else if (dayInt % 10 == 2 && dayInt != 12)
{
ordinalIndicator = "nd";
}
else if (dayInt % 10 == 3 && dayInt != 13)
{
ordinalIndicator = "rd";
}
return ordinalIndicator;
}
}
}
Next, we just need to save the file and build the project (if it is a web app), and then we can use the custom transformation method in our transformation.
And voila! Our transformation is much cleaner, the C# code is MUCH easier to manage within Visual Studio, and we have separated our concerns of ASCX transformation code and C# code.
Summary
Utilizing custom transformation methods provides many benefits for you as a developer and for any future developers that need to read or modify the transformation you wrote. Writing your logic within Visual Studio makes it much easier to write and manage your code since it is a full-featured IDE. Furthermore, if you follow good naming practices, it will be much easier for another developer to read your transformation with your custom transformation method and immediately know what is going on, as opposed to having to read through a mix of mark-up and C# code.