Kentico Deep Dive Pt 2 - Transformation Engine

A large majority of building a website is taking something (or a list of somethings) and displaying that on the website in a certain way.  Whether it be menus, products, events, news, banners, carousels, whatever, the repetition and styling of objects is pretty much the core of a website.
In systems such as MVC, this is done through for-loops and razor syntax in views, in the XML world, it’s done through XSLT style sheets, in php through echo and short open tags.

But in Kentico, they have presented a better way: Their Repeater/Transformation Engine.

In this article we’re going to first go through how the transformation engine works (including hierarchy transformations), and how you can utilize it to your own fun!

Datasources, repeaters, transformations, oh my!

In the wonderful land of Kentico, there are 3 elements I want to focus on that build this trifecta of awesomeness.
In the rendering of page content, you have a couple elements….

The Data – DataSources

First element you need is the actual data.  WHAT you are going to transform.  This can come in a variety of different flavors, be it Pages, custom queries, XML data sources, heck you can create a data source out of pretty much anything.

But whatever you are making a Data Source out of, it really comes down to what a Data Source is to Kentico, and that’s a DataTable.

A Data Table is pretty much what it means, it’s a table of data (duh).  A Data Table has Columns, and Rows, and either through SQL or custom logic, can have Filters applied.  SQL driven data sources also can leverage things like Order By, Where Conditions, Top N, and Columns statements.

Once a Data Source is ready and compiles its content into a DataTable, it then passes that data to the Repeater.

Repeater – The middle man

A repeater is a loose term that (more or less) combines a Data Source and a Transformation.  Some Repeaters already have the Data Source built in, while others (such as the Basic Repeater) require you to specify a Data Source Webpart that it will use as its content.

A repeater is responsible for applying the transformation(s) to the Data Source.  It does this by looping through the Rows in the data source, and passing each Row to the right transformation to be applied.  We’ll get more into that in a bit.

Transformation – Render me good!

The transformation engine is the final piece of the puzzle.  Users can completely control the output of the “row” passed to a transformation, styling the content however they please.  There are many flavors of transformations, my previous article covers them with pros and cons. 

How does a Transformation pull in the data?

If you may recall a Data Table has Columns and Rows.  Each row is passed to the transformation, which can be accessed by the column name.  This is largely how Transformations work, it’s a “Dictionary” of objects, with the ColumnName as the key.

For instance, if I have a Data Source that is of the CMS_UserInfo table, and it passes a row, that row has columns “UserID”:87, “UserGUID”:”abcde-feafda-afeaf3-3q34fda”, and “FullName”:”Trevor Fayas”

So when you do either an

  or it is (in the background) doing something to the liking of a

The Transformation Engine also passes some context parameters, such as the DataItemIndex, DataItemCount, and other values to help you in your transformation.

If a Data Source is just a Data Table, how do Hierarchy Transformations work?

One limitation with a Data Table is its flat, 2 dimensional, only containing Rows and Columns.  But as you know, tree structures often have a nested format to them, along with different types of pages or elements.

Hierarchy Transformations allow you to specify a variety of transformations to apply under certain circumstances, such as only on the 1^st level, or only for specific page types, and allow you to nest children transformations within them.  How does this work?

The answer comes from a certain set of relationship columns and references.  If you look at the CMS_Tree table, you’ll notice a couple of fields.

The NodeLevel, NodeOrder, and NodeParentID determine the structure, with these 3 fields you can rebuild a tree exactly as you would see it, revealing the nested structure.

The ClassName (Really the NodeClassID, I expanded to the ClassName) reveals the “type” of object it is.

The NodeID is an identifier that you can match up on to determine if that row matches the current object.

So the magic is, as long as these types of fields exist (ID, Level, Order, ParentID, and ClassName) the CMS can processes hierarchical transformations.

Doesn’t that only apply to Pages?

While the CMS_Tree has these fields, you are not limited to only display Page content in a Hierarchy.  As long as you provide these fields, you can take any object and make it a hierarchy display.

In essence that’s what the WebPart "Universal Viewer with Custom Query" does.  You can specify a SQL Query (which is the data source), and specify in the web part properties what the Level, Order, ID, Parent ID, and “Selected Item Value” map to.  The only one it does not specify is the Page Type, which means you do need to return a column “ClassName” that has the Page Type CodeName if you want the Hierarchy transformations to work (if you use a normal transformation, then you don’t as it doesn’t need to ‘select’ the right transformation, it can just send it to the normal one).

Leveraging the Transformations

Now to leverage the transformation engine for your own purposes.  As stated, as long as you provide the right fields, including a ClassName, you can ‘trick’ the CMS to transforming whatever you send it.

My Universal API Viewer (With Hierarchy Support) does just that.  In it I created a set of inheritable classes that you can utilize that take care of rendering the proper ID, ParentID, Level, Order, and Class Name, so you can take things like XML feeds, or external APIs to make them transformable objects in Kentico.

I recently took the Google Calendar API, which has “Attachments” and “Attendees” as child objects, and created 5 Page Types in Kentico (Google Calendar Event, Attachment Holder, Attachment, Attendee Holder, and Attendee), and then created a Hierarchy transformation to display the API results (which through my custom classes converts it into a DataTable with Level, Order, ID, ParentID, and ClassName).

Note: That if you want my set of inheritable classes, just download and install the Universal API Viewer, the supporting classes are included there.

Conclusion

Now that you have a grasp of the Transformation engine, you really have the ability to access any piece of data, internal to Kentico or external, and provide users with the ability to control the display. This is a far superior option than to hard-coded rendering of data, which require code changes if you want to alter how something is displayed.  Happy Kentico-ing!